Docs Técnicas

Operational Interoperability

Operational interoperability lets external systems use TREA contracts without turning contracts into HTTP clients. The chain exposes a plug; external systems present signed envelopes and signed transactions.

O conteúdo abaixo vem das fontes técnicas do repositório e é prerenderizado no site para leitura direta por pessoas, crawlers e agentes.

text

external system
  -> canonical envelope
  -> authenticated transport
  -> chain-aware gateway / acquirer / validator client
  -> trea simulate
  -> trea call / signed transaction
  -> contract receipt
  -> signed callback / audit trail

The contract never calls out to a POS, validator, acquirer, ERP, or bank API during consensus.

Envelope Families

| Envelope | Domain | Use | |----------|--------|-----| | PaymentIntentV1 | PAYMENT_INTENT_V1\0 | Card authorization consumed by spending vaults | | KycShareGrant | atlas-kyc-grant-v1 | Wallet-authorized private KYC disclosure | | ExternalAttestationV1 | ATLAS_TREA_EXTERNAL_ATTESTATION_V1 | External issuer attestation without storing evidence | | ContractCallbackV1 | ATLAS_TREA_CALLBACK_V1 | Node-signed callback derived from a receipt |

Envelopes are versioned, domain-separated, nonce-bound where appropriate, and time-limited. Raw PII, card secrets, and bank documents stay off-chain.

Card / POS / Acquirer Flow

text

card-sim / JavaCard -> signs PaymentIntentV1
POS                 -> forwards to acquirer
acquirer            -> POST /api/interop/payment-intent/verify
acquirer            -> POST /api/contracts/{vault}/simulate
acquirer            -> submits signed TREA transaction
acquirer            -> reads receipt
acquirer            -> POST /api/interop/callback/{tx_id}
POS                 -> approved / declined

The first verification step is optional if the acquirer verifies the same canonical bytes locally. Simulation is strongly recommended because it catches business rejections such as insufficient balance, replayed nonce, wrong asset, merchant block, or daily limit before submitting the transaction.

Chain-Side Endpoints

| Endpoint | Purpose | |----------|---------| | POST /api/interop/payment-intent/verify | Verify PaymentIntentV1 using the same logic as spending.verify_intent | | POST /api/interop/attestation/verify | Verify ExternalAttestationV1 signature and expiration | | POST /api/interop/callback/{tx_id} | Build a node-signed ContractCallbackV1 from a committed receipt | | POST /api/kyc/grant/redeem | Redeem a wallet-signed KYC grant privately with the validator |

Callbacks are derivative. The receipt remains the source of truth.

Repo Boundary

AtlasDB owns the chain-side plug: canonical bytes, verification endpoints, receipts, callbacks, and TREA contracts. Card applets, POS simulators, acquirer services, SDK packages, and JavaCard vectors can live in separate product repos as long as they target the documented endpoints.