Merge pull request #717 from Codex723/feat/contract-fuzzing-property-testing

feat(testing): added contract fuzzing and property-based testing

Author: Nanle-code

.cargo-mutants.toml

@@ -26,6 +26,12 @@ examine_globs = [
     "src/utils/crypto.rs",
     "src/commands/deploy.rs",
     "src/utils/templates.rs",
+    # Contract testing infrastructure
+    "src/utils/mock_soroban.rs",
+    "src/utils/wasm_hash.rs",
+    "src/utils/contract_mocks.rs",
+    "src/utils/contract_testing.rs",
+    "src/utils/test_generator.rs",
 ]
 
 # ── Skip ─────────────────────────────────────────────────────────────────────

.github/workflows/fuzzing.yml

@@ -7,13 +7,15 @@ on:
       - 'src/**'
       - 'fuzz/**'
       - 'tests/property_tests.rs'
+      - 'tests/contract_property_tests.rs'
       - '.github/workflows/fuzzing.yml'
       - 'Cargo.toml'
   pull_request:
     paths:
       - 'src/**'
       - 'fuzz/**'
       - 'tests/property_tests.rs'
+      - 'tests/contract_property_tests.rs'
       - '.github/workflows/fuzzing.yml'
       - 'Cargo.toml'
   # Allow manual dispatch with configurable fuzz duration.
@@ -66,6 +68,9 @@ jobs:
       - name: Run property-based tests
         run: cargo test --test property_tests --locked -- --test-threads=1
 
+      - name: Run contract property-based tests
+        run: cargo test --test contract_property_tests --locked -- --test-threads=1
+
       - name: Run all tests (includes property tests)
         run: cargo test --locked -- --test-threads=1
 
@@ -122,6 +127,11 @@ jobs:
           - fuzz_wasm_hash
           - fuzz_encrypted_bundle_parse
           - fuzz_template_operations
+          # Contract fuzzing harnesses
+          - fuzz_wasm_validation
+          - fuzz_contract_invocation
+          - fuzz_contract_spec_parse
+          - fuzz_test_generator
     steps:
       - uses: actions/checkout@v4
 

FUZZING_GUIDE.md

@@ -44,6 +44,9 @@ in the contract crate and use the same `PROPTEST_CASES` setting as this guide.
 # Run property tests with default 256 cases per property.
 cargo test --test property_tests
 
+# Run contract property tests.
+cargo test --test contract_property_tests
+
 # Increase cases for a deeper search.
 PROPTEST_CASES=5000 cargo test --test property_tests
 
@@ -63,6 +66,9 @@ cargo fuzz list --fuzz-dir fuzz
 # Run a specific target for 60 seconds.
 cargo fuzz run fuzz_validate_public_key --fuzz-dir fuzz -- -max_total_time=60
 
+# Run a contract fuzz target.
+cargo fuzz run fuzz_wasm_validation --fuzz-dir fuzz -- -max_total_time=60
+
 # Run with a size cap (good for initial exploration).
 cargo fuzz run fuzz_passphrase_strength --fuzz-dir fuzz \
     -- -max_total_time=120 -max_len=1024
@@ -120,6 +126,7 @@ Additional property suites live in their own files:
 |---|---|---|
 | [`tests/config_property_tests.rs`](tests/config_property_tests.rs) | Config round trips | TOML/JSON serialization preserves every value; merging is identity-on-empty, idempotent, and overlay-wins; malformed combinations (unknown network, duplicate wallet, non-HTTP endpoint, unknown overlay key) are rejected |
 | [`tests/wallet_import_property_tests.rs`](tests/wallet_import_property_tests.rs) | Wallet import/backup | The same invariants the wallet fuzz targets assert, run on stable in every `cargo test` sweep |
+| [`tests/contract_property_tests.rs`](tests/contract_property_tests.rs) | Contract testing infrastructure | WASM validation, WASM hash computation, mock contract invocation, mock storage, mock addresses, and mock environment invariants |
 
 ### Writing new properties
 
@@ -164,6 +171,10 @@ macro that receives raw bytes and should **never panic** regardless of input.
 | `fuzz_wallet_backup_parse` | Wallet backup documents: malformed JSON, truncated files, invalid StrKeys, oversized inputs, Unicode names |
 | `fuzz_wallet_import_envelope` | Encrypted backup envelopes: base64 fields, salt/nonce lengths, truncated ciphertext, KDF parameters, plaintext/encrypted classification |
 | `fuzz_wallet_backup_structured` | Near-valid backup documents built with `arbitrary::Arbitrary`, to reach the semantic checks the byte-level harness rarely hits |
+| `fuzz_wasm_validation` | WASM binary validation: magic header, minimum size, panic-freedom |
+| `fuzz_contract_invocation` | Mock contract client invocation: call counting, return/error determinism, reset |
+| `fuzz_contract_spec_parse` | Contract test spec JSON parsing: malformed JSON, truncated docs, hostile Unicode |
+| `fuzz_test_generator` | Test case generation from source: malformed Rust, empty files, arbitrary fragments |
 
 ### Wallet import & backup harnesses
 
@@ -203,6 +214,46 @@ The invariants asserted by the harnesses:
 - **No misclassification** — a JSON document is never treated as an encrypted
   bundle, which would prompt for a passphrase that does not exist.
 
+### Contract fuzzing harnesses
+
+The contract fuzzing harnesses target the Soroban contract testing infrastructure
+in StarForge. These harnesses exercise the mock Soroban environment, WASM
+validation, contract spec parsing, and test case generation — all of which
+process inputs that could come from untrusted contract source files or test
+specifications.
+
+```bash
+# WASM validation: magic header, minimum size, panic-freedom.
+cargo fuzz run fuzz_wasm_validation --fuzz-dir fuzz -- -max_total_time=60
+
+# Mock contract invocation: call counting, return/error determinism.
+cargo fuzz run fuzz_contract_invocation --fuzz-dir fuzz -- -max_total_time=60
+
+# Contract test spec JSON parsing: malformed JSON, truncated docs.
+cargo fuzz run fuzz_contract_spec_parse --fuzz-dir fuzz -- -max_total_time=60
+
+# Test case generation from source: malformed Rust, empty files.
+cargo fuzz run fuzz_test_generator --fuzz-dir fuzz -- -max_total_time=60
+```
+
+Seed corpora ship under `fuzz/corpus/fuzz_wasm_validation/`,
+`fuzz/corpus/fuzz_contract_spec_parse/`, and
+`fuzz/corpus/fuzz_test_generator/`, covering valid WASM binaries, valid
+contract test specs, and valid Rust source fragments respectively.
+
+The invariants asserted by the contract harnesses:
+
+- **Totality** — every input is handled gracefully; nothing panics.
+- **WASM validation** — inputs shorter than 8 bytes or without the `\0asm`
+  magic header are rejected; valid headers with sufficient length are accepted.
+- **Mock invocation** — call counts always match the number of invocations;
+  pre-configured return values and errors are returned deterministically;
+  errors take priority over return values; reset clears all state.
+- **Spec parsing** — malformed JSON, truncated documents, and hostile Unicode
+  produce errors, never panics.
+- **Test generation** — malformed Rust source, empty files, and arbitrary
+  fragments produce errors or empty results, never panics.
+
 ### Running a target
 
 ```bash
@@ -313,7 +364,7 @@ The fuzzing CI pipeline is defined in
 
 | Job | Trigger | What it does |
 |---|---|---|
-| `property-tests` | Every push / PR | Runs `cargo test --test property_tests` with 2 000 cases |
+| `property-tests` | Every push / PR | Runs `cargo test --test property_tests` and `cargo test --test contract_property_tests` with 2 000 cases |
 | `fuzz-build` | Every push / PR | Compiles all fuzz targets (catches compilation errors) |
 | `fuzz-smoke` | Every push / PR | 30-second smoke run per target in a matrix |
 | `coverage` | Every push / PR | Generates LCOV + JSON; uploads to Codecov |
@@ -335,7 +386,7 @@ both systems:
 ### Property test
 
 ```rust
-// In tests/property_tests.rs
+// In tests/contract_property_tests.rs
 proptest! {
     #[test]
     fn prop_my_contract_validates_input(amount in valid_amount_string()) {
@@ -377,3 +428,8 @@ because they process untrusted external input or handle cryptographic material:
 | `check_passphrase_strength` | `utils/crypto.rs` | zxcvbn integration, minimum length gate |
 | `compute_local_wasm_hash` | `commands/deploy.rs` | On-chain hash consistency |
 | `validate_contract_id` | `utils/config.rs` | Contract address validation |
+| `validate_wasm` | `utils/mock_soroban.rs` | WASM binary validation, magic header checks |
+| `compute_wasm_hash` | `utils/wasm_hash.rs` | WASM hash computation, environment validation |
+| `MockContractClient::invoke` | `utils/contract_mocks.rs` | Mock contract invocation, call logging |
+| `load_contract_test_spec` | `utils/contract_testing.rs` | Contract test spec parsing (JSON/TOML) |
+| `generate_from_source` | `utils/test_generator.rs` | Test case generation from Rust source |

fuzz/Cargo.toml

@@ -25,6 +25,9 @@ hex  = "0.4"
 # JSON assembly for the structured wallet-backup harness.
 serde_json = "1.0"
 
+# Temp-file creation for harnesses that write fuzzer input to disk.
+tempfile = "3.8"
+
 # ── Fuzz targets ─────────────────────────────────────────────────────────────
 # Each [[bin]] entry corresponds to a file under fuzz/fuzz_targets/.
 # Run a specific target with:
@@ -101,3 +104,31 @@ name = "fuzz_wallet_backup_structured"
 path = "fuzz_targets/fuzz_wallet_backup_structured.rs"
 test = false
 doc  = false
+
+# ── Contract fuzzing harnesses ───────────────────────────────────────────────
+# These harnesses target Soroban contract testing infrastructure: WASM
+# validation, mock contract invocation, spec parsing, and test generation.
+
+[[bin]]
+name = "fuzz_wasm_validation"
+path = "fuzz_targets/fuzz_wasm_validation.rs"
+test = false
+doc  = false
+
+[[bin]]
+name = "fuzz_contract_invocation"
+path = "fuzz_targets/fuzz_contract_invocation.rs"
+test = false
+doc  = false
+
+[[bin]]
+name = "fuzz_contract_spec_parse"
+path = "fuzz_targets/fuzz_contract_spec_parse.rs"
+test = false
+doc  = false
+
+[[bin]]
+name = "fuzz_test_generator"
+path = "fuzz_targets/fuzz_test_generator.rs"
+test = false
+doc  = false

fuzz/corpus/fuzz_contract_spec_parse/empty_spec.json

@@ -0,0 +1 @@
+{}

fuzz/corpus/fuzz_contract_spec_parse/malformed_spec.json

@@ -0,0 +1 @@
+{"contract_id":"CA3C5F6A9B2D1E0F4C7A8B3D5E6F1A2C3B4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F","environment":"testnet","test_cases":[{"name":"test_transfer","description":"Test basic transfer","inputs":{"from":"GABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789","to":"GABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789","amount":"100"},"expected":{"success":true}]

fuzz/corpus/fuzz_contract_spec_parse/valid_spec.json

@@ -0,0 +1 @@
+{"contract_id":"CA3C5F6A9B2D1E0F4C7A8B3D5E6F1A2C3B4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F","environment":"testnet","test_cases":[{"name":"test_transfer","description":"Test basic transfer","inputs":{"from":"GABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789","to":"GABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789","amount":"100"},"expected":{"success":true}}]}

fuzz/corpus/fuzz_test_generator/empty_source.rs

@@ -0,0 +1 @@
+// empty source file for fuzzing

fuzz/corpus/fuzz_test_generator/valid_source.rs

@@ -0,0 +1,5 @@
+#[test]
+fn test_transfer() {
+    let result = contract.transfer("alice", "bob", 100);
+    assert!(result.is_ok());
+}

fuzz/corpus/fuzz_wasm_validation/valid_wasm.bin

@@ -0,0 +1 @@
+\0asm\x01\x00\x00\x00\x01\x07\x01\x03\x65\x6e\x76\x00\x02\x00\x00