Initial sbtc docs update

concepts/sbtc/README.md

@@ -25,19 +25,13 @@ This documentation primarily covers sBTC-v1, which is designed as a builder-firs
 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)
+4. [Peg Wallet UTxO](peg-wallet-utxo.md)
+5. [Clarity Contracts](clarity-contracts.md)
+6. [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)
+7. [Security Considerations](security-considerations.md)
+8. [Future Development](future-development.md)
 
 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/clarity-contracts/sbtc-bootstrap-signers.md

@@ -0,0 +1,188 @@
+# sBTC Bootstrap Signers Contract Documentation
+
+This document provides a comprehensive overview of the sBTC Bootstrap Signers contract implemented in Clarity. The contract manages the rotation of signer keys for the sBTC system and includes utilities for multisignature address generation.
+
+## Table of Contents
+
+1. [Constants](#constants)
+2. [Error Codes](#error-codes)
+3. [Public Functions](#public-functions)
+4. [Read-Only Functions](#read-only-functions)
+5. [Private Functions](#private-functions)
+6. [Utility Functions](#utility-functions)
+
+## Constants
+
+The contract defines several constants:
+
+```clarity
+(define-constant key-size u33)
+```
+
+This constant sets the required length of public keys to 33 bytes.
+
+## Error Codes
+
+The contract defines several error codes for various scenarios:
+
+```clarity
+(define-constant ERR_KEY_SIZE (err u200))
+(define-constant ERR_INVALID_CALLER (err u201))
+(define-constant ERR_SIGNATURE_THRESHOLD (err u202))
+```
+
+- `ERR_KEY_SIZE`: Indicates an issue with the key size (error code 200).
+- `ERR_INVALID_CALLER`: Indicates that the function caller is not the current signer principal (error code 201).
+- `ERR_SIGNATURE_THRESHOLD`: Indicates an invalid signature threshold (error code 202).
+
+There's also a special error code prefix for individual key size errors:
+
+```clarity
+(define-constant ERR_KEY_SIZE_PREFIX (unwrap-err! ERR_KEY_SIZE (err true)))
+```
+
+This is used to generate unique error codes for each key in a list that might have an incorrect size.
+
+## Public Functions
+
+### rotate-keys-wrapper
+
+This function is used to rotate the keys of the signers. It's called whenever the signer set is updated.
+
+```clarity
+(define-public (rotate-keys-wrapper
+    (new-keys (list 128 (buff 33)))
+    (new-aggregate-pubkey (buff 33))
+    (new-signature-threshold uint)
+  )
+  ;; Function body...
+)
+```
+
+Parameters:
+
+- `new-keys`: A list of up to 128 new public keys, each 33 bytes long.
+- `new-aggregate-pubkey`: The new aggregate public key, 33 bytes long.
+- `new-signature-threshold`: The new signature threshold.
+
+The function performs several checks:
+
+1. Verifies that the signature threshold is valid (> 50% and <= 100% of the total number of signer keys).
+2. Checks that the caller is the current signer principal.
+3. Verifies that each new key has the correct length (33 bytes).
+4. Checks that the new aggregate public key has the correct length (33 bytes).
+
+If all checks pass, it calls the `rotate-keys` function in the `.sbtc-registry` contract to update the keys and address.
+
+## Read-Only Functions
+
+### pubkeys-to-spend-script
+
+Generates the p2sh redeem script for a multisig.
+
+```clarity
+(define-read-only (pubkeys-to-spend-script
+    (pubkeys (list 128 (buff 33)))
+    (m uint)
+  )
+  ;; Function body...
+)
+```
+
+### pubkeys-to-hash
+
+Computes the hash160 of the p2sh redeem script.
+
+```clarity
+(define-read-only (pubkeys-to-hash
+    (pubkeys (list 128 (buff 33)))
+    (m uint)
+  )
+  ;; Function body...
+)
+```
+
+### pubkeys-to-principal
+
+Generates a principal given a set of pubkeys and an m-of-n threshold.
+
+```clarity
+(define-read-only (pubkeys-to-principal
+    (pubkeys (list 128 (buff 33)))
+    (m uint)
+  )
+  ;; Function body...
+)
+```
+
+### pubkeys-to-bytes
+
+Concatenates a list of pubkeys into a buffer with length prefixes.
+
+```clarity
+(define-read-only (pubkeys-to-bytes (pubkeys (list 128 (buff 33))))
+  ;; Function body...
+)
+```
+
+### concat-pubkeys-fold
+
+Concatenates a pubkey buffer with a length prefix.
+
+```clarity
+(define-read-only (concat-pubkeys-fold (pubkey (buff 33)) (iterator (buff 510)))
+  ;; Function body...
+)
+```
+
+## Private Functions
+
+### signer-key-length-check
+
+Checks that the length of each key is exactly 33 bytes.
+
+```clarity
+(define-private (signer-key-length-check (current-key (buff 33)) (helper-response (response uint uint)))
+  ;; Function body...
+)
+```
+
+## Utility Functions
+
+The contract includes several utility functions for working with bytes and integers:
+
+### bytes-len
+
+Returns the length of a byte buffer as a single byte.
+
+```clarity
+(define-read-only (bytes-len (bytes (buff 33)))
+  ;; Function body...
+)
+```
+
+### uint-to-byte
+
+Converts a uint to a single byte.
+
+```clarity
+(define-read-only (uint-to-byte (n uint))
+  ;; Function body...
+)
+```
+
+### BUFF_TO_BYTE
+
+A constant list that maps uint values (0-255) to their corresponding byte representations.
+
+```clarity
+(define-constant BUFF_TO_BYTE (list
+  0x00 0x01 0x02 0x03 ...
+))
+```
+
+This constant is used by the `bytes-len` and `uint-to-byte` functions to perform efficient conversions.
+
+## Conclusion
+
+This contract provides essential functionality for managing signer keys in the sBTC system. It includes robust error checking and utility functions for working with public keys and generating multisignature addresses. The contract interacts with the `.sbtc-registry` contract to update signer information when keys are rotated.

concepts/sbtc/clarity-contracts/sbtc-deposit.md

@@ -0,0 +1,121 @@
+# sBTC Deposit Contract Documentation
+
+This document provides a comprehensive overview of the sBTC Deposit contract implemented in Clarity. The contract manages the process of completing deposits for the sBTC system, including validation and minting of sBTC tokens.
+
+## Table of Contents
+
+1. [Constants](#constants)
+2. [Error Codes](#error-codes)
+3. [Public Functions](#public-functions)
+4. [Private Functions](#private-functions)
+
+## Constants
+
+The contract defines two important constants:
+
+```clarity
+(define-constant txid-length u32)
+(define-constant dust-limit u546)
+```
+
+- `txid-length`: Sets the required length of a transaction ID (txid) to 32 bytes.
+- `dust-limit`: Defines the minimum amount for a deposit, set to 546 satoshis.
+
+## Error Codes
+
+The contract defines several error codes for various scenarios:
+
+```clarity
+(define-constant ERR_TXID_LEN (err u300))
+(define-constant ERR_DEPOSIT_REPLAY (err u301))
+(define-constant ERR_LOWER_THAN_DUST (err u302))
+(define-constant ERR_DEPOSIT (err u303))
+(define-constant ERR_INVALID_CALLER (err u304))
+```
+
+- `ERR_TXID_LEN`: Indicates that the TXID used in the deposit is not the correct length (error code 300).
+- `ERR_DEPOSIT_REPLAY`: Indicates that the deposit has already been completed (error code 301).
+- `ERR_LOWER_THAN_DUST`: Indicates that the deposit amount is lower than the dust limit (error code 302).
+- `ERR_DEPOSIT`: A general error code for deposit-related issues (error code 303).
+- `ERR_INVALID_CALLER`: Indicates that the function caller is not authorized (error code 304).
+
+There's also a special error code prefix for individual deposit errors:
+
+```clarity
+(define-constant ERR_DEPOSIT_INDEX_PREFIX (unwrap-err! ERR_DEPOSIT (err true)))
+```
+
+This is used to generate unique error codes for each deposit in a batch that might fail.
+
+## Public Functions
+
+### complete-deposit-wrapper
+
+This function handles a single deposit request, including validation and minting of sBTC.
+
+```clarity
+(define-public (complete-deposit-wrapper (txid (buff 32)) (vout-index uint) (amount uint) (recipient principal))
+    ;; Function body...
+)
+```
+
+Parameters:
+
+- `txid`: The transaction ID of the deposit (32 bytes).
+- `vout-index`: The index of the transaction output.
+- `amount`: The amount of the deposit.
+- `recipient`: The principal (address) to receive the minted sBTC.
+
+The function performs several checks:
+
+1. Verifies that the caller is the current signer principal.
+2. Checks that the deposit amount is greater than or equal to the dust limit.
+3. Verifies that the txid has the correct length (32 bytes).
+4. Ensures that the deposit has not already been completed (no replay).
+
+If all checks pass, it mints the sBTC to the recipient and calls the `complete-deposit` function in the `.sbtc-registry` contract to update the protocol state.
+
+### complete-deposits-wrapper
+
+This function handles multiple deposit requests in a single transaction (up to 650 deposits).
+
+```clarity
+(define-public (complete-deposits-wrapper (deposits (list 650 {txid: (buff 32), vout-index: uint, amount: uint, recipient: principal})))
+    ;; Function body...
+)
+```
+
+Parameters:
+
+- `deposits`: A list of up to 650 deposit structures, each containing a txid, vout-index, amount, and recipient.
+
+The function first checks that the caller is the current signer principal. Then it uses a fold operation with the `complete-individual-deposits-helper` function to process each deposit in the list.
+
+## Private Functions
+
+### complete-individual-deposits-helper
+
+This private function is used by `complete-deposits-wrapper` to process individual deposits in a batch.
+
+```clarity
+(define-private (complete-individual-deposits-helper (deposit {txid: (buff 32), vout-index: uint, amount: uint, recipient: principal}) (helper-response (response uint uint)))
+    ;; Function body...
+)
+```
+
+It calls `complete-deposit-wrapper` for each deposit and handles any errors that may occur during processing. If an error occurs, it generates a unique error code using the `ERR_DEPOSIT_INDEX_PREFIX`.
+
+## Important Notes
+
+1. Both `complete-deposit-wrapper` and `complete-deposits-wrapper` can only be called by the current bootstrap signer set address. They cannot be called directly by users.
+
+2. The contract interacts with two other contracts:
+
+   - `.sbtc-registry`: To get the current signer data and complete deposits.
+   - `.sbtc-token`: To mint sBTC tokens.
+
+3. The contract includes safeguards against replay attacks and ensures that deposit amounts are above the dust limit.
+
+## Conclusion
+
+This contract provides essential functionality for managing deposits in the sBTC system. It includes robust error checking, supports both single and batch deposits, and interacts with other contracts in the sBTC ecosystem to maintain the protocol's state. The contract's design prioritizes security and efficiency in handling Bitcoin to Stacks bridge operations.

concepts/sbtc/clarity-contracts/sbtc-registry.md

@@ -0,0 +1,20 @@
+# 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.

concepts/sbtc/clarity-contracts/sbtc-token.md

@@ -0,0 +1,19 @@
+# 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).