سجلات القرارات · ADR-007
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-007
- التاريخ
- 2026-09-21
- المصدر
- docs/adr/ADR-007.md
| Field | Value |
|---|---|
| ID | ADR-007 |
| Subject area | Traceability |
| Status | Accepted |
| Date | 2026-09-21 |
| Owners | A-REX Contributors |
| Related requirements | FR-04 (SDD §3) |
| Supersedes / superseded by | — |
Context
Lots become other lots: a truckload is split between buyers, silos are merged, wheat is milled into flour. FSMA 204's transformation critical tracking event and GS1 EPCIS 2.0's TransformationEvent both link inputs to outputs with quantities. The earlier design had a PROCESSED state but no way to create the processed lot, and its documentation described parent mappings that did not exist in the code.
Issue
How does a token record that one lot became another, so that recalls and mass-balance audits can follow it?
Assumptions
- Regulators and buyers ask for input-to-output links with quantities.
- Re-batching by holders is routine and should not need an institution.
Constraints
- The link must be atomic with the balance changes.
- Hooks must be able to see and govern the operation.
Alternatives considered
| Alternative | For | Against | Outcome |
|---|---|---|---|
An administrative setParent mapping | Simple | Not atomic, no quantities, can be forged after the fact | Rejected |
Separate split, merge and process functions | Explicit | Three functions and events for one operation with different cardinalities | Rejected |
One transform(from, to, inputIds, inputAmounts, outputs, outputAmounts, processRef) | Atomic, quantified, one event, one EPCIS mapping | Callers build arrays | Accepted |
Decision
transform burns the inputs from from and mints the outputs to to in one transaction, records parentsOf(output) = inputIds, emits one BatchTransformed, and runs every hook with OP_TRANSFORM on each leg. In the reference, a re-batch (same commodity and unit, Σ inputs = Σ outputs) needs only ownership or approval; any other transformation also needs TRANSFORMER_ROLE.
Argument
Making lineage an operation rather than a record means it cannot be written without the units actually moving, and it gives indexers one event per transformation instead of a reconstruction from transfers.
Consequences
Positive
- A recall walks
parentsOfbackwards andBatchTransformedforwards. - Holders can split and merge without waiting for an institution.
Negative
- The standard does not enforce quantity conservation for processing, because yields vary; that is a policy of the reference and of hooks.
Obligations it creates
- Processors hold
TRANSFORMER_ROLE; yield rules, if any, are hooks.
Implementation and evidence
| What | Where |
|---|---|
| Operation | ARexToken.transform, _isRebatch |
| Split, merge, processing, role | test/standard/ARexToken.test.js: splits a batch without any role…, merges two batches into one, processing into another commodity requires TRANSFORMER_ROLE |
| Executed walkthrough and lineage graph | test/standard/ImplementationGuide.test.js |