XvP Settlement

An XvP settlement delivers every leg together, or it delivers none. Local-only execution nets every position and moves it inside one transaction, or the whole settlement reverts; once a hashlock commits an external settlement, a blocked delivery can stay claimable while every other delivery still completes.

Senders approve first: approval escrows their assets, and execution moves net positions per asset.

The cutoff date lets an uncommitted settlement refund. Revealing a valid secret commits it and closes that refund path. When a leg lives on another chain, a hashlock coordinates its release through a shared secret, and the parties verify the external lock, the deadlines, and execution on each system themselves.

Why an exchange needs to settle without principal riskCopy Anchor Link

Two parties agree to exchange tokenized assets, a bond for cash, or one currency token for another. Whoever delivers first is exposed for the whole gap until the other side pays, and a counterparty can close that gap by not paying at all. XvP Settlement removes that exposure by making both deliveries depend on the same transaction: every leg moves together, or none of them move at all.

One primitive covers two exchange shapes market practice names separately. Delivery versus payment (DvP) moves a security against a cash token. Payment versus payment (PvP) moves one cash asset against another. XvP, X versus payment, is the umbrella term, where X stands for whichever asset is the variable leg.

Industry practice calls the exposure this removes principal risk: the loss a party takes by delivering its share of a trade before receiving the other side. Conventional markets manage that risk through central infrastructure, and even then final settlement lands one to two business days after the trade, under the T+1 and T+2 conventions most markets still run on. Here, settlement is a single transaction. For local-only execution, the contract applies every net delivery inside that one transaction. Approval escrows a sender's net contribution until execution runs or an available refund path releases it. A settlement still needs planning for locked capital, for a token's own restrictions, and for the contract and network risk any on-chain operation involves.

When a leg lives on another chain or an external system, a hashlock coordinates release through a shared secret instead of one shared transaction. That does not place both systems inside one atomic operation. The parties verify the external lock, the deadlines, and finality on each side before anyone reveals the secret. The platform does not price the trade, charge a settlement fee, or prove that an external leg completed; those stay with the parties' own commercial and reconciliation processes.

Why this settlement runs on the platform, not beside itCopy Anchor Link

The alternative to settling on the same platform as the asset is settling beside it. A bilateral escrow agent, a correspondent-bank DvP link, or a private clearing arrangement holds both legs until it decides to release them. That arrangement needs its own view of who may hold and receive the traded assets, kept separately from the token's own compliance rules, because it is a different system deciding on a movement it does not itself control. That gap is a seam: a delivery the escrow arrangement allows and the token's own compliance would have refused.

Every flow here is re-checked against the token's own restrictions at the moment of delivery, the same check that governs every other movement the asset makes: a mint, a freeze, an ordinary transfer, a coupon payment. Asset Lifecycle names the stage this happens in directly. Once an instrument is issued and unpaused, the platform services it for as long as it lives, and settling trades sits in that same Service stage next to paying coupons, freezing holdings, and collecting fees. A delivered settlement is a normal, compliance-checked transfer, so it lands in that asset's own record the same way every other servicing operation does.

The custody arrangement follows the same logic. Escrowed assets sit inside the settlement contract itself, not with the platform and not with any counterparty, and only the contract's execute and refund paths can move them. Compliance risk never migrates to a second custodian, because no second custodian exists.

Running a settlement day to dayCopy Anchor Link

Day to day, an XvP settlement is one record that carries an exchange from proposal all the way to its end. You create it, collect an approval from each sender, and watch it finish in exactly one of three states: executed, cancelled, or expired when the cutoff date passes.

You list every flow at creation: which asset moves, from whom, to whom, how much, and the cutoff date. Approval is collected sender by sender, so a settlement can sit partially approved, and each approval is the step that locks that sender's assets into escrow. Before that call can succeed, the sender must already hold an ERC-20 allowance on the asset for the settlement contract covering its own leg; too little answers DALP-1105, and raising the allowance and retrying clears it. Once every sender has approved, the settlement is ready, or armed if it is still waiting on a secret reveal. Execution is its own step, which any party can trigger, and an optional auto-execute can fire it the moment it becomes ready.

Three exits protect the parties if the exchange never completes. A sender can revoke their own approval before execution, which returns that sender's escrowed assets. Any local participant (a party to a leg that settles on this platform, as opposed to a leg on another chain or system) can cancel the whole settlement before execution. Once a settlement with an external leg is fully approved and waiting on its secret, cancellation instead needs a unanimous vote of the local participants. And the cutoff date is a hard deadline: a settlement that has not executed by then can no longer execute, and each participant withdraws exactly what they locked. A second withdrawal against the same settlement finds nothing left and answers DALP-2007. The one exception is a settlement already committed by a revealed secret, which stays executable past the deadline, as the architecture section explains. Withdrawal is a claim the participant makes rather than an automatic payout, and a token restriction can defer a refund until the participant claims to a permitted receiver. Committed settlements remain outside the expiry refund path.

The cutoff date is the one dial you set, and it must sit strictly after the moment you create the settlement; the factory checks that at creation and answers DALP-2011 when it does not. Set it too soon and it can pass before every sender approves, and there is no extension: you create a fresh settlement with a new deadline. Set it too far out and the first sender to approve leaves its assets in escrow for that whole window, whether or not anyone else acts. Size it to how long the parties actually need to approve, not to a fixed habit.

For local-only execution, a failed required delivery reverts the transaction. After a hashlock commitment, an undeliverable net amount can be parked while other deliveries proceed. The one narrow exception is a delivery blocked by a token's own controls after the settlement is already committed, which is parked for that participant to claim separately; the compliance section explains when that applies.

How it works and where the boundaries sitCopy Anchor Link

Each XvP settlement is its own dedicated escrow contract, and creating one is permissionless: anyone can create a settlement. Creation moves nothing on its own. Assets enter escrow only when each named sender approves and deposits its own leg, so naming a party in a settlement gives that settlement no claim on their assets until they act themselves. That contract is the settlement source of truth for the flows, approvals, deadline, and outcome, so the exchange cannot split across competing records.

Execution settles net positions rather than one transfer per flow. For each asset, the contract computes what each participant pays minus what they receive across all local flows. Net payers are debited from their escrow, net receivers get one delivery, and a participant whose flows cancel out moves nothing. Per asset, all net positions must sum to zero; if they do not, the settlement fails closed and answers DALP-1068. Escrow follows the same arithmetic: approval locks exactly the sender's net requirement per asset, so a participant whose flows offset locks nothing yet still must approve.

One check gates every payout. Before moving any funds, the contract verifies that each approved sender's escrowed amount exactly matches that requirement. A mismatch stops execution before anything moves: every escrow stays in the contract, and participants recover it through whichever exit still applies, revocation, cancellation, or withdrawal after the cutoff.

Gross flows (→ pays, ← receives) collapse into one net amount per participant: positive for a net payer whose escrow is debited, negative for a net receiver who is delivered that amount. The column must sum to zero per asset, or the settlement fails closed.

Before hashlock commitment, a failed delivery reverts the whole execution transaction. A committed settlement can park a blocked delivery for a later claim while completing its other net deliveries. A leg on another chain or system is coordinated rather than executed: the contract stores a hashlock, and the local legs settle only after the matching secret is revealed before the deadline. The external system runs its own locking and release against the same hashlock; this platform never controls that leg.

Revealing the secret commits the settlement. From that moment cancel, refund, and expiry all close, and execution is allowed even after the deadline, so a revealed secret cannot leave the local leg stranded or refunded while the external leg is claimed against it.

Any party can trigger execution. Completion still depends on successful transaction submission and the contract's execution checks. The parties remain responsible for staggering the deadlines across legs, so that each leg which consumes the secret later stays open longer.

The integration contractCopy Anchor Link

On the API, an XvP settlement is one object with a small verb set: create, approve, execute, reveal secret, revoke approval, cancel, withdraw after expiry. You create it once with every flow it will settle, collect an approval from each sender, and read its outcome from the settlement's own state.

You create a settlement from a flows array, and an empty one answers DALP-2012. Each local flow names the asset, sender, recipient, amount; it executes on the platform. An external flow is a coordination reference to a leg elsewhere: it adds an external chain id and the external asset's decimals, and the platform records it but never executes it. A settlement that includes an external flow must be created with either a raw secret or a precomputed 32-byte hashlock, or creation answers DALP-2010; local-only settlements need neither.

Approval is per sender, and each approval escrows that sender's assets. Execution succeeds only when every sender has approved, and, for a settlement with external flows, only after the secret has been revealed.

Auto-execution at creation is optional and off by default: with it off, revealing the secret makes the settlement ready, but execution is a separate call you make; with it on, execution fires the moment the settlement becomes ready.

Read outcomes from the settlement's state, never from a request's acceptance. An accepted create or approve call means the platform durably took the request, and the request's own outcome is recorded as a Settlement VerdictA Settlement Verdict lets you report success only when an operation actually happened, not from acceptance alone, across four recorded end states.Read the concept. The exchange itself has settled only when the settlement reports its executed state; the other terminal states, cancelled and expired, are equally final.

Controls and evidenceCopy Anchor Link

For a control function, an XvP settlement is an escrowed exchange whose enforcement point is execution, the moment assets change hands. Every flow of a regulated token is re-checked against that token's transfer restrictions at that point, not only at approval, and the on-chain settlement record is the audit evidence for the exchange.

The re-check closes the timing gap: a participant who passed eligibility checks at approval but lost them before settlement, for example through a sanctions hit or a revoked verification, cannot receive assets. For an uncommitted settlement, the failed check reverts execution. For a committed settlement, the blocked delivery can be parked for a later claim. The checks apply to the transfers execution actually performs, the net movements, on both the paying and the receiving side. Escrow is not a bypass; parking assets inside the settlement contract does not exempt the eventual payout from the asset's own compliance rules, so the escrow mechanism cannot be used to route around transfer restrictions.

A restriction against one participant does not trap the others, and the boundary with atomicity is precise. Before a settlement is committed, enforcement is atomic: a flow that fails its check stops the whole settlement and no assets move. Parking applies in exactly two places where reverting would punish the innocent. One is refunds, where a single blocked address cannot freeze every other participant's money. The other is delivery in a settlement already committed by a revealed secret, where unwinding is no longer possible. In both cases the blocked leg is parked for the affected participant to claim separately to a permitted address, while every other participant's settlement or refund proceeds. That claim runs on chain, not through the platform API: the participant calls claimRefund or claimSettled on the settlement contract directly with a permitted receiver address, and a call with no locked or parked balance behind it answers DALP-3028.

Evidence is on-chain and per settlement. The settlement record shows the flows as written, plus every approval, the deadline, and the terminal outcome; events timestamp approvals and revocations, the secret reveal, cancellations, execution, refunds, parked deliveries and their later claims. An auditor can reconstruct who committed what and when, and how the exchange ended, without relying on off-platform logs.

Frequently asked questionsCopy Anchor Link