HTLC explained
Understand how Hash Time-Locked Contracts coordinate XvP settlement legs with a shared secret and cutoff dates.
Hash Time-Locked Contracts (HTLCs) coordinate settlement legs with a shared secret and a deadline. In DALP XvP, an HTLC hashlock links the local settlement leg to an external leg, while the cutoff date prevents assets from staying locked forever.
HTLC requirements by flow type
An XvP settlement can contain local flows, external flows, or a mix of both. The HTLC requirement differs by type.
| Flow type | What DALP records | HTLC requirement |
|---|---|---|
| Local flow | The on-chain asset, sender, recipient, and amount managed by the DALP settlement contract | A hashlock is optional when every flow is local |
| External flow | The asset, sender, recipient, amount, external chain ID, and external asset decimals for the outside leg | The settlement requires a secret or precomputed hashlock |
The hashlock does not move assets by itself. The hashlock makes one secret usable across linked settlement legs. DALP validates the secret against the hashlock on the local settlement contract. The other chain or external system must use the same secret and safe timing for the exchange to complete.
The two controls
Hashlock
A hashlock is a 32-byte keccak256 hash of a secret value. It lets parties commit to a shared secret without revealing the preimage:
hashlock = keccak256(secret)The settlement can store the hashlock before the secret is public. When a party later reveals the secret, the contract hashes it and checks that it matches the stored hashlock. The public hashlock lets parties coordinate without sharing the secret early, because the preimage stays private until the owner is ready for the linked leg to execute.
Cutoff date
The cutoff date is the settlement deadline. Before the cutoff date, an approved settlement executes once the hashlock condition clears. After the cutoff date passes, the contract no longer accepts secret reveals, and any escrowed assets can be withdrawn instead of staying locked indefinitely.
For external XvP flows, cutoff dates must leave enough time for the receiving party to use the secret on the other leg. The staggering rule is directional: the settlement where the secret is revealed first should carry a later cutoff. If a party claims assets on the first chain after seeing the secret, the receiving settlement on the second chain must still accept reveals before its own cutoff expires.
Example exchange
A bank sells tokenised bonds for stablecoins across two EVM networks:
| Leg | Asset movement | Chain context | Timing role |
|---|---|---|---|
| Bond leg | Bank sends BOND to Investor | DALP local settlement | Must remain open after the stablecoin leg reveals the secret |
| Stablecoin leg | Investor sends USDC to Bank | External settlement leg | Reveals the secret first |
The bank generates a secret and shares only the hashlock with the investor. Both settlement legs use the same hashlock.
The sequence works because the bond leg remains open after the stablecoin leg reveals the secret. If the bond leg expired first, the bank could withdraw the bonds and still use the secret on the stablecoin leg. That timing would leave the investor exposed.
What happens when the secret is revealed
When you reveal a secret for a DALP XvP settlement, the platform checks the local settlement state before execution.
| Check | Required condition |
|---|---|
| Secret match | The provided secret hashes to the settlement hashlock |
| Sender approval | All local senders have approved the flows they send |
| Cutoff date | The settlement is still before its cutoff date |
| Auto-execute | If enabled, the settlement executes after the platform accepts the secret |
The XvP create API accepts either a raw secret or a precomputed hashlock for cross-chain flows. The hashlock must be a 0x-prefixed 32-byte hex string. Local-only settlements do not require a hashlock.
autoExecute defaults to false in the API schema. With auto-execute off, revealing the secret makes the settlement ready for execution, but a caller must trigger execution separately.
Failure modes
| Scenario | Local settlement outcome | What to do |
|---|---|---|
| No party reveals the secret | The settlement remains locked until the cutoff date | Withdraw after expiry |
| A local sender does not approve | The settlement cannot execute | Collect the missing approval or cancel the settlement where the workflow allows cancellation |
| A party reveals the secret too late on another leg | The receiving party may not have enough time to act locally | Use safer cutoff-date buffers before creating the exchange |
| A party submits the wrong secret | The hashlock check fails | Use the original preimage that produced the stored hashlock |
How to coordinate safely
Before you create or approve an HTLC settlement:
- Treat the secret as a settlement credential until you are ready to reveal it.
- Use the same hashlock on every linked leg.
- Confirm that each receiving leg stays open after the secret becomes visible.
- Keep enough operational time for network confirmation, wallet approval, and incident response.
- Run the external-flow verification checklist before you rely on an off-platform leg.
Related
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 settlement walkthrough
Follow a multi-party HTLC settlement where two DALP settlements use the same hashlock to coordinate token and USDC flows across Ethereum and Polygon.