HTLC primer

The cryptographic pattern that makes a cross-chain swap atomic, in plain terms.

If you have not built with hashed-timelock contracts before, this page gives you the idea in enough depth to read the rest of the documentation. If you have, you can skip it.

The problem

Imagine you and a counterparty want to exchange assets. You have an asset on chain A; they have an asset on chain B. Neither chain knows about the other. Neither of you trusts the other to send first — whoever sends first risks the other party walking away.

A traditional fix is to introduce a custodian: both of you send to a trusted middle party, who confirms both sides arrived and then forwards. This works but it concentrates trust and creates a custody point.

A hashed-timelock contract removes the custodian. The trust is replaced with two pieces of math.

The two pieces of math

1. A hash binds the two transactions

You pick a random secret s. You compute h = sha256(s). You give h to your counterparty. You both lock your assets in a contract on your respective chains that says: whoever can present a value whose SHA-256 hash equals h can claim this asset.

You alone know s. Your counterparty does not — they only know h.

To claim your counterparty's asset on chain B, you submit s. The contract checks sha256(s) == h, sees it does, and releases the asset to you. But — and this is the key step — submitting s to chain B made s public. Anyone watching chain B's transactions can now read s.

Your counterparty was watching. They take s, submit it to your lock on chain A, and claim your asset.

Two transactions, one secret, both sides moved.

2. A time-lock provides an exit

What if you change your mind, or your counterparty does not lock their side? You don't want your asset stuck forever. Each lock includes a time-lock: an absolute deadline after which the original locker can take their asset back.

The two time-locks are not equal. The one on the chain where the secret is revealed second (the chain whose claim happens second) is set later than the one where the secret is revealed first. That way, the party who claims second has a strictly shorter window — they cannot wait for their own time-lock to pass, refund, and also keep what the first claim already gave them.

The resulting safety property

Combining the two:

• If both parties claim, both have moved.

• If one party claims and the other does not, the claiming party has the other's asset, and the non-claiming party can refund.

• If no one claims, both parties refund.

There is no path that leaves one side moved and the other not. That is the atomic-swap property.

What it relies on

• The hash function must be collision-resistant. SHA-256 is what's used here. A break in SHA-256 would compromise the protocol.

• The two chains must enforce their own time-locks. Both Canton and Ethereum do.

• The time-locks must be asymmetric. The Cross-Chain Swap Engine sets the Canton-side time-lock strictly later than the Ethereum-side time-lock.

• The party that claims second must monitor for the secret's revelation in time. A party that doesn't notice the secret was revealed could miss their claim window. The protocol mitigates this by giving the second-claiming party a strictly shorter exposure window so the asymmetry favours them.

What it does not require

• It does not require trust between the user and the counterparty. The math enforces the property.

• It does not require an intermediary to custody assets. Each lock is on its own chain, controlled by its own contract.

• It does not require either chain to know about the other. The shared hashlock is the only off-chain bridge between them.

• It does not require either chain to support new cryptography. SHA-256 is a primitive both chains compute natively.

Where to next

• Security model — the three mechanical properties in detail.

• Atomic swap protocol — the actual five-step walkthrough.

• Counterparties — who provides the liquidity to take the other side.