决策记录
决策索引
Sixteen 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.
How to read a record
Every record follows the IBM architectural-decision template, so they can be compared line by line:
| Section | Answers |
|---|---|
| Decision in brief | the decision in one sentence (the italic line under the title) |
| Context | the situation and the forces that made a decision necessary |
| Issue | the question being decided |
| Assumptions and Constraints | what was taken as true, and what could not be changed |
| Alternatives considered | each option with its case for and against, and the outcome |
| Decision | what was decided, precisely enough to check it in the code |
| Argument | why this option over the others |
| Consequences | positive and negative effects, and the obligations the decision creates |
| Implementation and evidence | the contracts, documents and named tests that implement and prove it |
| Related decisions | the records it depends on or influences |
Records are numbered, dated and never deleted. A decision that is replaced is marked Superseded and points to its successor. Requirement identifiers (FR-nn, NFR-nn, C-nn) refer to the System Design Document, §3.
Decisions at a glance
| Record | Area | Decision | Status |
|---|---|---|---|
| ADR-001 | Scope of 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. | Accepted |
| ADR-002 | Token model | 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. | Accepted |
| ADR-003 | 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. | Accepted |
| ADR-004 | Extensibility | 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. | Accepted |
| ADR-005 | Error model | 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. | Accepted |
| ADR-006 | Data model | 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. | Accepted |
| ADR-007 | Traceability | 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. | Accepted |
| ADR-008 | Privacy | 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. | Accepted |
| ADR-009 | Deployment | 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. | Accepted |
| ADR-010 | Access control | 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. | Accepted |
| ADR-011 | Data model | 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. | Accepted |
| ADR-012 | Enforcement | 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. | Accepted |
| ADR-013 | Legal | 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. | Accepted |
| ADR-014 | Sustainability | 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. | Accepted |
| ADR-015 | Data integration | 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. | Accepted |
| ADR-016 | Implementation | 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. | Accepted |
How the decisions depend on each other
flowchart LR
subgraph S["Scope"]
A001["001 · interfaces only"]
A013["013 · legal neutrality"]
end
subgraph T["Token and data model"]
A002["002 · ERC-1155"]
A006["006 · open codes"]
A011["011 · pre-harvest"]
A008["008 · no personal data"]
end
subgraph E["Enforcement and control"]
A003["003 · ERC-7943"]
A012["012 · forced transfers"]
A010["010 · roles, terminal RETIRED"]
end
subgraph X["Extensibility"]
A004["004 · one hook interface"]
A005["005 · bytes32 codes"]
A007["007 · transform lineage"]
end
subgraph R["Reference implementation"]
A009["009 · attestation companion"]
A014["014 · carbon wrapper"]
A015["015 · oracle rounds"]
A016["016 · UUPS + ERC-7201"]
end
A001 --> A002 --> A003 --> A012
A001 --> A004 --> A005
A002 --> A007
A006 --> A011
A006 --> A008
A010 --> A012
A004 --> A012
A013 --> A003
A016 --> A009
A009 --> A014
A015 --> A016An arrow reads "shapes": ERC-1155 as the base (002) is what makes ERC-7943's multi-token variant the natural enforcement surface (003), which in turn defines what a forced transfer may skip (012).
When to write a new record
Write one when a change alters an interface, a normative rule, the trust model, the storage layout or a documented guarantee. Copy the structure of an existing record, take the next number, link the requirements it affects, and add it to the table above.