sBTC Builder Quickstart

source: Hiro

Get up and running with sBTC in 30 minutes or less. This guide covers the essentials for working with sBTC as a SIP-010 token in your smart contracts.

What is sBTC?

sBTC is Bitcoin on Stacks. It's a SIP-010 fungible token that maintains a 1:1 peg with Bitcoin, enabling you to use Bitcoin in smart contracts and DeFi applications on the Stacks blockchain.

Key points:

• 1:1 Bitcoin peg: 1 sBTC always equals 1 BTC

• SIP-010 token: Works like any other fungible token on Stacks

• Programmable: Use Bitcoin in smart contracts, DeFi protocols, and dApps

Quick Setup

Prerequisites

In order to get the most from this quickstart, you should familiarize yourself with Clarity, Clarinet, Stacks.js, and the Hiro Platform. These are the fundamental building blocks of building Stacks applications.

• Stacks Developer Quickstart - For a quick holistic introduction to the Stacks development process, tools, and fundamentals

• Clarity Crash Course - For a quick introduction to Clarity

• Clarinet Docs

• Stacks.js Docs

Local with Clarinet

If you would prefer to have your devnet running locally instead of in the Platform cloud, you can run one yourself.

1

Install Clarinet (version 3.x)

brew install clarinet

2

Create a new project

clarinet new my-sbtc-project
cd my-sbtc-project

3

Add sBTC requirements

clarinet requirements add SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-deposit

This automatically includes the sBTC token contract in your Clarinet context so you can reference it within your contracts.

4

Start devnet

clarinet devnet start

With either of these options, your Devnet wallets are automatically funded with sBTC. You just need to include the sBTC contract in your contract requirements as shown above.

Working with sBTC in Smart Contracts

sBTC follows the SIP-010 standard, making it easy to integrate into your contracts.

The primary function you'll be using is the transfer function. That's because sBTC exists as a 1:1 Bitcoin peg via a SIP-010 token. Minting is handled by the protocol, the main function of writing smart contracts that use sBTC is to move it around, which means using the transfer function.

Here's a very basic example of how to transfer sBTC within your contract.

Basic Transfer Example

Create a new contract that accepts sBTC payments. You can do this within the Clarinet project folder with clarinet contract new sbtc-payment.

contracts/sbtc-payment.clar

;; contracts/sbtc-payment.clar

;; Define the sBTC token contract reference
(define-constant sbtc-token 'SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token)

;; Error codes
(define-constant err-insufficient-balance (err u100))
(define-constant err-transfer-failed (err u101))

;; Accept sBTC payment
(define-public (pay-with-sbtc (amount uint) (recipient principal))
  (contract-call? sbtc-token transfer
    amount
    tx-sender
    recipient
    none))

You can test out this contract by either using the UI within the Platform to call the functions directly if you have devnet running or by opening the console with clarinet console.

Once you do that you'll see that your devnet accounts have automatically been funded with sBTC.

Once you are ready to deploy to testnet, you can do so by editing your deployment plan as outlined in this guide.

Conclusion

You can build pretty much anything you want using this simple foundation, as all of the complexity of sBTC is handled behind the scenes by the protocol.

What's needed now is for builders to take this foundation and build interesting, useful things with it. sBTC unlocks a lot of additional functionality for Bitcoin that previously would have only been possible with either custodied solutions or slow, complex solutions with poor UX.

If you are interested, you can read more about how sBTC works in the sBTC Concept Guide.