External Infrastructure Quickstart

This path is for oracle networks, gateways, custodians, indexers, payment processors, and other infrastructure that needs to connect to AtlasDB without executing network I/O inside a TREA contract.

Outcome: discover the chain, authenticate a request, simulate it, submit a signed transaction, and consume a persisted receipt.

Integration Boundary

external system
  -> canonical, domain-separated message
  -> signature verification / chain-aware gateway
  -> simulation
  -> signed AtlasDB transaction
  -> consensus and ledger validation
  -> persisted receipt / AEC state
  -> retry-safe external acknowledgement

TREA contracts do not call external APIs during consensus. External data enters through authenticated envelopes or signed transactions. Committed receipts and AEC state are the authoritative observation surfaces.

Obtain Network Parameters

The network operator must provide these values for each environment:

| Parameter | Required use | |-----------|--------------| | Chain ID | Domain separation and environment binding | | Node REST URL | Read, simulate, submit, and inspect | | Address format | Sender and contract identity validation | | Signature scheme | AtlasDB transactions use Ed25519 signing | | Signing context | Canonical bytes, nonce, and chain binding | | Finality policy | When an external workflow may act irreversibly | | Explorer URL | Human inspection and operational support | | Funding procedure | Fees or test funds when required |

Do not copy chain IDs, endpoints, or confirmation assumptions between local, testnet, and production environments. If any value is missing, stop before signing or submitting.

Five-Minute Local Flow

The repository dev chain provides a deterministic integration target. Start it in one shell:

cargo run -p atlas-dev-chain -- \
  --config crates/application/atlas-dev-chain/trea.dev.toml.example \
  --data-dir .atlas-dev-chain \
  dev

Inspect the environment from another shell:

cargo run -p atlas-dev-chain -- --json status
cargo run -p atlas-dev-chain -- --json accounts
curl -sS http://localhost:8545/health

Publish, deploy, and call the counter example from the TREA Dev Chain Runner. Each write returns a transaction hash and block receipt. Use that transaction hash for observation:

curl -sS http://localhost:8545/transactions/<tx_id>/receipt

The local runner proves the request/response flow. Production integrations must use the operator-provided network parameters and production signing policy.

Production Request Sequence

1. Read

Read chain status, account nonce, contract metadata, and any state required to construct the request. Never assume a cached nonce is still current.

2. Form And Authenticate

Build the canonical signing bytes for the exact transaction type and bind them to the configured chain context. Sign with the authorized Ed25519 identity. Keep private keys in the integration's normal secure signer or HSM boundary.

See REST Submission and Transaction Payload Reference for the wire payloads.

3. Simulate

Use POST /api/contracts/{contract_id}/simulate before a state-changing call. Simulation runs the contract and ledger checks without committing state, charging a fee, incrementing a nonce, or producing a receipt.

A successful simulation is advisory. State may change before submission, so the real transaction is validated again.

4. Submit

Submit the signed transaction through the node transaction endpoint described in REST Submission. Record the transaction ID, sender, nonce, contract, entrypoint, and submission time in the external system.

5. Observe And Finalize

Poll the transaction status and retrieve its persisted receipt. Apply the environment's finality policy before triggering an irreversible external action.

External integrations must use persisted receipts and AEC state as the source of truth. The contract event endpoint is a convenience and indexing surface; its in-memory log resets when a node restarts.

6. Retry Safely

Classify errors before retrying:

• transport failure: query by transaction ID before resubmitting;
• unknown submission result: reconcile status and receipt first;
• nonce conflict: refresh signing context and create a new transaction;
• deterministic contract or ledger rejection: do not retry unchanged input;
• temporary node unavailability: retry reads with bounded backoff and failover.

Never treat a simulation response or an in-memory event as proof of commit.

External Attestations And Callbacks

For data originating outside the chain, use a versioned, domain-separated envelope such as ExternalAttestationV1. Verify the envelope at the gateway, simulate the target call, submit the signed transaction, and derive any callback from the committed receipt.

ContractCallbackV1 is a node-signed convenience derived from a receipt. The receipt remains authoritative. See Operational Interoperability for the supported envelope families and verification endpoints.

Go-Live Checklist

• Pin chain ID, REST endpoints, and expected address format per environment.
• Test canonical signing bytes and Ed25519 verification with shared vectors.
• Define nonce ownership when multiple workers share a signer.
• Document the finality and confirmation policy.
• Reconcile submitted transaction IDs against persisted receipts.
• Make callbacks and downstream actions idempotent.
• Use bounded retries, timeouts, health checks, and endpoint failover.
• Monitor receipt lag, rejection codes, nonce conflicts, and node availability.
• Exercise node restart and event-log loss without losing integration state.
• Keep secrets, raw PII, and external evidence off-chain unless explicitly required.