PvP and DvP settlement hub
When to use local PvP, local DvP, or hashlock coordinated settlement, and how DALP runs approvals and atomic execution for each pattern.
DALP uses XvP settlement to coordinate PvP settlement, DvP settlement, and other tokenized asset exchanges between parties. Use a local flow when every token leg settles on the active EVM chain. Use hashlock coordination when a local DALP leg must wait for confirmation from an external workflow. DALP executes local token legs all-or-nothing, but it does not make external chains settle atomically with the local transaction.
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 so you can review it as an operator or auditor.
Related
- XvP Settlement: contracts, roles, and configuration
- Signing Flow: transaction signing and custody
- Compliance Transfer: transfer compliance checks
Flow overview
XvP means exchange versus payment. It covers the common settlement patterns used for tokenized assets:
| Settlement pattern | Use it when | DALP behaviour |
|---|---|---|
| PvP settlement | Both sides carry tokenized payment, cash, or stablecoin-like legs on the active EVM chain. | DALP locks sender approvals and releases the local token legs together in one execution transaction. |
| DvP settlement | A tokenized asset leg settles against a tokenized payment leg on the active EVM chain. | DALP uses the same approval and execution model, with both local legs completing or reverting together. |
| Hashlock coordinated settlement | One or more referenced legs happen in an external workflow. | DALP waits for the matching hashlock secret before executing the local leg. The external workflow remains outside the local settlement contract. |
For local flows, approving the settlement locks the sender's net required amount in escrow. The platform then releases all local net positions in one transaction. If that transaction cannot complete, it reverts and the settlement stays open until a party executes, cancels, or the expiry timestamp passes. For flows that target another chain, DALP uses a hashlock to gate local execution on the external workflow instead of claiming native cross-chain finality.
Managing settlements
You can manage XvP settlements through the Console, API, or CLI:
- Console: list settlements for an XvP add-on factory, open a settlement detail page, and review flows and approvals. Available operations include 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.
Apply the same checks before each channel: confirm the settlement address, participants, flow amounts, expiry, approval status, and whether the settlement is local-only or uses hashlock coordination for external-chain legs.
Happy path: local settlement
- The initiator creates the settlement. The platform deploys the settlement contract with a set of flow definitions. Each flow specifies a token address, sender, receiver, amount,
externalChainId, and external asset decimals. The expiration timestamp is fixed at creation and does not change. - 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. - Each sender calls
approve()on the settlement contract itself. That approval locks any required local escrow and records the sender. A sender appearing in several local flows gives one settlement approval. - Once all local senders have approved and the caller has revealed any required hashlock secret, the settlement is eligible for execution. When auto-execution is on, it starts immediately.
- Local execution debits locked escrow from net senders and transfers tokens to net receivers in one transaction. If any transfer fails because of a token-contract or compliance check, the entire execution transaction reverts.
- 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:
- The initiator provides a
hashlock(the hash of a secret) when creating the settlement. A hashlock is required when any flow targets an external chain. - 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.
- When the external HTLC executes, the secret (the preimage) becomes visible on that chain.
- Once all local senders have approved, you or any participant can call
revealSecret(bytes secret)on the settlement contract. The contract accepts the secret only when itskeccak256hash matches the settlement hashlock. - 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 only. You do not need to reveal a secret.
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. |
Related resources
- Choose a settlement type: decide whether your workflow needs local or hashlock coordinated settlement before you create it.
- Create a settlement: create the settlement record and define local or external flows.
- Approve a settlement: collect sender approvals before execution.
- Reveal a settlement secret: satisfy the HTLC hashlock before local execution.
- Execute a settlement: manually commit a ready settlement when you have disabled auto-execute.
- Cancel or recover a settlement: handle failed, expired, or abandoned settlement workflows.
- Pending approvals and XvP work queue: operate pending approval and XvP execution items from the operator queue.
- Stablecoin operations lifecycle: understand payment-token operations around settlement flows.
- Transfer approval controls: review compliance gates that can affect token transfers.
- Signing Flow: how transactions are signed and broadcast.
- Compliance Transfer: transfer validation for compliance-enabled tokens.
Treasury Distribution
How DALP fixed treasury yield uses a configured treasury address to fund holder-initiated claims for completed yield periods.
Integrations - External systems and network connectivity
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.