Solution Overview

Three tiers, one direction of dependency

A-REX separates what must be standardized from what must merely work:

The four layers of the standard

flowchart TB
    L3["Layer 3 · IARexAttest<br/>attestations for a batch and a topic"]
    L2["Layer 2 · IARexHook + IARexHookManager<br/>one ordered pipeline of rules"]
    L1["Layer 1 · IARexBatch<br/>identity, status, a metadata commitment, and lineage"]
    L0["Layer 0 · ERC-1155 + ERC-165 + IERC7943MultiToken<br/>balances and an enforcement surface"]
    L3 --- L2 --- L1 --- L0
    classDef l3 fill:#edf5ff,stroke:#0f62fe,color:#161616
    classDef l2 fill:#d0e2ff,stroke:#0f62fe,color:#161616
    classDef l1 fill:#a6c8ff,stroke:#0f62fe,color:#161616
    classDef l0 fill:#78a9ff,stroke:#0043ce,color:#161616
    class L3 l3
    class L2 l2
    class L1 l1
    class L0 l0

The two tiers of the repository and the direction of dependency

flowchart LR
    STD["<b>The standard</b><br/>standard/ · contracts/standard/<br/>normative · CC0"]
    REF["<b>Reference implementation</b><br/>ARexToken · ARexAttestations<br/>MIT"]
    DEMO["<b>Demonstrations</b><br/>7 hooks · 3 extensions<br/>MIT · not normative"]
    STD -->|implemented by| REF -->|demonstrated by| DEMO
    DEMO -.->|depend only on the interfaces| STD

The standard never depends on the reference; the token never depends on the hooks. Remove every hook and every extension and a conformant token still exists. A third party obtains the normative text through early access, rather than from this public chapter.

What a batch is

A batch is an ERC-1155 token id. The field layout stays in the normative text.

Everything richer — grade, moisture, protein, packaging, GS1 identifiers, the traceability lot code, the EUDR declaration reference, lab reports, the issuer's status table — lives in the metadata document whose hash is committed on-chain. The document follows a published JSON Schema aligned with EPCIS 2.0 and the FSMA 204 key data elements.

The transfer pipeline

Every balance change — mint, transfer, burn, forced transfer, transformation — passes through one choke point in the reference token. The order is fixed and auditable:

flowchart TD
    A[safeTransferFrom / createBatch / burn / forcedTransfer / transform] --> B[reentrancy lock]
    B --> C{paused?}
    C -- yes, not forced --> X1[EnforcedPause]
    C -- no --> D{canSend from / canReceive to<br/>conjunction of ELIGIBILITY hooks}
    D -- false --> X2[ERC7943CannotSend / CannotReceive]
    D -- true --> E{per id: exists? not retired?<br/>amount ≤ balance − frozen?}
    E -- fail --> X3[ARexBatchNotFound / ARexBatchRetired /<br/>ERC7943InsufficientUnfrozenBalance]
    E -- ok --> F{per id, per CHECK hook in order:<br/>check → code}
    F -- code ≠ 0 --> X4["ARexHookRejected(hook, code)"]
    F -- all 0 --> G[balances updated · supply tracked]
    G --> H[per id, per EXECUTED hook: onExecuted]
    H --> I[unlock]

Two views replay the same logic without changing state: canTransfer (boolean, as ERC-7943 requires) and transferCheck (the first rejection code, so an interface can tell the user why).

Forced transfers skip the pause and the eligibility checks — enforcement must work when everything else is frozen — but still run the hooks with OP_FORCED_TRANSFER, so a hook can insist, for example, on a court-order reference in the transfer data.

Lineage

transform is the single operation for splitting, merging and processing:

graph LR
    W1["wheat #1<br/>250 t · farmer"] -- "transform (re-batch)" --> W2["wheat #2<br/>100 t · buyer A"]
    W1 -- "transform (re-batch)" --> W3["wheat #3<br/>150 t · buyer B"]
    W2 -- "transform (processing, TRANSFORMER_ROLE)" --> F4["flour #4<br/>75 t · mill"]

• Re-batching (same commodity, same unit, conserved quantity) is open to any holder or approved operator: a cooperative splitting a silo lot among members, an exporter merging deliveries.
• Processing (anything else) additionally requires TRANSFORMER_ROLE.
• parentsOf(4) == [2], parentsOf(2) == [1]; one BatchTransformed event per operation, which is an EPCIS TransformationEvent by construction.

Enforcement

ENFORCER_ROLE can freeze any amount for any account (setFrozenTokens, may exceed the balance, as ERC-7943 specifies) and move tokens without the holder's consent (forcedTransfer). This is what makes a batch token usable outside a demo: a lender executing a warrant, a court ordering the seizure of stored grain, a warehouse recovering a lot after a customer loses keys. Every enforcement action is an event.

Hooks

A hook is a contract with five functions and a constant flags bitmap. The token caches the flags at registration, so a transfer costs one external call per interested hook, not one interface probe per capability per module. A hook learns which token is calling from msg.sender; one deployment can serve many tokens.

Reference hooks demonstrate the three capabilities:

Companion extensions (not hooks): CommodityPriceOracle, CarbonImmobilizationWrapper, ParametricInsurance.

Attestations

A companion contract records (batch, topic) → (issuer, reference, validity). Only issuers trusted for a topic can attest; revocation, expiry and loss of trust all make isAttested false. Topics are bytes32, so ERC-735 claim topics, Ethereum Attestation Service schema ids and hashes of certification names all work without a table in the standard.

Actors and roles

Nothing in the standard fixes these roles; they are how the reference implementation exercises the MUSTs ("restricted to an authorized role").

Deployment shapes

• Public L2 (Polygon, Arbitrum, Base, Optimism): cheapest, most composable; suited to commodity trading and financing where counterparties are businesses.
• Permissioned EVM chain: where data-protection authorities or the anchor institution require it; the EDPB expressly encourages permissioned designs. The standard is chain-agnostic.
• Hybrid: batches on a public chain, restricted data (plot polygons, producer identity) behind access-controlled storage referenced from metadata.

The reference stack deploys with one Ignition module or one script: token proxy, attestation registry, eligibility and expiry hooks.

Design decisions and the alternatives they replace