Settlement Verdict

A Settlement Verdict lets you report success only when an operation actually happened. Every accepted instruction becomes a tracked transaction request that ends in one of four recorded states: completed, failed, dead letter (held for operator intervention), or cancelled.

An acceptance response proves only that the instruction was durably recorded, not that it worked. Success is read from the verdict alone, and a screen or integration that stops waiting shows the operation as processing and keeps its status link.

The verdict is an application outcome. It does not replace the network's finality rules or the transaction receipt.

Why a recorded verdict mattersCopy Anchor Link

A Settlement Verdict separates two events that transaction systems often blur: the platform acknowledging an instruction and the platform confirming its outcome. Acceptance means the instruction is safely recorded. The verdict states what happened. Client reporting, statements, and downstream money movement key off the verdict alone.

The risk this removes is the false positive: telling a client an asset was issued or a payment settled when the operation later failed. In payment rails, a message acknowledgment is never a settlement confirmation; the platform applies the same discipline to on-chain writes. Integrations should wait for the recorded outcome before reporting that an operation succeeded.

This signal is not particular to one kind of operation. A custody approval clearing its wallet, an XvP settlement moving every leg together, a smart wallet deployment, and a corporate action all resolve through the same four states, because each is an accepted write against the platform's transaction state machine. Asset Lifecycle's own integration contract tells the reader to read the verdict the same way, instead of treating acceptance as completion. The verdict is not one of that page's named stages; it applies across every stage that writes to chain.

Use the verdict to track the platform operation and the network's finality rules to assess chain settlement risk. A recorded application outcome does not guarantee same-day settlement or make a transaction immune to reorganisation.

Following a request to its outcomeCopy Anchor Link

Day to day, a Settlement Verdict is the end state an operator watches a transaction toward. Every accepted write appears as a tracked request with a live status. The operator's question is whether it finished, and that is answered when the status reaches one of four terminal values: completed, failed, dead letter, or cancelled.

While a request is in progress it moves through named working states: received, queued, preparing, pending approval, signing, broadcasting, and confirming, so a request is never sitting in an unexplained limbo. Pending approval is a custody approval step where a designated approver authorizes the operation. If that approval is declined or expires, the request ends as failed with a matching reason; neither reopens, so submit a fresh instruction with a new idempotency key if the transfer is still needed. A screen that cannot wait for the verdict shows the operation as still processing and points to the work queue where its progress continues. It never shows success early, and it never leaves the operator on an endless spinner.

A failed verdict states its reason: a sub-status, an error message, and, when the platform recognizes the failure, a decoded explanation with a suggested next step. Dead letter means the platform has stopped retrying and holds the request for intervention until an operator requeues it. Cancelled records a deliberate stop by the requester. Before broadcast it takes effect immediately; after broadcast it succeeds only if a replacement transaction outruns the original on chain, using the network's replacement-transaction rules. If the original lands first, the request keeps the verdict its execution earned, so a cancel that lost the race is never recorded as cancelled and the verdict always reflects what actually happened.

One retry rule prevents duplicate execution: never resubmit an instruction because a wait timed out. Check the verdict first. A write that later completes would be duplicated by a blind resubmission.

How the outcome becomes durableCopy Anchor Link

A Settlement Verdict lets you learn what happened to a write without querying the chain yourself. It is a terminal state in the platform's own transaction state machine, and that state machine, not the blockchain receipt, is the source of truth for finality. Every accepted write is recorded as a request that moves through the seven working states named above, then settles into one of the four terminal outcomes: eleven states in total.

The status read reports the stored request record; it does not query the chain. The receipt for a mined transaction is a separate lookup, used for chain inspection and reconciliation. The two answer different questions: the verdict says what became of the requested operation, the receipt says what one chain transaction did.

Completion is gated on read visibility. After a write confirms on chain, the platform waits for its own index to process that block, up to 99 seconds, before reporting the completed state, so a caller that sees completed can normally read the result it produced. If the index lags past that bound, the current state returns anyway, and read views may trail the verdict briefly.

The verdict and the receipt answer different questions; only the verdict is the finality signal.

Terminal states are stable by construction. Completed and cancelled never change. Failed may be escalated to dead letter, and an operator with the organization update permission can requeue a failed or dead-letter request straight back into execution. Nothing else moves any of the four. Retries and crash recovery attach to the existing request rather than creating a new one, so each accepted write has exactly one verdict.

The integration contractCopy Anchor Link

A Settlement Verdict appears on the API as the terminal status of a transaction request. A write returns either a synchronous success carrying the result, or an accepted response carrying the request identifier and a status address. The integration is complete only when the observed status reaches one of the four terminal values.

By default a write returns HTTP 202 with a handle: the request id, its current state, and a status URL. The 202 proves the instruction was durably accepted; it says nothing about the outcome, and treating it as success is the integration bug this contract exists to prevent. Send Prefer: wait=N to wait inline for 5 to 99 seconds. Completion within that window returns HTTP 200 with the resource and transaction hashes. Otherwise, the response returns the same HTTP 202 tracking handle. See Idempotency and async settlement for the full header contract, including the hybrid Prefer: respond-async, wait=N form.

Poll the status URL until the request is terminal, or open its status event stream. The stream sends the current state and later changes. It closes at a terminal state or after 180 seconds. Fall back to polling when it closes without a verdict. For a fleet of in-flight requests, webhooks report a terminal state without polling any of them; a filterable list endpoint remains for ad hoc monitoring.

A failed verdict states an error message, a sub-status, and, when the failure maps to a known error, a structured code with decoded arguments and a suggested fix. Per the platform's error contract, branch on the code, not the message text.

A not-found from the status route means the id is unknown, outside your credential's scope, or still committing shortly after acceptance. In that last case, the not-found is transient. Never conclude the write did not happen; verify the key, wallet, and organization instead.

The queue attaches a matching submission to the existing transaction request when the idempotency key, sender, chain, and wallet selection match inside a 24-hour window. A route may perform other work before queue admission, so repeat an API request only when that route documents replay safety. A fresh key identifies a new instruction.

Controls and evidenceCopy Anchor Link

A Settlement Verdict serves compliance as the evidential record of what a submitted operation became. Each request keeps its acceptance time, terminal outcome, time of the last state change, failure detail, and linked on-chain transaction hashes, so an auditor can answer what happened, when, and why for any write after the fact.

Every write passes the same queue, so an operation that settles inside the synchronous wait leaves the same request record as one that reports back later.

The verdict records what happened; enforcement lives in the asset's own on-chain rules, which run when the operation executes and cannot be sidestepped by going around the platform. When those rules reject a write, the write reverts without moving any balance. The verdict then records a failed state with a structured reason: the party's identity is not registered for the asset, required identity claims are missing or revoked, or a specific rule module blocked the operation. The failing party and wallet are named when the platform can identify them. The auditor sees which control fired, not only that something failed.

An indexed resource read can lag the operation's status. A chain reorganisation can also change indexed activity after completion was recorded. Reconcile a mismatch using the request record and its transaction references.

The status surface also controls what it discloses: a lookup for a request owned by another organization answers exactly like a lookup for a missing one, so the surface cannot be probed to reveal another organization's activity.

Frequently asked questionsCopy Anchor Link