feat(fuzzer): add deterministic fuzz loop and crash reports

[MaxiTech444]

Overview

This PR completes the Rust address fuzzer with a deterministic mutation loop and structured crash reporting. It generates valid Stellar address seeds, applies the existing mutators, executes the parser safely, and records replayable panic findings without stopping the remaining iterations.

Related Issue

Closes #309

Changes

🧪 Fuzzing Loop and Crash Reporter

• [MODIFY] examples/rust-address-fuzzer/src/main.rs

  • Generate valid G, M, and C address seeds and apply randomized length/version mutations.
  • Run parser calls inside std::panic::catch_unwind so one panic does not terminate the fuzzing loop.
  • Preserve deterministic replay with --seed, including the seed and iteration in each finding.
  • Keep corpus and stdin modes available while reporting parser panics consistently.

• [MODIFY] examples/rust-address-fuzzer/src/report.rs

  • Add structured Finding records containing the input, mutator name, panic message, seed, and iteration.
  • Write each finding as JSON under findings/finding-XXXXXX.json.
  • Continue emitting an aggregate run summary and fail the process when findings are detected.

• [MODIFY] examples/rust-address-fuzzer/src/generate.rs

  • Correct M-address seed construction to use the Stellar payload order: public key followed by muxed ID.
  • Keep boundary muxed-ID coverage aligned with the parser.

• [MODIFY] .github/workflows/fuzz.yml

  • Upload the structured findings/ directory when a fuzz run fails.

Verification Results

cargo test --manifest-path examples/rust-address-fuzzer/Cargo.toml --offline
✅ 34/34 passed

cargo run --manifest-path examples/rust-address-fuzzer/Cargo.toml -- --random 1000 --max-iterations 1000 --seed 309
✅ 1,000 inputs completed with 0 findings

git diff --check
✅ Passed

Acceptance Criteria	Status
Run a bounded fuzzing loop with randomized mutators	✅ Valid G/M/C seeds use truncate, pad, and version-byte mutations
Survive parser panics and continue processing	✅ Parser calls are isolated with catch_unwind
Write replayable crash findings as JSON	✅ Findings include input, mutator, panic message, seed, and iteration
Support deterministic reproduction	✅ --seed fixes the PRNG sequence and finding metadata
Preserve failing evidence in CI	✅ Workflow uploads the findings/ directory

Summary by CodeRabbit

• Bug Fixes

  • Corrected muxed Stellar address payload generation and boundary round-trip validation.
  • Improved fuzzing to consistently generate valid addresses before applying targeted mutations.

• New Features

  • Fuzzing findings now include the input, mutation type, panic details, seed, and iteration.
  • Findings are saved as individual JSON files for easier investigation.

• Chores

  • Updated CI workflows to run checks from the appropriate example directories.
  • Fuzzing artifacts now upload the complete findings directory.

[drips-wave]

@MaxiTech444 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ff20e9ee-1d8f-4475-95a4-f10f3e8fc39d

📥 Commits

Reviewing files that changed from the base of the PR and between 494a2ec and 3a6991e.

📒 Files selected for processing (5)

• .github/workflows/ci-rust.yml
• .github/workflows/fuzz.yml
• examples/rust-address-fuzzer/src/generate.rs
• examples/rust-address-fuzzer/src/main.rs
• examples/rust-address-fuzzer/src/report.rs

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The Rust address fuzzer now mutates valid generated addresses, captures parser panics, and writes structured JSON findings. M-address payload ordering and round-trip tests are updated. CI runs from example directories and uploads the findings directory.

Changes

Address Fuzzer

Layer / File(s)	Summary
Finding data and JSON persistence examples/rust-address-fuzzer/src/report.rs	Report stores Finding records and writes escaped JSON files to the findings directory.
Muxed address payload layout examples/rust-address-fuzzer/src/generate.rs	M-address payload construction and boundary round-trip validation use ed25519_key(32) + muxed_id_BE(8).
Mutation loop and panic capture examples/rust-address-fuzzer/src/main.rs	The fuzzer generates valid addresses, applies named mutations, captures panic messages, and records seed and iteration metadata.
Workflow working directories and findings artifact .github/workflows/ci-rust.yml, .github/workflows/fuzz.yml	Rust commands run from their example directories. Fuzz failures upload the findings/ directory as fuzzer-findings.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: 🔵 Low · up to 3a699

The fuzzer now records structured crash reports and continues after parser panics, but report files may be lost on write failure or overwritten across repeated runs, leaving a failed CI job without complete replay evidence. The PR is mergeable with explicit owner awareness and follow-up to make persistence more durable.

Sequence Diagram(s)

sequenceDiagram
  participant FuzzLoop
  participant AddressGenerator
  participant Mutate
  participant Parser
  participant Report
  FuzzLoop->>AddressGenerator: generate valid address
  AddressGenerator-->>FuzzLoop: address input
  FuzzLoop->>Mutate: apply selected mutator
  Mutate-->>FuzzLoop: mutated input
  FuzzLoop->>Parser: parse inside catch_unwind
  Parser-->>FuzzLoop: success or panic payload
  FuzzLoop->>Report: write Finding JSON on panic

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 29.41% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 3 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main changes: a deterministic fuzz loop and crash reports.
Linked Issues check	✅ Passed	The PR implements issue #309 requirements. It adds seeded fuzzing with mutators, executes parsing inside catch_unwind, continues after panics, writes JSON Finding records under findings/, and supports…
Out of Scope Changes check	✅ Passed	The CI workflow updates and M-address layout correction are documented as required supporting fixes for this PR. No unrelated code changes are identified.

Full details: Linked Issues check

Explanation

The PR implements issue #309 requirements. It adds seeded fuzzing with mutators, executes parsing inside catch_unwind, continues after panics, writes JSON Finding records under findings/, and supports deterministic replay through --seed.

Full details: Docstring Coverage

Explanation

Docstring coverage is 29.41% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 3 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codeZe-us]

@MaxiTech444 fix the CI workflow issue

[MaxiTech444]

@MaxiTech444 fix the CI workflow issue

Done.

[codeZe-us]

PR reviewed