HTLC settlements
Use HTLC settlements to coordinate EVM asset exchanges across chains with a shared hashlock, local settlement controls, and party-managed secret reveal before each cutoff date.
HTLC (Hash Time-Locked Contract) settlements coordinate asset exchanges when tokens sit on different EVM networks. Each DALP settlement controls only the flows on its own chain. A shared hashlock links the matching settlements so the same secret can unlock each chain's local execution before that settlement reaches its cutoff date.
Read this page before you configure or review an HTLC settlement.
DALP enforces local-chain controls. The parties coordinate the cross-chain steps. The lifecycle can move through pending, armed, ready, executed, cancelled, or expired.
DALP controls local approvals, escrowed local flows, secret reveal, execution, cancellation, expiry, and withdrawal on the chain where the settlement exists.
The parties that create the matching settlements coordinate the cross-chain parts: choosing the shared hashlock, setting safe timelocks, revealing the secret on the intended chain, and reusing the revealed secret before the matching settlement expires.
HTLC settlement docs do not cover bridge transfers, non-EVM networks, off-chain asset movement, or execution of another chain's settlement from the local contract. For single-chain exchanges, use local settlements instead. For the protocol mechanics, read HTLC explained next. For an end-to-end setup example, read the HTLC walkthrough.
When to use HTLC settlements
Use HTLC settlements when the assets being exchanged exist on different EVM networks and each chain needs its own settlement. Both settlements share one hashlock so participants can reuse the revealed secret to unlock the matching settlement on another chain before expiry.
How HTLC settlements work
HTLC settlements use two linked components:
- Hashlock: a 32-byte keccak256 hash that links settlements across chains.
- Timelock: the cutoff timestamp after which that settlement expires.
One party generates a secret and shares only the hashlock with the other participants. The matching settlement on each chain uses the same hashlock. DALP can also derive the hashlock from a supplied secret during creation.
After all local senders approve, any caller with the correct secret can reveal it.
With auto-execute enabled, DALP executes the local flows after reveal. With auto-execute disabled, the settlement stays ready until a caller triggers execution separately.
The "Armed" state
HTLC settlements become armed after every local sender has approved, but before the secret is revealed. At that point, the local settlement is locked behind the hashlock and cutoff date while the parties finish the matching chain.
| State | Description |
|---|---|
| Pending | Settlement created, waiting for local sender approvals |
| Armed | All local senders approved, waiting for the matching secret reveal |
| Ready | Secret revealed, execution conditions satisfied, execution still available |
| Executed | Local flows completed |
| Cancelled | Settlement cancelled before completion |
| Expired | Cutoff date passed before the secret was revealed or execution completed |
External flows
HTLC settlements include two types of flows:
- Local flows: execute on the current chain when the settlement completes.
- External flows: informational references to assets on other chains.
External flows do not execute locally. They describe the assets and counterparties the other chain's settlement involves. Each party still operates its own settlement independently: create, approve, reveal, execute, cancel, or withdraw on that chain.
Auto-execute behavior
Auto-execute is an explicit settlement setting that you configure at creation time. When auto-execute is enabled, the settlement executes after both conditions are true:
- Every local sender has approved the settlement.
- The correct secret has been revealed.
If you leave auto-execute off, any caller can trigger execution after those conditions are met.
The Platform API and settlement wizard default this setting to off. Enable auto-execute only when you want the settlement to execute as soon as approval and secret reveal are both complete.
Timelock coordination
For cross-chain safety, timelocks must be staggered:
- The settlement where the secret is revealed first should have the later cutoff.
- The matching settlement should leave enough time for the other party to reuse the revealed secret before expiry.
Before you approve or reveal a secret, check that both settlements use the same hashlock, that each local flow is on the expected chain, and that the earlier cutoff still leaves enough time to reuse the revealed secret. See verify external flows for the operator checklist.
For a detailed explanation of how hashlocks protect the exchange, see HTLC explained.
Cancellation rules
| Situation | Cancellation possible? |
|---|---|
| Before all local senders approve | Yes. A local participant can cancel while the settlement is still pending. |
| Armed, before secret reveal | Yes, after every local participant has proposed cancellation. |
| After secret reveal | No. Cancellation is no longer allowed. |
Example scenario
In this example, an investor holds 100,000 USDC on Polygon and a bank holds 1,000 BOND tokens on Ethereum. Both parties want to exchange assets without moving them to a shared network. Each party creates a settlement on its own chain, both referencing the same hashlock.
The bank creates the Ethereum settlement with a hashlock. The investor opens a matching Polygon settlement with the same hashlock. After both settlements are armed, the bank reveals the secret on Polygon to unlock the USDC settlement. The investor then reuses the revealed secret on Ethereum to unlock the bond settlement.
For a complete multi-party example with balance tracking, see the HTLC walkthrough. For a focused operator check before approval or secret reveal, see verify external flows.
Further reading
Use the related HTLC pages in this order when you move from concept to operation:
Learn the hashlock, secret reveal, timelock, expiry, and refund mechanics behind this overview. Use this page before you configure your first HTLC settlement.
Configure and execute the multi-party cross-chain example with balance tracking.
Check chain IDs, external assets, hashlocks, cutoff timing, approvals, and secret reveal before execution.
Local settlement walkthrough
Follow a complete example of a local settlement where a Builder sells property tokens to a Buyer, with a Notary receiving a fee.
How HTLC works in XvP settlements
Understand how Hash Time-Locked Contracts coordinate XvP settlement legs with a shared secret and cutoff dates.