Hash Time Locked Contract

You’re viewing an old version of the Arkade contracts documentation. Go to Your first contract for the current version.

A hash time locked contract (HTLC) pays the receiver if they reveal a secret preimage, and refunds the sender after a deadline. Two HTLCs that share one hash make an atomic swap: when the receiver claims one, the preimage becomes public and unlocks the other. The code uses arkProvider, indexerProvider, serverPubkey, exitTimelock, serverUnrollScript, and hex from Set Up Your Project.

Path	Condition	Use
Claim	Preimage, receiver, operator	The receiver claims
Refund	Sender, operator, after `refundAt`	The receiver never claims
Exit claim	Preimage, receiver, after the exit delay	The operator is unavailable
Exit refund	Sender, after twice the exit delay	The operator is unavailable and the receiver never claims

The exit refund waits longer than the exit claim, so the receiver always has time to claim first.

Build the HTLC

The condition HASH160 <hash> EQUAL checks that the preimage hashes to hash160(preimage), which is RIPEMD160(SHA256(preimage)). Each helper adds VERIFY and the signature checks after it.

import {
  MnemonicIdentity,
  ConditionMultisigTapscript,
  ConditionCSVMultisigTapscript,
  CLTVMultisigTapscript,
  VtxoScript,
  networks,
} from '@arkade-os/sdk';
import { Script } from '@scure/btc-signer';
import { hash160 } from '@scure/btc-signer/utils.js';

const sender = MnemonicIdentity.fromMnemonic('abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about', { isMainnet: false });
const receiver = MnemonicIdentity.fromMnemonic('zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong', { isMainnet: false });
const senderPubkey = await sender.xOnlyPublicKey();
const receiverPubkey = await receiver.xOnlyPublicKey();

// The receiver creates the preimage and shares only its hash
const preimage = crypto.getRandomValues(new Uint8Array(32));
const condition = Script.encode(['HASH160', hash160(preimage), 'EQUAL']);

// Store refundAt with the contract: another value gives another address
const refundAt = BigInt(Math.floor(Date.now() / 1000)) + 86400n;

const claimLeaf = ConditionMultisigTapscript.encode({
  conditionScript: condition,
  pubkeys: [receiverPubkey, serverPubkey],
}).script;
const refundLeaf = CLTVMultisigTapscript.encode({
  pubkeys: [senderPubkey, serverPubkey],
  absoluteTimelock: refundAt,
}).script;
const exitClaimLeaf = ConditionCSVMultisigTapscript.encode({
  conditionScript: condition,
  pubkeys: [receiverPubkey],
  timelock: exitTimelock,
}).script;
const exitRefundLeaf = CSVMultisigTapscript.encode({
  pubkeys: [senderPubkey],
  timelock: { ...exitTimelock, value: exitTimelock.value * 2n },
}).script;

const htlc = new VtxoScript([claimLeaf, refundLeaf, exitClaimLeaf, exitRefundLeaf]);
console.log('HTLC address:', htlc.address(networks.mutinynet.hrp, serverPubkey).encode());

The claim path is:

OP_HASH160 <hash> OP_EQUAL OP_VERIFY <receiverPubkey> OP_CHECKSIGVERIFY <serverPubkey> OP_CHECKSIG

Claim with the preimage

claimWithPreimageIdentity signs as the receiver and attaches the preimage to each input. The operator rejects the spend if the preimage does not match the hash.

import { ArkAddress, claimWithPreimageIdentity, signAndSubmitOffchainTx } from '@arkade-os/sdk';

const { vtxos } = await indexerProvider.getVtxos({
  scripts: [hex.encode(htlc.pkScript)],
  spendableOnly: true,
});
if (vtxos.length === 0) throw new Error('Fund the HTLC address first');
const vtxo = vtxos[0];

const receiverAddress = 'tark1...'; // the receiver's Arkade address

const arkTxid = await signAndSubmitOffchainTx({
  identity: claimWithPreimageIdentity(receiver, preimage),
  provider: arkProvider,
  inputs: [{
    ...vtxo,
    tapLeafScript: htlc.findLeaf(hex.encode(claimLeaf)),
    tapTree: htlc.encode(),
  }],
  outputs: [{ amount: BigInt(vtxo.value), script: ArkAddress.decode(receiverAddress).pkScript }],
  serverUnrollScript,
});
console.log('Claimed:', arkTxid);

To refund after refundAt, pass refundLeaf to findLeaf and sign with sender. The SDK sets the transaction’s locktime from the path. The SDK’s VHTLC.Script builds a six-path HTLC with the same structure. It adds refund paths that the sender and receiver sign together, so they can cancel before the deadline.

Overview

Working with Tapscript

Experimental

Build the HTLC

Claim with the preimage

​Build the HTLC

​Claim with the preimage

Build the HTLC

Claim with the preimage