# Overview
Source: https://docs.settlemint.com/docs/operators/system-addons/xvp-settlement/overview
XvP Settlement coordinates multi-party asset exchanges for DALP assets. Local
settlements execute all local flows in one transaction; external-flow settlements
use hashlocks and secrets to coordinate with a leg that stays outside the local execution.
XvP Settlement coordinates asset-for-asset exchanges between two or more parties. The platform supports local settlements where every flow executes on the same chain, and external-flow settlements where DALP executes the local leg and uses a hashlock secret to coordinate with a leg outside that execution.
Read this page before the detailed setup and API reference pages if you are a platform operator, asset issuer, or integration team deciding which settlement pattern to configure.
Use this overview to decide whether your settlement can stay fully local or must depend on an external rail, chain, custodian, ledger, or counterparty process.
The operator owns the settlement design: which assets move, which senders must approve, which cutoff date applies, and whether any external leg can honour the same hashlock and timing. DALP owns the configured local flow, approval state, expiry path, and execution outcome.
## What XvP provides [#what-xvp-provides]
XvP gives operators one record for a controlled exchange. Participants use that record to follow the settlement from proposed flows through sender approvals to final execution or expiry.
The settlement record does not remove the external operating model. Before you create a settlement, decide which system owns pricing, custody confirmation, and reconciliation. That system must also handle external-chain evidence and fee handling independently.
| Need | DALP-owned part | Operator-owned part |
| -------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Same-chain exchange | DALP records the local flows, collects sender approvals, and executes the flows together. | Confirm each sender's token balance and transfer permissions, and set the cutoff date. |
| External-flow coordination | DALP records the external-flow reference and coordinates the local leg through the hashlock or secret path. | Run and evidence the external rail or counterparty process that honours the same hashlock and timing. |
| Settlement evidence | DALP exposes the local settlement state and local execution outcome. | Combine that evidence with external confirmations when the exchange depends on a leg outside DALP. |
## Scope and settlement patterns [#scope-and-settlement-patterns]
The `X` in XvP is the variable leg of the exchange. In DALP, the same primitive can support delivery-versus-payment and payment-versus-payment patterns when the exchanged assets use DALP-compatible token contracts.
| Pattern | Typical use | What DALP coordinates |
| -------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Delivery versus payment | A bond, fund unit, or equity token moves against a tokenised cash leg | Asset flows and sender approvals through to expiry and local execution |
| Payment versus payment | One tokenised cash asset moves against another | Multi-party token flows and approval state |
| External-flow coordination | A local DALP leg depends on a leg outside the local execution | The local flow, external-flow reference, hashlock, secret reveal, and expiry path |
DALP does not make an external rail or another blockchain settle by itself. For external-flow settlements, the off-chain leg remains a referenced coordination leg. Operators still need the external system or counterparty process that honours the same hashlock and timing.
## Choose a settlement mode [#choose-a-settlement-mode]
Start with the settlement model before you use the API reference. The reference pages describe the API steps, but the mode determines which approvals, expiry path, and execution path apply.
| If you need to... | Use this path | Why it comes first |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Decide which settlement type to configure | [Choose a settlement type](/docs/operators/system-addons/xvp-settlement/choose-settlement-type) | The mode decides whether DALP executes every flow locally or coordinates a local leg with an external leg. |
| Check the execution boundary | [XvP execution models](/docs/operators/system-addons/xvp-settlement/execution-boundaries) | Responsibility checks clarify which duties belong to DALP and which belong to the operator's external-flow, fee, ledger, and evidence systems. |
| Run a same-chain exchange | [Local settlements](/docs/operators/system-addons/xvp-settlement/local/overview) | Local settlements cover sender approvals and escrow. They also explain cancellation, expiry, and how atomic execution behaves. |
| Coordinate an external-flow exchange | [HTLC settlements](/docs/operators/system-addons/xvp-settlement/htlc/overview) | HTLC settlements explain hashlocks, secret reveal, timelock coordination, and per-chain responsibility. |
| Stop or recover a settlement | [Cancel or recover a settlement](/docs/operators/system-addons/xvp-settlement/cancel-or-recover) | Cancellation and expiry recovery depend on the mode, approval state, cutoff date, and HTLC secret state. |
| Find the API call for the next step | [Settlement API reference](/docs/operators/system-addons/xvp-settlement/actions/create) | Use the API reference after the settlement type and current state are clear. |
### Compare local and HTLC settlements [#compare-local-and-htlc-settlements]
| Mode | When to use it | Execution model | Follow-up page |
| ------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| Local settlement | All executable flows are on the same chain and use DALP-compatible token contracts | Senders approve the flows. When the settlement executes, the local flows complete together or the transaction reverts. | [Local settlements](/docs/operators/system-addons/xvp-settlement/local/overview) |
| External-flow settlement | The local DALP leg depends on a referenced leg outside the local execution | DALP stores the external-flow reference, derives or accepts a hashlock, and uses secret reveal to coordinate the local settlement with the external process. | [HTLC settlements](/docs/operators/system-addons/xvp-settlement/htlc/overview) |
Use a local settlement when DALP owns every executable transfer. Use an external-flow settlement when DALP should lock and execute a local leg only after the external side follows the same hashlock coordination.
## Simplest working use [#simplest-working-use]
The simplest XvP settlement has two local flows on the same chain:
1. Create the settlement with `autoExecute`, `cutoffDate`, `country` for V3 identity registration, and a `flows` array where each item has `type: "local"`, `assetId`, `from`, `to`, and `amount`.
2. Each sender approves the settlement for the assets in that sender's flow.
3. Execute the settlement. DALP completes the local flows together. If one required local transfer cannot complete, the transaction reverts instead of leaving a partial exchange.
For an external-flow settlement, add at least one local flow and at least one `type: "external"` flow. Your create request must include either a `secret` or a precomputed `hashlock`. External flows also require `externalChainId` and `externalAssetDecimals` so you can coordinate the referenced leg outside the local execution.
## Key concepts [#key-concepts]
| Term | Meaning |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Flow | One asset transfer: a token moves from a sender to a recipient in a specified amount |
| Local flow | A flow DALP can execute in the local settlement contract |
| External flow | A reference to a leg outside the local execution. DALP records its token address, sender, recipient, amount, external chain ID, and external asset decimals for coordination, but does not execute that external leg locally. |
| Approval | A local sender locks the assets for that sender's flow into the settlement contract |
| Hashlock | A 32-byte hash that links a settlement to a secret preimage |
| Secret | The preimage that proves the hashlock and can trigger the external-flow reveal path |
| Cutoff date | The expiry deadline after which operators can use the expiry and withdrawal paths instead of executing the settlement |
## Settlement lifecycle [#settlement-lifecycle]
A settlement starts in `Pending`. Sender approvals move it toward execution. The terminal path depends on whether the settlement executes, is cancelled by a party, or expires at the cutoff date.
| Lifecycle point | Meaning |
| ---------------- | ------------------------------------------------------------------------------------------- |
| Pending | The settlement exists and is waiting for the required sender approvals |
| Ready to execute | A local settlement has the required approvals and can be executed |
| Armed | An external-flow settlement has the required approvals and waits for the secret reveal path |
| Executed | The executable local flows completed successfully |
| Cancelled | The settlement was cancelled before execution |
| Expired | The cutoff date passed before execution |
Local settlements and external-flow settlements share the same high-level lifecycle, but the reveal and withdrawal
paths differ. Read the mode-specific overview before running an operational procedure.
## Operational checks before creating a settlement [#operational-checks-before-creating-a-settlement]
* Confirm the XvP Settlement add-on is installed for the target system.
* Confirm each local sender has sufficient balance and the wallet-verification status needed to approve its flow.
* Set a cutoff date that gives all parties enough time to approve or reveal the secret before expiry.
* For external-flow settlements, agree the secret or hashlock process with the counterparty before creating the settlement.
* Keep the external leg outside the DALP settlement record unless your external system can prove that it followed the same hashlock and expiry window.
## Further reading [#further-reading]
Single-chain settlements where DALP executes all flows together. Read this for sender approvals, escrow behaviour, cancellation rules, and how atomic execution works when one transfer cannot complete.
Settlements where one leg depends on an external chain or counterparty. Covers hashlocks, secret reveal, and timelock coordination.
API calls for every stage of a settlement, from creation through approval and execution to cancellation. Use this after choosing the settlement model.
Stop or recover a settlement. The available paths depend on mode and current approval status.