Audit Readiness Package

1. Purpose

This document is what an external auditor receives on day one: scope, build instructions, invariants, threat model pointers, test coverage matrix, known limitations and the questions we want answered. It does not replace an audit; the audit is a stated precondition for a production anchor and for submitting the ERC.

2. Scope

Lines of Solidity in scope: about 2,600.

3. Build and test

npm ci                      # OpenZeppelin 5.3.0 pinned by lockfile
npx hardhat compile         # solc 0.8.22, viaIR, evm paris; ARexToken with optimizer.runs = 1
npm test                    # reference implementation, hooks, extensions, invariants (46 tests)
npm run interface-ids       # ERC-165 ids
npx hardhat run scripts/gas-report-standard.js
AREX_INVARIANT_STEPS=2000 AREX_INVARIANT_SEED=1 npx hardhat test test/standard/Invariants.test.js

4. Trust model

Hooks are trusted code: a hook can block all transfers. Registration verifies ERC-165 and non-zero flags only.

5. Invariants (with tests)

6. Threat model pointers

See whitepaper chapter Security Framework and docs/SYSTEM-DESIGN.md §9 for actors, capabilities and scenarios (malicious hook, hook re-entrance, compromised enforcement or upgrader key, status abuse, issuer fraud, metadata substitution, pre-flight staleness, gas griefing, upgradeable hook trust).

7. Test coverage matrix

8. Known limitations and open questions for the auditor

1. Data stash in storage. safeTransferFrom writes data to storage for hook consumption and deletes it afterwards. Cost is proportional to data length; no security impact identified. Confirm no path leaves opData populated.
2. currentOp context. forcedTransfer and transform set a storage flag consumed by _update. Confirm no re-entrant path could observe a stale flag (the lock should prevent it).
3. _isRebatch gating. A holder can transform without a role when commodity/unit are equal and quantities are conserved. Confirm this cannot be abused to launder a batch's identity (issuer becomes the operator; parents are recorded).
4. Hook DoS. A hook that reverts blocks the token until removed. Accepted by design; confirm removeHook and pause are always reachable.
5. ERC-1155 receiver callback runs after the lock is released (standard behaviour). Confirm state is final before the callback.
6. DeliveryHook relies on data == abi.encode(deliveryId) for settlement. Confirm a third party cannot craft a settlement for someone else's delivery (sender/receiver/amount/batch must match).
7. PerishabilityHook exponential approximation interpolates linearly within a half-life; check monotonicity.
8. Oracle median uses insertion sort bounded by reporter count; confirm no unbounded growth (_values per round).
9. Upgrade safety: ERC-7201 struct is append-only; confirm no inherited OpenZeppelin storage collisions (validated by the upgrades plugin in tests).

9. Out of scope

Off-chain metadata availability; the identity provider behind eligibility; the legal classification of any offering; the physical existence of goods.

10. Deliverables expected from the audit

Findings with severity and reproduction; confirmation or refutation of each invariant; an opinion on §8; a re-audit of fixes. Publication of the final report is a condition of the engagement.