sBTC 注册表

概述

该 sBTC 注册合约 (sbtc-registry.clar）充当 sBTC 系统的中央注册表。它管理提款请求、已完成的存款以及当前签名者集合。此合约对于维护状态并协调 sBTC 生态系统内的操作至关重要。

错误常量

• ERR_UNAUTHORIZED （u400）：表示未授权访问。
• ERR_INVALID_REQUEST_ID （u401）：表示无效的提款请求 ID。
• ERR_AGG_PUBKEY_REPLAY （u402）：表示尝试重放聚合公钥。
• ERR_MULTI_SIG_REPLAY （u403）：表示尝试重放多重签名地址。

状态变量

• last-withdrawal-request-id：跟踪最新的提款请求 ID。
• current-signature-threshold：存储当前所需签名阈值。
• current-signer-set：维护当前签名者公钥列表。
• current-aggregate-pubkey：保存当前聚合公钥。
• current-signer-principal：存储当前签名者的主体地址。

数据映射

withdrawal-requests

存储按请求 ID 索引的提款请求详情。

• 字段：

  • amount：正在提款的 sBTC 数量（以 sats 计）
  • max-fee：提款的最高费用
  • sender：发送方的主体地址
  • recipient：BTC 收款地址（版本和哈希字节）
  • block-height：创建该请求时的燃烧区块高度

withdrawal-status

跟踪按请求 ID 索引的提款请求状态。

• 值： bool （true 表示已接受，false 表示已拒绝，none 表示待处理）

completed-deposits

记录已完成的存款交易，以防止重放攻击。

• 键： {txid: (buff 32), vout-index: uint}
• 值： {amount: uint, recipient: principal}

aggregate-pubkeys

跟踪已使用的聚合公钥，以防止重放攻击。

• 键： (buff 33) （聚合公钥）
• 值： bool

multi-sig-address

跟踪已使用的多重签名地址，以防止重放攻击。

• 键： principal （多重签名地址）
• 值： bool

protocol-contracts

存储已授权的协议合约地址。

• 键： principal （合约地址）
• 值： bool

只读函数

get-withdrawal-request

按 ID 获取提款请求。

• 参数：

  • id: uint
• 返回： （optional {amount: uint, max-fee: uint, sender: principal, recipient: {version: (buff 1), hashbytes: (buff 32)}, block-height: uint, status: (optional bool)}）

get-completed-deposit

通过交易 ID 和输出索引获取已完成的存款。

• 参数：

  • txid: (buff 32)
  • vout-index: uint
• 返回： （optional {amount: uint, recipient: principal}）

get-current-signer-data

返回当前签名者集合信息。

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

get-current-aggregate-pubkey

返回当前聚合公钥。

• 返回： (buff 33)

get-current-signer-principal

返回当前签名者的主体地址。

• 返回： principal

get-current-signer-set

返回当前签名者公钥集合。

• 返回： (list 128 (buff 33))

公共函数

create-withdrawal-request

创建一个新的提款请求。仅协议合约可调用。

• 参数：

  • amount: uint
  • max-fee: uint
  • sender: principal
  • recipient: {version: (buff 1), hashbytes: (buff 32)}
  • height: uint
• 返回： (response uint uint)

complete-withdrawal-accept

将某个提款请求标记为已接受。

• 参数：

  • request-id: uint
  • bitcoin-txid: (buff 32)
  • output-index: uint
  • signer-bitmap: uint
  • fee: uint
• 返回： (response bool uint)

complete-withdrawal-reject

将某个提款请求标记为已拒绝。

• 参数：

  • request-id: uint
  • signer-bitmap: uint
• 返回： (response bool uint)

complete-deposit

记录一笔已完成的存款交易。

• 参数：

  • txid: (buff 32)
  • vout-index: uint
  • amount: uint
  • recipient: principal
• 返回： (response bool uint)

rotate-keys

更新签名者集合、多重签名主体地址和聚合公钥。

• 参数：

  • new-keys: (list 128 (buff 33))
  • new-address: principal
  • new-aggregate-pubkey: (buff 33)
  • new-signature-threshold: uint
• 返回： (response (buff 33) uint)

私有函数

increment-last-withdrawal-request-id

递增并返回下一个提款请求 ID。

• 返回： uint

is-protocol-caller

检查调用者是否为已授权的协议合约。

• 返回： (response bool uint)

validate-protocol-caller

验证给定主体是否为已授权的协议合约。

• 参数：

  • caller: principal
• 返回： (response bool uint)

事件

该合约会通过（ print）为重要操作发出事件：

• 提款请求创建："withdrawal-create"
• 提款接受："withdrawal-accept"
• 提款拒绝："withdrawal-reject"
• 存款完成："completed-deposit"

上述操作会通过合约中的 print 语句发出事件。

安全考虑

1

访问控制

只有已授权的协议合约才能调用某些函数。

2

重放防护

该合约可防止针对存款、聚合公钥和多重签名地址的重放攻击。

3

状态管理

该合约会谨慎管理提款状态和当前签名者集合。