Lifecycle events and fields
Events appear in batch.events. The wire frame version and event schema are independent. The schema described here is onchain.lifecycle.v1. JSON fragments on this page illustrate tagged values; they are not complete events or captured production messages.
Common lifecycle envelope
All listed fields are present on lifecycle events. Nullable relations are emitted as null, not omitted. The minimal source-quality envelope is a separate shape described below.
Evidence stages are pending_observation, admitted_intent, receipt_complete, canonicality_assessment, resolution_assessment. An enum value does not imply its own public event type.
facets contains required network, owners, signers, tokenIds, conditionIds, stages, correctionTargets; the latter six are arrays and may be empty. NetworkRef is an object with namespace: "eip155", chain_id: 137 as a JSON integer and genesis_hash as a Hash32. It is distinct from frame scope’s string network polygon:137. Signer facets do not imply a signer selector.
Domain IDs are opaque and are not interchangeable with transaction hashes. Hash32 uses 0x followed by 64 lowercase hex characters; addresses use 0x followed by 40 lowercase hex characters. Null relation means no known relation, not a zero hash. Raw uint256 values use canonical unsigned decimal strings, with range 0 through 2^256−1; revisions use u64 decimal strings.
fill.intent
An admitted provisional participation from supported calldata. It is not an execution result. Payload requires kind: "intent", intent_id (Hash32) and pending (object).
All pending fields below are present; only calculationEvidenceRef can be null.
Calculation fragment:
The other variant is provisional_maker_taking with required raw amount string and rule string identifying the supported calculation rule. Unavailable reasons: taker_execution_dependent, rule_unverified, zero_maker_amount, fill_exceeds_signed_maker_amount, arithmetic_overflow. Fields from another variant are not substitutes for the selected result.
Save intent as provisional; exclude it from actual volume. Valid admitted pending facts do not claim executionGuaranteed: true. One transaction can have several intents, and repeated order hashes do not prove a unique execution relation.
transaction.included and transaction.reverted
These describe a full receipt outcome for a particular inclusion. Payload requires kind: "inclusion", inclusion_id (Hash32), outcome (success/revert) and normalizationStatus (tagged object).
Normalization fragment:
Other statuses are no_exchange_events, reverted, or unsupported with required reason. Unsupported reasons: incomplete_taker_emission, fee_evidence, match_shape, conservation, amount_exceeds_u128, arithmetic_overflow.
Record outcome and normalization separately from executions. Revert creates no fills. Unsupported normalization is not a zero fill. Success does not prove finality or guarantee supported executions. Receipt-only inclusion is valid, and this envelope is not the raw receipt.
fill.execution
A normalized execution from a complete receipt. A later event of the same type can refine its intent relation, with a new revision rather than another trade.
Payload fields are all required and non-null:
side is string "0" (buy) or "1" (sell). Remaining amounts are uint256 decimal strings. Cash and shares use raw units from verified asset configuration; maker/taker perspectives must not be summed as independent volume.
Correlation fragment:
Exact correlation requires status: "exact" and value (IntentId). Ambiguous requires status: "ambiguous" and candidates (IntentId array). Unavailable requires reason: intent_not_observed, unsupported_invocation or insufficient_evidence. No exact join is promised from transaction hash alone. Missing intent correlation does not turn receipt-backed actual amounts into estimates.
Apply by execution/entity and revision, respecting occurrence canonicality. Receipt-first and partial fills are valid. See identities and amounts.
canonicality.changed
An updated chain-evidence assessment of one inclusion. Payload requires kind: "canonicality_changed", inclusion_id (Hash32), prior and current.
Assessment values: unassessed, included, orphaned, depth_confirmed, chain_finalized. Fragment:
Update the canonical projection of this inclusion and related executions. Reinclusion creates a different occurrence. Depth does not establish chain finality. canonicality.orphaned and canonicality.chain_finalized are not wire event types: they are assessment values in this event type.
transaction.resolution
Evidence about an observed transaction’s fate, not a fabricated receipt or automatic terminal replacement. Required payload fields: kind: "resolution", resolution_id Hash32, reason object, status object and evidence_ref Hash32.
The nested tag is named reason, not kind. Status is either unresolved, or receipt_observed with required inclusion_ids Hash32 array. Fragment:
Save the assessment and revision, allowing later receipt evidence. Resolution creates neither an execution nor volume.
source.gap and capability.changed
These report source observation quality using a minimal envelope. They do not require the lifecycle relation/facets fields above.
Required fields: schema, eventId, eventType, entityId, assessmentRevision, rulesVersion, observedAt, evidenceStage, payload, plus delivered eventOrdinal. observationReason, when available, is present as a string (realtime, recovery_backfill, late_resolution); otherwise it is omitted, not emitted as null.
rulesVersion is source-quality.v1, evidenceStage is source_observation, revision is "1". Entity ID uses idx:v1:source-quality: followed by Hash32; it is not a transaction ID. Observation time is an RFC3339 string.
Payload requires only sourceScope, network, contractScope, capability, reason. Network is string polygon:137. Source/contract scopes are bounded lowercase ASCII names using letters, digits, ., :, _, -.
source.gap has capability gap; reasons are transport, protocol, queue_overload, queue_failure, process_restart, process_shutdown, source_control, removed_log. capability.changed has capability ready and reason subscription_ack.
Update quality coverage without creating fills. Quiet-wallet subscriptions can receive these notices; ready does not recover missing pending. Private epochs/recovery bytes are excluded. See source health.
Mixed wire names
Preserve snake_case fields such as intent_id, execution_id, resource_ids, inclusion_id, resolution_id, evidence_ref and resolution variant fields. The common envelope and many nested structs use camelCase. Converting the entire payload to a uniform casing changes the contract.
Complete synthetic source-derived examples
These are deterministic software fixtures produced by the existing reducer and serializers, not observed trades or production captures. The pending fixture has orderSignatureVerified: false and synthetic evidence references: it demonstrates reducer output and JSON shape only, not successful signed-envelope verification or admission.
The following six objects are complete stored lifecycle domain events. They are not a customer batch frame: delivery adds eventOrdinal and the batch envelope. Normal lifecycle facets are preserved. The success, orphan correction, revert and unresolved examples illustrate different fixture scenarios; do not aggregate them into one trade.
fill.intent: complete stored domain event
transaction.included: complete stored domain event
fill.execution: complete stored domain event
canonicality.changed: complete stored domain event
transaction.reverted: complete stored domain event
transaction.resolution: complete stored domain event
Quality notices: complete projected batch frames
These two deterministic fixtures use the actual replay projection and server serializer. Unlike stored domain events above, each includes a delivery ordinal and batch envelope. Private epochs and quality routing facets are excluded. The fixture clock is synthetic, not a current source-status claim.