Visão Geral da Solução

Três níveis, um único sentido de dependência

O A-REX separa o que deve ser padronizado do que precisa apenas funcionar:

As quatro camadas do padrão

flowchart TB
    L3["Camada 3 · IARexAttest<br/>attest · revokeAttestation · isAttested · emissores confiáveis por tópico"]
    L2["Camada 2 · IARexHook + IARexHookManager<br/>hookFlags · check → bytes32 · onExecuted · getHooks"]
    L1["Camada 1 · IARexBatch<br/>createBatch · batchOf · setBatchStatus · setBatchMetadata · transform · parentsOf"]
    L0["Camada 0 · ERC-1155 + ERC-165 + IERC7943MultiToken<br/>freeze · forcedTransfer · canSend · canReceive · canTransfer"]
    L3 --- L2 --- L1 --- L0
    classDef l3 fill:#edf5ff,stroke:#0f62fe,color:#161616
    classDef l2 fill:#d0e2ff,stroke:#0f62fe,color:#161616
    classDef l1 fill:#a6c8ff,stroke:#0f62fe,color:#161616
    classDef l0 fill:#78a9ff,stroke:#0043ce,color:#161616
    class L3 l3
    class L2 l2
    class L1 l1
    class L0 l0

Os dois níveis do repositório e o sentido da dependência

flowchart LR
    STD["<b>O padrão</b><br/>standard/ · contracts/standard/<br/>normativo · CC0"]
    REF["<b>Implementação de referência</b><br/>ARexToken · ARexAttestations<br/>MIT"]
    DEMO["<b>Demonstrações</b><br/>7 hooks · 3 extensões<br/>MIT · não normativo"]
    STD -->|implementado por| REF -->|demonstrado por| DEMO
    DEMO -.->|dependem apenas das interfaces| STD

O padrão nunca depende da referência; o token nunca depende dos hooks. Remova todos os hooks e todas as extensões e ainda existirá um token conforme. Essa é a propriedade que permite a um terceiro implementar o A-REX sem adotar nada deste repositório além de seis arquivos de interface.

O que é um lote

Um lote é um identificador de token ERC-1155 com um registro:

struct Batch {
    address issuer;        // who created it (or performed the transformation)
    uint64  createdAt;
    uint8   status;        // 0 ACTIVE · 255 RETIRED (terminal) · 1..254 issuer-defined
    bytes32 commodity;     // keccak256("HS:100199"), keccak256("FAO:0111"), keccak256("GTIN:0779…")
    bytes32 unit;          // UN/CEFACT Rec. 20: "KGM", "TNE", "LTR", "BX"
    uint64  producedAt;    // 0 = not yet produced (pre-harvest)
    uint64  expiresAt;     // 0 = none
    bytes32 originRef;     // hash / reference to origin evidence — never coordinates
    bytes32 metadataHash;  // keccak256 of the off-chain document
    string  uri;           // where the document is
}

Tudo o que é mais rico — classificação, umidade, proteína, embalagem, identificadores GS1, o código de lote de rastreabilidade, a referência da declaração do EUDR, laudos de laboratório, a tabela de status do emissor — fica no documento de metadados cujo hash é registrado on-chain. O documento segue um JSON Schema publicado, alinhado ao EPCIS 2.0 e aos elementos-chave de dados da FSMA 204.

O pipeline de transferência

Toda mudança de saldo — cunhagem, transferência, queima, transferência forçada, transformação — passa por um único ponto de passagem obrigatória no token de referência. A ordem é fixa e auditável:

flowchart TD
    A[safeTransferFrom / createBatch / burn / forcedTransfer / transform] --> B["trava de reentrância"]
    B --> C{"pausado?"}
    C -- sim, não forçada --> X1[EnforcedPause]
    C -- não --> D{"canSend (from) / canReceive (to)<br/>conjunção dos hooks ELIGIBILITY"}
    D -- falso --> X2[ERC7943CannotSend / CannotReceive]
    D -- verdadeiro --> E{"por id: existe? não baixado?<br/>quantidade ≤ saldo − congelado?"}
    E -- falha --> X3[ARexBatchNotFound / ARexBatchRetired /<br/>ERC7943InsufficientUnfrozenBalance]
    E -- ok --> F{"por id, por hook CHECK, em ordem:<br/>check → código"}
    F -- código ≠ 0 --> X4["ARexHookRejected(hook, code)"]
    F -- todos 0 --> G["saldos atualizados · oferta total contabilizada"]
    G --> H["por id, por hook EXECUTED: onExecuted"]
    H --> I["liberar trava"]

Duas funções view reproduzem a mesma lógica sem alterar o estado: canTransfer (booleano, como exige o ERC-7943) e transferCheck (o primeiro código de rejeição, para que uma interface possa dizer ao usuário por quê).

As transferências forçadas dispensam a pausa e as verificações de elegibilidade — o enforcement precisa funcionar quando todo o resto está congelado —, mas ainda executam os hooks com OP_FORCED_TRANSFER, de modo que um hook pode exigir, por exemplo, a referência de uma ordem judicial nos dados da transferência.

Linhagem

transform é a operação única para dividir, unir e processar:

graph LR
    W1["trigo #1<br/>250 t · produtor"] -- "transform (reagrupamento)" --> W2["trigo #2<br/>100 t · comprador A"]
    W1 -- "transform (reagrupamento)" --> W3["trigo #3<br/>150 t · comprador B"]
    W2 -- "transform (processamento, TRANSFORMER_ROLE)" --> F4["farinha #4<br/>75 t · moinho"]

• O reagrupamento (mesma commodity, mesma unidade, quantidade conservada) está aberto a qualquer titular ou operador aprovado: uma cooperativa dividindo um lote de silo entre os associados, um exportador unindo entregas.
• O processamento (qualquer outro caso) exige, adicionalmente, TRANSFORMER_ROLE.
• parentsOf(4) == [2], parentsOf(2) == [1]; um evento BatchTransformed por operação, o que equivale, por construção, a um TransformationEvent do EPCIS.

Enforcement

ENFORCER_ROLE pode congelar qualquer quantidade de qualquer conta (setFrozenTokens, podendo exceder o saldo, conforme especifica o ERC-7943) e mover tokens sem o consentimento do titular (forcedTransfer). É isso que torna um token de lote utilizável fora de uma demonstração: um financiador executando um warrant, um tribunal determinando a apreensão de grãos armazenados, um armazém recuperando um lote depois que um cliente perde as chaves. Toda ação de enforcement é um evento.

Hooks

Um hook é um contrato com cinco funções e um bitmap constante de flags. O token armazena as flags em cache no momento do registro, de modo que uma transferência custa uma chamada externa por hook interessado, e não uma sondagem de interface por capacidade por módulo. Um hook descobre qual token o está chamando por msg.sender; uma única implantação pode atender a muitos tokens.

Os hooks de referência demonstram as três capacidades:

Extensões complementares (não são hooks): CommodityPriceOracle, CarbonImmobilizationWrapper, ParametricInsurance.

Atestações

Um contrato complementar registra (batch, topic) → (issuer, reference, validity). Somente emissores confiáveis para um tópico podem atestar; a revogação, a expiração e a perda de confiança tornam isAttested falso. Os tópicos são bytes32, de modo que tópicos de declaração do ERC-735, identificadores de esquema do Ethereum Attestation Service e hashes de nomes de certificação funcionam sem uma tabela no padrão.

Atores e papéis

Nada no padrão fixa esses papéis; eles são a forma como a implementação de referência exercita os requisitos DEVE ("restrito a um papel autorizado").

Formas de implantação

• L2 pública (Polygon, Arbitrum, Base, Optimism): a mais barata e a mais componível; adequada à negociação e ao financiamento de commodities em que as contrapartes são empresas.
• Rede EVM permissionada: quando as autoridades de proteção de dados ou a instituição âncora a exigirem; o EDPB incentiva expressamente projetos permissionados. O padrão é agnóstico quanto à blockchain.
• Híbrida: lotes em uma rede pública, dados restritos (polígonos de parcelas, identidade do produtor) em armazenamento com controle de acesso, referenciado a partir dos metadados.

A pilha de referência é implantada com um único módulo do Ignition ou um único script: proxy do token, registro de atestações, hooks de elegibilidade e de validade.

Decisões de projeto e as alternativas que elas substituem