Decision records

Index of decisions

Twenty-two recorded decisions behind A-REX Core: for each one, the situation that forced it, the options that were weighed, what was decided, why, and where the decision is implemented and tested.

ADR-001: Standardize interfaces only; modules stay outside the standard

Only the specification and the interfaces in contracts/standard/ are normative; the reference token, hooks and extensions are implementations that may change without changing the standard.

ADR-002: ERC-1155 as the base token standard

A-REX Core extends ERC-1155: one contract holds many lots, each lot is an id with a quantity, and every conformant token is a complete ERC-1155 token.

ADR-003: Adopt ERC-7943 (multi-token variant) verbatim for enforcement

Freezing, forced transfers and eligibility come from ERC-7943, copied verbatim, so that liens, seizures and embargoes have the shape compliance tooling already recognizes.

ADR-004: One hook interface, flags cached at registration, ordered evaluation

Every rule is an independent IARexHook contract; the token calls the hooks in registration order, using flags cached at registration, and stops at the first rejection.

ADR-005: bytes32 rejection codes instead of strings or hook-side custom errors

A hook refuses by returning a namespaced bytes32 code; the token reverts with ARexHookRejected(hook, code) and exposes the same code before the transaction through transferCheck.

ADR-006: Open codes instead of closed enumerations

Commodity, unit, lifecycle status and attestation topic are open codes (bytes32 or uint8), so a new crop, unit, lifecycle or certification never requires a new version of the standard.

ADR-007: Lineage through an atomic transform operation

Split, merge and processing are one operation, transform, which burns inputs, mints outputs, records their parents on-chain and emits one event that maps to an EPCIS TransformationEvent.

ADR-008: No personal data on-chain

The batch record never holds coordinates or natural-person identifiers; origin is a reference to evidence, and precise geodata lives off-chain behind access control.

ADR-009: Attestations implemented in a companion contract

The reference implements IARexAttest in a separate ARexAttestations contract bound to one token, because embedding it pushed the token over the EIP-170 size limit.

ADR-010: Authority comes from roles, never from balances; RETIRED is terminal

Only an account with STATUS_ROLE can change a lot's status or metadata; holding units grants no authority, and once a lot is RETIRED (255) no one can revive it.

ADR-011: Pre-harvest lots are first-class (producedAt == 0)

A batch may be created before the goods exist: producedAt == 0 means not yet produced, so forwards, warrants and crop receivables use the same token as the delivered lot.

ADR-012: Forced transfers bypass pause and eligibility but still run hooks

A forced transfer works while the token is paused and against ineligible or frozen accounts, but it still passes through the hooks with OP_FORCED_TRANSFER, so a hook can require an order reference.

ADR-013: Legal neutrality: the standard does not classify the token

The standard takes no position on whether a batch token is a security, a commodity or a document of title; it ships the enforcement surface every classification needs and leaves policy to hooks and counsel.

ADR-014: Carbon as a registry-immobilised wrapper plus attestations; no primary issuance

Carbon credits are never created on-chain: the reference records credits immobilised in their registry, links tonnes to lots, mirrors retirement and publishes an attestation.

ADR-015: Oracle rounds keyed by round number, not wall clock

Commodity prices are agreed in numbered rounds per commodity, finalized at quorum with the median, so results do not depend on when submissions fall relative to a time bucket.

ADR-016: UUPS upgradeability with ERC-7201 storage and a per-file optimizer setting

The reference token is a UUPS proxy with ERC-7201 namespaced storage, compiled with optimizer.runs = 1 so that it fits EIP-170 at 24,136 bytes.

ADR-017: Namespaced extensions in batch metadata (schema 1.3.0)

Hooks are the single extension point of A REX Core, and anyone can deploy one. A rule often needs facts about a batch that the core fields do not hold. Examples: a moisture reading at intake, the registry serials of carb

ADR-018: A declared product carbon footprint under extensions.pact_pcf

A batch may carry a product carbon footprint that a named third party calculated, copied from a WBCSD PACT footprint into extensions.pact_pcf of the metadata document and validated by a published fragment. The reference implementation never calculates, sums or propagates one.

ADR-019: Capabilities in the standard, policy in profiles

A REX Core already gives implementations the tools that regulated trade needs: freezing and forced transfers (ERC 7943, ADR 003, ADR 012), pause, eligibility and the AREX:SANCTIONED code, attestations with trusted issuer

ADR-020: ERC-3643 compatibility as a read-through facade and a notification-only hook

ERC 3643 is a Final ERC for permissioned tokens, run in production by issuers, transfer agents, wallets, explorers and compliance vendors (the ERC3643 Association reports more than 140 members). Their tooling reads a sma

ADR-021: ONCHAINID claims whose validity is A-REX trust, computed live

ERC 3643 decides who may hold a token with ONCHAINID: each holder's wallet points to an identity contract (ERC 734 keys, ERC 735 claims), and the token's identity registry requires claims of given topics signed by claim

ADR-022: An EAS mirror that only publishes what A-REX says, under chain-independent schemas

EAS is the public good attestation layer on Ethereum and most of its L2s (deployed at fixed addresses per chain, predeployed at 0x4200…0021 on OP stack chains). Verifiers, indexers and explorers (easscan) read it without