diff --git a/concepts/sbtc/README.md b/concepts/sbtc/README.md index c3472ce4b8..415607e2a2 100644 --- a/concepts/sbtc/README.md +++ b/concepts/sbtc/README.md @@ -1,35 +1,43 @@ -# sBTC +## Introduction to sBTC -To understand sBTC, we first need to understand the current limitations of Bitcoin (BTC). +sBTC is a SIP-10 token on the Stacks blockchain that represents Bitcoin (BTC) in a 1:1 ratio. It enables Bitcoin holders to utilize their BTC within the Stacks ecosystem, allowing participation in DeFi applications and other smart contract functionalities while maintaining a peg to the underlying Bitcoin. -Bitcoin is to date the most secure and decentralized blockchain. While Bitcoin is the largest cryptocurrency by market cap, comparatively few applications exist within the Bitcoin ecosystem. Developers interested in building applications for the Bitcoin community often find it difficult or impossible to implement their logic directly on the Bitcoin chain. Although Bitcoin has a simple scripting system built in, it lacks the expressiveness of many other smart contract languages. +### Purpose -sBTC is for: +The primary purpose of sBTC is to bridge the Bitcoin and Stacks ecosystems, providing Bitcoin holders with access to the rich functionality of smart contracts on the Stacks blockchain without sacrificing the security and value of their BTC holdings. -* Bitcoin holders who want to participate in smart contracts. -* Developers who want to build applications on Bitcoin. +### Version -sBTC empowers developers to build applications on Bitcoin by bridging Bitcoin and [Stacks](https://www.stacks.co/). We achieve this by introducing a fungible token (sBTC) on the Stacks blockchain. The token has the following properties: +This documentation primarily covers sBTC-v1, which is designed as a builder-first stand-in for a more decentralized version. Future versions (e.g., sBTC-v2) will introduce a more robust, open-network signer set and additional economic incentives for signers to faithfully process transactions. -* **1:1 redeemability**. sBTC can always be exchanged 1:1 for BTC on the Bitcoin chain, as long as the Stacks blockchain is operational. -* **Open membership**. Anyone can participate in the sBTC protocol. No centralized entity maintains custody over any BTC in the protocol. +### Key Benefits -Other tokens which try to achieve the same end as sBTC are +1. **Bitcoin Compatibility**: Allows Bitcoin holders to participate in the Stacks ecosystem without selling their BTC. +2. **DeFi Access**: Enables BTC holders to engage with decentralized finance applications on Stacks. +3. **Quick Conversions**: Facilitates rapid movement between BTC and sBTC. +4. **Decentralized Management**: Utilizes a set of signers for maintaining the peg wallet. +5. **Community Governance**: Involves the community in key decisions, such as selecting the initial signing set. -* [xBTC](https://www.stacks.co/blog/tokensoft-wrapped-fundamental-bitcoin-defi-building-blocks-xbtc) +## Table of Contents -While these tokens all achieve the same value as BTC, they maintain BTC reserves through trusted entities. sBTC is the only truly decentralized Bitcoin backed asset on Stacks. +1. [Key Concepts](key-concepts.md) +2. [Core Features](core-features.md) +3. [sBTC Operations](operations/README.md) + - [Deposit](operations/deposit.md) + - [Withdrawal](operations/withdrawal.md) +4. [Internal Representations](internal-representations/README.md) + - [Peg Wallet UTxO](internal-representations/peg-wallet-utxo.md) + - [Clarity Contracts](internal-representations/clarity-contracts.md) +5. [Auxiliary Features](auxiliary-features/README.md) + - [Transaction Fee Sponsorship](auxiliary-features/fee-sponsorship.md) + - [Dynamic Blocklist](auxiliary-features/dynamic-blocklist.md) + - [Signer Wallet Rotation](auxiliary-features/signer-wallet-rotation.md) +6. [User Interactions](user-interactions/README.md) + - [Depositing BTC to sBTC](user-interactions/depositing.md) + - [Withdrawing sBTC to BTC](user-interactions/withdrawing.md) + - [Using sBTC in DeFi](user-interactions/defi-usage.md) +7. [Wallet Integration](wallet-integration.md) +8. [Security Considerations](security-considerations.md) +9. [Future Development](future-development.md) -## How does sBTC work? - -Bitcoin holders can do two things to interact with sBTC, deposit and withdraw. Both of these operations are controlled through special Bitcoin transactions. - -To deposit BTC into sBTC, a Bitcoin holder would create a deposit transaction on the Bitcoin chain. This deposit transaction informs the protocol how much BTC the holder has deposited, and to which Stacks address the holder wishes to receive the sBTC. The sBTC system responds to the deposit transaction by minting sBTC to the given Stacks address. - -To withdraw BTC, a Bitcoin holder creates a withdrawal transaction on the Bitcoin chain. This withdrawal transaction informs the protocol how much sBTC the holder wishes to withdraw, from which stacks address the sBTC should be withdrawn and which Bitcoin address should receive the withdrawn BTC. In response to this transaction, the sBTC system burns the requested amount of sBTC from the given Stacks address and fulfills the withdrawal by issuing a BTC payment to the given BTC address with the same amount. - -The following diagram illustrates the deposit and withdrawal flows. - -
- -Next let's take a deeper look at the design of sBTC. +For developers and contributors, please refer to the [sBTC-v1 GitHub repository](https://github.com/stacks-network/sbtc) for the latest updates and development progress. diff --git a/concepts/sbtc/auxiliary-features/README.md b/concepts/sbtc/auxiliary-features/README.md new file mode 100644 index 0000000000..91478824f4 --- /dev/null +++ b/concepts/sbtc/auxiliary-features/README.md @@ -0,0 +1,9 @@ +# Auxiliary Features + +This section covers additional features that enhance the functionality and security of the sBTC system: + +1. [Transaction Fee Sponsorship](fee-sponsorship.md): Allowing sBTC transactions to be sponsored +2. [Dynamic Blocklist](dynamic-blocklist.md): Enhancing security through a flexible blocklist system +3. [Signer Wallet Rotation](signer-wallet-rotation.md): Enabling secure key rotation for sBTC Bootstrap Signers + +These auxiliary features contribute to the overall robustness and user-friendliness of the sBTC ecosystem. diff --git a/concepts/sbtc/auxiliary-features/dynamic-blocklist.md b/concepts/sbtc/auxiliary-features/dynamic-blocklist.md new file mode 100644 index 0000000000..59bc1b82c5 --- /dev/null +++ b/concepts/sbtc/auxiliary-features/dynamic-blocklist.md @@ -0,0 +1,40 @@ +# Dynamic Blocklist + +The Dynamic Blocklist is a security feature implemented in the sBTC system to prevent malicious activities and enhance overall security. + +## Overview + +- The sBTC Bootstrap Signers are launched with support for dynamic blocklists. +- The blocklist is based on an on-host querying system. +- It helps screen deposits and withdrawals for potential security risks. + +## Implementation + +1. Each individual Signer is responsible for running the dynamic blocklist system. +2. Signers have the option to provide their own functionality, but default behavior is provided with the initial system. +3. The blocklist is queried through a local API that the sBTC Bootstrap Signer accesses when deciding whether to approve or deny an sBTC operation. + +## Components + +1. **Dynamic Blocklist Client**: Runs on every machine that hosts an sBTC Bootstrap Signer. +2. **Local API**: Hosted by the Dynamic Blocklist Client for queries from the sBTC Bootstrap Signer. +3. **Update Mechanism**: Allows the blocklist to be updated dynamically as new threats are identified. + +## Use Cases + +The dynamic blocklist can be used to: + +1. Block deposits from known malicious addresses. +2. Prevent withdrawals to sanctioned or high-risk addresses. +3. Flag suspicious patterns of activity for further review. + +## Benefits + +1. **Enhanced Security**: Helps prevent malicious actors from abusing the sBTC system. +2. **Flexibility**: Can be updated quickly to respond to new threats. +3. **Compliance**: Assists in adhering to regulatory requirements. + +## Considerations + +- The blocklist system must balance security with user privacy and system decentralization. +- Regular audits and community oversight may be necessary to ensure the blocklist is not misused. diff --git a/concepts/sbtc/auxiliary-features/fee-sponsorship.md b/concepts/sbtc/auxiliary-features/fee-sponsorship.md new file mode 100644 index 0000000000..43207e98cb --- /dev/null +++ b/concepts/sbtc/auxiliary-features/fee-sponsorship.md @@ -0,0 +1,38 @@ +# Transaction Fee Sponsorship + +Transaction Fee Sponsorship is a feature in sBTC-v1 that allows users to pay for Stacks transaction fees using sBTC instead of STX. + +## Overview + +- sBTC transactions on Stacks can be sponsored in return for some sBTC. +- This feature improves user experience by allowing sBTC holders to use their tokens for gas fees. + +## Implementation + +The fee sponsorship system is implemented using the approach suggested in [stacks-network/stacks-core#4235](https://github.com/stacks-network/stacks-core/issues/4235). + +Key points: + +1. sBTC users can get support from existing STX holders for transaction fees. +2. The sponsor pays the STX fee and receives sBTC in return. + +## User Experience + +From a user's perspective: + +1. When initiating an sBTC transaction, they can opt for fee sponsorship. +2. The user agrees to pay a small amount of sBTC for the sponsorship. +3. The transaction is then processed with the fees paid in STX by the sponsor. + +## Benefits + +1. **Improved UX**: Users don't need to hold STX to use sBTC. +2. **Lower Barrier to Entry**: New users can start using sBTC without first acquiring STX. +3. **Flexibility**: Provides an additional option for handling transaction fees. + +## Future Development + +While sBTC-v1 includes a basic sponsorship system, future versions may implement more advanced features: + +- **Dynamic Transaction Fee Market**: Allow sBTC users to choose the transaction sponsor who requires the least sBTC in return. +- **Automated Sponsorship**: Integrate sponsorship directly into wallets and dApps for a seamless experience. diff --git a/concepts/sbtc/auxiliary-features/signer-wallet-rotation.md b/concepts/sbtc/auxiliary-features/signer-wallet-rotation.md new file mode 100644 index 0000000000..350f5f3efa --- /dev/null +++ b/concepts/sbtc/auxiliary-features/signer-wallet-rotation.md @@ -0,0 +1,41 @@ +# Signer Wallet Rotation + +Signer Wallet Rotation is a crucial security feature in the sBTC system that allows sBTC Bootstrap Signers to rotate their private keys securely. + +## Overview + +- sBTC Bootstrap Signers have the ability to rotate their private keys. +- This feature enhances the long-term security of the sBTC system. +- Key rotation is coordinated among signers and requires on-chain voting. + +## Process + +1. Signers coordinate offline to initiate the key rotation process. +2. Signers vote on-chain for the new signer set (new set of keys). +3. Once the new signer set is determined, signers conduct a wallet handoff. +4. The signers re-execute the Distributed Key Generation (DKG) process. + +## Implementation + +The Signer Wallet Rotation process is facilitated by: + +1. **Signer Key Rotation CLI**: Allows individual signers to initiate a private key rotation. +2. **Key Rotation Clarity Contracts**: Handle the on-chain aspects of the rotation process. + +## Security Considerations + +- The rotation process must ensure that the sBTC UTxO remains secure throughout the transition. +- Proper coordination among signers is crucial to prevent any disruption in sBTC operations. +- The new keys must be thoroughly verified before being put into use. + +## Benefits + +1. **Enhanced Security**: Regular key rotations reduce the risk of key compromise. +2. **Flexibility**: Allows for the replacement of compromised or lost keys. +3. **Continuity**: Enables long-term operation of the sBTC system with evolving security measures. + +## Best Practices + +- Signers should rotate their keys on a regular schedule (e.g., every 6 months). +- Emergency rotation procedures should be in place for suspected key compromises. +- The rotation process should be audited and tested regularly to ensure smooth execution when needed. diff --git a/concepts/sbtc/core-features.md b/concepts/sbtc/core-features.md new file mode 100644 index 0000000000..507e06e9b0 --- /dev/null +++ b/concepts/sbtc/core-features.md @@ -0,0 +1,40 @@ +# Core Features of sBTC + +sBTC offers several core features that make it a powerful trust-minimized Bitcoin bridge between Stacks and Bitcoin: + +## 1. 1:1 Bitcoin Backing + +Each sBTC token is backed by an equivalent amount of Bitcoin in the peg wallet. This ensures that sBTC maintains a stable value relative to BTC. + +## 2. Decentralized Management + +The sBTC peg wallet is maintained and managed by a set of sBTC signers. This decentralized approach enhances security and reduces single points of failure. + +## 3. Quick Conversions + +sBTC facilitates rapid movement between BTC and sBTC: + +- BTC to sBTC conversion can be completed within 3 Bitcoin blocks +- sBTC to BTC conversion can be completed within 6 Bitcoin blocks + +## 4. SIP-10 Compatibility + +sBTC adheres to the SIP-10 fungible token standard on the Stacks blockchain. This ensures wide compatibility with Stacks wallets and applications. + +## 5. Dynamic Blocklist + +The signer binary incorporates an effective screening mechanism for a dynamic blocklist. This feature helps prevent malicious activities and enhances the overall security of the system. + +## 6. Community Governance + +The initial sBTC signing set is determined by a community vote, weighted by STX holdings. This approach ensures that the community has a say in the management of the sBTC system. + +## 7. Signer Key Rotation + +sBTC signers have the ability to rotate their private keys, enhancing long-term security of the system. + +## 8. Transaction Fee Sponsorship + +sBTC transactions on Stacks can be sponsored, allowing users to pay transaction fees in sBTC instead of STX. + +These core features work together to create a secure, efficient, and user-friendly bridge between Bitcoin and the Stacks ecosystem. Let's dig into each of these features. diff --git a/concepts/sbtc/future-development.md b/concepts/sbtc/future-development.md new file mode 100644 index 0000000000..ff64f298ba --- /dev/null +++ b/concepts/sbtc/future-development.md @@ -0,0 +1,38 @@ +# Future Development + +This document outlines the roadmap for future development of sBTC beyond the initial v1 release. + +## sBTC v2 + +The next major version of sBTC is planned for late 2024 and will introduce several key improvements: + +1. **Decentralized Signer Set**: Transition from the bootstrap signer set to a more decentralized model where Stacks miners also act as sBTC signers. + +2. **Native Stacks Integration**: sBTC operations will be handled natively by Stacks nodes, removing the need for separate signer infrastructure. + +3. **Economic Incentives**: Introduce rewards for signers/miners to incentivize faithful processing of sBTC operations. + +4. **Improved Scalability**: Optimize the system to handle higher transaction volumes and reduce confirmation times. + +## Potential Future Enhancements + +1. **Cross-chain Interoperability**: Explore bridging sBTC to other blockchain ecosystems. + +2. **Advanced DeFi Integrations**: Develop more sophisticated DeFi primitives leveraging sBTC. + +3. **Layer 2 Solutions**: Investigate Layer 2 scaling solutions for faster and cheaper sBTC transactions. + +4. **Privacy Enhancements**: Research and potentially implement privacy-preserving features for sBTC transactions. + +5. **Governance Improvements**: Refine the governance model for protocol upgrades and parameter adjustments. + +## Community Involvement + +The future development of sBTC will heavily rely on community input and contributions. Developers, researchers, and users are encouraged to participate in: + +- Proposing and discussing improvement proposals +- Contributing to the codebase +- Participating in testnets and security audits +- Providing feedback on user experience and feature requests + +Stay tuned to the official sBTC communication channels for updates on the development roadmap and opportunities to contribute to the future of Bitcoin on Stacks. diff --git a/concepts/sbtc/internal-representations/README.md b/concepts/sbtc/internal-representations/README.md new file mode 100644 index 0000000000..ff247bffa9 --- /dev/null +++ b/concepts/sbtc/internal-representations/README.md @@ -0,0 +1,8 @@ +# Internal Representations + +This section covers the internal representations of BTC used in the sBTC system: + +1. [Peg Wallet UTxO](peg-wallet-utxo.md): How the Bitcoin peg is maintained +2. [Clarity Contracts](clarity-contracts.md): Smart contracts that manage sBTC on the Stacks blockchain + +These internal representations form the backbone of the sBTC system, enabling secure and efficient operations between the Bitcoin and Stacks blockchains. diff --git a/concepts/sbtc/internal-representations/clarity-contracts.md b/concepts/sbtc/internal-representations/clarity-contracts.md new file mode 100644 index 0000000000..acc9ad95ff --- /dev/null +++ b/concepts/sbtc/internal-representations/clarity-contracts.md @@ -0,0 +1,119 @@ +# sBTC Clarity Contracts Documentation + +This document provides an overview and detailed explanation of the sBTC Clarity contracts. These contracts are designed to facilitate the creation, management, and transfer of sBTC tokens on the Stacks blockchain. + +## Contracts Overview + +1. [sbtc-bootstrap-signers](#sbtc-bootstrap-signers) +2. [sbtc-deposit](#sbtc-deposit) +3. [sbtc-registry](#sbtc-registry) +4. [sbtc-token](#sbtc-token) +5. [sbtc-withdrawal](#sbtc-withdrawal) + +## sbtc-bootstrap-signers + +This contract manages the signer set for the sBTC protocol. + +### Key Functions + +- `rotate-keys-wrapper`: Rotates the keys of the signers when the signer set is updated. +- `pubkeys-to-spend-script`: Generates the p2sh redeem script for a multisig. +- `pubkeys-to-principal`: Generates a principal given a set of pubkeys and an m-of-n threshold. + +### Constants + +- `key-size`: The required length of public keys (33 bytes). +- `ERR_KEY_SIZE`: Error code for invalid key size. +- `ERR_INVALID_CALLER`: Error code for unauthorized function caller. +- `ERR_SIGNATURE_THRESHOLD`: Error code for invalid signature threshold. + +## sbtc-deposit + +This contract handles the deposit of BTC to mint sBTC. + +### Key Functions + +- `complete-deposit-wrapper`: Completes a deposit request, minting sBTC to the recipient. +- `complete-deposits-wrapper`: Handles multiple deposit requests in a single transaction. + +### Constants + +- `txid-length`: The required length of a transaction ID (32 bytes). +- `dust-limit`: The minimum amount of satoshis that can be deposited (546 sats). +- `ERR_TXID_LEN`: Error code for invalid transaction ID length. +- `ERR_DEPOSIT_REPLAY`: Error code for attempting to complete an already processed deposit. +- `ERR_LOWER_THAN_DUST`: Error code for deposits below the dust limit. +- `ERR_INVALID_CALLER`: Error code for unauthorized function caller. + +## sbtc-registry + +This contract serves as the central registry for the sBTC protocol, managing withdrawal requests, deposits, and signer data. + +### Key Functions + +- `create-withdrawal-request`: Creates a new withdrawal request. +- `complete-withdrawal-accept`: Marks a withdrawal request as accepted. +- `complete-withdrawal-reject`: Marks a withdrawal request as rejected. +- `complete-deposit`: Records a completed deposit. +- `rotate-keys`: Updates the signer set, multi-sig principal, and aggregate public key. + +### Data Structures + +- `withdrawal-requests`: Map storing withdrawal request details. +- `withdrawal-status`: Map storing the status of withdrawal requests. +- `completed-deposits`: Map storing completed deposit information. +- `aggregate-pubkeys`: Map storing aggregate public keys to prevent replay attacks. +- `multi-sig-address`: Map storing multi-sig addresses to prevent replay attacks. +- `protocol-contracts`: Map storing active protocol contracts. + +## sbtc-token + +This contract implements the sBTC token, following the SIP-010 fungible token standard. + +### Key Functions + +- `protocol-transfer`: Transfers sBTC between accounts (only callable by protocol contracts). +- `protocol-lock`: Locks sBTC by burning tokens and minting locked tokens. +- `protocol-unlock`: Unlocks sBTC by burning locked tokens and minting regular tokens. +- `protocol-mint`: Mints new sBTC tokens. +- `protocol-burn`: Burns sBTC tokens. +- `transfer`: Transfers sBTC tokens (implements SIP-010). + +### Token Properties + +- `token-name`: The name of the token ("sBTC"). +- `token-symbol`: The symbol of the token ("sBTC"). +- `token-uri`: Optional URI for token metadata. +- `token-decimals`: The number of decimal places for the token (8). + +## sbtc-withdrawal + +This contract handles the withdrawal of sBTC to receive BTC. + +### Key Functions + +- `initiate-withdrawal-request`: Initiates a new withdrawal request. +- `accept-withdrawal-request`: Accepts and processes a withdrawal request. +- `reject-withdrawal-request`: Rejects a withdrawal request. +- `complete-withdrawals`: Processes multiple withdrawal requests in a single transaction. + +### Constants + +- `MAX_ADDRESS_VERSION`: Maximum value of a valid address version (6). +- `MAX_ADDRESS_VERSION_BUFF_20`: Maximum address version for 20-byte hash addresses (4). +- `MAX_ADDRESS_VERSION_BUFF_32`: Maximum address version for 32-byte hash addresses (6). +- `DUST_LIMIT`: Minimum amount of sBTC that can be withdrawn (546 sats). + +### Error Codes + +- `ERR_INVALID_ADDR_VERSION`: Invalid address version. +- `ERR_INVALID_ADDR_HASHBYTES`: Invalid address hash bytes. +- `ERR_DUST_LIMIT`: Withdrawal amount below dust limit. +- `ERR_INVALID_REQUEST`: Invalid withdrawal request ID. +- `ERR_INVALID_CALLER`: Unauthorized function caller. +- `ERR_ALREADY_PROCESSED`: Withdrawal request already processed. +- `ERR_FEE_TOO_HIGH`: Paid fee higher than requested. + +## Conclusion + +These contracts work together to create a decentralized system for managing sBTC, a synthetic representation of Bitcoin on the Stacks blockchain. The contracts handle key operations such as minting sBTC through deposits, burning sBTC through withdrawals, managing the signer set, and maintaining the overall state of the protocol. diff --git a/concepts/sbtc/internal-representations/peg-wallet-utxo.md b/concepts/sbtc/internal-representations/peg-wallet-utxo.md new file mode 100644 index 0000000000..bec7647482 --- /dev/null +++ b/concepts/sbtc/internal-representations/peg-wallet-utxo.md @@ -0,0 +1,33 @@ +# Peg Wallet UTxO + +The Peg Wallet UTxO is a crucial component of the sBTC system, representing the Bitcoin backing for all sBTC tokens in circulation. + +## Single UTxO Model + +The sBTC peg wallet is always represented as a single Unspent Transaction Output (UTxO) on the Bitcoin blockchain. This design choice simplifies management and improves efficiency. + +## UTxO Management + +The Signer coordinator is responsible for managing this single UTxO: + +1. It consolidates all deposit and withdrawal requests. +2. It creates best-effort batches that can be used in a single UTxO. +3. The new UTxO spends the amount in the previous UTxO plus any confirmed deposits, minus any confirmed withdrawals. + +## Batching Process + +The batching process is optimized to maintain the single UTxO invariant while creating optimal batches: + +1. When there are multiple sBTC operation requests, the Signer coordinator groups them by approval sets. +2. In cases where there are differing approval sets across all active sBTC operations, the Signer coordinator will batch the deposit UTxOs into groups that have the maximum group size per approval set. + +## Advantages of the Single UTxO Model + +1. **Simplicity**: Easier to track and manage a single UTxO. +2. **Efficiency**: Reduces the number of Bitcoin transactions needed for sBTC operations. +3. **Security**: Centralizes the funds in a single, well-secured output. + +## Security Considerations + +- The single UTxO is managed by the sBTC Bootstrap Signer Set, requiring a threshold of signers to approve any spending. +- Regular audits and monitoring are crucial to ensure the UTxO always accurately represents the total sBTC in circulation. diff --git a/concepts/sbtc/key-concepts.md b/concepts/sbtc/key-concepts.md new file mode 100644 index 0000000000..71e04830ac --- /dev/null +++ b/concepts/sbtc/key-concepts.md @@ -0,0 +1,42 @@ +# Key Concepts + +Understanding sBTC requires familiarity with several key concepts: + +## sBTC + +sBTC is a SIP-10 token on the Stacks Blockchain that can be converted back to BTC on the Bitcoin Blockchain. The key property of sBTC is its 1:1 peg to Bitcoin, meaning 1 sBTC is always equivalent to 1 BTC. + +## sBTC Operation + +An sBTC operation is any action initiated within the sBTC protocol. The two primary operations are: + +- Depositing BTC to mint sBTC +- Withdrawing sBTC to receive BTC + +## sBTC UTxO + +The sBTC UTxO is the single unspent transaction output (UTxO) on the Bitcoin blockchain that holds the entire BTC balance pegged into sBTC. This UTxO is managed and maintained by the sBTC Signers. + +## sBTC Bootstrap Signer + +In sBTC-v1, the sBTC Bootstrap Signer Set is an entity separate from the Stacks Nakamoto signer. sBTC signer responsibilities include: + +- Signing sBTC operations +- Communicating with contracts on the Stacks chain +- Managing the sBTC UTxO + +This role is specific to sBTC-v1. In future version of sBTC, Nakamoto and sBTC signers will be the same entity. + +## sBTC Bootstrap Signer Set + +The sBTC Bootstrap Signer Set is the group of all sBTC signers. This set has full democratic access to the sBTC UTxO. Key properties include: + +- Selected through a community vote weighted by STX holdings +- Responsible for maintaining the security of the peg wallet +- Ability to rotate their private keys for enhanced security + +## SIP-10 Token + +sBTC adheres to the SIP-10 (Stacks Improvement Proposal 10) standard for fungible tokens on the Stacks blockchain. This ensures compatibility with wallets and applications that support the SIP-10 standard. + +Understanding these concepts is crucial for grasping the overall architecture and functionality of sBTC. In the following sections, we'll explore how these concepts come together to create sBTC. diff --git a/concepts/sbtc/operations/README.md b/concepts/sbtc/operations/README.md new file mode 100644 index 0000000000..7ef0469189 --- /dev/null +++ b/concepts/sbtc/operations/README.md @@ -0,0 +1,8 @@ +# sBTC Operations + +This section covers the main operations in the sBTC system: + +1. [Deposit](deposit.md): Converting BTC to sBTC +2. [Withdrawal](withdrawal.md): Converting sBTC back to BTC + +These operations form the core functionality of sBTC, allowing users to move value between the Bitcoin and Stacks ecosystems. diff --git a/concepts/sbtc/operations/deposit.md b/concepts/sbtc/operations/deposit.md new file mode 100644 index 0000000000..bfac1e538c --- /dev/null +++ b/concepts/sbtc/operations/deposit.md @@ -0,0 +1,42 @@ +# sBTC Deposit Operation + +The deposit operation allows users to convert their BTC to sBTC. This process involves moving BTC from the Bitcoin blockchain to the Stacks blockchain as sBTC. + +## Process Overview + +1. An API call referencing a Bitcoin transaction initiates the deposit process. +2. The deposit can be completed within a single Bitcoin block. +3. The Deposit API relays deposit information to the sBTC Bootstrap Signers. +4. sBTC Bootstrap Signers verify and process the deposit. +5. Equivalent sBTC is minted on the Stacks blockchain. + +## Deposit API + +The Deposit API plays a crucial role in the deposit process: + +- It relays deposit information to the sBTC Bootstrap Signers. +- It reduces the cost for deposit on rejection. +- It simplifies the sBTC system and makes it easier to service. + +## Bitcoin Deposit Requirements + +Deposits must meet specific requirements to be considered valid: + +1. The deposit must pay to a taproot address. +2. The deposit must be spendable by a consensus threshold of signers. +3. The deposit must fit a specific format that cannot be clawed back in the short term. + +## Security Considerations + +- The sBTC Bootstrap Signers screen deposits using a dynamic blocklist to prevent malicious activities. +- Multiple confirmations may be required before the deposit is considered final. + +## User Experience + +From a user's perspective, the deposit process involves: + +1. Initiating a BTC transaction to a specified address. +2. Waiting for the transaction to be confirmed on the Bitcoin blockchain. +3. Receiving the equivalent amount of sBTC in their Stacks wallet. + +The sBTC bridge web app provides a user-friendly interface for tracking the status of deposit operations. diff --git a/concepts/sbtc/operations/withdrawal.md b/concepts/sbtc/operations/withdrawal.md new file mode 100644 index 0000000000..23e79d1f84 --- /dev/null +++ b/concepts/sbtc/operations/withdrawal.md @@ -0,0 +1,39 @@ +# sBTC Withdrawal Operation + +The withdrawal operation allows users to convert their sBTC back to BTC. This process involves burning sBTC on the Stacks blockchain and releasing the equivalent amount of BTC on the Bitcoin blockchain. + +## Process Overview + +1. A Clarity contract call initiates the withdrawal process. +2. The withdrawal requires 6 sortitions (Stacks block confirmations) for completion. +3. After confirmation, sBTC Bootstrap Signers create the withdrawal transaction on the Bitcoin network. +4. The user receives BTC in their specified Bitcoin address. + +## Withdrawal Confirmation + +The requirement for 6 sortitions serves several purposes: + +1. It ensures the finality of the Stacks transaction. +2. It prevents issues that could arise from potential Bitcoin forks. +3. It gives sBTC Bootstrap Signers sufficient time to verify and process the withdrawal. + +## Failure Cases + +Some withdrawal failures can be resolved earlier than 6 sortitions, but others may only fail after the sBTC Bootstrap Signer attempts to create the withdrawal transaction. + +## Security Considerations + +- The multi-sortition confirmation process helps prevent double-spending attempts. +- sBTC Bootstrap Signers verify the withdrawal request before processing it. +- The dynamic blocklist is consulted to prevent withdrawals to known malicious addresses. + +## User Experience + +From a user's perspective, the withdrawal process involves: + +1. Initiating a withdrawal request through a Stacks wallet or dApp. +2. Specifying the amount of sBTC to withdraw and the destination Bitcoin address. +3. Waiting for the required confirmations (6 sortitions). +4. Receiving BTC in the specified Bitcoin address. + +The sBTC bridge web app will provide a user-friendly interface for tracking the status of withdrawal operations. diff --git a/concepts/sbtc/security-considerations.md b/concepts/sbtc/security-considerations.md new file mode 100644 index 0000000000..0d50297e90 --- /dev/null +++ b/concepts/sbtc/security-considerations.md @@ -0,0 +1,55 @@ +# Security Considerations + +This document outlines key security considerations for the sBTC system. + +## Peg Wallet Security + +- The sBTC peg wallet is secured by a multi-signature scheme requiring a threshold of signers +- Private keys for signers must be stored securely, ideally in hardware security modules +- Regular security audits of signer infrastructure should be conducted + +## Signer Set + +- The initial signer set is determined by community vote to ensure decentralization +- A minimum of 5 signers is recommended for adequate security and fault tolerance +- Signer set should be geographically distributed to mitigate risks + +## Key Rotation + +- Signers can rotate their private keys to mitigate risks of key compromise +- Key rotation process must be carefully coordinated to maintain peg wallet security + +## Dynamic Blocklist + +- Signers implement a dynamic blocklist to prevent processing of suspicious transactions +- Blocklist criteria and implementation must be regularly reviewed and updated + +## Smart Contract Security + +- All sBTC-related Clarity contracts should undergo thorough security audits +- Formal verification of critical contract components is recommended +- Upgrade mechanisms should be carefully designed and controlled + +## Transaction Validation + +- Rigorous validation of deposit and withdrawal transactions on both Bitcoin and Stacks chains +- Implement safeguards against double-spend attacks and transaction malleability + +## Operational Security + +- Strict access controls and monitoring for all sBTC infrastructure +- Regular security training for all personnel involved in sBTC operations +- Incident response plans should be established and regularly tested + +## User Security + +- Clear guidelines for users on securely storing and transacting with sBTC +- Education on potential risks and best practices + +## Ongoing Security + +- Regular security assessments and penetration testing of the entire sBTC system +- Bug bounty program to incentivize responsible disclosure of vulnerabilities +- Continuous monitoring for unusual activity or potential exploits + +By adhering to these security considerations, the sBTC system aims to provide a robust and secure bridge between Bitcoin and the Stacks ecosystem. However, security is an ongoing process and these measures should be regularly reviewed and updated. diff --git a/concepts/sbtc/user-interactions/README.md b/concepts/sbtc/user-interactions/README.md new file mode 100644 index 0000000000..81d34c8d0e --- /dev/null +++ b/concepts/sbtc/user-interactions/README.md @@ -0,0 +1,9 @@ +# User Interactions + +This section covers the primary ways users interact with the sBTC system: + +1. [Depositing BTC to sBTC](depositing.md) +2. [Withdrawing sBTC to BTC](withdrawing.md) +3. [Using sBTC in DeFi](defi-usage.md) + +These interactions form the core user experience of the sBTC ecosystem, enabling seamless movement between Bitcoin and Stacks, as well as participation in Stacks-based decentralized finance applications. diff --git a/concepts/sbtc/user-interactions/defi-usage.md b/concepts/sbtc/user-interactions/defi-usage.md new file mode 100644 index 0000000000..77b94ca5c6 --- /dev/null +++ b/concepts/sbtc/user-interactions/defi-usage.md @@ -0,0 +1,71 @@ +# Using sBTC in DeFi Applications + +This guide explains how users can utilize their sBTC in various Decentralized Finance (DeFi) applications on the Stacks blockchain. + +## Overview + +sBTC allows Bitcoin holders to participate in DeFi applications on the Stacks blockchain without selling their BTC. This opens up opportunities for earning yield, providing liquidity, and engaging in other financial activities. + +## Common DeFi Use Cases for sBTC + +1. **Lending and Borrowing** + + - Lend your sBTC to earn interest + - Use sBTC as collateral to borrow other assets + +2. **Liquidity Provision** + + - Provide liquidity to sBTC trading pairs in decentralized exchanges + - Earn fees from trades in these pools + +3. **Yield Farming** + + - Stake your sBTC or sBTC liquidity pool tokens in yield farming protocols + - Earn additional tokens or fees as rewards + +4. **Synthetic Assets** + - Use sBTC as collateral to mint synthetic assets representing other cryptocurrencies or real-world assets + +## Step-by-Step Guide + +1. **Choose a DeFi Application** + + - Research and select a Stacks-based DeFi application that supports sBTC + +2. **Connect Your Wallet** + + - Connect your Stacks wallet containing sBTC to the DeFi application + +3. **Select the Desired Action** + + - Choose the DeFi activity you want to engage in (e.g., lending, providing liquidity) + +4. **Approve sBTC Usage** + + - Grant permission for the DeFi application to use your sBTC + +5. **Confirm the Transaction** + + - Review and confirm the transaction details + - Submit the transaction to the Stacks blockchain + +6. **Monitor Your Position** + - Keep track of your sBTC position in the DeFi application + - Be aware of any risks or potential liquidation scenarios + +## Important Considerations + +- Always research and understand the risks associated with any DeFi application before using it +- Be aware of smart contract risks and the possibility of bugs or exploits +- Understand the terms and conditions of each DeFi protocol, including fees and reward structures +- Keep track of your transactions for tax reporting purposes + +## Direct BTC to DeFi Integration + +Some DeFi applications may offer direct integration with the sBTC bridge, allowing you to deposit BTC and immediately use it in the DeFi application. This process typically involves: + +1. Selecting the option to deposit BTC directly into the DeFi application +2. Sending BTC to the provided address +3. The application automatically converts BTC to sBTC and uses it in the selected DeFi activity + +This streamlined process can make it even easier for Bitcoin holders to participate in Stacks-based DeFi. diff --git a/concepts/sbtc/user-interactions/depositing.md b/concepts/sbtc/user-interactions/depositing.md new file mode 100644 index 0000000000..23d4efe3e4 --- /dev/null +++ b/concepts/sbtc/user-interactions/depositing.md @@ -0,0 +1,46 @@ +# Depositing BTC to sBTC + +This guide explains the process of converting BTC to sBTC, allowing users to bring their Bitcoin into the Stacks ecosystem. + +## Process Overview + +1. User initiates a deposit through the sBTC bridge dashboard or a compatible wallet. +2. User sends BTC to a specified address. +3. The deposit is processed and confirmed on the Bitcoin blockchain. +4. Equivalent sBTC is minted on the Stacks blockchain and sent to the user's Stacks address. + +## Step-by-Step Guide + +1. **Access the sBTC Bridge** + + - Navigate to the sBTC bridge dashboard or use a compatible wallet. + +2. **Initiate Deposit** + + - Select the "Deposit BTC" option. + - Specify the amount of BTC you want to convert to sBTC. + +3. **Send BTC** + + - You'll be provided with a Bitcoin address to send your BTC to. + - Send the exact amount of BTC specified in the previous step. + +4. **Wait for Confirmation** + + - The system will wait for the Bitcoin transaction to be confirmed (usually within 3 Bitcoin blocks). + +5. **Receive sBTC** + - Once confirmed, the equivalent amount of sBTC will be minted and sent to your Stacks address. + - This process is typically completed within a single Bitcoin block after confirmation. + +## Important Considerations + +- Ensure you're using the official sBTC bridge or a trusted, compatible wallet. +- Double-check all addresses and amounts before sending BTC. +- Be aware of any minimum deposit amounts or fees associated with the process. +- The conversion rate is always 1:1 (1 BTC = 1 sBTC). + +## Troubleshooting + +- If your deposit doesn't appear after several confirmations, check the transaction status on a Bitcoin block explorer. +- For any issues, contact the sBTC support team through official channels. diff --git a/concepts/sbtc/user-interactions/withdrawing.md b/concepts/sbtc/user-interactions/withdrawing.md new file mode 100644 index 0000000000..491cb0aa00 --- /dev/null +++ b/concepts/sbtc/user-interactions/withdrawing.md @@ -0,0 +1,47 @@ +# Withdrawing sBTC to BTC + +This guide explains the process of converting sBTC back to BTC, allowing users to move their assets from the Stacks ecosystem back to the Bitcoin blockchain. + +## Process Overview + +1. User initiates a withdrawal through the sBTC bridge dashboard or a compatible wallet. +2. The withdrawal request is processed on the Stacks blockchain. +3. After confirmation (6 Stacks block sortitions), the sBTC Bootstrap Signers process the withdrawal. +4. BTC is sent to the user's specified Bitcoin address. + +## Step-by-Step Guide + +1. **Access the sBTC Bridge** + + - Navigate to the sBTC bridge dashboard or use a compatible wallet. + +2. **Initiate Withdrawal** + + - Select the "Withdraw sBTC" or "Redeem sBTC" option. + - Specify the amount of sBTC you want to convert back to BTC. + - Enter the Bitcoin address where you want to receive your BTC. + +3. **Confirm the Transaction** + + - Review the details of your withdrawal request. + - Confirm the transaction, which will be submitted to the Stacks blockchain. + +4. **Wait for Confirmation** + + - The system will wait for 6 Stacks block sortitions (confirmations) to ensure the finality of the transaction. + - This process typically takes about 60-90 minutes. + +5. **Receive BTC** + - Once confirmed and processed by the sBTC Bootstrap Signers, the equivalent amount of BTC will be sent to your specified Bitcoin address. + +## Important Considerations + +- Ensure you're using the official sBTC bridge or a trusted, compatible wallet. +- Double-check the Bitcoin address you're withdrawing to. Errors cannot be reversed. +- Be aware of any minimum withdrawal amounts or fees associated with the process. +- The conversion rate is always 1:1 (1 sBTC = 1 BTC). + +## Troubleshooting + +- If your withdrawal doesn't appear after several hours, check the transaction status on both Stacks and Bitcoin block explorers. +- For any issues, contact the sBTC support team through official channels. diff --git a/concepts/sbtc/wallet-integration.md b/concepts/sbtc/wallet-integration.md new file mode 100644 index 0000000000..0091b5afc8 --- /dev/null +++ b/concepts/sbtc/wallet-integration.md @@ -0,0 +1,50 @@ +# Wallet Integration + +This guide outlines how wallet developers can integrate sBTC deposits and withdrawals directly into their wallets, providing Bitcoin holders with easy access to Stacks smart contracts. + +## Deposit Flow + +To support sBTC deposits: + +1. Add an option for users to deposit BTC as sBTC +2. When selected, prompt the user for the BTC amount to deposit +3. Generate a deposit address using the sBTC deposit API (docs coming soon) +4. Display deposit instructions to the user +5. Monitor for the deposit transaction on Bitcoin +6. Once confirmed, show the sBTC balance in the wallet + +## Withdrawal Flow + +To support sBTC withdrawals: + +1. Add an option for users to withdraw sBTC to BTC +2. When selected, prompt for the sBTC amount and BTC address +3. Construct and broadcast the sBTC withdrawal transaction +4. Monitor for completion of the withdrawal (6 Stacks block confirmations) +5. Update the wallet balances once withdrawal is processed + +## Balance Updates + +- Update and display both BTC and sBTC balances after deposits/withdrawals +- Show pending/processing status for in-flight operations + +## API Integration + +Integrate with the sBTC deposit API and Stacks blockchain API to: + +- Generate deposit addresses +- Monitor deposit/withdrawal status +- Query sBTC balances + +## Security Considerations + +- Use secure key management for signing sBTC transactions +- Validate all user inputs +- Handle error cases gracefully +- Follow best practices for Bitcoin and Stacks address generation/validation + +## Testing + +Thoroughly test deposit and withdrawal flows on testnet before mainnet launch. + +For more details on the APIs and contracts, refer to the sBTC developer documentation.