# sBTC 提现

## 概述

这个 [sBTC 提现合约](https://github.com/stacks-network/sbtc/blob/main/contracts/contracts/sbtc-withdrawal.clar) (`sbtc-withdrawal.clar`）负责管理 sBTC 系统的提现流程。它处理提现请求的发起、接受和拒绝，确保与其他 sBTC 合约进行正确的验证和交互。

## 常量

### 错误代码

* `ERR_INVALID_ADDR_VERSION` （u500）：无效的地址版本。
* `ERR_INVALID_ADDR_HASHBYTES` （u501）：无效的地址 hashbytes。
* `ERR_DUST_LIMIT` （u502）：提现金额低于尘埃限额。
* `ERR_INVALID_REQUEST` （u503）：无效的提现请求 ID。
* `ERR_INVALID_CALLER` （u504）：调用者不是当前签名者主体。
* `ERR_ALREADY_PROCESSED` （u505）：提现请求已处理。
* `ERR_FEE_TOO_HIGH` （u505）：支付的费用高于请求金额。
* `ERR_WITHDRAWAL_INDEX_PREFIX`：提现索引错误的前缀。
* `ERR_WITHDRAWAL_INDEX` （u506）：通用提现索引错误。

### 其他常量

* `MAX_ADDRESS_VERSION` （u6）：地址版本的最大值。
* `MAX_ADDRESS_VERSION_BUFF_20` （u4）：20 字节 hashbytes 的最大版本。
* `MAX_ADDRESS_VERSION_BUFF_32` （u6）：32 字节 hashbytes 的最大版本。
* `DUST_LIMIT` （u546）：提现所需的最小 sBTC 金额。

## 公开函数

### initiate-withdrawal-request

发起新的提现请求。

* 参数：
  * `amount`: `uint` - 要提现的 sBTC 数量
  * `recipient`: `{ version: (buff 1), hashbytes: (buff 32) }` - 比特币地址详情
  * `max-fee`: `uint` - 该提现的最高费用
* 返回： `(response uint uint)`

### accept-withdrawal-request

接受一个提现请求。

* 参数：
  * `request-id`: `uint` - 提现请求 ID
  * `bitcoin-txid`: `(buff 32)` - 比特币交易 ID
  * `signer-bitmap`: `uint` - 签名者位图
  * `output-index`: `uint` - 比特币交易中的输出索引
  * `fee`: `uint` - 实际支付的费用
* 返回： `(response bool uint)`

### reject-withdrawal-request

拒绝一个提现请求。

* 参数：
  * `request-id`: `uint` - 提现请求 ID
  * `signer-bitmap`: `uint` - 签名者位图
* 返回： `(response bool uint)`

### complete-withdrawals

处理多个提现请求（接受或拒绝）。

* 参数：
  * `withdrawals`: `（list 600 {...}）` - 提现详情列表
* 返回： `(response uint uint)`

## 只读函数

### validate-recipient

验证收款人的比特币地址格式。

* 参数：
  * `recipient`: `{ version: (buff 1), hashbytes: (buff 32) }` - 比特币地址详情
* 返回： `(response bool uint)`

## 私有函数

### complete-individual-withdrawal-helper

用于在批量操作中处理单个提现的辅助函数。

* 参数：
  * `withdrawal`: `{...}` - 单个提现详情
  * `helper-response`: `(response uint uint)` - 用于处理的累加器
* 返回： `(response uint uint)`

## 与其他合约的交互

* `.sbtc-token`：调用 `protocol-lock`, `protocol-burn-locked`, `protocol-mint`，以及 `protocol-unlock` 用于代币操作。
* `.sbtc-registry`：调用 `create-withdrawal-request`, `get-withdrawal-request`, `get-current-signer-data`, `complete-withdrawal-accept`，以及 `complete-withdrawal-reject` 用于管理提现请求和签名者数据。

## 安全考虑

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

只有当前签名者主体可以接受或拒绝提现请求。
{% endstep %}

{% step %}
**尘埃限额**

强制执行最低提现金额，以防止垃圾请求并确保经济可行性。
{% endstep %}

{% step %}
**费用管理**

确保实际费用不超过用户设置的最高费用。
{% endstep %}

{% step %}
**地址验证**

对比特币地址格式进行全面验证。
{% endstep %}

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

防止重复处理提现请求。
{% endstep %}
{% endstepper %}

## 比特币地址类型

该合约支持多种比特币地址类型，包括：

* P2PKH（Pay-to-Public-Key-Hash）
* P2SH（Pay-to-Script-Hash）
* P2SH-P2WPKH（P2SH 嵌套 P2WPKH）
* P2SH-P2WSH（P2SH 嵌套 P2WSH）
* P2WPKH（Pay-to-Witness-Public-Key-Hash）
* P2WSH（Pay-to-Witness-Script-Hash）
* P2TR（Pay-to-Taproot）

每种地址类型在收款人结构中都由特定的版本字节和 hashbytes 格式表示。


---

# 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-withdrawal.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.