🛠️
Stacks Documentation
  • Start Here
  • 🧠Concepts
    • Stacks 101
      • What Is Stacks?
      • Bitcoin Connection
      • Proof of Transfer
      • Stacks Among Other Layers
      • Financial Incentive and Security Budget
    • Network Fundamentals
      • Network Basics
      • Mainnet and Testnets
      • Accounts
      • Authentication
      • Bitcoin Name System
      • SIPs
      • Technical Specifications
    • Block Production
      • Mining
      • Signing
      • Bitcoin Finality
      • Bitcoin Reorgs
      • Stacking
    • Transactions
      • How Transactions Work
      • Post Conditions
    • Clarity
      • Overview
      • Decidability
    • sBTC
      • Core Features
      • sBTC Operations
        • Deposit
        • Withdrawal
        • Deposit vs Withdrawal Times
      • Emily API
      • Peg Wallet UTXO
      • Clarity Contracts
        • sBTC Registry
        • sBTC Token
        • sBTC Deposit
        • sBTC Withdrawal
      • Auxiliary Features
        • Transaction Fee Sponsorship
        • Signer Wallet Rotation
      • Walkthroughs
        • Signer Process Walkthrough
        • sBTC Transaction Walkthrough
      • sBTC FAQ
    • Gaia
      • Configuration
      • Deploy Gaia Hub
      • Amazon EC2
      • Linux
      • Mac OS
  • 🛠️Guides & Tutorials
    • Developer Quickstart
    • Clarity Crash Course
    • Build a Borrowing & Lending Protocol
    • Bitcoin Integration
      • Sending Bitcoin with Leather Wallet
      • Verifying a Bitcoin Transaction
      • Parsing a Bitcoin Transaction
    • Create Tokens
      • Creating a NFT
      • Creating a Fungible Token
    • Build a Frontend
      • Post Conditions with Stacks.js
      • Authentication with Stacks.js
      • Sending Transactions with Stacks.js
    • Testing Smart Contracts
      • Fuzz Testing
    • Run a Node
      • Run a Node with Docker
      • Run a Node with Digital Ocean
      • Run a Node with a Hosted Provider
      • Run a Node with Quicknode
      • Run a Bitcoin Node
      • Run a Pruned Bitcoin Node
    • Run a Miner
      • Miner Prerequisites
      • Miner Costs and Fees
      • Mine Testnet Stacks Tokens
      • Mine Mainnet Stacks Tokens
      • Verify Miner
    • Run a Signer
      • Signer Quickstart
      • How to Read Signer Logs
      • How to Monitor a Signer
      • Best practices for running a Signer
      • OpSec Best Practices
    • sBTC
      • How to Run an sBTC Signer
      • Best practices for running an sBTC Signer
      • How to Use the sBTC Bridge
      • Earn sBTC Rewards
    • Stack STX
      • Solo Stack
      • Operate a Pool
      • Stack with a Pool
      • Increase Stacked Position
      • Stop Stacking
    • Oracles
    • Community Tutorials
  • 📚Reference
    • API
    • Clarity Types
    • Clarity Functions
    • Clarity Keywords
    • Stacks Node Configuration
    • Signer Configuration
    • Stacks Tooling
  • 🏗️Example Contracts
    • Audited Starter Contracts
    • Stacking
    • BNS
    • Multi Send
  • 🧡Press & Top Links
    • 🔶2024
      • 🔸January 2024
      • 🔸February 2024
      • 🔸March 2024
      • 🔸April 2024
      • 🔸May 2024
      • 🔸June 2024
      • 🔸July 2024
      • 🔸August 2024
      • 🔸September 2024
      • 🔸October 2024
      • 🔸November 2024
      • 🔸December 2024
    • 🔶2025
      • 🔸January 2025
      • 🔸February 2025
      • 🔸March 2025
      • 🔸April 2025
      • 🔸May 2025
  • 🧡Bitcoin Theses and Reports
    • 🟠Bitcoin Theses
    • 📙Bitcoin Reports
  • Contribute
Powered by GitBook
On this page
  • Overview
  • Error Constants
  • State Variables
  • Data Maps
  • withdrawal-requests
  • withdrawal-status
  • completed-deposits
  • aggregate-pubkeys
  • multi-sig-address
  • protocol-contracts
  • Read-only Functions
  • get-withdrawal-request
  • get-completed-deposit
  • get-current-signer-data
  • get-current-aggregate-pubkey
  • get-current-signer-principal
  • get-current-signer-set
  • Public Functions
  • create-withdrawal-request
  • complete-withdrawal-accept
  • complete-withdrawal-reject
  • complete-deposit
  • rotate-keys
  • Private Functions
  • increment-last-withdrawal-request-id
  • is-protocol-caller
  • validate-protocol-caller
  • Events
  • Security Considerations

Was this helpful?

  1. Concepts
  2. sBTC
  3. Clarity Contracts

sBTC Registry

PreviousClarity ContractsNextsBTC Token

Last updated 6 months ago

Was this helpful?

Overview

The (sbtc-registry.clar) serves as the central registry for the sBTC system. It manages withdrawal requests, completed deposits, and the current signer set. This contract is crucial for maintaining the state and coordinating operations within the sBTC ecosystem.

Error Constants

  • ERR_UNAUTHORIZED (u400): Indicates unauthorized access.

  • ERR_INVALID_REQUEST_ID (u401): Signifies an invalid withdrawal request ID.

  • ERR_AGG_PUBKEY_REPLAY (u402): Indicates an attempt to replay an aggregate public key.

  • ERR_MULTI_SIG_REPLAY (u403): Signifies an attempt to replay a multi-signature address.

State Variables

  • last-withdrawal-request-id: Tracks the latest withdrawal request ID.

  • current-signature-threshold: Stores the current threshold for required signatures.

  • current-signer-set: Maintains a list of current signer public keys.

  • current-aggregate-pubkey: Holds the current aggregate public key.

  • current-signer-principal: Stores the current signer's principal address.

Data Maps

withdrawal-requests

Stores withdrawal request details indexed by request ID.

  • Fields:

    • amount: Amount of sBTC being withdrawn (in sats)

    • max-fee: Maximum fee for the withdrawal

    • sender: Principal of the sender

    • recipient: BTC recipient address (version and hashbytes)

    • block-height: Burn block height where the request was created

withdrawal-status

Tracks the status of withdrawal requests indexed by request ID.

  • Value: bool (true if accepted, false if rejected, none if pending)

completed-deposits

Records completed deposit transactions to prevent replay attacks.

  • Key: {txid: (buff 32), vout-index: uint}

  • Value: {amount: uint, recipient: principal}

aggregate-pubkeys

Tracks used aggregate public keys to prevent replay attacks.

  • Key: (buff 33) (aggregate public key)

  • Value: bool

multi-sig-address

Tracks used multi-signature addresses to prevent replay attacks.

  • Key: principal (multi-sig address)

  • Value: bool

protocol-contracts

Stores authorized protocol contract addresses.

  • Key: principal (contract address)

  • Value: bool

Read-only Functions

get-withdrawal-request

Retrieves a withdrawal request by its ID.

  • Parameters:

    • id: uint

  • Returns: (optional {amount: uint, max-fee: uint, sender: principal, recipient: {version: (buff 1), hashbytes: (buff 32)}, block-height: uint, status: (optional bool)})

get-completed-deposit

Fetches a completed deposit by transaction ID and output index.

  • Parameters:

    • txid: (buff 32)

    • vout-index: uint

  • Returns: (optional {amount: uint, recipient: principal})

get-current-signer-data

Returns current signer set information.

  • Returns: {current-signer-set: (list 128 (buff 33)), current-aggregate-pubkey: (buff 33), current-signer-principal: principal, current-signature-threshold: uint}

get-current-aggregate-pubkey

Returns the current aggregate public key.

  • Returns: (buff 33)

get-current-signer-principal

Returns the current signer's principal.

  • Returns: principal

get-current-signer-set

Returns the current set of signer public keys.

  • Returns: (list 128 (buff 33))

Public Functions

create-withdrawal-request

Creates a new withdrawal request. Only callable by protocol contracts.

  • Parameters:

    • amount: uint

    • max-fee: uint

    • sender: principal

    • recipient: {version: (buff 1), hashbytes: (buff 32)}

    • height: uint

  • Returns: (response uint uint)

complete-withdrawal-accept

Marks a withdrawal request as accepted.

  • Parameters:

    • request-id: uint

    • bitcoin-txid: (buff 32)

    • output-index: uint

    • signer-bitmap: uint

    • fee: uint

  • Returns: (response bool uint)

complete-withdrawal-reject

Marks a withdrawal request as rejected.

  • Parameters:

    • request-id: uint

    • signer-bitmap: uint

  • Returns: (response bool uint)

complete-deposit

Records a completed deposit transaction.

  • Parameters:

    • txid: (buff 32)

    • vout-index: uint

    • amount: uint

    • recipient: principal

  • Returns: (response bool uint)

rotate-keys

Updates the signer set, multi-sig principal, and aggregate public key.

  • Parameters:

    • new-keys: (list 128 (buff 33))

    • new-address: principal

    • new-aggregate-pubkey: (buff 33)

    • new-signature-threshold: uint

  • Returns: (response (buff 33) uint)

Private Functions

increment-last-withdrawal-request-id

Increments and returns the next withdrawal request ID.

  • Returns: uint

is-protocol-caller

Checks if the caller is an authorized protocol contract.

  • Returns: (response bool uint)

validate-protocol-caller

Validates if a given principal is an authorized protocol contract.

  • Parameters:

    • caller: principal

  • Returns: (response bool uint)

Events

The contract emits events (via print) for important actions:

  • Withdrawal request creation: "withdrawal-create"

  • Withdrawal acceptance: "withdrawal-accept"

  • Withdrawal rejection: "withdrawal-reject"

  • Deposit completion: "completed-deposit"

Security Considerations

  1. Access Control: Only authorized protocol contracts can call certain functions.

  2. Replay Prevention: The contract prevents replay attacks on deposits, aggregate public keys, and multi-signature addresses.

  3. State Management: The contract carefully manages the state of withdrawals and the current signer set.

🧠
sBTC Registry contract