Skip to main content

Hash time-locked contracts

Each leg of a swap is an HTLC escrow with two ways out:
  • Claim: anyone presenting the secret whose sha256 equals the hashlock releases the funds to the leg’s recipient.
  • Refund: after the leg’s timelock, the funds go back to the funder.

sha256 on every chain

Both legs use the same hashlock, sha256(secret), and the secret is 32 bytes.
  • Why sha256: Bitcoin Script has OP_SHA256 but no keccak. Using sha256 everywhere lets one secret open a Bitcoin P2WSH escrow and an EVM, TRON or Solana escrow alike. The EVM and TRON contracts compute sha256, not keccak256.
  • Why exactly 32 bytes: the EVM and TRON contracts take the secret as bytes32, and the Solana program enforces the same length. A longer preimage could open one leg but not the other.
  • Format in the API: hashlock is 64 hex characters (no 0x). The secret sent to the claim builder is 32-byte hex.
The initiator generates the secret locally and only sends the hashlock. A hashlock already used by a live swap is refused; generate a new secret for each swap.

Asymmetric timelocks

The two legs do not expire at the same time.
  • The initiator holds the secret and funds the long leg.
  • The counterparty funds the short leg.
The initiator reveals the secret by claiming the short leg. The counterparty then needs time to use that secret on the long leg before the initiator could refund it. If the timelocks were equal, or reversed, the initiator could wait, claim at the last moment and refund their own leg — holding a free option on the trade.

How the server picks them

Each chain has a safe timelock, set from its finality and reorg risk. The current values in the server’s chain config are: Chain keys, contracts and confirmation depths are in Networks. For a pair of chains:
  1. The leg on the chain with the longer safe timelock is the long (initiator) leg. On a tie, leg b — the taker’s — is the long leg.
  2. The short leg gets its chain’s timelock.
  3. The long leg gets max(its chain's timelock, short leg + 2 hours). The minimum gap between the legs is 2 hours.
Examples:
  • BTC ↔ Base: the Bitcoin leg is long at 24 h, the EVM leg is short at 4 h.
  • Base ↔ Solana (tie): the short leg is 4 h, the long leg is 6 h.
Timelocks are fixed when the swap is created and are absolute times. GET /v1/swaps/{id} shows them per leg.

Claiming after the reveal

Once the initiator claims the short leg, the secret is public, and the counterparty must claim the long leg before the long leg’s timelock. After it, the initiator can refund the long leg and would hold both. With the defaults, the long leg’s timelock is at least 2 hours after the short leg’s (20 hours when the long leg is Bitcoin), so that is how long the counterparty has at the least, even when the initiator claims at the last moment of the short leg. On EVM, TRON and Solana, Hashlock’s keeper tries to claim the long leg for the counterparty as soon as it sees the secret. That is a convenience, not a guarantee: if the long leg is still unclaimed as its timelock nears, claim it yourself with the claim builder. A Bitcoin claim needs the receiver’s own signature, so the receiver claims it.

Sequencer outages on Base and Robinhood Chain

Base and Robinhood Chain are L2s: one sequencer orders their transactions. While it is down, transactions on that chain are delayed, claims included, and the outage comes out of the claim window, because timelocks are absolute.
  • Base allows forced inclusion of a transaction through Ethereum L1, but it can take up to about 12 hours.
  • Robinhood Chain offers no forced inclusion that fits inside a claim window.
An outage longer than the time left before a leg’s timelock can make its claim late. The contract refuses a claim after the timelock, and the funder can then refund that leg. The keeper retries a failed claim for at least 10 minutes and then gives up unless something re-triggers it, so after a longer outage the counterparty should send the claim itself once the chain accepts transactions again. Timelocks on Base and Robinhood Chain are the same as on Ethereum; size deals with a leg on either with that in mind.
On Bitcoin, a refund’s timelock is measured against the chain’s median time past, which trails real time. A refund built just after the timelock may be rejected by nodes as non-final; the refund builder says so and tells you how far behind the chain clock is.
TRON ↔ TRON swaps are not offered: one side of the pair must be on another chain.