Decision records · ADR-011
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.
- Document ID
- ADR-011
- Date
- 2026-09-21
- Source
- docs/adr/ADR-011.md
| Field | Value |
|---|---|
| ID | ADR-011 |
| Subject area | Data model |
| Status | Accepted |
| Date | 2026-09-21 |
| Owners | A-REX Contributors |
| Related requirements | FR-03 (SDD §3) |
| Supersedes / superseded by | — |
Context
Most agricultural credit in Latin America finances a harvest before it exists: Brazil's CPR, forward contracts and input-for-grain swaps. The earlier design required the harvest date to be in the past, which made these instruments unrepresentable and forced a second token type for the same crop.
Issue
Can a batch represent goods that have not been harvested yet, and who decides whether such a batch can move?
Assumptions
- Pre-harvest instruments are the dominant form of agricultural credit in the region.
- Whether pre-harvest units may trade depends on the market, not on the standard.
Constraints
- One token type from field to delivery.
Alternatives considered
| Alternative | For | Against | Outcome |
|---|---|---|---|
| A separate future-lot token | Explicit | Two standards for one crop; lineage breaks at harvest | Rejected |
producedAt == 0 means not yet produced; hooks decide transferability | One token for the whole life of the crop | Readers must handle a zero date | Accepted |
Decision
createBatch accepts producedAt == 0. The standard does not say whether such a batch may be transferred; the reference ExpiryHook(allowPreHarvestTransfers) shows both policies, returning AREX:BATCH_NOT_PRODUCED when transfers are disallowed.
Argument
The date being unknown is a fact about the goods; whether they may trade is a policy of the market. Keeping the fact in the record and the policy in a hook serves both a spot marketplace and a crop-finance platform with the same token.
Consequences
Positive
- Crop receivables, forwards and warrants are expressible.
- Lineage continues from the pre-harvest lot to the harvested and processed lots.
Negative
- Integrators must not treat
producedAt == 0as 1970.
Obligations it creates
- Spot-only marketplaces register
ExpiryHook(false).
Implementation and evidence
| What | Where |
|---|---|
| Validation | ARexToken._storeBatch |
| Hook | contracts/reference/hooks/ExpiryHook.sol |
| Tests | test/standard/ARexToken.test.js: allows pre-harvest batches (producedAt == 0), ExpiryHook can block pre-harvest transfers |