Development

Repository layout

See PROJECT-STRUCTURE.md. In one line: standard/ and contracts/standard/ are the standard; contracts/reference/ is the reference implementation (token, attestations) with the demonstration hooks and extensions.

Change workflow

1. Decide which tier the change touches. A change to contracts/standard/ or standard/AREX-CORE.md is a change to the standard: open a discussion, write the migration note, and get two independent implementers to confirm (see standard/README.md).
2. Add a failing regression test in test/standard/.
3. Make the smallest compatible change.
4. Run the focused test, then npm test, then npm run interface-ids if an interface changed (ids must match the specification) and scripts/gas-report-standard.js if the pipeline changed.
5. Update the SDD (component catalogue, RTM), the relevant ADR (or add one), and the whitepaper chapter that describes the behaviour. Regenerate whitepaper/ui/public/llm-full.txt in the arex-site repository.

Upgradeable-contract rules (reference token)

• ERC-7201 namespaced storage: append fields to TokenStorage; never reorder or remove.
• No constructors with proxy state; _disableInitializers() in the implementation constructor.
• Inheritance changes are storage-layout changes.
• Pin OpenZeppelin (lockfile) and run the upgrades plugin validation before any upgrade.
• Production upgrades go through a multisig and a timelock (SYSTEM-DESIGN.md §8.4).
• Keep ARexToken under 24,576 bytes; the per-file optimizer.runs = 1 override is the last lever, hooks and companions are the first.

Hook rules

• Implement IARexHook (use ARexHookBase); declare capabilities in hookFlags() and keep them constant.
• check is a view that returns a code; it never reverts for policy. Return OK for OP_FORCED_TRANSFER unless the rule governs enforcement.
• onExecuted never calls balance-changing functions of the token.
• Read the batch from IARexBatch(msg.sender); do not store the token address.
• Keep check bounded: no iteration over history; configuration arrays capped.

Documentation rule

Every claim in the whitepaper and docs is one of: implemented and linked to code; verified by a named test or reproducible command; proposed and marked as future work; or an external fact with a primary source and date. Tests are not an audit; data-model fields are not regulatory compliance; the standard does not classify the token.