Sapio Primer

Day 9: Rubin's Bitcoin Advent Calendar

Welcome to day 9 of my Bitcoin Advent Calendar. You can see an index of all the posts here or subscribe at to get new posts in your inbox

We’re through the basics sections of the Advent calendar ow! Time for some more… specific content on the bleeding edge!

This post is your introduction to the world of Sapio. Sapio is the programming framework I’ve been developing for Bitcoin Smart Contracts. There’s a ton of material on the website, so this post is going to be a bit high-level and then you should jump into the docs after to learn more.

What the heck is Sapio?

Sapio is a tool that helps you design and use Bitcoin smart contracts based on covenants (like CTV) as well as manage potentially recursive state transitions at terminal states.

That’s a mouthful and a half… let’s break it down with a very basic vault deposit example.

Suppose I have 10 bitcoin sitting in my normal wallet. I want to deposit it to an exchange. I go to my exchange and request an address to deposit to. The exchange wants their coins to be in a special cold storage whereby any move from cold storage has to “mature” for 10 days since it was claimed before it’s spendable as a hot-spend, otherwise it stays in cold. The hot wallet has logic such that any unused funds after it transacts, goes back into the cold-storage contract. We saw a contract like this in the day 7 post.

The exchange can use Sapio to generate an address that expects 10 coins and encodes this cold-to-hot logic without requiring the cold keys be online! Better than that, I don’t even have to contact the exchange for the address. The exchange can distribute a codesigned Sapio WASM applet that runs on my own machine locally. I download the applet into my Sapio Studio GUI and that generates the exchange deposit UX form for the contract that I (or my wallet) automatically fills out and then generates a proper address/spending transaction.

Upon receipt of the deposit information, (which can in certain circumstances be completely on-chain in the txn, so no need for a separate communication channel), the exchange can us the WASM to generate an identical deposit program to verify the user isn’t cheating somehow. Bada-bing-bada-boom!

We’ll see in close detail examples like this coming in the following posts, but to sum up, Sapio helped us with the following:

  1. Authoring a Smart Contract Application for a cold storage deposit solution
  2. Distributing it as a deterministic executable with a GUI User using it to make a deposit
  3. Receiving funds as a depositee directly into a smart contract
  4. Generating withdrawal transactions out of the vault
  5. Putting the remaining funds back into the cold storage

This is not a hypothetical, all of these components exist and are usable today! Where there is an asterisk is that BIP-119 CTV does not yet exist, and so for apps like this the exchange would have to run some kind of signing server you connect to. This works, but is a worse trust model. For some applications, you don’t need CTV if you can get all of a contract’s parties to run their own oracles. Therefore you can still accomplish a lot without a worse trust model with what’s there today!

Over the remaining posts we’ll go into great detail on different applications built in Sapio, but for now you can skim through to get started playing around with your own designs.

to continue the conversation...

© 2011-2021 Jeremy Rubin. All rights reserved.