XChain Platform Action - ATTEST
This action covers the external-data attestation lifecycle. A request is v0 (VM-emitted). Below a network’s response-mirror activation height, the answer is v1, a validator-broadcast transaction. At or above that height, a finalized response does not arrive as its own on-chain transaction: it is agreed by the validator network and delivered to every indexer through the hub, and only shows up on chain afterward, batched together with other responses, as v5 (batch head) and v6 (batch continuation). See Response delivery, below, for how the two paths work and which one a given request uses. Two more versions round out the lifecycle: v2 (system-synthesized expiry) and the cross-chain relay legs v3 (a request materialized onto BTC) and v4 (the response relayed back to the origin chain).
All attestation capability stake lives on BTC, so a request emitted by an LTC or DOGE contract has no responsible set where it landed and cannot be fulfilled there. v3 materializes such a request onto BTC, giving it a real BTC block_index; from that point the ordinary v0/v1 machinery services it. v4 carries the outcome back so the origin chain fires the contract callback. Both legs are gated (see the Formats section) and inert until then.
PARAMS
| Name | Type | Description |
|---|---|---|
VERSION |
Integer | Format version (0=request, 1=response, 2=expire, 3=relay request, 4=relay response, 5=batch head, 6=batch continuation) |
ORIGIN_CHAIN |
String | Chain a relayed request was emitted on (LTC or DOGE); v3 only |
ORIGIN_ACTION_INDEX |
Integer | The origin chain’s v0 action_index: the relay correlation key, and together with ORIGIN_CHAIN the exactly-once relay identity on BTC; v3 only |
HOME_RESPONSE_ACTION_INDEX |
Integer | The BTC v1 action_index whose outcome is being relayed; v4 only |
SNAPSHOT_BLOCK |
Integer | BTC-anchored block the cross_chain signer set is pinned at, and the plane both relay gates resolve on; v3 and v4 |
REQUEST_ID |
String | 64-hex SHA-256 over tx_hash:root_action_index:emitter_path:contract_index:emitter_position (colon-delimited) |
PROVIDER_ID |
String | Governance-registered provider (http_get, llm, etc.); present in v0 and v1 |
REQUEST_PAYLOAD |
String | Provider-specific payload (URL for http_get, JSON envelope for llm); v0 only |
CALLBACK_METHOD |
String | Contract method to invoke on response (max 64 chars); v0 only |
CALLBACK_PARAMS |
String | JSON array of developer-supplied params echoed back to the callback; v0 only |
REDUNDANCY |
Integer | Required validator signatures (1, 3, or 5); v0 only |
DEADLINE_BLOCKS |
Integer | Blocks until the request auto-expires (capped by provider’s deadline_window_blocks); v0 only |
FEE_TICK |
String | (optional) Tick the attestation fee is paid in; only XCHAIN accepted; v0 only |
FEE_AMOUNT |
String | (optional) Attestation fee, precision no finer than the GAS tick’s own decimals; v0 only |
RESPONSE_PAYLOAD |
String | Response body (base64-encoded on the wire, decoded to UTF-8 for storage and callback); v1 only |
STATUS |
String | ok, timeout, no_quorum, provider_error, or expired; v1 only |
META |
String | Provider-defined metadata (HTTP status code for http_get; model ID for llm); v1 only |
SIG_COUNT |
Integer | Number of (pubkey, sig) pairs that follow; v1 only |
PUBKEY_n |
String | 64-hex Ed25519 pubkey, qualified for attestation at the request block; v1 only |
SIG_n |
String | 128-hex Ed25519 signature over the canonical message; v1 only |
BATCH_KEY |
String | 64-hex SHA-256 over ATTESTBATCH:NETWORK:WINDOW_START:WINDOW_END (colon-delimited); the batch’s own identifier, and the key a v6 wire cites to find its head; v5 and v6 |
WINDOW_START |
Integer | Start of the batch’s time window, unix seconds; v5 only |
WINDOW_END |
Integer | End of the batch’s time window, unix seconds; v5 only |
ROW_COUNT |
Integer | Number of responses carried in the batch; 0 remains valid if an empty v5 head lands; v5 only |
BTC_BLOCK_HEIGHT |
Integer | BTC block height the batch’s validator signer set is checked against; v5 only |
BATCH_CRC32 |
String | 8-hex CRC32 checksum of the batch’s uncompressed contents, checked after reassembly; v5 and v6 |
TOTAL_CHUNKS |
Integer | Total number of wires (the head plus its continuations) the batch is split across; v5 and v6 |
BODY_B64 |
String | Base64 of the batch’s compressed contents, or the head’s share of them when the batch continues into v6 wires; v5 only |
CHUNK_INDEX |
Integer | This continuation’s position among the batch’s wires (the head is position 0); v6 only |
BODY_B64_CHUNK |
String | Base64 continuation of the compressed contents begun in the head; v6 only |
Formats
Version 0 - Request (VM-emitted)
ATTEST|0|REQUEST_ID|PROVIDER_ID|REQUEST_PAYLOAD|CALLBACK_METHOD|CALLBACK_PARAMS|REDUNDANCY|DEADLINE_BLOCKS[|FEE_TICK|FEE_AMOUNT]
The trailing FEE_TICK|FEE_AMOUNT pair is optional. A feeless request omits them entirely (the SDK serializer trims trailing empties), so feeless v0 wire strings are byte-identical to the pre-fee format with no migration needed.
Version 1 - Response (validator-broadcast, variable-length signature list)
ATTEST|1|REQUEST_ID|PROVIDER_ID|RESPONSE_PAYLOAD|STATUS|META|SIG_COUNT|PUBKEY1|SIG1|PUBKEY2|SIG2|...
Version 2 - Expire (system-synthesized; never user-broadcast)
ATTEST|2|REQUEST_ID
Version 3 - Relay request (cross-chain, BTC only, flag-day gated)
ATTEST|3|REQUEST_ID|ORIGIN_CHAIN|ORIGIN_ACTION_INDEX|PROVIDER_ID|REQUEST_PAYLOAD|REDUNDANCY|DEADLINE_BLOCKS|SNAPSHOT_BLOCK|SIG_COUNT|PUBKEY1|SIG1|...
Version 4 - Relay response (cross-chain, origin chain only, flag-day gated)
ATTEST|4|REQUEST_ID|HOME_RESPONSE_ACTION_INDEX|RESPONSE_PAYLOAD|STATUS|META|SNAPSHOT_BLOCK|SIG_COUNT|PUBKEY1|SIG1|...
Both relay versions activate at ATTEST_RELAY_ACTIVATION (BTC 963000 on mainnet, genesis on testnet and regtest). Below the height they are rejected as an unknown VERSION and persist nothing. Every indexer and hub must be deployed before that height.
Version 5 - Batch head (system-published, Dogecoin only)
ATTEST|5|BATCH_KEY|NETWORK|WINDOW_START|WINDOW_END|ROW_COUNT|BTC_BLOCK_HEIGHT|BATCH_CRC32|TOTAL_CHUNKS|BODY_B64
Version 6 - Batch continuation (system-published, Dogecoin only)
ATTEST|6|BATCH_KEY|CHUNK_INDEX|TOTAL_CHUNKS|BATCH_CRC32|BODY_B64_CHUNK
The publisher considers each closed wall-clock hour on Dogecoin. A window with no finalized responses publishes nothing, while a window with responses lands one batch: a v5 head plus as many v6 continuations as it needs to carry every response finalized in that hour. The wires are compressed and split so each fits inside a single action. A v5 head with ROW_COUNT=0 remains valid if one lands, which keeps the wire compatible with older publishers, but current publishers do not create one for a quiet window. A batch is capped at 256 responses and 1,048,576 bytes (1 MiB) of uncompressed content; a window that would need more than that is refused outright, loudly, rather than silently dropped or truncated.
Examples
ATTEST|0|abc...def|http_get|https://example.com/v1/score/42|handleResponse|["ctx-42"]|1|10
VM-emitted request for an off-chain HTTP GET, single-validator redundancy, 10-block deadline, feeless
ATTEST|0|abc...def|http_get|https://example.com/v1/score/42|handleResponse|["ctx-42"]|1|10|XCHAIN|0.5
Same request carrying a 0.5 XCHAIN attestation fee (escrowed from FEE_PAYER at request time)
ATTEST|1|abc...def|http_get|{"score":7}|ok|200|1|a1b2...|c3d4...
Validator-broadcast response with one Ed25519 signature
ATTEST|2|abc...def
System-synthesized expiry for request abc...def
Rules
Version 0 (request)
- VM emission only; the
IS_EMISSIONflag must be set byexecute.processEmission. User-broadcast v0 is rejected. PROVIDER_IDmust be governance-registered (indexer validates against its provider registry).REDUNDANCYmust appear in the provider’sallowed_redundancylist.REQUEST_PAYLOADsize must be no larger than the provider’smax_request_bytes.DEADLINE_BLOCKSmust be greater than 0 and no larger than the provider’sdeadline_window_blocks.CONTRACT_INDEX(carried viaEMITTER) must reference an existing contract.REQUEST_IDis verified by re-deriving fromtx_hash:root_action_index:emitter_path:contract_index:emitter_position(colon-delimited; defends against compromised VM).- Admission flag-day (
ATTEST_ADMISSION_ACTIVATIONinprotocol/constants.js; mainnet 961000, testnet/regtest genesis): at/above the height, a request whose responsible set at its own block is smaller thanREDUNDANCY(e.g. after the stake-weighted-quorum source-dedupe) is rejected at admission, since the v1 path can never collectREDUNDANCYsignatures from a smaller set. Below the height the request is accepted and expires atDEADLINE_BLOCKunchanged (replay bit-identical). - Per-block admission caps (
ATTEST_REQUEST_CAPSinprotocol/constants.js; in force from genesis on every network, mainnet armed at0under the 2026-09-09 ruling on a history holding zero attestations): a block admits at mostperContract(2) requests from any one contract andperBlock(10) in total, counted over the admitted v0s earlier in the same block (action_indexorder, which is total, so every node counts the same prefix). An admitted request obligesREDUNDANCYvalidators to make a provider call the requester does not pay for, so the ceiling is what bounds validator spend; the per-contract share stops one contract taking the whole ceiling. Over-cap producesinvalid: ATTEST cap (…), which, being an emission validation failure, fails the whole enclosing EXECUTE: the over-cap request, the under-cap requests the same EXECUTE already emitted, and its state writes all roll back together. A contract that needs more than two attestations spaces them across blocks.
Responsible-set selection
The responsible set is the top REDUNDANCY validators ranked by SHA256(request_id || pubkey) ascending over the validators holding the attestation capability at the request’s block. At and above STAKE_WEIGHTED_QUORUM_ACTIVATION two further rules apply, in this order:
- Provider stake floor. Staking sources whose aggregate
attestationstake is below the request provider’smin_stake_xchainare dropped before ranking, so a freed slot goes to the next qualifying validator rather than shrinking the set. This is a higher, per-provider bar on top of theattestationcapabilityMIN_STAKE(1000 XCHAIN):http_getrequires 10000 andllmrequires 25000, because serving anllmattestation carries more trust and more upstream cost. The bar is on the staking SOURCE, not on each delegated key, so one 25000 stake qualifies all of that source’s keys and splitting 25000 across five keys qualifies none of them. Comparison is exact decimal and inclusive at the boundary. The floor is block-anchored (governance changes carry an activation block), so every hub and indexer resolves the same value for the same request; a node that cannot resolve a floor computes an EMPTY responsible set rather than assuming zero. - Source dedupe. Of the survivors, one slot per staking source (the source’s lowest-hash key), so a source that delegates N keys cannot occupy N responsible slots.
Below the activation neither rule applies and the legacy per-key ranking runs unchanged, so replay of pre-activation history is bit-identical. The canonical conformance vectors for the whole rule live in protocol/test-vectors/responsible_set.json.
Widening: how the served set can grow beyond REDUNDANCY
Independent of the two rules above, the set actually served can widen beyond the REDUNDANCY validators ranked above. At and above ATTEST_RESPONSIBLE_WIDENING_ACTIVATION, up to ATTEST_RESPONSIBLE_WIDENING.maxSlots (2) further validators are admitted as the request’s serviceable window elapses, one slot per equal segment of that window, starting ATTEST_RESPONSIBLE_WIDENING.confirmations (3) blocks after the request. At and above ATTEST_ZERO_CONF_ACTIVATION, keyed on the request’s own block, the ladder runs a second stage instead, ATTEST_RESPONSIBLE_WIDENING_V2: it starts at the request’s own block (startOffset 0, matching zero-confirmation service, below) and grants one extra slot immediately (headroom 1) rather than waiting for the first segment to elapse, so a set holding one member that can never sign still finalizes inside the first segment with no clock involved at all; maxSlots stays 2, so the served pool can still reach REDUNDANCY + 3 members in the worst case. A request whose deadline falls at or before the ladder’s own start is granted headroom outright rather than dividing a non-positive window.
Widening only ever changes who may additionally serve and earn a share of the fee (see Fee flow, below); it never changes the set a request is admitted against or the set charged for a missed round in per-validator accountability, which stays the unwidened, REDUNDANCY-ranked set throughout.
Fee fields (v0, optional)
FEE_TICK, when present, must equal the GAS tick (XCHAIN); any other value producesinvalid: FEE_TICK (only XCHAIN accepted). Arbitrary fee ticks are a post-launch rule loosening; the wire carries the tick now so no future format change is needed.FEE_AMOUNTmust parse to a precision no finer than the GAS tick’s own decimals; a finer value producesinvalid: FEE_AMOUNT (precision > N dp)where N =min(8, gasDecimals). The escrow/debit/credit ledger rows round to the tick’s decimals, so a finer fee would be charged rounded whileattests.fee_amountkept the unrounded string, desyncing the reward split from the escrow. The production XCHAIN genesis issuance is pinned to 8 decimals, so in production the cap is 8 dp; on a decimals-0 regtest GAS tick the cap is 0 (integer fees only). The VM gateway (xchain.attestation.request) additionally rejects values above 8 dp at emit time as an outer sanity bound.FEE_AMOUNT > 0requires a non-nullFEE_TICK; absent tick producesinvalid: FEE_TICK (required when FEE_AMOUNT > 0).FEE_PAYER(the contract address emitting the request) must hold at leastFEE_AMOUNTof the GAS tick; insufficient balance producesinvalid: insufficient funds (FEE_AMOUNT). As with any failed emission validation, this fails the whole enclosing EXECUTE.- A valid
FEE_AMOUNT > 0debitsFEE_PAYERand writes an escrow row at the v0action_index. Absent or zero value means feeless with no ledger movement.
Version 1 (response)
- Checked before anything else: if the request is at or above its network’s response-mirror activation height, an on-chain v1 is rejected outright with
invalid: ATTEST v1 after mirror activation. Such a request is answered only through the hub mirror (see Response delivery, below); a v1 transaction reaching the chain for it is stale or hostile. - Indexer rejects if
REQUEST_IDdoes not match apendingrow from a prior v0. PROVIDER_IDmust equal the request’s provider.- Indexer’s
BLOCK_INDEXmust be no greater than the request’sDEADLINE_BLOCK. - Each
PUBKEY_nis checked against theattestationcapability snapshot at the request’sblock_index(not the response’s; every hub must compute the same set). - Each
SIG_nmust Ed25519-verify against the canonical message underPUBKEY_n. - Valid signature count must be at least
REDUNDANCY(the request’sREDUNDANCYparameter). Sub-quorum responses are rejected and the request remains pending.
Version 2 (expire)
- Never user-broadcast:
VALID_ACTION_NAMESacceptsATTESTfor the decoder’s v0/v1 paths, but v2 is rejected if it appears in a user transaction. - Synthesized once per stale pending request: indexer queries
SELECT * FROM attests WHERE version=0 AND request_status='pending' AND deadline_block < <current_block>and synthesizes one v2 per row. REQUEST_IDmust match an existingpendingrow.
Version 3 (relay request, BTC only)
- Accepted only on BTC, and only at/above
ATTEST_RELAY_ACTIVATIONresolved on BOTH planes: this action’s own BTCblock_indexand theSNAPSHOT_BLOCKit carries. The landing height is what makes the leg inert before the flag day, since it cannot be forged the way a broadcaster-suppliedSNAPSHOT_BLOCKcan; the snapshot is the plane the hub resolves the same flag-day on, and the only one it has when it decides whether to co-sign, so gating on the landing height alone would accept a v3 the federation never produced and resolve its quorum against the pre-activation signer set. Below the height on either plane, and on any other chain, it is treated exactly as an unknown VERSION: nothing is persisted. ORIGIN_CHAINmust beLTCorDOGE.ORIGIN_ACTION_INDEXmust be a positive integer.SNAPSHOT_BLOCKmust not exceed this action’sblock_index, so a broadcaster cannot pin a future signer set.PROVIDER_ID,REDUNDANCY,REQUEST_PAYLOADsize and the derived deadline are validated exactly as for v0.REQUEST_IDmust not already exist on this chain; one request materializes once.- The relay identity
(ORIGIN_CHAIN, ORIGIN_ACTION_INDEX)must not already name a request on this chain; one origin request materializes once on BTC. This is a second, independent gate and is not implied by theREQUEST_IDrule above:REQUEST_IDis derived from the origin transaction’stx_hash, so an origin-chain reorg that re-emits the sameORIGIN_ACTION_INDEXfrom a different transaction yields a differentREQUEST_IDand clears that rule. A duplicate relay identity producesinvalid: ORIGIN_ACTION_INDEX (relay identity already materialized on this chain), an explicit stored verdict every node reaches identically, rather than a silent drop or a second BTC materialization that nothing on BTC can retract. - The signature list must meet the
cross_chainfederation quorum atSNAPSHOT_BLOCK: stake-weighted (source-deduped) at/aboveSTAKE_WEIGHTED_QUORUM_ACTIVATION, otherwise the legacymax(2f+1, ceil((N+1)/2))signer count. This is the same rule the XCALL dispatch leg applies. - The stored request row is feeless, carries no callback and no
contract_index(the contract is on the origin chain), and pins its responsible set at this action’s BTCblock_index. A v1 fulfilling it closes the request but fires no local callback.
Version 4 (relay response, origin chain only)
- Accepted only off BTC, and only at/above
ATTEST_RELAY_ACTIVATIONresolved on theSNAPSHOT_BLOCKthe action carries. The gate is deliberately NOT resolved on the localblock_index: a BTC-derived height is already exceeded by LTC and DOGE local heights, so gating there would activate the leg immediately. STATUSmust beokorexpired. The retryable statuses (no_quorum,timeout,provider_error) are refused, because the home chain may still fulfill the request.REQUEST_IDmust name apendingrequest on this chain whoseorigin_chainis this chain, i.e. one this chain admitted for relay. A native request cannot be closed by a v4.- The signature list must meet the same
cross_chainquorum as v3, over the relay-response canonical. - On acceptance the request goes
fulfilled(ok) orerrored(expired), its v0 fee escrow settles, and the contract callback is injected with the identical argument shape a locally serviced attestation produces.
Version 5 (batch head, Dogecoin only)
- Accepted only on Dogecoin; system-published only, never user-broadcast.
BATCH_KEYmust equal the SHA-256 ofATTESTBATCH:NETWORK:WINDOW_START:WINDOW_END; a head whose key does not match its own declared window is rejected.WINDOW_STARTmust not exceedWINDOW_END, andROW_COUNTmust not exceed 256.TOTAL_CHUNKSis the number of wires (this head plus its continuations) the batch is split across; once every continuation arrives, the reassembled and decompressed contents must decode to exactlyROW_COUNTresponses matching the header fields exactly, or the whole batch is invalid with no partial acceptance.- The Dogecoin indexer checks the batch’s own quorum signature, covering the whole window, against the validator capability snapshot at
BTC_BLOCK_HEIGHT; it does not separately re-check each carried response’s own signatures there. Those are checked, using the same rule a live response is checked against (see Canonical signing message, mirror era, below), once the responses reach Bitcoin, the chain that actually applies them, through the same delivery path a live response takes.
Version 6 (batch continuation, Dogecoin only)
- Accepted only on Dogecoin; system-published only, never user-broadcast.
- Belongs to the head sharing its
BATCH_KEY;CHUNK_INDEXnumbers its position among the batch’s wires (the head itself is position 0), andTOTAL_CHUNKSmust match the head’s. - A batch missing any of its declared continuations cannot be reassembled; it stays incomplete until the missing wire arrives, rather than being rejected outright.
Canonical signing messages (v3/v4)
The relay legs sign pipe-joined field lists, with free-form payloads folded in as SHA-256 digests so the signed bytes stay bounded:
ATTEST|RELAY_REQUEST|request_id|snapshot_block|network|origin_chain|origin_action_index|provider_id|sha256(request_payload)|redundancy|deadline_blocks
ATTEST|RELAY_RESPONSE|request_id|snapshot_block|network|origin_chain|home_response_action_index|provider_id|sha256(response_body)|status|meta
At/above EQUIV_HEADER_ACTIVATION (resolved on SNAPSHOT_BLOCK) each is wrapped in the uniform equivocation header with TAG=XATTEST and a phase-specific ROUND_ID, so the request and response legs of one request_id never share a round key.
Canonical signing message (v1)
Each SIG_n covers the canonical bytes:
request_id || provider_id || sha256(response_payload) || status || meta
Where sha256(response_payload) is the lowercase hex digest of the raw response bytes (after base64-decoding the wire field).
Canonical signing message (v1, mirror era)
At or above the response-mirror activation height, the signed message carries one more field, separated from the rest by a |: the effective time at which the response becomes bindable.
request_id || provider_id || sha256(response_payload) || status || meta | effective_time
The round’s leader proposes the effective time a short margin ahead of the moment of agreement; every other signer checks the proposed time against its own clock before it signs, so a leader proposing an implausible time simply fails to collect a valid quorum. Below the activation height the signed message is the five-field concatenation above with no separator and no effective time, unchanged. Because the two messages are built differently, a signature valid for one can never be mistaken for a signature under the other, so a request cannot be admitted under one era and answered under the other.
Lifecycle
- VM EXECUTE emits ATTEST v0; indexer stores a v0 row in the consolidated
atteststable (version=0) withrequest_status='pending'. - Validators staked for the
attestationcapability detect the request via the hub’sAttestationRoundpolling. - Top-
REDUNDANCYvalidators (deterministic leader sort bySHA-256(request_id || pubkey)) fetch via the provider and gossipATTEST_PROPOSE. - What happens next depends on the request’s own response-mirror activation height (see Response delivery, below). Below it, the leader publishes ATTEST v1 on-chain with
REDUNDANCYEd25519 signatures, paying the broadcast cost itself. At or above it, nobody broadcasts a transaction: the finalized response is written into the validator network’s shared database, passed on to every hub, and delivered to every indexer that way. - On a terminal response, whether it arrived as an on-chain v1 or through the mirror, the indexer flips the request to
fulfilled(STATUS=ok) orerrored(a genuinely terminal failure such asexpired) and injects a system EXECUTE invoking the callback. A retryable v1 (STATUSofno_quorum,timeout, orprovider_error) is recorded but leavesrequest_status='pending', so the responsible set can attempt another round before the deadline; no callback fires yet. - If
DEADLINE_BLOCKpasses while stillpending(no terminal v1, or only retryable rounds), the indexer’s per-block expiry pipeline synthesizes ATTEST v2 (flips status toexpired, fires the callback withstatus='expired').
sequenceDiagram
participant VM
participant Indexer
participant Validators
participant Leader
VM->>Indexer: ATTEST v0, request emitted
Note over Indexer: store v0 row, request_status=pending
Validators->>Indexer: poll for pending requests, AttestationRound
Validators->>Validators: fetch via provider, gossip ATTEST_PROPOSE
Leader->>Indexer: ATTEST v1, REDUNDANCY signatures
alt terminal status, ok or errored
Indexer->>Indexer: flip request_status, inject callback EXECUTE
else retryable, no_quorum or timeout or provider_error
Indexer->>Indexer: record v1, request_status stays pending
end
alt DEADLINE_BLOCK passes while still pending
Indexer->>Indexer: synthesize ATTEST v2, flip to expired, fire callback
end
stateDiagram-v2
[*] --> pending: ATTEST v0 emitted
pending --> fulfilled: v1 terminal, STATUS=ok
pending --> errored: v1 terminal non-ok, e.g. expired
pending --> expired: DEADLINE_BLOCK passes while still pending, v2 synthesized
fulfilled --> [*]
errored --> [*]
expired --> [*]
note right of pending: retryable v1, no_quorum, timeout, or provider_error, leaves request_status pending
Response delivery: on-chain versus the hub mirror
Each network has its own response-mirror activation height, ATTEST_RESPONSE_MIRROR_ACTIVATION in protocol/constants.js, checked against the request’s own block: mainnet is null (inactive; every mainnet request today uses the on-chain path above), testnet is 151324 (armed on 2026-09-07 at the chain tip in the v0.15.0 train, so a testnet request at or above that block uses the mirror), and regtest is 0 (active from genesis, so every regtest request already uses the mirror).
Steps 1 through 3 above are unchanged either way: the request is emitted the same way, and the same top-REDUNDANCY validators still agree on the answer together. What changes is what happens with that agreed answer.
Below the activation height, the leader broadcasts it on-chain as an ATTEST v1 transaction, paying the broadcast cost, and the callback fires once that transaction mines.
At or above the activation height, nobody broadcasts a transaction for the response. Instead, the agreed answer, together with a signed effective time the leader picks a short margin ahead of the moment of agreement, is written into the validator network’s shared database and passed on to every hub in the federation, so every indexer receives it regardless of which hub it is connected to. Each indexer then applies the response on its own, deterministically, at the first block whose own clock has reached the response’s signed effective time, as long as that block is still at or before the request’s deadline; a response that would not become due until after the deadline never applies; the deadline’s own expiry (v2) closes that request instead. The applied response is recorded exactly like an on-chain one, a v1 row with the agreed body and the verifying signatures, except that it carries no transaction: it is generated by the indexer itself, the same way a request’s expiry (v2) is. Because delivery already happened through the mirror, an ATTEST v1 that reaches the chain for a request at or above the height is rejected as invalid: ATTEST v1 after mirror activation.
The full history of mirror-delivered responses still reaches the chain. For each closed hourly window, no finalized responses means the publisher publishes nothing; one or more responses means the federation lands one Dogecoin batch of the v5/v6 form described above. Before publishing, a hub asks its Dogecoin indexer which pending windows already have a valid, complete head and treats those windows as landed. A v5 head with ROW_COUNT=0 remains valid if one lands, including one proposed by an older hub. A node with no connection to the validator network can therefore reconstruct every response and replay every callback from the chain alone, but the absence of a batch does not distinguish a quiet window from a missing one.
Zero-confirmation service, above ATTEST_ZERO_CONF_ACTIVATION
Above a network’s ATTEST_ZERO_CONF_ACTIVATION height, keyed on the request’s own block, three more changes apply together, because a mixed fleet must agree on the leader slot, the responsible set and the applied row identically for the same request:
- The responsible set is served the moment the request mines, at the tip block, rather than after a confirmation wait. The
attestationcapability snapshot a request is served against is still resolved the same reorg-buried number of blocks below the request as always; the wait removed here only ever protected a hub’s own provider spend against a request that later reorgs, never the capability snapshot itself. - The widening ladder (see Responsible-set selection, above) runs its second stage from the request’s own block, so a set holding one member that can never sign can still finalize immediately.
- The mirror applier falls through an inert first candidate response to the next admissible one, described below, instead of leaving the request stuck retrying the same inert candidate until its deadline.
ATTEST_ZERO_CONF_ACTIVATION is non-null for a network only where the response-mirror height and the widening ladder’s own activation height are both non-null and no higher than it, so a network is never served at zero confirmations without the mirror already delivering answers and the ladder’s headroom already able to absorb a stalled member.
More than one round can finalize for the same request (for instance a round that finalizes twice under two leader slots), so more than one agreed answer can reach the mirror for it. Below ATTEST_ZERO_CONF_ACTIVATION the indexer tries only the earliest candidate, by signed effective_time, tie-broken by the candidate’s own response hash; if that candidate can no longer be admitted (its signers have since fallen out of the responsible set, for instance) the request stays pending until its deadline, because the same candidate is re-selected and re-refused at every later block. At and above the height, keyed on the request’s own block, the indexer instead orders every candidate for the request the same way on every node and tries them in order, binding the first one it can admit. Exactly one candidate ever binds for a request; the rest remain visible in the mirror table for audit.
Effects on v1 with valid signatures
- At or above the response-mirror activation height, only a terminal
okresponse is ever delivered this way: a retryable round stays in the validator network’s own records rather than becoming a row here, andexpiredis already handled locally by v2. Such a response is generated by the indexer itself from the mirror-delivered response rather than parsed from a broadcast transaction (see Response delivery, above), but is otherwise persisted exactly as below. - Persists a v1 row into the
atteststable (version=1) with the agreed body and the verified federation sigs inlined as a JSON array invalidator_signatures(always, including retryable rounds on the on-chain path, for audit). A v0 request and its v1 response(s) are separate rows correlated byrequest_id. - Terminal statuses flip the matching v0
attestsrow:fulfilled(STATUS=ok) orerrored(a terminal failure such asexpired). - Retryable statuses (
no_quorum,timeout,provider_error) leaverequest_status='pending'untouched so a later round can still reach quorum before the deadline (or the v2 expiry path takes over). No status flip and no callback for these. - On a terminal status only, synthesizes an EXECUTE injecting the callback with params
[request_id, provider_id, status, response_payload, ...original_callback_params]. - Every
original_callback_paramselement is coerced to a string before injection (the VM parameter bus is string-typed), so a request that supplied[42, true, null]reaches the callback as['42', 'true', 'null']. Contracts must re-parse numeric or boolean context withparseInt,parseFloat, orJSON.parseas needed. SOURCEis set tocontract_addresssoxchain.getSourceAddress() === xchain.getContractAddress()inside the callback.- Callback is wrapped in a savepoint; a callback failure does NOT roll back the response row.
Effects on v2 (expire)
- Creates an entry in the
actionstable (gets a newaction_indexso the synthetic event is replay-deterministic and rollback-correct). - Flips the matching v0
attests.request_statusfrompendingtoexpired(v2 writes no row of its own). - Synthesizes an EXECUTE injecting the contract’s callback with params
[request_id, provider_id, 'expired', '', ...original_callback_params]. - As on the v1 path, every
original_callback_paramselement is coerced to a string before injection; re-parse typed context inside the callback. SOURCEis set tocontract_address(matches the v1 callback convention).- Callback is wrapped in a savepoint; a callback failure does not roll back the status flip.
Fee flow
When a v0 request carries FEE_AMOUNT > 0, the fee is escrowed from FEE_PAYER at request time and disposed of when the request reaches a terminal state. All movements are GAS-denominated (XCHAIN). Settlement is deterministic across validators (bcmulfloor to GAS decimals; remainder dust stays in the REWARD pool).
| Event | Fee movement |
|---|---|
v0 valid, FEE_AMOUNT > 0 |
Debit FEE_PAYER and write escrow row (at the v0 action_index). |
v1 → fulfilled (STATUS=ok) |
Release escrow and credit the REWARD pool; one validator_rewards row per responsible-set pubkey (reward_type='attest_fee', round_reference= request action_index), each bcmulfloor(bcdiv(fee, N, 18), '1', 8). Floor dust stays in the pool. Empty responsible set means full fee stays in the pool. |
v1 → errored (terminal non-ok, e.g. expired) |
Release escrow and refund FEE_PAYER (service not rendered). |
v1 retryable (no_quorum / timeout / provider_error) |
No movement: escrow stays locked, request stays pending. |
| v2 expiry (synthesized) | Release escrow and refund FEE_PAYER. |
At and above the response-mirror activation height, nobody broadcasts a transaction for the response, so there is nothing to reimburse: the full escrow above is split across the responsible-set pubkeys with nothing carved out first. Below the height, on networks where a reimbursement for the leader’s on-chain broadcast cost is active, that reimbursement is paid to the responsible set’s lowest-hash member before the remaining escrow is split among the whole set; where no such reimbursement is active the full escrow already splits the same way as above the height.
At and above ATTEST_ZERO_CONF_ACTIVATION, keyed on the request’s own block, a fulfilled settle changes once more. Because the widening ladder now grants headroom from the request’s own block (see Responsible-set selection, above), the recomputed responsible set can include a member the round never actually needed and that never signed. So above the height the escrow instead splits equally among the pubkeys that verifiably signed the accepted response, sorted by pubkey before paying, rather than the recomputed responsible set; each signer’s validator_rewards row and the bcmulfloor rounding are otherwise unchanged. errored and expired refunds are untouched by this change: a request that never fulfills has no signer set to pay, so it keeps refunding FEE_PAYER exactly as above.
validator_rewards rows are paid out to stakers via COLLECT (the same path as protocol rewards, hence the XCHAIN-only constraint, since that chain has no per-row tick column). A reorg mid-fulfillment rolls back the release and reward rows generically (credits/debits/escrows by action_index, rewards by block_index) and resets request_status to pending; the earlier v0 escrow row survives.
Notes
REQUEST_IDis the cross-version foreign key; every v1 and v2 must reference an existing v0.- A quiet hour is no longer provable from the chain alone: an hourly window with no finalized responses intentionally leaves no v5 head.
- The positional label in the indexer’s internal format string for v0 is
CALLBACK_PARAMS_JSON(so named to signal that the field carries a JSON array). The data object key used throughout the handler and the stored column name isCALLBACK_PARAMS. The name in this PARAMS table (CALLBACK_PARAMS) is the canonical user-facing name and matches the stored key; the_JSONsuffix in the format string is an implementor hint, not a separate field. - Storage is consolidated into a single
atteststable: v0 (request) and v1 (response) rows are version-discriminated and correlated byrequest_id, mirroring howmessagesholds every MESSAGE variant in one table. v2 (expire) writes no row, it only flips the v0 row’srequest_status. Validator sigs live inline as a JSON array in the response row’svalidator_signaturescolumn; per-validator accountability tallies live inattest_validator_stats. - The optional
FEE_TICK/FEE_AMOUNTrequest fee is live. The separategas_escrow(callback-gas) field remains stubbed at'0'; real callback-gas escrow is Phase 3 economic work, independent of the request fee. - Publishing a v5/v6 batch pays no reward of its own; it is a durability measure, not a service the protocol compensates separately.
- Which path answers a given request (on-chain broadcast or the hub mirror) is fixed for that request the moment it is admitted, by
ATTEST_RESPONSE_MIRROR_ACTIVATIONinprotocol/constants.jschecked against the request’s own block, so a request is never admitted under one rule and answered under the other. - See
EXECUTE.mdfor the system-synthesized EXECUTE that delivers attestation callbacks and for the cross-contract call mechanics that share the same emission and savepoint patterns.
Copyright © 2025–2026 Dankest, LLC
Based on XChain Platform by Dankest, LLC – https://dankest.llc
Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later) with a commercial license available for proprietary use.
You may use, modify, and distribute this material under the terms of the License. See LICENSE and NOTICE for full terms. See the licensing overview.