# sBTC 存款

## 概述

这个 [sBTC 存款合约](https://github.com/stacks-network/sbtc/blob/main/contracts/contracts/sbtc-deposit.clar) (`sbtc-deposit.clar`）管理 sBTC 系统的存款流程。它负责在用户存入比特币时对 sBTC 代币进行验证和铸造，并与 sBTC 注册表合约交互以更新协议状态。

## 常量

* `txid-length`：交易 ID 的必需长度（32 字节）。
* `dust-limit`：有效存款的最低金额（546 聪）。

## 错误常量

* `ERR_TXID_LEN` （u300）：表示所提供的交易 ID 长度不正确。
* `ERR_DEPOSIT_REPLAY` （u301）：表示尝试重放一个已经完成的存款。
* `ERR_LOWER_THAN_DUST` （u302）：表示存款金额低于尘埃限额。
* `ERR_DEPOSIT_INDEX_PREFIX`：用于批量处理中存款相关错误的前缀。
* `ERR_DEPOSIT` （u303）：通用存款错误。
* `ERR_INVALID_CALLER` （u304）：表示调用方没有执行该操作的授权。

***

## 公开函数

### complete-deposit-wrapper

处理单个存款请求。

* 参数：
  * `txid`: `(buff 32)` - 比特币交易 ID
  * `vout-index`: `uint` - 存款交易的输出索引
  * `amount`: `uint` - 要铸造的 sBTC 数量（以聪为单位）
  * `recipient`: `principal` - 接收铸造后 sBTC 的 Stacks 地址
* 返回： `(response bool uint)`

{% stepper %}
{% step %}
**验证与授权**

1. 验证调用方是否为当前签名者主体。
2. 检查存款金额是否高于尘埃限额。
3. 验证交易 ID 长度。
   {% endstep %}

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

4. 确保该存款之前尚未被处理（防止重放）。
   {% endstep %}

{% step %}
**执行**

5. 通过以下方式向接收方铸造 sBTC 代币： `.sbtc-token`的 `protocol-mint`.
6. 通过以下方式更新 sBTC 注册表合约中的存款状态： `.sbtc-registry`的 `complete-deposit`.
   {% endstep %}
   {% endstepper %}

***

### complete-deposits-wrapper

在单笔交易中处理多个存款请求。

* 参数：
  * `deposits`: `（list 650 {txid: (buff 32), vout-index: uint, amount: uint, recipient: principal}）` - 存款数据列表
* 返回： `(response uint uint)`

{% stepper %}
{% step %}
**授权**

1. 验证调用方是否为当前签名者主体。
   {% endstep %}

{% step %}
**批量处理**

2. 遍历存款列表，使用以下方法处理每一项： `complete-individual-deposits-helper` 函数查询比特币区块头哈希。
   {% endstep %}
   {% endstepper %}

***

## 私有函数

### complete-individual-deposits-helper

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

* 参数：
  * `deposit`: `{txid: (buff 32), vout-index: uint, amount: uint, recipient: principal}` - 单笔存款数据
  * `helper-response`: `(response uint uint)` - 用于跟踪已处理存款的累加器
* 返回： `(response uint uint)`

{% stepper %}
{% step %}
**调用存款包装器**

1. 调用 `complete-deposit-wrapper` 来处理单笔存款。
   {% endstep %}

{% step %}
**成功处理**

2. 如果成功，则增加已处理存款计数。
   {% endstep %}

{% step %}
**错误处理**

3. 如果发生错误，则会连同额外的索引信息一起传播（使用 `ERR_DEPOSIT_INDEX_PREFIX` 或相关错误常量）。
   {% endstep %}
   {% endstepper %}

***

## 与其他合约的交互

* `.sbtc-registry`：调用 `get-current-signer-data`, `get-completed-deposit`，以及 `complete-deposit` 来管理存款状态。
* `.sbtc-token`：调用 `protocol-mint` 以创建新的 sBTC 代币。

***

## 安全考虑

1. 访问控制：只有当前签名者主体可以调用存款完成函数。
2. 重放防护：合约会检查此前已处理的存款，以防止重放攻击。
3. 尘埃限额：强制设置最低存款金额，以防止垃圾交易并确保经济可行性。
4. 交易 ID 验证：确保所提供的交易 ID 长度正确。


---

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