XvP Settlement Flow

Purpose: Step-by-step walkthrough of the atomic multi-party settlement process, including local execution, cross-chain hashlock coordination, and failure recovery.

• Doc type: How-to

What you'll find here

• Happy path for local (single-chain) settlement execution
• Cross-chain hashlock lifecycle and secret reveal mechanics
• Approval system and execution gates
• Failure modes and atomicity guarantees at each step
• Sequence diagram of multi-party settlement coordination

Related

• XvP Settlement -- contracts, roles, and configuration
• Signing Flow -- transaction signing and custody
• Compliance Transfer -- transfer compliance checks

---

Flow overview

The XvP (Exchange versus Payment) settlement flow coordinates atomic token exchanges between multiple parties. "Atomic" means all token transfers in a settlement succeed together or all revert together -- there is no intermediate state where some parties have received tokens and others have not. For settlements involving external chains, a hashlock mechanism coordinates execution across networks.

Happy path -- local settlement

1. Initiator creates settlement -- the settlement contract is deployed with a set of flow definitions. Each flow specifies a sender, receiver, token address, and amount. An expiration timestamp is set at creation and is immutable.
2. Senders grant ERC20 allowances -- each sender in a local flow calls approve() on the relevant token contract, granting the settlement contract permission to transfer their tokens.
3. Senders approve the settlement -- each sender calls approve() on the settlement contract itself, signaling readiness to execute. Approvals can be revoked before execution.
4. Execution gate satisfied -- once all local senders have approved (and the hashlock is satisfied, if applicable), the settlement is eligible for execution. If auto-execution is enabled, this triggers immediately.
5. Atomic token transfers -- all local flows execute in a single transaction. The settlement contract calls transferFrom for each flow. If any individual transfer fails (insufficient allowance, compliance revert, or other ERC20 error), the entire transaction reverts.
6. Settlement marked executed -- an on-chain record confirms the settlement completed. No further approvals or executions are possible.

Cross-chain hashlock lifecycle

When a settlement includes flows with externalChainId != 0, the hashlock mechanism coordinates execution across chains:

1. Settlement created with hashlock -- the initiator provides a hashlock (the hash of a secret) at creation time. This is required when any flow targets an external chain.
2. External HTLC deployment -- counterparties on external chains deploy Hash Time-Locked Contracts using the same hashlock. These HTLCs lock the external-chain tokens, mirroring the flows defined in the settlement.
3. Secret revealed on external chain -- when the external HTLC executes, the secret (preimage) becomes public on-chain.
4. Secret relayed to settlement -- anyone calls revealSecret(bytes secret) on the settlement contract. This function is permissionless -- no single party can block settlement by withholding the secret once it is public.
5. Execution proceeds -- with both the hashlock satisfied and all local approvals collected, the settlement executes atomically as described in the local flow above.

For pure local settlements where all flows have externalChainId = 0, the hashlock is optional and the execution gate requires only local approvals.

Approval management

• Per-sender scope -- each sender approves the entire settlement, not individual flows. A sender appearing in multiple flows provides one approval.
• Revocation -- any sender can revoke their approval before execution by calling revoke(). This resets their approval status without affecting other senders.
• Auto-execution -- when the auto-execution flag is set at creation, the settlement executes automatically the moment all gates are satisfied. Without auto-execution, a separate execute() call is required after all conditions are met.

Failure modes

• Settlement expired -- the expiration timestamp has passed. No further approvals or execution attempts are accepted. Funds remain with their original owners.
• Insufficient ERC20 allowance -- a sender's token allowance is less than the flow amount. The execution transaction reverts atomically; no partial transfers occur.
• Missing local approvals -- not all senders have approved. Execution is blocked until every local sender has called approve().
• Hashlock not satisfied -- for cross-chain settlements, the secret has not been revealed on the settlement contract. Execution is blocked until revealSecret() is called with the correct preimage.
• Token transfer failure -- if any individual transferFrom call fails (e.g., a compliance-enabled token rejects the transfer), the entire settlement transaction reverts. All tokens remain with their original owners.

Related resources

• XvP Settlement -- contracts, roles, and configuration
• Signing Flow -- how transactions are signed and broadcast
• Compliance Transfer -- transfer validation for compliance-enabled tokens
• Capabilities overview -- how capabilities extend the platform