# XvP settlement flow

Source: https://docs.settlemint.com/docs/architecture/flows/xvp-settlement
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 [#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.

<Mermaid
  chart="`
sequenceDiagram
  participant Client as Operator or API client
  participant DALP as DALP Execution Engine
  participant Compliance as Compliance transfer checks
  participant Settlement as XvP settlement contract
  participant Signer as Signing flow
  participant Chain as SMART Protocol contracts
  participant Indexer as Chain Indexer

  Client->>DALP: Create settlement instruction
  DALP->>DALP: Build payload with flows, parties, expiry, and hashlock when used
  DALP->>Compliance: Check token-leg eligibility
  DALP->>Signer: Sign creation, approval, or execution write
  Signer->>Chain: Broadcast signed settlement transaction
  Chain->>Settlement: Store setup or execute all token legs
  Settlement-->>Chain: Revert the full transaction if any leg fails
  Chain-->>Indexer: Emit settlement state
  Indexer-->>Client: Expose status and evidence

`"
/>

## Related [#related]

* [XvP Settlement](/docs/architecture/components/capabilities/xvp-settlement): contracts, roles, and configuration
* [Signing Flow](/docs/architecture/flows/signing-flow): transaction signing and custody
* [Compliance Transfer](/docs/architecture/flows/compliance-transfer): transfer compliance checks

***

## Flow overview [#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.

![XVP settlement setup](/docs/screenshots/xvp/xvp-setup-1.webp)

## Managing settlements [#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-settlements` command 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 [#happy-path-local-settlement]

<Mermaid
  chart="`
sequenceDiagram
  participant Initiator
  participant Settlement as Settlement Contract
  participant SenderA as Sender A
  participant SenderB as Sender B
  participant Token as Token Contracts
  participant ReceiverA as Receiver A
  participant ReceiverB as Receiver B

  Initiator->>Settlement: 1. Create settlement (flows + expiration)
  SenderA->>Token: 2a. ERC20 approve(settlement, amount)
  SenderB->>Token: 2b. ERC20 approve(settlement, amount)
  SenderA->>Settlement: 3a. approve() locks net escrow
  SenderB->>Settlement: 3b. approve() locks net escrow
  Settlement->>Settlement: 4. All approvals received; execute
  Settlement->>Token: 5a. Release locked escrow to ReceiverB
  Settlement->>Token: 5b. Release locked escrow to ReceiverA
  Token-->>ReceiverB: Tokens received
  Token-->>ReceiverA: Tokens received
  Settlement->>Settlement: 6. Mark executed

`"
/>

1. **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.
2. **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.
3. **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.
4. **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.
5. **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.
6. **Settlement is marked executed:** the settlement contract records the executed state. No further approvals, revocations, cancellations, or executions are possible.

## External-chain hashlock lifecycle [#external-chain-hashlock-lifecycle]

When a settlement includes flows with `externalChainId != 0`, the hashlock coordinates the local settlement gate with an external-chain workflow:

1. **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.
2. **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.
3. **Secret revealed externally:** when the external HTLC executes, the secret, also called the preimage, becomes visible on that chain.
4. **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 its `keccak256` hash matches the settlement hashlock.
5. **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 [#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.                      |

![Active settlement transaction monitoring](/docs/screenshots/xvp/xvp-details-1.webp)

## Failure modes [#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. |

<Callout type="info">
  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.
</Callout>

## Related resources [#related-resources]

* [XvP Settlement](/docs/architecture/components/capabilities/xvp-settlement): contracts, roles, and configuration
* [Signing Flow](/docs/architecture/flows/signing-flow): how transactions are signed and broadcast
* [Compliance Transfer](/docs/architecture/flows/compliance-transfer): transfer validation for compliance-enabled tokens
* [Capabilities overview](/docs/architecture/components/capabilities): how capabilities extend the platform