XvP Settlement

XvP Settlement coordinates token exchanges between parties as an execution primitive, not a venue, matching engine, bridge, or compliance decision point. Upstream systems must resolve price discovery, order matching, participant eligibility, and compliance policy before a settlement is created.

The settlement contract guarantees that either every local flow executes in one transaction or every local flow reverts. External flows are references to legs on other chains. DALP records their parameters and can gate local execution on a shared hashlock secret. DALP does not make separate chains execute as one atomic transaction.

Owned contracts

Settlement model

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

Every settlement must include at least one local flow. That keeps the XvP contract responsible for at least one token movement on the active chain instead of acting as a pure off-chain coordination record.

Flow types

DALP validates local flows before execution. External flows include an external chain ID and external asset decimals so operators can reconcile the referenced leg. External flows skip local token introspection and do not move tokens on the active chain.

Creation inputs

The create API accepts the XvP factory address, name, auto-execution flag, future cutoff date, and flow array. External-flow settlements must include either a raw secret or a precomputed hashlock. Local-only settlements do not require either value.

Current XvP factories that use identity registration also require an ISO 3166-1 numeric country code for the settlement contract identity. The create response returns the transaction hash and created settlement contract address.

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 uses type: "external", the settlement requires a shared hashlock for coordination:

1. Creation -- the settlement creator provides either the raw secret or its hashlock when any flow is external
2. External HTLC -- counterparties run the matching workflow on the external chain using the same hashlock
3. Secret reveal -- once the secret is available, anyone can submit it to the settlement. Counterparties cannot block local 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, 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

• Local atomic execution -- all local flows execute in a single transaction or none execute. There is no intermediate local-chain state where some transfers have completed and others have not.
• External-leg coordination -- external flows are referenced for coordination and reconciliation. Their lock, release, and recovery behaviour is handled by the matching external-chain workflow, not by the DALP settlement contract on the active chain.
• 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 require sufficient token allowances before execution. External flows do not require local allowances.
• Withholding protection -- the permissionless secret reveal path prevents a party from blocking local execution after the matching secret is public.

Dependencies

Configuration surface

Operator surfaces

XvP settlement operations are exposed through the Asset Console, API, and CLI. The same settlement state is used across those channels: settlement flows, local approvals, cancellation votes, expiration status, stored secret metadata, and execution eligibility.

Use each channel for a different operating mode:

• Asset Console: human operators can review settlement detail, inspect flow and approval status, and trigger the settlement actions available for the current state.
• API: applications can create settlements, list or read settlement state, approve or revoke approval, execute eligible settlements, submit or withdraw cancellation requests, withdraw expired settlements, reveal secrets, and decrypt stored settlement secrets.
• CLI: operators and test workflows can call the xvp-settlements command group for list, read, create, approve, revoke-approval, execute, cancel, withdraw-cancel, withdraw-expired, reveal-secret, and decrypt operations. Withdrawal is split between cancellation-request withdrawal and expired-settlement withdrawal.

For external-chain legs, DALP records the leg parameters and gates local execution on the hashlock secret. DALP does not turn separate chains into one transaction. The external-chain workflow must lock and release the matching leg, then reveal the shared secret so the local settlement can proceed.

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