Overview
Local settlements execute all asset transfers atomically on a single blockchain. Learn when to use local settlements and how the approval workflow operates.
Local settlements handle multi-party asset exchanges where every asset exists on the same blockchain. The settlement contract escrows sender assets during approval, then executes every flow in one transaction after all required sender approvals are in place.
When to use local settlements
Use local settlements when:
- All assets being exchanged are on the same blockchain.
- The settlement does not need cross-chain coordination.
- Every sender can approve the assets they contribute before the cutoff date.
For exchanges involving assets on different chains, see HTLC settlements.
How local settlements work
- Creator defines flows. Specify each transfer: the asset, amount, sender, and recipient.
- Senders approve. Each sender locks the assets they contribute into the settlement contract.
- Settlement executes. The settlement executes automatically after all approvals when auto-execute is enabled, or after a manual execution trigger when auto-execute is disabled.
- Assets are distributed. Recipients receive their assets in the same execution transaction.
Only senders approve
Only parties who send assets need to approve. Recipients do not approve unless they also send assets in another flow.
State diagram
Local settlements follow this lifecycle:
| State | Description |
|---|---|
| Pending | Settlement created and waiting for sender approvals. |
| Ready | All senders approved and the settlement can execute. |
| Executed | All flows completed successfully in one transaction. |
| Cancelled | Settlement cancelled before execution. Locked assets return to their senders. |
| Expired | Cutoff date passed before execution. Locked assets can be withdrawn through the expiry flow. |
Auto-execute behavior
Auto-execute is a settlement setting. When it is enabled, the settlement executes as soon as all senders approve. No manual execution step is required.
When auto-execute is disabled, anyone can manually trigger execution after all sender approvals are received. This leaves room for a final review before committing the flows.
Cancellation rules
A local participant is any address that sends or receives assets in a local flow. Any local participant can cancel an open local settlement before execution. When cancelled, all locked assets return to their original senders. See how to cancel a settlement.
For HTLC settlements that include external flows, cancellation has stricter conditions after every local sender has approved. See HTLC settlements before using local settlement cancellation rules for a cross-chain workflow.
Example scenario
Corporate bond trade with broker fee:
- Investment Bank holds 1,000 corporate bonds (CORP-BOND).
- Asset Manager wants to purchase them for 100,000 USDC.
- Broker facilitated the trade and receives a 500 USDC fee.
The settlement includes three flows:
- Investment Bank to Asset Manager: 1,000 CORP-BOND.
- Asset Manager to Investment Bank: 100,000 USDC.
- Asset Manager to Broker: 500 USDC.
The Broker creates the settlement defining all three flows. The Investment Bank approves flow 1 and locks its bonds into the contract. The Asset Manager approves flows 2 and 3 and locks 100,500 USDC total. Once all approvals are received, the settlement executes. The Asset Manager receives bonds, the Investment Bank receives payment, and the Broker receives the fee in the same transaction.
For a complete walkthrough with balance tracking, see the local settlement walkthrough.
Further reading
XvP execution models
Clarify what DALP executes for local XvP settlement, what it records for external-flow settlement, and which off-chain checks remain outside the settlement contract.
Walkthrough
Follow a complete example of a local settlement where a Builder sells property tokens to a Buyer, with a Notary receiving a fee.