Add AFL++ fuzzing test crate and docs

Makefile

@@ -46,6 +46,10 @@ build-test-wasms: fmt
 build-fuzz:
 	cd tests/fuzz/fuzz && cargo +nightly fuzz check
 
+# Builds the afl fuzz test. Requires cargo-afl, see tests/fuzz_afl/README.md.
+build-fuzz-afl:
+	cd tests/fuzz_afl/fuzz && cargo afl build
+
 readme:
 	cd soroban-sdk \
 		&& cargo +nightly rustdoc --features testutils -- -Zunstable-options -wjson \

soroban-sdk/src/testutils/arbitrary.rs

@@ -1,15 +1,17 @@
-//! Support for randomized testing of Soroban contracts, with [`cargo-fuzz`] or
-//! [`proptest`].
+//! Support for randomized testing of Soroban contracts, with [`cargo-fuzz`],
+//! [`cargo-afl`], or [`proptest`].
 //!
 //! This module provides a pattern for generating Soroban contract types for the
 //! purpose of fuzzing and property testing Soroban contracts. It is focused on
 //! implementing the [`Arbitrary`] trait, which turns generated bytes into Rust
-//! values: `cargo-fuzz` consumes it directly, and `proptest` through a bridge.
+//! values: `cargo-fuzz` and `cargo-afl` consume it directly, and `proptest`
+//! through a bridge.
 //!
 //! The examples in this module are written for `cargo-fuzz`. For generating the
 //! same values in a `proptest` property test, see the [`proptest`] module.
 //!
 //! [`cargo-fuzz`]: https://github.com/rust-fuzz/cargo-fuzz/
+//! [`cargo-afl`]: https://github.com/rust-fuzz/afl.rs/
 //! [`Arbitrary`]: ::arbitrary::Arbitrary
 //! [`proptest`]: crate::testutils::proptest
 //!
@@ -21,10 +23,10 @@
 //! This module is only available when the "testutils" Cargo feature is defined.
 //!
 //!
-//! ## About `cargo-fuzz` and `Arbitrary`
+//! ## About `cargo-fuzz`, `cargo-afl`, and `Arbitrary`
 //!
-//! In its basic operation `cargo-fuzz` fuzz generates raw bytes and feeds them
-//! to a program-dependent fuzzer designed to exercise a program, in our case a
+//! In its basic operation a fuzzer generates raw bytes and feeds them to a
+//! program-dependent fuzz target designed to exercise a program, in our case a
 //! Soroban contract.
 //!
 //! `cargo-fuzz` programs declare their entry points with a macro:
@@ -170,6 +172,85 @@
 //!     // fuzz the program based on the input
 //! });
 //! ```
+//!
+//!
+//! ## Fuzzing with `cargo-afl` instead of `cargo-fuzz`
+//!
+//! Everything above applies unchanged when fuzzing with [`cargo-afl`], which
+//! drives [AFL++] instead of libFuzzer: prototypes are generated by the same
+//! [`Arbitrary`] trait, and are converted to contract types with the same
+//! [`FromVal`] or [`IntoVal`] conversions. `cargo-afl` runs on stable Rust,
+//! whereas `cargo-fuzz` requires a nightly compiler.
+//!
+//! [AFL++]: https://aflplus.plus
+//!
+//! Install the tooling, which builds AFL++ from source and so needs a C
+//! compiler and LLVM available, and let AFL++ tune the machine for fuzzing:
+//!
+//! ```text
+//! cargo install cargo-afl --locked
+//! cargo afl system-config
+//! ```
+//!
+//! An AFL++ fuzz target is a crate with a `main` that calls the [`afl::fuzz!`]
+//! macro, and it depends on the `arbitrary` crate directly, because that is
+//! where the `Arbitrary` derive comes from and where `fuzz!` looks up the trait:
+//!
+//! ```toml
+//! [dependencies]
+//! afl = "0.18"
+//! arbitrary = { version = "~1.3.0", features = ["derive"] }
+//! soroban-sdk = { version = "*", features = ["testutils"] }
+//! my-contract = { path = ".." }
+//! ```
+//!
+//! [`afl::fuzz!`]: https://docs.rs/afl/latest/afl/macro.fuzz.html
+//!
+//! ```
+//! # macro_rules! fuzz {
+//! #     (|$data:ident: $dty: ty| $body:block) => { };
+//! # }
+//! use arbitrary::Arbitrary;
+//! use soroban_sdk::testutils::arbitrary::SorobanArbitrary;
+//! use soroban_sdk::{Address, Env, IntoVal};
+//!
+//! #[derive(Arbitrary, Debug)]
+//! struct TestInput {
+//!     deposit_amount: i128,
+//!     claim_address: <Address as SorobanArbitrary>::Prototype,
+//! }
+//!
+//! fn main() {
+//!     fuzz!(|input: TestInput| {
+//!         // Create the `Env` inside the closure, not outside: AFL++ reuses the
+//!         // process for many inputs, and state created outside the closure
+//!         // would leak from one input into the next.
+//!         let env = Env::default();
+//!         let claim_address: Address = input.claim_address.into_val(&env);
+//!         // fuzz the contract based on the input
+//!     });
+//! }
+//! ```
+//!
+//! Build with `cargo afl build`, which is `cargo build` with the AFL++
+//! instrumentation added, and fuzz the resulting binary with an input directory
+//! containing at least one seed input:
+//!
+//! ```text
+//! cargo afl build
+//! cargo afl fuzz -i in -o out target/debug/fuzz_target_1
+//! ```
+//!
+//! Fuzz debug builds, at least at first: they keep integer overflow checks and
+//! `debug_assert!`s enabled, and those catch bugs a release build allows.
+//!
+//! Crashing inputs are written to `out/default/crashes/`. The target reads an
+//! input on stdin when it is not being driven by AFL++, so a crash is replayed
+//! by feeding the file back in:
+//!
+//! ```text
+//! RUST_BACKTRACE=1 ./target/debug/fuzz_target_1 < out/default/crashes/id:000000*
+//! ```
 
 /// A reexport of the `arbitrary` crate.
 ///