Skip to content

Latest commit

 

History

History
115 lines (79 loc) · 4.2 KB

sbtc-withdrawal.md

File metadata and controls

115 lines (79 loc) · 4.2 KB

sBTC Withdrawal Contract Documentation

Overview

The sBTC Withdrawal contract (sbtc-withdrawal.clar) manages the withdrawal process for the sBTC system. It handles the initiation, acceptance, and rejection of withdrawal requests, ensuring proper validation and interaction with other sBTC contracts.

Constants

Error Codes

  • ERR_INVALID_ADDR_VERSION (u500): Invalid address version.
  • ERR_INVALID_ADDR_HASHBYTES (u501): Invalid address hashbytes.
  • ERR_DUST_LIMIT (u502): Withdrawal amount below dust limit.
  • ERR_INVALID_REQUEST (u503): Invalid withdrawal request ID.
  • ERR_INVALID_CALLER (u504): Caller is not the current signer principal.
  • ERR_ALREADY_PROCESSED (u505): Withdrawal request already processed.
  • ERR_FEE_TOO_HIGH (u505): Paid fee higher than requested.
  • ERR_WITHDRAWAL_INDEX_PREFIX: Prefix for withdrawal index errors.
  • ERR_WITHDRAWAL_INDEX (u506): General withdrawal index error.

Other Constants

  • MAX_ADDRESS_VERSION (u6): Maximum value of an address version.
  • MAX_ADDRESS_VERSION_BUFF_20 (u4): Maximum version for 20-byte hashbytes.
  • MAX_ADDRESS_VERSION_BUFF_32 (u6): Maximum version for 32-byte hashbytes.
  • DUST_LIMIT (u546): Minimum amount of sBTC for withdrawal.

Public Functions

initiate-withdrawal-request

Initiates a new withdrawal request.

  • Parameters:
    • amount: uint - Amount of sBTC to withdraw
    • recipient: { version: (buff 1), hashbytes: (buff 32) } - Bitcoin address details
    • max-fee: uint - Maximum fee for the withdrawal
  • Returns: (response uint uint)

accept-withdrawal-request

Accepts a withdrawal request.

  • Parameters:
    • request-id: uint - Withdrawal request ID
    • bitcoin-txid: (buff 32) - Bitcoin transaction ID
    • signer-bitmap: uint - Bitmap of signers
    • output-index: uint - Output index in the Bitcoin transaction
    • fee: uint - Actual fee paid
  • Returns: (response bool uint)

reject-withdrawal-request

Rejects a withdrawal request.

  • Parameters:
    • request-id: uint - Withdrawal request ID
    • signer-bitmap: uint - Bitmap of signers
  • Returns: (response bool uint)

complete-withdrawals

Processes multiple withdrawal requests (accept or reject).

  • Parameters:
    • withdrawals: (list 600 {...}) - List of withdrawal details
  • Returns: (response uint uint)

Read-only Functions

validate-recipient

Validates the recipient's Bitcoin address format.

  • Parameters:
    • recipient: { version: (buff 1), hashbytes: (buff 32) } - Bitcoin address details
  • Returns: (response bool uint)

Private Functions

complete-individual-withdrawal-helper

Helper function to process individual withdrawals in the batch operation.

  • Parameters:
    • withdrawal: {...} - Individual withdrawal details
    • helper-response: (response uint uint) - Accumulator for processing
  • Returns: (response uint uint)

Interactions with Other Contracts

  • .sbtc-token: Calls protocol-lock, protocol-burn-locked, protocol-mint, and protocol-unlock for token operations.
  • .sbtc-registry: Calls create-withdrawal-request, get-withdrawal-request, get-current-signer-data, complete-withdrawal-accept, and complete-withdrawal-reject for managing withdrawal requests and signer data.

Security Considerations

  1. Access Control: Only the current signer principal can accept or reject withdrawal requests.
  2. Dust Limit: Enforces a minimum withdrawal amount to prevent spam and ensure economic viability.
  3. Fee Management: Ensures that the actual fee doesn't exceed the maximum fee set by the user.
  4. Address Validation: Implements thorough validation of Bitcoin address formats.
  5. State Management: Prevents double-processing of withdrawal requests.

Bitcoin Address Types

The contract supports various Bitcoin address types, including:

  • P2PKH (Pay-to-Public-Key-Hash)
  • P2SH (Pay-to-Script-Hash)
  • P2SH-P2WPKH (P2SH nested P2WPKH)
  • P2SH-P2WSH (P2SH nested P2WSH)
  • P2WPKH (Pay-to-Witness-Public-Key-Hash)
  • P2WSH (Pay-to-Witness-Script-Hash)
  • P2TR (Pay-to-Taproot)

Each address type is represented by a specific version byte and hashbytes format in the recipient structure.