XvP Settlement

Why this settlement runs on the platform, not beside it#

The alternative is settling beside the asset: 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.

Until a revealed secret commits the settlement, every local flow of a token with compliance rules is re-checked against those rules at execution, the same check an ordinary transfer passes. A plain ERC-20 asset has no compliance contract and is not checked. Settling trades sits in the Service stage of the Asset Lifecycle, 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.

Escrowed assets sit in the settlement contract, not in a platform or counterparty wallet, and the contract releases them only through execution or a refund path. Other controls still reach them. A holder of the System manager role can point every settlement of a factory at new contract logic, because each settlement reads its logic from the factory on every call. The asset's Custodian can force a transfer out of the settlement address or freeze it, and the asset's Emergency role can pause the token, which stops execution and refunds for that asset.

Running a settlement day to day#

An XvP settlement is one record that carries an exchange from proposal to its end. In the Console you work it from Settlements. 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 reads Pending while it collects approvals and can sit partially approved, and each approval is the step that locks that sender's assets into escrow. The platform first grants the settlement contract an ERC-20 allowance on each asset where the sender's current allowance falls short of the net amount it locks, then approves. A contract call that arrives with too little allowance answers DALP-1105, and raising the allowance and retrying clears it. Once every sender has approved, the settlement reads Ready, or Waiting for secret while a secret reveal is outstanding. After the reveal it reads Ready after reveal. Execution is its own step, which any account can trigger, and an optional auto-execute can fire it the moment it becomes ready.

A local participant is a party to a leg that settles on this platform. Three exits protect the parties if the exchange never completes.

• Revoke. Before execution, a sender can revoke their own approval, which returns that sender's escrowed assets. On a settlement with an external leg, revocation closes once every sender has approved.
• Cancel. Any local participant can cancel the whole settlement before execution. Once a settlement with an external leg is fully approved and waiting for its secret, cancellation instead needs a unanimous vote of the local participants.
• Withdraw after the cutoff. The cutoff date is a hard deadline: a settlement that has not executed by then can no longer execute. One withdrawal then refunds every participant exactly what they locked, and any account may send it. A second withdrawal against the same settlement is refused with DALP-2007. The one exception is a settlement already committed by a revealed secret, which stays executable past the deadline, as How it works and what it covers explains. A token that refuses one participant's refund parks that refund in the settlement until the participant claims it to a receiver the token accepts, and the other refunds complete. Committed settlements remain outside the expiry refund path.

The cutoff date 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 need to approve.

How it works and what it covers#

Each XvP settlement is its own dedicated escrow contract, and any user can create one from the system's XvP factory, except a participant whose account restricts securities transfers. 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 local flows, approvals, deadline and outcome.

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, where → pays and ← 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. Execution after the deadline and parking of a blocked delivery or refund come with version 4 of the settlement logic. Each settlement runs whatever logic its factory points at, and a System manager can repoint a factory, which changes the rules for settlements already open. A factory still on an earlier version reverts the whole execution on a failed delivery and cannot execute after the deadline.

Any account can trigger execution. Completion still depends on successful transaction submission and the contract's execution checks. The parties set the deadlines across legs so that a leg that consumes the secret later stays open longer.

The integration contract#

On the API, an XvP settlement is one object with a small verb set: create, approve, execute, store, decrypt and reveal a secret, revoke approval, cancel or vote to cancel, withdraw after expiry, and claim a parked amount. You create it once with every flow it settles, collect an approval from each sender, and read its outcome from the settlement's own state. Only the wallet that created the settlement can store its secret. The platform seals the secret under that wallet's signature, so only that wallet can decrypt it again. On chain, anyone who presents the secret can reveal it once every sender has approved and before the cutoff date.

You create a settlement from a flows array, and an empty one answers DALP-2012. Each local flow names the asset, sender, recipient and amount, and 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 Verdict. The exchange itself has settled only when the settlement reports its executed state. The other terminal states, cancelled and expired, are equally final.

When a corporate action changes the escrowed token#

A stock split, bonus issue or other corporate action that changes every holder's units by a ratio also changes what a settlement escrows. The platform sizes the settlement's units from its per-owner deposits, and the action mints to or burns from the settlement the sum.

From the action's record date until its step lands, the settlement refuses new deposits, revealing a secret, settling, and also cancelling, withdrawing and refunding when one of its flows is in that token. Participants cannot cancel, withdraw or refund until the step lands. Then the step cancels a settlement that is still open and refunds every deposit on the new basis. A settlement whose secret has been revealed is committed, so it settles its flows re-based by the action once the step has landed. A settlement cancelled before the freeze stays cancelled.

Controls and evidence#

For a control function, an XvP settlement is an escrowed exchange whose enforcement point is execution, the moment assets change hands. Until a revealed secret commits the settlement, 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, a failed check reverts execution and nothing moves. A committed settlement skips the re-check, because it can no longer refund. A delivery that the token itself refuses is parked for the recipient to claim later, and the other deliveries complete. The re-check runs on every local flow as you wrote it: the flow's sender, its recipient and its full amount, checked against the token's compliance rules before any net delivery moves. The settlement contract sits on the compliance bypass list, so a deposit into escrow skips the recipient-side checks. Execution restores them: before a settlement is committed, the contract checks every local flow from its sender to its recipient and refuses a recipient on the bypass list. After a revealed secret commits it, that per-flow check is skipped, and only the token's own check on the payout from the settlement contract applies.

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 two places. In refunds, one blocked address must not freeze every other participant's money. During delivery after a secret reveal, unwinding is no longer possible. A freeze of the settlement contract's own address, or a pause of the token, still blocks every participant's delivery and refund for that asset until it is lifted. 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. The participant claims it with “Claim parked amount” under the settlement's “Actions” menu, in the Console or the Investor portal, or through the Platform API with POST /api/v2/addons/xvp-settlements/{settlementAddress}/parked-claims. The claim names the receiving address, which defaults to the claiming wallet. A wallet with nothing parked is refused before anything is sent, with DALP-3028. A receiving address the token refuses moves nothing, and the participant can claim again to another address. An amount parked before the platform began recording parked amounts stays claimable only on chain, by calling claimRefund or claimSettled on the settlement contract directly.

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 questions#