Overview
HTLC settlements coordinate asset exchanges across different blockchains using hash time-locked contracts. Learn when to use HTLC and how cross-chain coordination works.
HTLC (Hash Time-Locked Contract) settlements enable coordinated asset exchanges when tokens exist on different blockchains. A cryptographic hash links the settlements on each chain, ensuring either both sides execute or neither does.
When to use HTLC settlements
Use HTLC settlements when:
- Assets being exchanged exist on different blockchains
- You need trustless coordination without a central intermediary
- Cross-chain atomic guarantees are required
For exchanges where all assets are on the same chain, use local settlements instead.
How HTLC settlements work
HTLC settlements use two linked components:
- Hashlock - A cryptographic hash that links settlements across chains
- Timelock - A deadline after which the settlement expires
One party generates a secret and shares only the hash (hashlock) with others. Settlements on each chain are created with the same hashlock. When the secret is revealed on one chain, it becomes public and can be used to execute settlements on all linked chains.
The "Armed" state
HTLC settlements have a unique state called "Armed" that occurs after all local senders approve but before the secret is revealed:
| State | Description |
|---|---|
| Pending | Settlement created, waiting for sender approvals |
| Armed | All senders approved, waiting for secret to be revealed |
| Executed | Secret revealed, all flows completed |
| Cancelled | Settlement cancelled before armed |
| Expired | Cutoff date passed before secret was revealed |
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 don't execute locally. They serve as documentation of what should happen on the other chain. Each party is responsible for creating and managing the settlement on their respective chain.
External flow purpose
External flows help all parties understand the complete transaction structure. They don't transfer any assets.
Auto-execute behavior
When auto-execute is enabled (the default), the settlement executes automatically when:
- All local senders have approved (settlement is Armed)
- The correct secret is revealed
If auto-execute is disabled, someone must manually trigger execution after the secret is revealed.
Timelock coordination
For cross-chain safety, timelocks must be staggered:
- The settlement where the secret is revealed first should have a later timelock
- This gives the other party time to use the revealed secret before their settlement expires
For a detailed explanation of how hashlocks ensure security, see HTLC explained.
Cancellation rules
| Situation | Cancellation possible? |
|---|---|
| Before secret revealed | Yes - if ALL local participants (both senders and recipients) propose cancellation |
| After secret revealed | No - cancellation is not allowed |
Unanimous cancellation required
HTLC settlements can be cancelled only if ALL local participants (both senders and recipients) send a cancellation vote before the secret is revealed. Once unanimous consent is reached, the settlement is cancelled and 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 to swap atomically across chains
The Bank creates the Ethereum settlement with a hashlock. The Investor creates a matching settlement on Polygon with the same hashlock. After both settlements are Armed, the Bank reveals the secret on Polygon to claim USDC. The Investor then uses that secret on Ethereum to claim BOND tokens.
For a complete multi-party example with balance tracking, see the HTLC walkthrough.
Further reading
Walkthrough
Follow a complete example of a local settlement where a Builder sells property tokens to a Buyer, with a Notary receiving a fee.
HTLC explained
Understand how Hash Time-Locked Contracts enable trustless cross-chain asset exchanges. Learn about hashlocks, timelocks, and why the mechanism is cryptographically secure.