rust-miniscript

The Miniscript compiler is non-deterministic. Outputs can change between:

• Different versions of the library.
• Different machines.
• Different executions on the same machine.
• Different implementations (e.g., Rust vs. C++ versions).

Because the compiler might reorder elements (e.g., changing and_b(A, B) to and_b(B, A)), do not use a Policy as a stable identifier for a Miniscript.

Best Practice: Run the policy through the compiler once, and use the resulting Miniscript output as your stable identifier.

The Miniscript Policy compiler (available via the compiler feature) converts a Bitcoin Policy into a Miniscript. It uses a brute-force algorithm with heuristics to find a Miniscript that minimizes the spending_weight, calculated as:

spending_weight = spk_cost + witness_cost

where spk_cost is the cost of the scriptPubKey and witness_cost is the expected cost of the witness based on satisfaction and dissatisfaction probabilities.

Note: To use the compiler, ensure you have enabled the compiler feature in your Cargo.toml.

When a fuzz test fails, the output includes a hex-encoded version of the input that caused the crash on the final line.

To reproduce the crash:

1. Copy the hex string from the crash summary.
2. Create or edit a duplicate_crash test. Use extend_vec_from_hex to pass the hex string into do_test.
3. Run cargo test.

Important: If you used specific RUSTFLAGS (like --cfg=hashes_fuzz) during fuzzing, you must use the same flags when running cargo test.

Template for duplicate_crash:

#[cfg(test)]
mod tests {
    use miniscript::bitcoin::hex::FromHex;

    #[test]
    fn duplicate_crash() {
        let v = Vec::from_hex("abcd").unwrap();
        super::do_test(&v);
    }
}

The miniscript project uses honggfuzz for fuzzing. To run the standard fuzzing suite (briefly fuzzing every target as performed in CI), execute the fuzz.sh script from the fuzz/ directory.

Prerequisites: To build honggfuzz, you must have libunwind installed, along with libopcodes and libbfd from binutils 2.38. Note that binutils 2.39 introduced breaking API changes.

Nix Setup: On Nix, you can obtain the required libraries and disable conflicting hardening flags by running:

nix-shell -p libopcodes_2_38 -p libunwind
# Inside the nix-shell:
NIX_HARDENING_ENABLE=''${NIX_HARDENING_ENABLE/fortify/}
NIX_HARDENING_ENABLE=''${NIX_HARDENING_ENABLE/fortify3/}
./fuzz.sh

For extended fuzzing sessions, use the following utilities:

• List all targets:

  source ./fuzz-util.sh
  listTargetNames

- **Run all targets for one hour:**
  ```bash
./cycle.sh

Note: cycle.sh uses chrt to reduce job priority. Edit the script to run for longer durations.

• Run a single target indefinitely:

  cargo hfuzz run <target>

To use rust-miniscript in an embedded or no_std environment, you must disable the default features. See the embedded/ directory in the repository for a concrete implementation example.

# Example Cargo.toml configuration
rust-miniscript = { version = "13.0.0", default-features = false }

You can speed up fuzzing by replacing real hashing and signing code with broken cryptography. This allows the fuzzer to forge signatures or find hash preimages more easily.

Warning: This may result in spurious bug reports because the broken crypto does not respect real algebraic or encoding invariants. NEVER compile production code with these flags.

To use broken crypto, compile and run the fuzzing scripts with the following RUSTFLAGS:

RUSTFLAGS="--cfg=hashes_fuzz --cfg=secp256k1_fuzz" ./fuzz.sh

This replaces the hashing library with broken hashes and the secp256k1 library with broken cryptography.

New fuzz tests are located in the fuzz_target/ directory. Follow these steps to add one:

1. Create the test: Copy an existing fuzz test and modify the do_test function. Place it in the appropriate crate's directory or directly in fuzz_target/.
2. Add dependencies: If your test requires new dependencies, add them to generate-files.sh so they are included in the generated Cargo.toml.
3. Regenerate configuration: Run ./generate-files.sh to update the Cargo.toml and CI jobs.
4. Verify the test: Run ./fuzz.sh <target>. A working test will produce a rapid stream of data; a failing test will error out quickly.