Visión general de la solución

Tres niveles, una sola dirección de dependencia

A-REX separa lo que hay que estandarizar de lo que basta con que funcione:

Las cuatro capas del estándar

flowchart TB
    L3["Capa 3 · IARexAttest<br/>atestaciones por lote y por tema"]
    L2["Capa 2 · IARexHook + IARexHookManager<br/>una sola cadena ordenada de reglas"]
    L1["Capa 1 · IARexBatch<br/>identidad, estado, hash de los metadatos y linaje"]
    L0["Capa 0 · ERC-1155 + ERC-165 + IERC7943MultiToken<br/>saldos y controles de cumplimiento"]
    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

Los dos niveles del repositorio y la dirección de la dependencia

flowchart LR
    STD["<b>El estándar</b><br/>standard/ · contracts/standard/<br/>normativo · CC0"]
    REF["<b>Implementación de referencia</b><br/>ARexToken · ARexAttestations<br/>MIT"]
    DEMO["<b>Demostraciones</b><br/>7 hooks · 3 extensiones<br/>MIT · no normativas"]
    STD -->|implementado por| REF -->|demostrado por| DEMO
    DEMO -.->|dependen solo de las interfaces| STD

El estándar nunca depende de la implementación de referencia, y el token nunca depende de las reglas externas (hooks). Si quitas todos los hooks y todas las extensiones, sigues teniendo un token conforme. Los terceros obtienen el texto normativo con el acceso anticipado, no a través de este capítulo público.

Qué es un lote

Un lote es un id de token ERC-1155. La estructura de sus campos se reserva para el texto normativo.

El resto de la información vive en un documento de metadatos cuyo hash queda registrado en la cadena: calidad, humedad, proteína, envase, identificadores GS1, código de lote de trazabilidad, referencia de la declaración EUDR, informes de laboratorio y la tabla de estados del emisor. El documento sigue un JSON Schema publicado, alineado con EPCIS 2.0 y con los elementos de datos clave de la FSMA 204.

Recorrido de una transferencia

Todo cambio de saldo pasa por un único punto de control en el token de referencia: acuñación, transferencia, quema, transferencia forzosa y transformación. El orden es fijo y se puede auditar:

flowchart TD
    A[safeTransferFrom / createBatch / burn / forcedTransfer / transform] --> B["bloqueo contra reentrada"]
    B --> C{"¿en pausa?"}
    C -- sí, no forzada --> X1[EnforcedPause]
    C -- no --> D{"canSend from / canReceive to<br/>deben aprobar todos los hooks ELIGIBILITY"}
    D -- false --> X2[ERC7943CannotSend / CannotReceive]
    D -- true --> E{"por id: ¿existe? ¿no está retirado?<br/>¿cantidad ≤ saldo − congelado?"}
    E -- falla --> X3[ARexBatchNotFound / ARexBatchRetired /<br/>ERC7943InsufficientUnfrozenBalance]
    E -- correcto --> F{"por id, cada hook CHECK en orden:<br/>check → código"}
    F -- código ≠ 0 --> X4["ARexHookRejected(hook, code)"]
    F -- todos 0 --> G["se actualizan los saldos · se registra la emisión total"]
    G --> H["por id, cada hook EXECUTED: onExecuted"]
    H --> I["desbloqueo"]

Dos vistas reproducen la misma lógica sin modificar el estado. canTransfer devuelve un booleano, como exige ERC-7943. transferCheck devuelve el primer código de rechazo, para que una interfaz pueda explicarle al usuario por qué no se permite la operación.

Las transferencias forzosas se saltan la pausa y las comprobaciones de habilitación, porque los controles de cumplimiento tienen que funcionar aunque todo lo demás esté congelado. Aun así, pasan por los hooks con OP_FORCED_TRANSFER. Así, un hook puede exigir, por ejemplo, la referencia a una orden judicial en los datos de la transferencia.

Linaje

transform es la única operación para dividir, fusionar y procesar lotes:

graph LR
    W1["trigo #1<br/>250 t · agricultor"] -- "transform (reagrupación)" --> W2["trigo #2<br/>100 t · comprador A"]
    W1 -- "transform (reagrupación)" --> W3["trigo #3<br/>150 t · comprador B"]
    W2 -- "transform (procesamiento, TRANSFORMER_ROLE)" --> F4["harina #4<br/>75 t · molino"]

• La reagrupación (mismo producto, misma unidad, cantidad conservada) está abierta a cualquier titular u operador aprobado. Por ejemplo, una cooperativa que reparte un lote de silo entre sus socios o un exportador que fusiona varias entregas.
• El procesamiento (cualquier otro caso) requiere además TRANSFORMER_ROLE.
• parentsOf(4) == [2], parentsOf(2) == [1]. Cada operación emite un solo evento BatchTransformed, que por diseño equivale a un TransformationEvent de EPCIS.

Controles de cumplimiento

ENFORCER_ROLE puede congelar cualquier cantidad en cualquier cuenta con setFrozenTokens, incluso por encima del saldo, como especifica ERC-7943. También puede mover tokens sin el consentimiento del titular con forcedTransfer. Esto es lo que hace que un token de lote sirva fuera de una demostración: un prestamista que ejecuta un warrant, un tribunal que ordena embargar grano almacenado o un almacén que recupera un lote cuando un cliente pierde sus claves. Cada medida de cumplimiento queda registrada como un evento.

Hooks

Un hook es un contrato con cinco funciones y un mapa de bits constante de indicadores (flags). El token guarda esos indicadores en caché al registrar el hook. Así, una transferencia cuesta una llamada externa por cada hook interesado, y no una consulta de interfaz por cada capacidad de cada módulo. El hook sabe qué token lo llama gracias a msg.sender, de modo que un solo despliegue puede servir a muchos tokens.

Los hooks de referencia muestran las tres capacidades:

Extensiones complementarias (no son hooks): CommodityPriceOracle, CarbonImmobilizationWrapper, ParametricInsurance.

Atestaciones

Un contrato complementario registra atestaciones (certificados o constancias verificables) con la forma (batch, topic) → (issuer, reference, validity). Solo los emisores de confianza para un tema pueden emitirlas. La revocación, el vencimiento o la pérdida de confianza hacen que isAttested devuelva falso. Como los temas son bytes32, el estándar no necesita una tabla: sirven igual los temas de claims de ERC-735, los ids de esquema de Ethereum Attestation Service y los hashes de nombres de certificaciones.

Actores y roles

El estándar no fija estos roles. Son la forma en que la implementación de referencia cumple los requisitos obligatorios (MUST), como «restringido a un rol autorizado».

Opciones de despliegue

• L2 pública (Polygon, Arbitrum, Base, Optimism): la opción más barata y la que mejor se integra con otros protocolos. Encaja con el comercio y la financiación de commodities cuando las contrapartes son empresas.
• Cadena EVM con permisos: para cuando lo exigen las autoridades de protección de datos o la institución ancla. El EDPB recomienda expresamente los diseños con permisos. El estándar funciona en cualquier cadena.
• Híbrida: los lotes van en una cadena pública y los datos restringidos (polígonos de parcelas, identidad del productor) quedan en un almacenamiento con control de acceso, referenciado desde los metadatos.

La pila de referencia se despliega con un solo módulo de Ignition o un solo script: proxy del token, registro de atestaciones y hooks de habilitación y de vencimiento.

Decisiones de diseño y alternativas descartadas