Decision records · ADR-002
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.
- Document ID
- ADR-002
- Date
- 2026-09-21
- Source
- docs/adr/ADR-002.md
| Field | Value |
|---|---|
| ID | ADR-002 |
| Subject area | Token model |
| Status | Accepted |
| Date | 2026-09-21 |
| Owners | A-REX Contributors |
| Related requirements | FR-02, NFR-06 (SDD §3) |
| Supersedes / superseded by | — |
Context
An agricultural lot is fungible inside itself (every kilogram of lot 1 is equal) and distinct from every other lot (lot 1 is not lot 2). An issuer such as an elevator or a cooperative creates thousands of lots a season and splits and merges them routinely. Wallets, explorers, custodians and marketplaces already support the common token standards; a new base would start with no tooling.
Issue
Which base token standard should represent agricultural batches: ERC-20 per lot, ERC-721 per lot, or ERC-1155 ids with quantities?
Assumptions
- Lots are fungible within themselves and distinct from each other.
- Issuers create thousands of lots; splitting and merging are routine operations, not exceptions.
- Existing wallet and indexer support is a precondition for adoption.
Constraints
- Must be an existing, final ERC with broad tooling.
- Must express a quantity of a specific lot.
Alternatives considered
| Alternative | For | Against | Outcome |
|---|---|---|---|
| ERC-20, one contract per lot | Universal wallet support | One deployment per lot; lineage would have to cross contracts; no batch operations | Rejected |
| ERC-721, one NFT per lot | Unique identity per lot | No quantities; fractions need wrappers; partial delivery is not expressible | Rejected |
| ERC-1155, one id per lot with quantities | Many lots in one contract, quantities, batch transfers, broad support | totalSupply is overloaded in ERC1155Supply, which some clients handle poorly | Accepted |
Decision
A-REX Core is an extension of ERC-1155. A lot is a token id; its units are the id's balance; a conformant token MUST implement ERC-1155 and ERC-165 and MUST track totalSupply(id).
Argument
ERC-1155 is the only final standard that natively expresses "many distinct lots, each with a quantity" in one contract, which is exactly the shape of agricultural inventory. It also gives lineage a natural home: splitting and merging are burns and mints of ids in the same contract.
Consequences
Positive
- Wallets, explorers and marketplaces that know ERC-1155 work unchanged.
- One deployment serves every lot of an issuer; batch transfers amortize gas.
Negative
- Clients must call
totalSupply(uint256)by signature in ethers v6 because of the overload. - ERC-1155 receiver callbacks run after state changes, as in every ERC-1155 token.
Obligations it creates
- The reference inherits OpenZeppelin
ERC1155Supplyso that supply per lot is exact after partial burns.
Implementation and evidence
| What | Where |
|---|---|
| Implementation | contracts/reference/core/ARexToken.sol (ERC1155Upgradeable, ERC1155SupplyUpgradeable) |
| ERC-1155 interface id reported | test/standard/ARexToken.test.js: reports the standard interface ids… |
| Supply per lot | test/standard/Invariants.test.js: Σ balances(id) == totalSupply(id) |