Initial sbtc docs update

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.
-
-<figure><img src="../../.gitbook/assets/Diagram Feb 2 2024.png" alt=""><figcaption></figcaption></figure>
-
-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.

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.

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.

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.

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.

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.

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.

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.