Skip to main content

Atomic Swap

The JavaScript path to cross-chain atomic swaps with @mintlayer/sdk. The same workflow in Go lives in the Go guides; the wallet-cli guide Atomic Swap with Bitcoin (HTLC) explains the full protocol: roles, the secret/hash flow, and timelock planning (the Bitcoin timelock must be shorter than the Mintlayer one). This page shows how to build the Mintlayer side in code.

If a party stalls, the HTLC's refund path returns the funds once the timelock expires.

1. Alice locks ML with the secret hash​

// Secret generated off-band (e.g. crypto.randomBytes(32)); only the hash is shared
const secretHash = {
  hex: 'a3f1c2...',     // hash of the secret
  string: null,
};

const signedTx = await client.createHtlc({
  amount: 100,
  // token_id: 'tmltk1...',          // optional: swap a token instead of ML
  secret_hash: secretHash,
  spend_address: bobMlAddress,       // where a successful claim pays out
  spend_pubkey: bobPubkeyHex,
  refund_address: aliceAddress,      // where a refund returns
  refund_timelock: 172800,           // e.g. 48h, agreed off-chain
});

await client.broadcastTx(signedTx);

2. Alice claims Bob's BTC (on Bitcoin)​

Alice spends Bob's Bitcoin HTLC by revealing the secret; this happens on the Bitcoin side with your Bitcoin tooling and is unchanged by the SDK.

3. Bob extracts the secret and claims the ML​

// Read the secret from Alice's claim transaction on Bitcoin
const secret = await client.extractHtlcSecret({
  transaction_id: txid,
  transaction_hex: rawTxHex,
});

// Or ask the connected wallet for a secret hash when you are the one generating it:
const hash = await client.requestSecretHash({});

// Claim the Mintlayer HTLC
const claimTx = await client.spendHtlc({ transaction_id: mlHtlcTxId, secret });
await client.broadcastTx(claimTx);

4. Refund path​

If the swap never completes, the original locker reclaims after the timelock:

const refundTx = await client.refundHtlc({ transaction_id: mlHtlcTxId });
await client.broadcastTx(refundTx);

Checklist​

  • Agree off-chain on amounts, rate, and timelock durations before locking anything.
  • Bitcoin timelock strictly shorter than the Mintlayer timelock.
  • Only the hash is shared; the secret is revealed by the first claim.
  • Verify the on-chain HTLC (amount, addresses, timelock) before locking the other side.