Bridging BTC and STX (v5)

This is an update to the first article about the Clarity Bitcoin library from May 2021.

Clarity Bitcoin library is a tool that allows users to trigger action on the Stacks blockchain if and only if a certain Bitcoin transaction was mined on the Bitcoin blockchain. The Clarity Bitcoin library is a smart contract on the Stacks blockchain that helps developer to verify Bitcoin transactions. The smart contracts on the Stacks blockchain have a view on the Bitcoin blockchain, more precisely on the block hash of all Bitcoin blocks. Using this block hash together with some details about the bitcoin transaction (so-called merkle proofs) it can be cryptographically proven that the bitcoin transaction was indeed mined.

Version 5

With version 5, FriendsFerdinand, MarvinJanssen and myself created an updated version of the library that is more secure and that has more features. The source code and tests can be found on github: https://github.com/friedger/clarity-bitcoin.

In contrast to the first version, this version 5 allows to

• verify transactions in any Bitcoin block. The first version could only handle Bitcoin blocks that have a corresponding Stacks block.

• verify transactions containing witness data. The first version could only handle legacy Bitcoin transactions.

• calculate the txid of a bitcoin tx with witness data when parsing a segwit transaction using parse-wtx. Note, that the hash of the full transaction data with witness data is the wtxid, not the txid.

The library contract has the following high-level functions:

• was-tx-mined-compact and was-segwit-tx-mined-compact returning the (ok txid) and (ok wtxid) if the provided Bitcoin transaction data could be verified.

• parse-tx and parse-wtx returning a structured object for inputs, outputs and if necessary the witness data.

Tools for merkle proofs

The library contract clarity-bitcoin-lib-v5 requires some data from bitcoin transactions that needs to be collected from a bitcoin node. There is a tool at sbtc.tech that provides the required data for testnet bitcoin transaction. It can be used to try out the library contract and better understand the required data . Check the merkle proof button and enter your testnet transaction.

Applications

The most important use case next year will be sBTC. sBTC will probably use an optimised version in the Stacks node using the same technique.

Today, we see Alex using clarity-bitcoin library for $BR20 token bridging. There is also catamaranswaps.org for over-the-counter swaps of BTC and STX.

The library contract is deployed on mainnet at https://explorer.hiro.so/txid/SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.clarity-bitcoin-lib-v5?chain=mainnet