# sBTC 注册表

## 概述

该 [sBTC 注册合约](https://github.com/stacks-network/sbtc/blob/main/contracts/contracts/sbtc-registry.clar) (`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"

{% hint style="info" %}
上述操作会通过合约中的 `print` 语句发出事件。
{% endhint %}

## 安全考虑

{% stepper %}
{% step %}
**访问控制**

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

{% step %}
**重放防护**

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

{% step %}
**状态管理**

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stacks.co/learn/zh/sbtc/clarity-contracts/sbtc-registry.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.