Skip to content
Catalyst Documentation

Fulfilling BTC Orders

To determine whether an order involves a Bitcoin transaction, check the GetOrderData.order.orderData.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. For example:
    • 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 (GetOrderData.order.orderData.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 to decode the address.

VersionNameEncoding SchemePrefixHash Length
0UnknownIgnore
1P2PKHBase58Check(00+PKH)1*20
2P2SHBase58Check(05+SH)3*20
3P2WPKHBech32bc1q**20
4P2WSHBech32bc1q**32
5P2TRBech32mbc1p**32

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

The following guidelines assume you are implementing this from the perspective of a solver. You need to convert the expected output script into a Bitcoin address that can be used with your wallet:

  • P2PKH (Pay-to-PubKey-Hash):

    • The recipient is the public key hash. Encode the first 20 bytes with Base58Check. Prepend with 00, and encode with Base58Check.

  • P2SH (Pay-to-Script-Hash):

    • The recipient is the script hash. Encode the first 20 bytes with Base58Check. Prepend with 05, and encode with Base58Check.

  • P2WPKH (Pay-to-Witness-PubKey-Hash):

    • The recipient is the witness. Encode the first 20 bytes with Bech32. Prepend with bc1q.

  • P2WSH (Pay-to-Witness-Script-Hash):

    • The recipient is the witness hash. Encode the first 32 bytes with Bech32. Prepend with bc1q.

  • P2TR (Pay-to-Taproot):

    • The recipient is the witness hash. Encode the first 32 bytes with Bech32m. Prepend with bc1p.

  • Nested Witness Addresses/Outputs:

    • These are P2SH addresses and should be treated like any other P2SH address.

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.