Architecture

Trust boundaries

The two Sway contracts are authoritative for positions, custody liabilities, listings, settlement, and permissions. Cloudflare services are query and quote infrastructure; they cannot create positions or change contract state without a signed Fuel transaction. Vault and BondMarket remain the only production contracts. The separate test-assets faucet is testnet-only and mints valueless assets directly to connected wallets.

Data flow

1. The Vault and BondMarket emit complete events with monotonic position/order IDs.
2. The API Worker queries finalized receipts from Envio HyperFuel every minute. Empty ranges advance only the cursor; projection and R2 writes run only when log receipts are present.
3. Each Envio page containing logs is written immutably to compressed R2.
4. ABI-decoded events are reduced idempotently into D1 by transaction and receipt ID.
5. D1 retains active/latest positions, orders, bounded activity, cursors, and reconciliation metadata.
6. Global statistics, marketplace discovery, and history are served from D1.
7. Connected account views call Vault::position_count and Vault::get_position directly, then match position NFT asset IDs against the wallet's live UTXOs.
8. Indexed account rows are merged only to retain escrowed listings, unbonding positions, claims, and history when the NFT is no longer in the wallet.
9. Fuel RPC/GraphQL reconciliation is required before the index is marked healthy.

Direct native NFT transfers that bypass the Vault transfer method are valid, so wallet UTXOs—not the indexed owner field—are authoritative for held positions.

Oracle

The Oracle Worker reads O2 PriceUpdated events through Envio HyperFuel using a bounded 120-block window ending ten blocks behind the reported height. It validates nine collateral decimals, nonzero and ordered bid/ask values, a maximum age of 60 seconds, no more than 30 seconds of future clock skew, and a maximum 200 bp spread. It uses the conservative bid and floors O2's 18-decimal value to the Vault's six-decimal price format.

HyperFuel 429 and server failures are retried three times. Validated source prices refresh after 15 seconds and remain available as stale-if-error only while the O2 observation itself is within the 60-second safety window. Signed quotes are never cached and are bound to:

network domain | vault contract | asset | price | issued | expiry | nonce

The signer key is a Worker secret. Quotes expire after 120 seconds and nonces are one-use on-chain. O2 source asset IDs never become Vault collateral IDs:

• Testnet source: O2 fFUEL 0x43eebd58e837c2e8fa94f1b2db1268175c551b5b1bf41a59fafc4f2c69ab7dc2 maps at the same per-unit rate to Fuel Earn tFUEL 0x375178f2c1ef7f63524e6693c5ef44a0738a787ca6a392e08ccd021d9ce5bcd2 and tstFUEL 0x3a48ed1a9fcbff66ea96c87491922e183332cbfe8ec6ffb42c6b2427ba6f92d7. O2's canonical testnet FUEL market currently has no published feed value.
• Mainnet source: native FUEL 0x27821a5432b60fb3e70c64d0a612c2c86218c1088dd0f0f1b0dd6ae5ae17bd5b.

Testnet FUEL and stFUEL quotes use exactly the same O2 FUEL price; each quote is still bound to its distinct collateral asset ID. This is an explicit testnet 1:1 simulation, not an independent stFUEL price. Mainnet stFUEL remains disabled until an authoritative rate is approved. Mainnet price reads support local verification, but mainnet quote signing and transactions remain disabled.

Storage

R2 stores complete compressed source evidence. D1 stores bounded current state. No unbounded raw receipts or decoded history belong in D1.