System design · AREX-STRUCT

Project structure

Nothing in contracts/standard/ imports anything else in the repository; hooks and extensions depend on the interfaces, never on ARexToken.

Document ID: AREX-STRUCT
Version: 2.1
Date: 2026-09-22
Source: docs/PROJECT-STRUCTURE.md

Field	Value
Document ID	AREX-STRUCT
Version	2.1
Date	2026-09-22

Where everything lives, what depends on what, and which files are normative.

Dependencies between folders

flowchart LR
    SPEC["standard/<br/>specification · schema"] --- IFACE["contracts/standard/<br/>interfaces · CC0"]
    CORE["contracts/reference/core/<br/>ARexToken · ARexAttestations"] -->|implements| IFACE
    HOOKS["contracts/reference/hooks/<br/>7 hooks + mocks"] -->|implements IARexHook| IFACE
    EXT["contracts/reference/extensions/<br/>3 companions"] -->|uses IARexAttest| IFACE
    EX["contracts/examples/<br/>documentation hooks"] --> HOOKS
    TESTS["test/standard/"] --> CORE
    TESTS --> HOOKS
    TESTS --> EXT
    TESTS --> EX
    DOCS["docs/ · whitepaper/"] -.->|checked by scripts/check-docs.js| TESTS

Nothing in contracts/standard/ imports anything else in the repository; hooks and extensions depend on the interfaces, never on ARexToken.

The standard (normative, CC0)

Path	Contents
`standard/AREX-CORE.md`	the specification in ERC format
`standard/README.md`	interface ids, layers, versioning, change process
`standard/schema/batch-metadata.schema.json`	JSON Schema of the off-chain metadata document
`standard/examples/batch-metadata.example.json`	an example document that validates against the schema
`contracts/standard/IARexBatch.sol`	layer 1: batch identity, status, metadata commitment, lineage
`contracts/standard/IARexHook.sol`	layer 2: the hook interface
`contracts/standard/IARexHookManager.sol`	layer 2: pipeline management on the token
`contracts/standard/IARexAttest.sol`	layer 3: attestations
`contracts/standard/IERC7943MultiToken.sol`	layer 0: ERC-7943, copied verbatim
`contracts/standard/ARexCodes.sol`	operations, flags, statuses, recommended codes, helpers
`contracts/standard/ARexInterfaceIds.sol`	ERC-165 ids as constants

Reference implementation and demonstrations (MIT, not normative)

Path	Contents
`contracts/reference/core/ARexToken.sol`	UUPS token implementing layers 0–2
`contracts/reference/core/ARexAttestations.sol`	layer 3 companion registry
`contracts/reference/hooks/ARexHookBase.sol`	abstract base for hooks
`contracts/reference/hooks/EligibilityHook.sol`	allow and block lists, sanctions with source and TTL
`contracts/reference/hooks/ExpiryHook.sol`	expiry and pre-harvest gating
`contracts/reference/hooks/AttestationHook.sol`	a required attestation per commodity
`contracts/reference/hooks/PerishabilityHook.sol`	decay models and value views
`contracts/reference/hooks/SeasonalHook.sol`	windows per commodity and operation
`contracts/reference/hooks/DeliveryHook.sol`	delivery lifecycle, unit lock, settlement
`contracts/reference/hooks/TraceabilityHook.sol`	EPCIS-shaped event log
`contracts/reference/hooks/mocks/`	`RecordingHook`, `ReentrantHook`, `InterfaceIdProbe` (tests only)
`contracts/reference/extensions/`	`CommodityPriceOracle`, `CarbonImmobilizationWrapper`, `ParametricInsurance`, `mocks/TestERC20`
`contracts/reference/proxy/ERC1967ProxyImport.sol`	compiles OpenZeppelin's proxy for the Ignition module
`contracts/examples/`	`SeasonHook`, `MaxLotPerBuyerHook`, `MyHook`: the hooks printed in the documentation

Tests, scripts and deployment

Path	Contents
`test/standard/ARexToken.test.js`	batches, lineage, enforcement, pipeline, attestations, conformance, upgrade
`test/standard/DomainHooks.test.js`	perishability, seasonal, delivery, traceability, sanctions
`test/standard/Extensions.test.js`	oracle, carbon wrapper, insurance
`test/standard/Invariants.test.js`	seeded randomized invariants
`test/standard/ImplementationGuide.test.js`	the Implementation Guide chapter, executed
`test/standard/helpers.js`	fixtures and constants for tests
`scripts/deploy-standard.js`, `deploy-full-standard.js`	minimal and full reference stacks
`scripts/smoke-standard.js`	narrated walkthrough of one lot
`scripts/gas-report-standard.js`	gas with 0, 1 and 2 hooks, and per hook
`scripts/getInterfaceIds.js`	ERC-165 ids from the compiled interfaces
`scripts/check-docs.js`	keeps the documentation identical to executed code
`ignition/modules/ARexToken.js`	Hardhat Ignition deployment of the minimal stack
`.github/workflows/ci.yml`	compile, interface ids, docs check, tests, documented commands, site build
`hardhat.config.js`	solc 0.8.22, viaIR, `paris`; `optimizer.runs = 1` for `ARexToken`
`package.json`, `package-lock.json`	OpenZeppelin pinned to 5.3.0

Documentation

Path	Contents
`docs/README.md`	documentation map with ids, audiences and status
`docs/SYSTEM-DESIGN.md`	AREX-SDD-001, the System Design Document
`docs/adr/`	sixteen architectural decision records and their index
`docs/AUDIT-READINESS.md`	audit scope, trust model, invariants, coverage
`docs/ARCHITECTURE.md`	one-page summary of the SDD
`docs/HOOK-DEVELOPMENT.md`	how to write, test and register a hook
`docs/GETTING-STARTED.md`, `DEVELOPMENT.md`, `TESTING.md`, `CONFIGURATION.md`	engineering guides
`docs/history/`	the reviews that motivated A-REX Core
`whitepaper/ui/content/`	sixteen whitepaper chapters and the diagram sheets
`whitepaper/ui/`	the IBM Carbon documentation site
`whitepaper/ui/public/llm-full.txt`	the whitepaper as one plain-text file

Naming

A-REX Core is the standard (layers 0–3).
ARexToken is the reference implementation. Third parties are encouraged to name their own implementations differently.
The prefix ERC is not used in contract or interface names: no ERC number has been assigned and the EIP editors reject self-assigned names.