Where should you develop your blockchain app?
→ Download our guide to Web3 ecosystemsClose Icon

Future Work for Clarity: Better Bitcoin Interactivity

We often talk about how Stacks enables Bitcoin applications, but what does that mean in practice? In this post, we’ll take a look at how the Stacks blockchain interacts with Bitcoin and explore in depth how we can add support for new functionality and better Bitcoin interactivity.

Deep dive
July 18, 2022
Staff Software Engineer
Improving Clarity's Connection to Bitcoin
Your subscription could not be saved. Please try again.
Thanks for subscribing.

Product updates & dev resources straight to your inbox

Copy link

The Stacks blockchain is uniquely positioned to make reading from the Bitcoin chain easy for smart contracts on the Stacks network, and proof-of-transfer consensus even makes certain kinds of bitcoin transactions programmable from the Stacks network. This post will cover two different kinds of applications that can make use of this power (bridges and programmable proof-of-transfer slots), and discuss some proposed mechanisms in SIP-015 that make implementing those applications possible in the Stacks network.

Bitcoin Bridges

A bitcoin bridge is an application that enables depositing bitcoin (BTC) into another blockchain and withdrawing that bitcoin from the blockchain back into the Bitcoin blockchain after some interactions. Bridges come in many varieties, with varying levels of trust, but one thing that all bridges must do is read and validate Bitcoin transactions. For these operations to be trustless, they must be performed as part of a smart contract.

You can conceptualize these operations as two different smart contract methods:

parse_bitcoin_transaction(tx: Buffer) -> {
sender: BitcoinAddress,
recipient: BitcoinAddress,
amount: uint

validate_bitcoin_transaction(tx: Buffer) -> bool

The first method (parse_bitcoin_transaction) is relatively easy to implement: its job is to just parse the bitcoin transaction’s bytes into more easily handled data structures. Almost all smart contracting languages make this possible, and this is possible using Clarity as well.

The second method (validate_bitcoin_transaction) is harder: it needs to:

  1. Check that the bitcoin transaction was actually included in a Bitcoin block.
  2. Check that this Bitcoin block is in the real Bitcoin blockchain history.

Implementing a check like this is different in different blockchains, but most require implementing a smart contract that can function as a Bitcoin light client. This means that the smart contract must check the history of Bitcoin block headers for the correctness of their block difficulties, that this history is correctly linked together, and that the given bitcoin transaction is included in some block in that history.

Having done these checks, such smart contracts are still vulnerable to Bitcoin forks: if a fork occurs, a transaction that was previously valid may no longer be so.

The Stacks blockchain’s close relationship to Bitcoin allows this validation check to be implemented much more easily (more on that below) and can eliminate the vulnerability to Bitcoin forks. SIP-015 proposes a new method for the Clarity language:

get-burn-block-info? header-hash block-height

This method will return the hash of the Bitcoin block header at the given Bitcoin block height. Because every node in the Stacks network (miners and followers) must evaluate the Bitcoin blockchain as part of evaluating Stacks blocks, this information is available to every Stacks node. This proposed method would make that information available to Clarity too, and, as a result, available to all Clarity smart contracts.

With SIP-015 activated, bridges could replace the validation of a given Bitcoin block with a simple call to this method. Importantly, because a Bitcoin fork will lead to a Stacks fork, use of this method would seamlessly allow Stacks smart contracts to deal with Bitcoin forks: after a fork, the returned value of this method would change, and any Stacks transaction that tried to prove a Bitcoin transaction was included in a forked-away block would fail.

Programmable PoX Reward Slots

The Stacks blockchain’s consensus algorithm, Proof-of-Transfer, validates the behavior of Stacks miners with the Bitcoin blockchain. Stacks miners compete with one another through a combination of Bitcoin burns and Bitcoin transfers. The rules governing these Bitcoin transactions are the Proof-of-Transfer algorithm.

Proof-of-Transfer operates in reward cycles. During each reward cycle, 4000 “slots” are randomly distributed to participants in the PoX smart contract. When a slot is selected for a given Bitcoin height, any miners who wish to be candidates for mining a Stacks block during that Bitcoin block must send bitcoin to that address as part of their “block commitment.”

In a sense, the PoX smart contract is “writing” to the Bitcoin blockchain: state changes in the PoX Stacks smart contract cause Stacks miners to alter their behavior on the Bitcoin blockchain, sending Bitcoin transactions to different Bitcoin addresses depending on the PoX contract’s state. SIP-015 proposes some changes to the PoX contract which would allow Clarity developers to harness this power.

One function in the SIP-015 proposal for smart contracts working with PoX is:


The “aggregation” methods of the PoX contract are used to support use cases like Stacking pools and delegation. This new rollback method, though, allows the caller to change the reward address for a slot that they control in a future reward cycle (slots in previous or the current cycle cannot be changed).

By giving contract authors the ability to stack from contracts and then dynamically select the reward address, contract authors can experiment with programmable PoX reward slots. Many different kinds of applications can be built around this concept – slots are a form of “bitcoin future” because each slot has some expected, but not predetermined, bitcoin payout, and contract authors can experiment with different ways of exposing the bitcoin future.

For example, dynamic slots could be used for a form of short-lived wrapped BTC or as rotating rewards for fully decentralized stacking pools. By exposing this programmability to smart contracts, SIP-015’s proposed changes would allow contract authors to build applications for PoX that we have not even considered. 


As discussed above, some of SIP-015’s proposed changes will improve Bitcoin functionality. SIP-015 is still in active revision and the implementation work is under way in the stacks-blockchain repository (see active issues). The Stacks Foundation is leading this effort, but we encourage anyone from the community to contribute to the issues or weigh in on SIP-015 (either on the PR, or through the Github discussions).

This post is part of an ongoing series to highlight future work for Clarity. You can read about language and reliability improvements here, and I will discuss work around language analysis tools in a future post.

Copy link
Hiro news & product updates straight to your inbox
Only relevant communications. We promise we won’t spam.

Related stories