# AGENTS.md
## OVERVIEW
System-contract artifact crate that validates Solidity bytecode at build time and exports typed Rust constants plus ABI bindings.
## STRUCTURE
- `build.rs`: forge-driven bytecode generation, hash validation, versioned constant codegen.
- `src/lib.rs`: generated constant includes and `alloy_sol_types::sol!` interface bindings.
- `contracts/`: Solidity implementations.
- `contracts/interfaces/`: ABI interface sources used by Rust bindings.
- `artifacts/`: versioned bytecode JSON artifacts and `*-latest.json` references.
- `scripts/`: Foundry scripts used by build-time bytecode generation.
## KEY PATTERNS
- Build script is authoritative for artifact consistency checks.
- Generated bytecode must match `*-latest.json` hash or build fails.
- Versioned artifacts are semver-sorted and emitted as `Vx_y_z_*` constants with `LATEST_*` aliases.
- Each new system contract needs both script wiring and generated include wiring.
- Keep interface paths stable because `sol!` macro references source files directly.
## ANTI-PATTERNS
- Do not update Solidity code without updating artifacts and validating hashes.
- Do not hand-edit generated files in `OUT_DIR` expectations.
- Modify `build.rs` or artifacts instead.
- Do not collapse versioned artifacts into a single mutable JSON file.
- Preserve immutable historical versions for spec traceability.
## WHERE TO LOOK
- Add a new system contract export: update `build.rs` contract list and `src/lib.rs` module include + interface binding.
- Rotate to a new bytecode version: add `artifacts/<Name>-X.Y.Z.json` and update `<Name>-latest.json`.
- Debug bytecode mismatch failures: `build.rs::validate_contract_bytecode` diagnostics.
- Update ABI interface only: `contracts/interfaces/*.sol` and consuming modules in `src/lib.rs`.