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:
- Assets being exchanged exist on different EVM networks
- Each chain needs its own local settlement, but both settlements must share one hashlock
- Participants need 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, execution remains a separate step after the settlement is ready.
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 expected on the other chain.
Each party still operates its own chain's settlement: create, approve, reveal, execute, cancel, or withdraw there.
External flow purpose
External flows help all parties read the complete transaction structure. They do not transfer assets from the local settlement contract.
Auto-execute behavior
Auto-execute is an explicit settlement setting. When auto-execute is enabled, a settlement executes after both conditions are true:
- Every local sender has approved the settlement.
- The correct secret has been revealed.
If auto-execute is disabled, anyone can call execution after those conditions are true.
The API and settlement wizard default this setting to disabled. Enable auto-execute only when the workflow should 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. |
Unanimous cancellation required
Once an HTLC settlement is armed, every local participant must send a cancellation vote before the secret is revealed. When the last required vote lands, the settlement is cancelled and escrowed assets are refunded. See how to cancel a settlement.
Example scenario
Cross-chain bond purchase:
- Investor has 100,000 USDC on Polygon.
- Bank has 1,000 BOND tokens on Ethereum.
- They want linked settlements without moving either asset away from its own network.
The bank creates the Ethereum settlement with a hashlock. The investor creates 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:
HTLC explained
Learn the hashlock, secret reveal, timelock, expiry, and refund mechanics behind the overview.
HTLC walkthrough
Configure and execute the multi-party cross-chain example with balance tracking.
Verify external flows
Check chain IDs, external assets, hashlocks, cutoff timing, approvals, and secret reveal before execution.