GITBOOK-331: Add sBTC builder quickstart

kenrogers · gitbook-bot · commit 9023ce23fe71 · 2025-08-08T20:36:57.000Z
diff --git a/.gitbook/assets/image (25).png b/.gitbook/assets/image (25).png
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -97,6 +97,7 @@
   * [Best practices for running a Signer](guides-and-tutorials/running-a-signer/best-practices-to-run-a-signer.md)
   * [OpSec Best Practices](guides-and-tutorials/running-a-signer/opsec-best-practices.md)
 * [sBTC](guides-and-tutorials/sbtc/README.md)
+  * [sBTC Builder Quickstart](guides-and-tutorials/sbtc/sbtc-builder-quickstart.md)
   * [How to Run an sBTC Signer](guides-and-tutorials/sbtc/how-to-run-sbtc-signer.md)
   * [Best practices for running an sBTC Signer](guides-and-tutorials/sbtc/best-practices-for-running-an-sbtc-signer.md)
   * [How to Use the sBTC Bridge](guides-and-tutorials/sbtc/how-to-use-the-sbtc-bridge.md)
diff --git a/guides-and-tutorials/hello-stacks-quickstart-tutorial.md b/guides-and-tutorials/hello-stacks-quickstart-tutorial.md
@@ -1,4 +1,4 @@
-# Hello Stacks Quickstart Tutorial
+# Developer Quickstart
 
 ## Build Your First Stacks App in 30 Minutes
 
@@ -10,16 +10,16 @@ This tutorial will help you build a working Stacks application in just 30 minute
 
 **What you'll learn:**
 
-- How to write a Clarity smart contract
-- How to deploy contracts to Stacks testnet
-- How to connect a wallet to your app
-- How to interact with contracts from a frontend
+* How to write a Clarity smart contract
+* How to deploy contracts to Stacks testnet
+* How to connect a wallet to your app
+* How to interact with contracts from a frontend
 
 **Prerequisites:**
 
-- Basic familiarity with web development (HTML, CSS, JavaScript)
-- A modern web browser
-- 30 minutes of your time
+* Basic familiarity with web development (HTML, CSS, JavaScript)
+* A modern web browser
+* 30 minutes of your time
 
 Let's get started!
 
@@ -50,7 +50,7 @@ Clarity is Stacks' smart contract language, designed for safety and predictabili
 
 Clarity is inspired by LISP and uses a functional programming approach. Everything in Clarity is an expression wrapped in parentheses. This can be a bit overwhelming at first if you are used to languages like JavaScript or Solidity, but the learning curve is short and Clarity is a simple language to understand once you dive in and start using it.
 
-For a more detailed introduction, check out the [Clarity Crash Course](./clarity-crash-course.md) in the docs.
+For a more detailed introduction, check out the [Clarity Crash Course](clarity-crash-course.md) in the docs.
 
 ### Write the Contract
 
@@ -135,11 +135,12 @@ The `tx-sender` variable is particularly useful because it's automatically set b
 Finally, every public function in Clarity must return a response type, which is why you see `ok` wrapping our return values. This ensures that every function call has a clear success or failure outcome, making your contracts much more predictable and easier to debug.
 
 <details>
+
 <summary><strong>🔍 Deep Dive: Understanding the Contract Code (Optional)</strong></summary>
 
 Want to understand exactly what each part of the contract is doing? Let's walk through every function and concept used in our message board contract. Links to the official documentation are included for each function, so you may dive deeper if you want.
 
-### How We Store Data on the Blockchain
+#### How We Store Data on the Blockchain
 
 Let's start with how we're storing our messages. We use [`define-map`](../reference/functions.md#define-map) to create what's essentially a database table on the blockchain:
 
@@ -165,7 +166,7 @@ Finally, we need a way to keep track of how many messages we've posted so far:
 
 The [`define-data-var`](../reference/functions.md#define-data-var) creates a single variable that persists on the blockchain. We start it at `u0` (that's how you write the number 0 for unsigned integers in Clarity). The `u` prefix might look weird if you're coming from other languages, but it's just Clarity's way of saying "this is a positive integer."
 
-### The Heart of Our Contract: Adding Messages
+#### The Heart of Our Contract: Adding Messages
 
 Now let's break down the most important function, the one that actually adds messages to our board:
 
@@ -184,17 +185,17 @@ When you call [`define-public`](../reference/functions.md#define-public), you're
 
 Inside the function, we use [`let`](../reference/functions.md#let) to create a local variable. This is like declaring a variable inside a function in other languages, but with Clarity's unique syntax. We're creating a variable called `id` and setting it to the current message count plus 1.
 
-*Here's where Clarity might trip you up if you're coming from other languages.* Notice how we write `(+ (var-get message-count) u1)` instead of something like `message-count + 1`. In Clarity, operators like `+`, `-`, `>`, and `<` are actually functions that use prefix notation. So `(+ 2 3)` means "add 2 and 3" (instead of `2 + 3` like you'd write in JavaScript or Python). This is part of Clarity's LISP-inspired syntax where everything is a function call.
+_Here's where Clarity might trip you up if you're coming from other languages._ Notice how we write `(+ (var-get message-count) u1)` instead of something like `message-count + 1`. In Clarity, operators like `+`, `-`, `>`, and `<` are actually functions that use prefix notation. So `(+ 2 3)` means "add 2 and 3" (instead of `2 + 3` like you'd write in JavaScript or Python). This is part of Clarity's LISP-inspired syntax where everything is a function call.
 
 The [`var-get`](../reference/functions.md#var-get) function reads the current value of our message counter, and [`+`](../reference/functions.md#add) adds 1 to create the next message ID.
 
 Next, we store the message content using [`map-set`](../reference/functions.md#map-set), which is like inserting a row into a database table. We store the message content with the new ID we just created.
 
-We also store who posted the message using another [`map-set`](../reference/functions.md#map-set) call (*Notice how we use `tx-sender` here*). This is a special variable that Clarity automatically sets to the address of whoever called the function. You can't fake this or manipulate it, which makes it perfect for tracking message authors.
+We also store who posted the message using another [`map-set`](../reference/functions.md#map-set) call (_Notice how we use `tx-sender` here_). This is a special variable that Clarity automatically sets to the address of whoever called the function. You can't fake this or manipulate it, which makes it perfect for tracking message authors.
 
 We update our message counter using [`var-set`](../reference/functions.md#var-set), and finally return [`ok`](../reference/functions.md#ok) with the new message ID. In Clarity, all public functions must return either `(ok value)` for success or `(err error)` for failure. This ensures that every function call has a predictable outcome.
 
-### Reading Messages Back
+#### Reading Messages Back
 
 Now let's look at how we read messages back from the blockchain. Our simplest function is:
 
@@ -219,7 +220,7 @@ We have similar functions for getting the message author and the total message c
 
 The message count function is particularly simple because it just reads our counter variable and returns it. No parameters needed since there's only one counter.
 
-### A More Complex Function: Getting Recent Messages
+#### A More Complex Function: Getting Recent Messages
 
 Let's look at our most complex function:
 
@@ -242,7 +243,7 @@ The [`map`](../reference/functions.md#map) function applies another function to
 
 We use [`list`](../reference/functions.md#list) to create a list of message IDs, and [`-`](../reference/functions.md#subtract) for subtraction to calculate which recent messages to fetch.
 
-### What Makes Clarity Special
+#### What Makes Clarity Special
 
 Now that you've seen the code, let me explain some of the key concepts that make Clarity different from other smart contract languages.
 
@@ -678,26 +679,26 @@ Now that you have the basics down, here are some ways to continue your Stacks de
 
 ### Learn More About Clarity
 
-- **[Clarity Book](https://book.clarity-lang.org/)**: Comprehensive guide to Clarity development
-- **[Clarity Reference](https://docs.stacks.co/docs/clarity)**: Complete documentation of Clarity functions
-- **[Clarity Crash Course](https://docs.stacks.co/docs/clarity-crash-course)**: Quick introduction to Clarity concepts
+* [**Clarity Book**](https://book.clarity-lang.org/): Comprehensive guide to Clarity development
+* [**Clarity Reference**](https://docs.stacks.co/docs/clarity): Complete documentation of Clarity functions
+* [**Clarity Crash Course**](https://docs.stacks.co/docs/clarity-crash-course): Quick introduction to Clarity concepts
 
 ### Explore Advanced Features
 
-- **Error Handling**: Learn about Clarity's `try!` and `unwrap!` functions
-- **Access Control**: Implement admin functions and permissions
-- **Token Standards**: Build fungible (SIP-010) and non-fungible (SIP-009) tokens
+* **Error Handling**: Learn about Clarity's `try!` and `unwrap!` functions
+* **Access Control**: Implement admin functions and permissions
+* **Token Standards**: Build fungible (SIP-010) and non-fungible (SIP-009) tokens
 
 ### Development Tools
 
-- **[Clarinet](https://github.com/hirosystems/clarinet)**: Local development environment for Clarity
-- **[Hiro Platform](https://platform.hiro.so)**: Hosted development environment
-- **[Stacks Explorer](https://explorer.stacks.co)**: View transactions and contracts on mainnet
+* [**Clarinet**](https://github.com/hirosystems/clarinet): Local development environment for Clarity
+* [**Hiro Platform**](https://platform.hiro.so): Hosted development environment
+* [**Stacks Explorer**](https://explorer.stacks.co): View transactions and contracts on mainnet
 
 ### Community Resources
 
-- **[Stacks Discord](https://discord.gg/stacks)**: Connect with other developers
-- **[Stacks Forum](https://forum.stacks.org)**: Ask questions and share projects
-- **[Stacks GitHub](https://github.com/stacks-network)**: Contribute to the ecosystem
+* [**Stacks Discord**](https://discord.gg/stacks): Connect with other developers
+* [**Stacks Forum**](https://forum.stacks.org): Ask questions and share projects
+* [**Stacks GitHub**](https://github.com/stacks-network): Contribute to the ecosystem
 
 Happy building! 🚀
diff --git a/guides-and-tutorials/sbtc/sbtc-builder-quickstart.md b/guides-and-tutorials/sbtc/sbtc-builder-quickstart.md
@@ -0,0 +1,122 @@
+# sBTC Builder Quickstart
+
+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](../hello-stacks-quickstart-tutorial.md) - For a quick holistic introduction to the Stacks development process, tools, and fundamentals
+* [Clarity Crash Course](../clarity-crash-course.md) - For a quick introduction to Clarity
+* [Clarinet Docs](https://docs.hiro.so/tools/clarinet)
+* [Stacks.js Docs](https://docs.hiro.so/reference/stacks.js)
+
+Choose your preferred development environment:
+
+#### Option 1: Hiro Platform (Recommended)
+
+The fastest way to start building with sBTC is using the Hiro Platform's hosted devnet. The Platform integrates with your GitHub account. You can either import an existing project from GitHub or start with a Platform template and have it synced with your GitHub account.
+
+After you create the project in the Platform, you can clone it locally and work with the Platform's cloud devnet by connecting your API key as described in the template's README files. This will allow you to work on your code locally but let Platform handle the complexities of actually running the devnet.
+
+1. **Create an account** at [platform.hiro.so](https://platform.hiro.so)
+2. **Create or import a project**
+   * Select a template or import your own project from GitHub. There are several templates available to use as a starting point. Some have only smart contracts and some are full-stack dapp templates. Starting with one of these ensures you are building with best practices.
+   * Navigate to your project dashboard
+3. **Start devnet**
+   * Click the "Devnet" tab
+   * Click "Start Devnet"
+   * Wait for status to show "Active"
+4. **Connect your wallet**
+   * Your devnet wallets are automatically funded with STX and sBTC
+   * Use the provided wallet addresses within the templates
+   * The platform templates are automatically connected to Devnet, and there are instructions in the READMEs of the templates for how to connect your frontend to your Devnet instance
+
+#### Option 2: 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)
+
+    ```bash
+    brew install clarinet
+    ```
+2.  **Create a new project**
+
+    ```bash
+    clarinet new my-sbtc-project
+    cd my-sbtc-project
+    ```
+3.  **Add sBTC requirements**
+
+    ```bash
+    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**
+
+    ```bash
+    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`.
+
+```clarity
+;; 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.&#x20;
+
+<figure><img src="../../.gitbook/assets/image (25).png" alt=""><figcaption></figcaption></figure>
+
+Once you are ready to deploy to testnet, you can do so by editing your deployment plan as outlined in [this guide](https://docs.hiro.so/tools/clarinet/sbtc-integration).
+
+### 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](../../concepts/sbtc/).
