Registros de decisão · ADR-001
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.
- ID do documento
- ADR-001
- Data
- 2026-09-21
- Fonte
- docs/adr/ADR-001.md
| Field | Value |
|---|---|
| ID | ADR-001 |
| Subject area | Scope of the standard |
| Status | Accepted |
| Date | 2026-09-21 |
| Owners | A-REX Contributors |
| Related requirements | FR-01, C-01 (SDD §3) |
| Supersedes / superseded by | — |
Context
A token standard is adopted when implementing it costs less than staying incompatible. The code base that preceded A-REX Core put a farm registry, an identity contract, enumerations of crops and grades and a valuation formula into its specification, and marked the registry and the identity contract as REQUIRED. An elevator in Argentina or an exporter in Colombia would have had to adopt somebody else's registry, identity model and crop list to be conformant.
The standards that did get adopted followed the opposite path. ERC-3643 (T-REX) and ERC-7943 each define a small interface, ship a working reference implementation, and let the ecosystem build compliance modules around them. ERC-1400, which tried to cover everything, gathered few independent implementations.
Issue
What exactly is normative in A-REX, and what is only a demonstration?
Assumptions
- Independent teams implement a standard only if conformance is cheap and does not force a product choice on them.
- ERC editors and reviewers reject proposals that prescribe a product or a business model.
- Domain rules (perishability, seasons, custody, carbon, insurance) differ per issuer and per jurisdiction.
Constraints
- The standard must be publishable as an ERC (CC0, ERC format, RFC 2119 keywords).
- Nothing outside the token may be required for conformance (C-01).
Alternatives considered
| Alternative | For | Against | Outcome |
|---|---|---|---|
| Keep the earlier 19-function surface with a required registry and identity | Feature-complete out of the box | No independent implementer would accept a mandatory registry and identity stack; every new crop needs a new version | Rejected |
| Standardize only four interfaces (batch, hook, hook manager, attestations) plus ERC-7943 | Small, implementable, composable; domain rules live in hooks | The reference must demonstrate that the small core is sufficient | Accepted |
| Publish a product and no standard | Fastest to ship | No interoperability; contradicts the goal of a public standard | Rejected |
Decision
Only standard/AREX-CORE.md and the files in contracts/standard/ (IARexBatch, IARexHook, IARexHookManager, IARexAttest, IERC7943MultiToken, ARexCodes, ARexInterfaceIds) are normative, under CC0. Everything in contracts/reference/ (the token, the attestation registry, the seven hooks and three extensions) is a reference implementation or a demonstration, under MIT, and may change in any release without a change to the standard.
Argument
A small normative surface is what makes the standard adoptable; the reference implementation and the demonstrations are what make it credible. Keeping them separate lets the demonstrations evolve quickly while the interfaces stay frozen, which is the pattern that took ERC-3643 from a product to a standard.
Consequences
Positive
- A third party can be conformant by implementing five interfaces, with no dependency on this repository.
- Domain rules can be added, replaced or removed without a standards process.
Negative
- The standard alone does not solve a business problem; adopters need hooks, from this repository or their own.
- Every document must say whether a statement is normative or illustrative, which costs editorial discipline.
Obligations it creates
- A change to
contracts/standard/is a major version with a migration note and needs confirmation from two independent implementers (standard/README.md). - No normative text may reference a contract in
contracts/reference/.
Implementation and evidence
| What | Where |
|---|---|
| Normative text | standard/AREX-CORE.md |
| Normative interfaces | contracts/standard/ |
| Reference and demonstrations | contracts/reference/ |
| A token with no hooks is conformant | test/standard/ARexToken.test.js: reports the standard interface ids, including ERC-7943 multi-token 0x41c4fbad |