From 5ba7a00ccf77619c0d14b0e1a7669ce1409c00f8 Mon Sep 17 00:00:00 2001
From: Jah-yee <166608075+Jah-yee@users.noreply.github.com>
Date: Sun, 18 Oct 2026 10:30:50 +0800
Subject: [PATCH] fix(docs): audit crate list in contracts/README.md against
 actual subdirectories
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add 11 missing crate entries to the contract catalog:
- allowance-race: ERC-20 approve→transferFrom race condition fixture
- benchmark: Performance benchmark harness with WASM-size ceilings
- deposit-withdraw: Auth-gap vulnerability (S001) demonstration
- multisig-no-recovery: Stuck-state vulnerability variant
- private-transfer: Zcash-style shielded-balance ZK demo
- security-disclaimers: Standardized security disclaimers module
- sep41-compliance: SEP-41 token-interface conformance suite
- test-support: Shared test helpers to reduce CI compile times

Also update Structure section to document scripts/, fixtures/, and
MIGRATION_NOTES.md which were previously undocumented.

Fixes #1825
---
 contracts/README.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/contracts/README.md b/contracts/README.md
index fa3342a9..3dabeb83 100644
--- a/contracts/README.md
+++ b/contracts/README.md
@@ -4,18 +4,34 @@ This directory contains the Soroban contracts used by Sanctifier for analysis, f
 
 ## Contract catalog
 
+- `allowance-race`: Demonstrates the classic ERC-20 `approve → transferFrom` race
+  condition with safe `increase_allowance` / `decrease_allowance` helpers.
 - `amm-pool`: Automated market-maker fixture for slippage and reserve-invariant checks.
+- `benchmark`: Performance benchmark harness with compile-time WASM-size and
+  CPU-instruction ceilings for token and vesting contracts.
 - `bridge`: Cross-domain transfer fixture for authorization and replay analysis.
+- `deposit-withdraw`: Demonstrates the auth-gap vulnerability (S001) — a `withdraw`
+  function without `require_auth` that can be drained by any caller.
 - `flashloan-token`: Flash-loan execution fixture for temporary-balance safety checks.
 - `governance`: Proposal and voting fixture for control-plane validation.
 - `kani-poc`: Model-checking fixture used by formal verification workflows.
 - `multisig`: Multi-party authorization fixture for threshold and signer-order checks.
+- `multisig-no-recovery`: Demonstrates the stuck-state vulnerability — an N-of-M multisig
+  with no signer rotation, guardian, or recovery path.
 - `my-contract`: Baseline token-like contract used for deterministic testing/fuzzing examples.
 - `oracle`: Price-feed fixture for stale-data and trust-boundary validation.
+- `private-transfer`: Zcash-style shielded-balance private transfer demo using Groth16
+  ZK proofs with hidden amounts and identities.
 - `proxy`: Upgradeability fixture that emits governance-relevant upgrade/admin events.
 - `reentrancy-guard`: Reentrancy defense fixture contract.
 - `runtime-guard-wrapper`: Runtime guard and monitoring wrapper fixture.
+- `security-disclaimers`: Standardized security disclaimers and safe usage guidelines
+  module with runtime safety checks and security levels (CRITICAL/HIGH/MEDIUM/LOW).
+- `sep41-compliance`: Standardized SEP-41 token-interface compliance suite that
+  verifies all ten SEP-41 functions across contracts.
 - `shadowing-example`: Demonstrates variable-shadowing patterns and safer alternatives.
+- `test-support`: Shared test helpers (Env, token, asserts, SEP-41 compliance harness)
+  to reduce CI compile times across contracts.
 - `timelock`: Delayed execution fixture for governance sequencing.
 - `token-with-bugs`: Intentionally vulnerable token fixture for negative-path validation.
 - `unsafe-prng-example`: Fixture exposing predictable randomness usage.
@@ -34,6 +50,9 @@ This directory contains the Soroban contracts used by Sanctifier for analysis, f
 ## Structure
 - `vulnerable-contract/`: A reference implementation demonstrating common security pitfalls Sanctifier can detect.
 - `fixtures/finding-codes/`: Scan fixtures mapped to `S001` through `S012`.
+- `scripts/`: Testnet deployment script (`testnet-deploy.sh`) for deploying contracts to testnet.
+- `fixtures/`: Additional fixture contracts and XDR construction examples (`auth_gap_contract.rs`, `xdr_raw_construction.rs`, `versioning/`).
+- `MIGRATION_NOTES.md`: Migration notes for security disclaimer updates across contracts.
 
 ## 🔐 Security Disclaimers