A-REX Core — System Design Document

flowchart LR
    subgraph Actors
        ISS[Issuer / originator]
        HLD[Holder / buyer]
        PRC[Processor]
        WHS[Warehouse / inspector]
        CERT[Certifier / laboratory / authority]
        ENF[Enforcement: lender, court custodian, compliance]
        GOV[Governance multisig]
    end
    subgraph "A-REX Core system (on-chain)"
        TOK[(ARexToken)]
        ATT[(ARexAttestations)]
        HKS[(Hooks)]
        EXT[(Extensions: oracle, carbon, insurance)]
    end
    subgraph "External systems"
        IDP[Identity / screening provider]
        REG[Legal registries: EWR, CPR-e, DDS, carbon registries]
        META[Metadata storage: IPFS / HTTPS / restricted vault]
        IDX[Indexer / EPCIS exporter]
        WAL[ERC-1155 wallets, marketplaces, ERC-7943 tooling]
    end
    ISS --> TOK
    HLD --> TOK
    PRC --> TOK
    WHS --> TOK
    CERT --> ATT
    ENF --> TOK
    GOV --> TOK
    TOK <--> HKS
    HKS --> ATT
    HKS --> EXT
    IDP -. feeds .-> HKS
    REG -. referenced by .-> TOK
    TOK -. metadataHash/uri .-> META
    TOK -. events .-> IDX
    WAL <--> TOK
mermaid
flowchart TB
    subgraph L0["Layer 0 · ERC-1155 · ERC-165 · IERC7943MultiToken"]
        E1[balances, approvals, batch transfers]
        E2[freeze · forcedTransfer · canSend/canReceive · canTransfer]
    end
    subgraph L1["Layer 1 · IARexBatch"]
        B1[Batch record]
        B2[status · metadata]
        B3[transform · parentsOf]
    end
    subgraph L2["Layer 2 · IARexHook · IARexHookManager"]
        H1[ordered pipeline]
        H2[check → code · onExecuted · eligibility]
    end
    subgraph L3["Layer 3 · IARexAttest"]
        A1[attest / revoke / isAttested]
        A2[trusted issuers per topic]
    end
    subgraph REF["Reference implementation"]
        T[ARexToken]
        AT[ARexAttestations]
        HK[Eligibility · Expiry · Attestation · Perishability · Seasonal · Delivery · Traceability · Legacy]
        EX[CommodityPriceOracle · CarbonImmobilizationWrapper · ParametricInsurance]
    end
    L0 --> T
    L1 --> T
    L2 --> T
    L3 --> AT
    T --> HK
    HK --> AT
    HK --> EX
mermaid
classDiagram
    class ARexToken {
      +createBatch()
      +transform()
      +setBatchStatus()
      +setFrozenTokens()
      +forcedTransfer()
      +registerHook()
      +transferCheck()
      -_update()
    }
    class ARexAttestations {
      +attest()
      +revokeAttestation()
      +isAttested()
      +setTrustedIssuer()
    }
    class IARexHook {
      <<interface>>
      +hookFlags()
      +check()
      +onExecuted()
      +canSend()
      +canReceive()
    }
    class EligibilityHook
    class ExpiryHook
    class AttestationHook
    class PerishabilityHook
    class SeasonalHook
    class DeliveryHook
    class TraceabilityHook
    class CommodityPriceOracle
    class CarbonImmobilizationWrapper
    class ParametricInsurance
    ARexToken --> "0..n" IARexHook : ordered pipeline
    IARexHook <|.. EligibilityHook
    IARexHook <|.. ExpiryHook
    IARexHook <|.. AttestationHook
    IARexHook <|.. PerishabilityHook
    IARexHook <|.. SeasonalHook
    IARexHook <|.. DeliveryHook
    IARexHook <|.. TraceabilityHook
    AttestationHook --> ARexAttestations : isAttested
    ParametricInsurance --> ARexAttestations : isAttested
    CarbonImmobilizationWrapper --> ARexAttestations : attest
    ARexAttestations --> ARexToken : batchExists
mermaid
erDiagram
    BATCH ||--o{ BATCH : "parentsOf"
    BATCH ||--o{ ATTESTATION : "topic"
    BATCH ||--o{ DELIVERY : "batchId"
    BATCH ||--o{ TRACE_EVENT : "id"
    BATCH ||--o{ CARBON_LINK : "batchId"
    BATCH ||--o{ POLICY : "batchId"
    ACCOUNT ||--o{ BALANCE : "id"
    ACCOUNT ||--o{ FROZEN : "id"
    BATCH {
        uint256 id
        address issuer
        uint64 createdAt
        uint8 status
        bytes32 commodity
        bytes32 unit
        uint64 producedAt
        uint64 expiresAt
        bytes32 originRef
        bytes32 metadataHash
        string uri
    }
    ATTESTATION {
        bytes32 topic
        address issuer
        bytes32 ref
        uint64 issuedAt
        uint64 expiresAt
        bool revoked
    }
    DELIVERY {
        uint256 deliveryId
        address sender
        address receiver
        address carrier
        uint256 amount
        uint8 status
        bool breach
    }
    TRACE_EVENT {
        uint64 eventTime
        bytes32 bizStep
        bytes32 disposition
        bytes32 readPoint
        bytes32 bizLocation
        uint256 quantity
    }
mermaid
sequenceDiagram
    participant H as Holder
    participant T as ARexToken
    participant K1 as Hook 1 (CHECK)
    participant K2 as Hook 2 (CHECK, EXECUTED)
    H->>T: safeTransferFrom(from, to, id, amount, data)
    T->>T: lock, op = TRANSFER, paused?, canSend(from)/canReceive(to)
    T->>T: batch exists? not retired? amount ≤ balance − frozen?
    T->>K1: check(op, operator, from, to, id, amount, data)
    K1-->>T: 0
    T->>K2: check(...)
    K2-->>T: 0
    T->>T: balances updated, supply tracked
    T->>K2: onExecuted(...)
    T->>T: unlock
    T-->>H: TransferSingle
mermaid
sequenceDiagram
    participant M as Mill (TRANSFORMER_ROLE, approved)
    participant T as ARexToken
    participant K as Hooks
    M->>T: transform(farmer, mill, [1], [1000], [flour], [750], processRef)
    T->>T: approval? rebatch or role?, op = TRANSFORM, opData = abi.encode(processRef)
    T->>K: check(TRANSFORM, ..., from=farmer, to=0, id=1, 1000)
    T->>T: burn 1000 of #1
    T->>T: store batch #2 (parents=[1]), BatchCreated
    T->>K: check(TRANSFORM, ..., from=0, to=mill, id=2, 750)
    T->>T: mint 750 of #2
    T->>K: onExecuted(...) per leg
    T-->>M: BatchTransformed([1],[1000],[2],[750],processRef)
mermaid
sequenceDiagram
    participant E as Enforcer
    participant T as ARexToken
    participant K as Hooks
    E->>T: forcedTransfer(holder, custodian, id, amount)
    T->>T: role, balance ≥ amount, frozen := min(frozen, balance − amount) → Frozen
    T->>T: op = FORCED_TRANSFER (pause and eligibility bypassed)
    T->>K: check(FORCED_TRANSFER, ...)
    K-->>T: 0 (reference hooks allow)
    T->>T: balances, onExecuted
    T-->>E: ForcedTransfer
mermaid
sequenceDiagram
    participant S as Sender
    participant D as DeliveryHook
    participant C as Carrier
    participant R as Receiver
    participant T as ARexToken
    S->>D: schedule(token, id, receiver, carrier, amount, ...) → lock amount
    C->>D: pickUp, markInTransit, recordReading
    R->>D: confirmDelivered
    S->>T: safeTransferFrom(S, R, id, amount, abi.encode(deliveryId))
    T->>D: check → OK (delivery DELIVERED, parties/amount match)
    T->>D: onExecuted → SETTLED, unlock
mermaid
flowchart LR
    subgraph Chain["EVM chain (L2 public or permissioned)"]
        P[Proxy] --> I[ARexToken impl]
        P --> HK[Hooks]
        P --> AT[Attestations]
        HK --> EX[Extensions]
    end
    subgraph OffChain["Off-chain"]
        API[Origination / ERP service] -->|ISSUER, STATUS| P
        IDX[Indexer] -->|events| DB[(traceability DB / EPCIS)]
        META[(Metadata store)]
        VAULT[(Restricted data)]
        SCR[Screening provider] --> HK
    end
    Chain -. events .-> IDX
    P -. uri/hash .-> META
    META -. pointer .-> VAULT