| name | foundry-differential-tests |
| description | Create Foundry differential tests comparing production Solidity contracts against an independent reference model. Use when Codex needs paired deployments, paired actions, public-view state comparisons, strict equality checks, and root-cause classification of production/reference divergence. |
Foundry Differential Tests
Setup
Deploy production and reference systems side by side. Use shared actor setup, balances, markets, approvals, and configuration. Keep the paired-action helpers in a differential base contract.
Compare public behavior, not internals:
- return values
- ERC20/native balances
- deposited/locked/available balances from view functions
- public order/market/price-level views
- public metadata and configuration views
Do not compare internal storage layout, packed ids, or implementation-private traversal state unless the public interface exposes it.
Test Construction
- Start with deterministic scenarios that each prove one public semantic.
- Execute the same operation on production and reference.
- Compare all relevant public state after each step.
- Add fuzzing only after deterministic coverage has pinned the behavior.
- Keep helpers symmetric:
_placeLimitPair, _marketOrderPair, _batchPair, _assert...Pair.
Use typed interfaces for the reference boundary. Raw fallback calldata should only be modeled if the task explicitly includes fallback ABI behavior.
Equality And Tolerance
Default to strict equality. A one-unit mismatch is still a finding. Add tolerance only when the public spec defines tolerance or the user explicitly asks for an approximate property.
Failure Handling
When a differential test fails, classify before fixing:
harness defect: the paired setup is invalid or asymmetricreference bug: the independent model does not match public/spec behaviorproduction bug: production diverges from public/spec behaviorspec mismatch: the test documents a behavior not satisfied by production and should intentionally remain failing
Fix harness defects and reference bugs when requested. Preserve production/spec failures unless the user explicitly asks to change production code.
Validation
Run focused tests first, then the differential suite. If the fixture has a reference-only switch, also run representative tests against the reference-only deployment to catch reference completeness gaps.
