Filling BTC Orders

Catalyst supports a Bitcoin validation layer. However, filling Bitcoin swaps is technically more involved than filling EVM swaps. If you are already filling EVM swaps and are interested in filling BTC swaps, or if you want to add Bitcoin swaps to your app through Catalyst, reach out and we can get you onboarded.

To determine whether an order involves a Bitcoin transaction, check the orderDto.order.outputs[].token field. If the token indicates Bitcoin, ensure the following conditions are met:

• The first 30 bytes of the token should be 0x000000000000000000000000BC0000000000000000000000000000000000. The 13th byte is 0xBC.

• The 31st byte indicates the number of confirmations required before the order can be verified on-chain.

  • 0x00 and 0x01 represent 1 confirmation.
  • 0x02 represents 2 confirmations.
  • 0x03 represents 3 confirmations, and so on.

• The 32nd byte contains an address version identifier, which should be decoded as uint8.

If the transaction is directed to Bitcoin, the address (orderDto.order.outputs[].recipient) will contain a relevant destination hash or witness, not the address itself. This value must be used along with the address version identifier – the 32nd byte of the token – to decode the address.

Version	Name	Encoding Scheme	Prefix	Hash Length
0	Unknown	Ignore
1	P2PKH	Base58Check(00+PKH)	1*	20
2	P2SH	Base58Check(05+SH)	3*	20
3	P2WPKH	Bech32	bc1q**	20
4	P2WSH	Bech32	bc1q**	32
5	P2TR	Bech32m	bc1p**	32

* Prefixes are determined by the encoding scheme.
** Part of the prefix – 1q/1p – is determined by the encoding scheme.

You can use the script below to get inspiration for how to decode the Bitcoin address from an output description.

import bs58check from 'bs58check';
import { bech32, bech32m } from 'bech32';

const hexStringToUint8Array = (hexString: string) =>
  Uint8Array.from(
    hexString.match(/.{1,2}/g)!.map((byte) => parseInt(byte, 16))
  );

function decodeBitcoinAddress(
  version: number,
  recipientHash: string,
  testnet = false,
): string {
  if (version === 1) {
    const prefix = !testnet ? '00' : '6F';
    const bytes = hexStringToUint8Array(
      prefix + recipientHash.replace('0x', '').slice(0, 40)
    );
    return bs58check.encode(bytes);
  }
  if (version === 2) {
    const prefix = !testnet ? '05' : 'C4';
    const bytes = hexStringToUint8Array(
      prefix + recipientHash.replace('0x', '').slice(0, 40)
    );
    return bs58check.encode(bytes);
  }
  const prefix = !testnet ? 'bc' : 'tb';
  if (version === 3) {
    const bytes = hexStringToUint8Array(
      recipientHash.replace('0x', '').slice(0, 40)
    );
    const words = bech32.toWords(bytes);
    words.unshift(0x00);
    return bech32.encode(prefix, words);
  }
  const bytes = hexStringToUint8Array(
    recipientHash.replace('0x', '').slice(0, 64)
  );
  if (version === 4) {
    const words = bech32.toWords(bytes);
    words.unshift(0x00);
    return bech32.encode(prefix, words);
  }
  if (version === 5) {
    const words = bech32m.toWords(bytes);
    words.unshift(0x01);
    return bech32m.encode(prefix, words);
  }

  throw Error(`Unsupported Address Type ${version}`);
}

Once the address is generated, create a Bitcoin transaction with at least one output that exactly matches the described output from the initiated order. The transaction can have any number of inputs and outputs, as long as one output precisely matches the one specified by the order’s output. This flexibility allows for batch filling, consolidation, and more.

If the calldata is set on the output description, the Bitcoin transaction needs a second output which is exactly the next output index after the output filling the order:

// Assuming you use BitcoinJS PSBT:
import * as bitcoin from 'bitcoinjs-lib';
...
bitcoin.initEccLib(ecc); // For Taproot support.

const mainnet: boolean;
const psbt = new bitcoin.Psbt({
  network: mainnet ? bitcoin.networks.bitcoin : bitcoin.networks.testnet,
});

// ... add inputs

// Add the solving output.
psbt.addOutput({ address: to, value: outputValue });

// The very next output should be an OP_RETURN
const opReturnData = returnData.replace("0x", "");
if (opReturnData.length > 0) {
  const data_embed = bitcoin.payments.embed({
      data: [hexStringToUint8Array(opReturnData)],
  });
  psbt.addOutput({
    script: data_embed.output!,
    value: 0n,
  });
}

// ... complete transaction