تصميم النظام · AREX-ARCH
A-REX Architecture — one-page summary
The full design — context, requirements, component model, data model, sequence diagrams, operational model, security controls, measured performance, decision records and the traceability matrix — is in SYSTEM DESIGN.md.
- معرّف المستند
- AREX-ARCH
- الإصدار
- 2.0 (summary of AREX-SDD-001)
- التاريخ
- 2026-09-21
- المصدر
- docs/ARCHITECTURE.md
| Field | Value |
|---|---|
| Document ID | AREX-ARCH |
| Version | 2.0 (summary of AREX-SDD-001) |
| Date | 2026-09-21 |
The full design — context, requirements, component model, data model, sequence diagrams, operational model, security controls, measured performance, decision records and the traceability matrix — is in SYSTEM-DESIGN.md. This page is the summary.
Two tiers, one direction of dependency
flowchart TB
S["<b>The standard</b><br/>standard/ + contracts/standard/<br/>interfaces · CC0"]
R["<b>Reference implementation</b><br/>contracts/reference/core<br/>ARexToken · ARexAttestations · MIT"]
D["<b>Demonstrations</b><br/>contracts/reference/hooks · extensions<br/>not normative · MIT"]
S -->|implemented by| R
R -->|demonstrated by| D
D -.->|depend only on the interfaces| S| Tier | Location | Depends on | May change without a standard change |
|---|---|---|---|
| Standard | standard/, contracts/standard/ | nothing | no (major version, two implementers) |
| Reference | contracts/reference/core/ | the standard, OpenZeppelin | yes |
| Demonstrations | contracts/reference/hooks/, contracts/reference/extensions/, contracts/examples/ | the standard interfaces only | yes |
Layers
| Layer | Interface | Content |
|---|---|---|
| 0 | ERC-1155, ERC-165, IERC7943MultiToken | balances; freeze; forced transfer; eligibility; canTransfer |
| 1 | IARexBatch | batch record (open codes, pre-harvest, origin reference, metadata hash), role-only status, transform lineage |
| 2 | IARexHook, IARexHookManager | ordered rule pipeline; bytes32 codes; ARexHookRejected(hook, code) |
| 3 | IARexAttest | attestations per (batch, topic); trusted issuers per topic |
The choke point
Every balance change passes through _update: lock → pause → eligibility → per-id (exists, not retired, frozen) → hooks check in order → balances → hooks onExecuted → unlock. canTransfer and transferCheck replay it as views.
Reference components
| Component | Role |
|---|---|
ARexToken | layers 0–2; UUPS; ERC-7201; 24,136 bytes |
ARexAttestations | layer 3 companion |
EligibilityHook, ExpiryHook, AttestationHook | minimal demonstration hooks |
PerishabilityHook, SeasonalHook, DeliveryHook, TraceabilityHook | domain hooks (decay, windows, custody, EPCIS events) |
CommodityPriceOracle, CarbonImmobilizationWrapper, ParametricInsurance | companion extensions |
Roles (reference token)
ISSUER, TRANSFORMER, STATUS, ENFORCER, HOOK_ADMIN, PAUSER, UPGRADER, DEFAULT_ADMIN; ATTEST_ADMIN on the attestation registry. Authority never derives from balances.
Design rules in one line each
Open codes, never enums; one cached hook interface, never capability probes per transfer; bytes32 codes, never strings; status by role, never by balance, with a terminal retire; pre-harvest is first-class; lineage through transform; enforcement from ERC-7943; an origin reference, never coordinates; nothing required beyond the token; ERC-7201 storage. Rationale: ADR-001…016.