XvP settlement flow
How the DALP XvP settlement flow executes atomic multi-party token exchanges, from settlement creation through approval collection and optional hashlock coordination for external-chain legs to all-or-nothing execution.
System context
XvP settlement coordinates approvals and token legs before the settlement contract executes the exchange. The flow depends on the standard signing and compliance-transfer paths, then records settlement state for operators and auditors.
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 token exchanges between multiple parties. For local flows, approving the settlement locks the sender's net required amount in escrow. Execution then releases all local net positions in one transaction. If execution cannot complete, the full execution transaction reverts and the settlement remains open until it is executed, cancelled, or expires. For flows that reference another chain, DALP uses a hashlock to coordinate the local execution gate with the external workflow instead of claiming native cross-chain finality.
Managing settlements
Operators can manage XvP settlements through the Asset Console, API, or CLI:
- Asset Console: list settlements for an XvP add-on factory, open a settlement detail page, review flows and approvals, and run eligible actions such as approve, revoke approval, execute, cancel, withdraw expired settlements, decrypt stored secrets, and reveal secrets.
- API: use the XvP settlement endpoints to create, list, read, approve, revoke approval, execute, cancel, withdraw cancellation requests, withdraw expired settlements, reveal a secret, or decrypt a stored settlement secret.
- CLI: use the
xvp-settlementscommand group for the same operational surface when automating or testing settlement workflows from a terminal.
Use the same business checks before each channel: confirm the settlement address, participants, flow amounts, expiration, approval status, and whether the settlement is local-only or uses hashlock coordination for external-chain legs.
Happy path: local settlement
- Initiator creates settlement: the settlement contract is deployed with a set of flow definitions. Each flow specifies a token address, sender, receiver, amount,
externalChainId, and external asset decimals. An expiration timestamp is set at creation and does not change. - Senders grant ERC20 allowances: each sender in a local flow calls
approve()on the relevant token contract, granting the settlement contract permission to lock their net required token amount. - Senders approve the settlement: each sender calls
approve()on the settlement contract itself. That approval locks any required local escrow and records the sender approval. A sender appearing in several local flows gives one settlement approval. - Execution gate is satisfied: once all local senders have approved and any required hashlock secret has been revealed, the settlement is eligible for execution. If auto-execution is enabled, this can happen immediately.
- Local net positions settle together: local execution debits locked escrow from net senders and transfers tokens to net receivers in one transaction. If any transfer fails because of token-contract or compliance behaviour, the entire execution transaction reverts.
- Settlement is marked executed: the settlement contract records the executed state. No further approvals, revocations, cancellations, or executions are possible.
External-chain hashlock lifecycle
When a settlement includes flows with externalChainId != 0, the hashlock coordinates the local settlement gate with an external-chain workflow:
- Settlement created with hashlock: the initiator provides a
hashlock, which is the hash of a secret. A hashlock is required when any flow targets an external chain. - External HTLC deployment: counterparties on external chains deploy Hash Time-Locked Contracts using the same hashlock. Those contracts lock the external-chain tokens for the matching off-platform workflow.
- Secret revealed externally: when the external HTLC executes, the secret, also called the preimage, becomes visible on that chain.
- Secret revealed to DALP: once all local senders have approved, anyone can call
revealSecret(bytes secret)on the settlement contract. The contract accepts the secret only when itskeccak256hash matches the settlement hashlock. - Local execution proceeds: with the hashlock satisfied and all local approvals collected, the settlement can execute its local flows.
For pure local settlements where every flow has externalChainId = 0, the execution gate requires local approvals. Revealing a secret is not required.
Approval and state controls
| Control | What it means | Operator check |
|---|---|---|
| Per-sender approval | Each local sender approves the settlement, not each individual flow. | Confirm every local sender has an approval before execution. |
| Revocation | A sender can revoke approval before execution. For external settlements, revocation is blocked after the settlement reaches the committed state with all local approvals in place. | Check whether the settlement is still active and revocation is allowed before asking a signer to revoke. |
| Cancel vote | Participants can propose cancellation and withdraw a cancel proposal while cancellation is still allowed. | Check active cancel votes before treating a settlement as ready. |
| Expired withdrawal | After expiry, escrowed assets can be released through the expired-withdrawal path. | Confirm the cutoff timestamp has passed and the withdrawal has not already been processed. |
| Auto-execution | When auto-execution is enabled, execution can start as soon as approval and hashlock gates are satisfied. | Treat the final required approval or secret reveal as a possible execution trigger. |
Failure modes
| Failure mode | Platform behaviour | Operator response |
|---|---|---|
| Settlement expired | Approval and execution attempts are rejected after the cutoff timestamp. | Use the expired-withdrawal path where escrowed assets need to be released. |
| Insufficient ERC20 allowance | The sender's settlement approval reverts before the missing escrow can be locked. | Ask the sender to approve the settlement contract for the required token amount. |
| Missing local approval | Execution is blocked until every local sender has approved. | Collect the missing approval or cancel the settlement if the parties will not proceed. |
| Hashlock not satisfied | External-chain settlements cannot execute locally until the correct secret is revealed. | Reveal the preimage once it is available from the external workflow. |
| Invalid secret | The settlement rejects a secret whose keccak256 hash does not match the hashlock. | Verify the external-chain preimage before retrying. |
| Token transfer failure | If a token contract or compliance module rejects one local transfer, the execution transaction reverts. | Resolve the token, allowance, or compliance issue, then retry execution while the settlement remains active. |
XvP settlement contracts can be operated through the Asset Console, API, and CLI. Local flows execute atomically on the current chain. External-chain legs use hashlock coordination and need the matching external workflow to reveal the shared secret before local execution can proceed. DALP does not make the external chain native to the local settlement contract.
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
Treasury Distribution
How DALP fixed treasury yield uses a configured treasury address to fund holder-initiated claims for completed yield periods.
Integration overview
Overview of DALP's integration architecture covering documented provider surfaces and configurable project-specific integrations across custody, compliance, networks, market data, storage, secrets, payments, wallets, ERP, and security controls.