XvP Settlement

Purpose: Describe the XvP Settlement capability -- an atomic settlement engine ensuring all-or-nothing token exchanges across multiple parties with optional cross-chain coordination.

• Doc type: Reference

What you'll find here

• Multi-party settlement mechanics and flow types
• Hashlock coordination for cross-chain legs
• Approval system and execution gates
• Trust boundaries and expiration safety

Boundary

The XvP Settlement engine handles the atomic execution of token exchanges between parties. It does not handle price discovery, order matching, or compliance verification -- those are upstream concerns resolved before a settlement is created. The settlement contract guarantees that either all flows execute together or none execute at all.

Owned contracts

Settlement model

A settlement consists of one or more flows, each specifying a sender, receiver, token, and amount. Any number of participants can be involved, and a single settlement can contain multiple token flows across different ERC20 tokens.

Flow types

Local flows are validated for ERC20 compliance before execution. External flows skip token introspection -- they serve as a coordination record for legs that settle on other networks.

Approval system

Each sender in a local flow must explicitly approve the settlement before execution can proceed. The approval system provides:

• Per-sender approvals -- each party approves the entire settlement, not individual flows
• Revocation support -- any sender can revoke approval before execution
• Auto-execution option -- when enabled, execution triggers automatically once all local approvals (and hashlock, if applicable) are satisfied

Only senders in local flows must provide ERC20 allowances and approvals. Senders appearing only in external flows do not need to approve on this chain.

Hashlock coordination

When any flow targets an external chain (externalChainId != 0), the settlement requires a shared hashlock for cross-chain coordination:

1. Creation -- the settlement creator provides a hashlock (hash of a secret) when any flow is external
2. External HTLC -- counterparties deploy Hash Time-Locked Contracts on external chains using the same hashlock
3. Secret reveal -- once the secret is revealed on the external chain, anyone can call revealSecret(bytes secret) on the settlement contract. This is permissionless -- counterparties cannot block completion once the secret is public.
4. Execution gate -- local transfers execute only after both conditions are met: all local approvals received AND hashlock satisfied

For pure local settlements (all flows have externalChainId = 0), the hashlock is optional and can be omitted entirely.

Roles

There is no dedicated admin role on the settlement itself. Once created, the settlement's terms are immutable -- the creator cannot modify flows or parameters after deployment.

Trust boundaries

• Atomic execution -- all local flows execute in a single transaction or none execute. There is no intermediate state where some transfers have completed and others have not.
• Expiration safety -- every settlement has a configurable expiration date. After expiration, the settlement cannot execute and no funds are at risk of being locked indefinitely.
• ERC20 allowance verification -- local flows are validated for sufficient token allowances before execution. External flows do not require local allowances.
• Withholding protection -- the permissionless revealSecret function prevents any single party from blocking settlement completion by withholding the hashlock secret.

Dependencies

Configuration surface

Failure modes

Related

• XvP settlement flow for the step-by-step execution sequence
• Capabilities layer overview for how capabilities extend the platform
• SMART Protocol integration (ERC-3643) for the compliance framework
• Component catalog for the full platform inventory