> For the complete documentation index, see [llms.txt](https://steakhouse.financial/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://steakhouse.financial/docs/products/zh/infrastructure/box-vaults/box-vaults-technical.md).

# 技术参考

这是 Box 的智能合约技术参考文档。Box 是由 Steakhouse Financial 构建的 ERC-4626 子金库。本文档说明了合约的角色与权限（Owner、Curator、Guardian、Allocator、Feeder）、时间锁治理、配置与兑换安全控制、生命周期状态，以及面向 Aave v3 和 Morpho Blue 的资金模块集成。

## Box 的作用

* 持有单一基础资产（例如 USDC），并发行 ERC-4626 份额。
* 在基础资产与白名单 ERC-20 代币之间进行配置。
* 通过白名单资金模块进行借贷。
* 使用代币预言机和资金模块 NAV 跟踪净资产价值（NAV）。

## 架构

{% @mermaid/diagram content="flowchart LR
VaultV2\[Morpho Vault V2] --> Adapter\[BoxAdapter / BoxAdapterCached]
Adapter --> Box\[Box Vault]
Box --> Swapper\[Swapper Integrations]
Box --> Tokens\[Whitelisted Tokens]
Box --> Funding\[Funding Modules]
Funding --> Aave\[FundingAave]
Funding --> Morpho\[FundingMorpho]" %}

Adapters 是 Box 预期的 feeder。Box 份额由 adapters 持有，并通过以下方式回传给 Vault V2 `previewRedeem` （缓存于 `BoxAdapterCached`).

## 角色与权限

**Owner**

* 设置 curator。
* 转移所有权。
* 设置 `skimRecipient`.

**Curator**

* 管理 allocators 和资金模块。
* 添加/移除白名单代币和预言机。
* 配置滑点限制。
* 提交带时间锁的变更。
* 可以发起关闭。

**Guardian**

* 否决带时间锁的操作（`revoke`).
* 触发关闭。
* 在 winddown 之前可以从关闭状态恢复。
* 仅可在最终 winddown 中更新预言机。
* 通常由代表 Vault V2 份额持有者的 Aragon DAO 控制。

**Allocator**

* 执行交换（`allocate`, `deallocate`, `reallocate`).
* 通过资金模块质押抵押品、借款和还款。
* 可以使用 `flash` 来执行原子化多步骤操作。

**Feeder**

* 唯一被允许存入/铸造份额的角色。
* 在实践中，adapters 充当 feeders。

## 时间锁治理

关键功能需要时间锁延迟，并且在执行前必须通过 `submit()` 排队。治理的设计是刻意让 Vault V2 份额持有者能够通过由 Aragon DAO 控制的 guardian 介入，从而在需要时否决已排队的操作或触发关闭。

典型的带时间锁操作包括：

* 添加/移除 feeders
* 设置 `maxSlippage`
* 添加代币、预言机、资金模块或设施
* 设置 guardian

时间锁延迟默认值为 `0`；部署时应初始化为非零延迟，以防止立即执行。

## 配置与兑换安全

Box 强制实施 **两层滑点控制**:

1. **单次兑换滑点检查** 基于预言机价格，每次兑换都必须满足 `received ≥ expected * (1 - maxSlippage)`.
2. **周期滑点预算** 已实现滑点会相对于 NAV 在以下周期内进行跟踪 `slippageEpochDuration`。如果累计滑点超过 `maxSlippage`，则在该周期重置之前会阻止进一步兑换。

在 **winddown**期间，按周期的限制会被忽略，而单次兑换容差会线性提升至 1%。

{% @mermaid/diagram content="flowchart LR
Allocator\[Allocator] -->|Allocate| Box\[Box Vault]
Box -->|Oracle price| Oracle\[Token Oracle]
Box -->|Execute swap| Swapper\[Swapper]
Swapper -->|Tokens back| Box
Box -->|Emit event| Allocator
" %}

## 生命周期状态

{% @mermaid/diagram content="stateDiagram-v2
\[*] --> Normal
Normal --> Shutdown: guardian/curator triggers
Shutdown --> Normal: guardian recovers (before warmup)
Shutdown --> Winddown: shutdownWarmup elapsed
Winddown --> \[*]" %}

## 资金模块

Box 通过 `IFunding` 模块集成借贷协议。每个模块都由 Box 拥有，并支持：

* 设施（协议特定配置）
* 白名单抵押代币
* 白名单债务代币

Box 只会添加 **空的** 资金模块（无设施、无代币、无债务）。

### FundingAave（Aave v3）

* `facilityData` 必须为空（`""`).
* 使用 Aave Pool 和可选的 `eMode`.
* `质押` 提供抵押品并启用抵押品使用。
* `borrow` 将债务代币返还给 Box。
* NAV 为 `抵押品价值 - 债务价值`，最低为 0。

### FundingMorpho（Morpho Blue）

* `facilityData` 编码 Morpho 市场参数。
* 每个模块支持多个设施。
* 通过 `lltvCap` 对每个市场的 LLTV 强制执行 LTV 上限。
* `质押` / `borrow` 按设施进行验证。
* 按设施计算 NAV 并汇总，最低为 0。

## 闪电操作

Allocator（或在 winddown 期间的任何人）可以调用 `flash()` 为复杂序列临时获取流动性。flash 期间会缓存 NAV 以防止操纵，并且 flash 代币必须在同一笔交易中归还。

## 审计与源码

* ChainSecurity 审计（2025 年 12 月）： [2025-12-16-chainsecurity.pdf](https://github.com/Steakhouse-Financial/box/blob/52ab8b9f20184c5882448df7be31701df1cf6f39/audits/2025-12-16-chainsecurity.pdf)
* Cantina 审计（2026 年 1 月）： [2026-01-06-cantina.pdf](https://github.com/Steakhouse-Financial/box/blob/52ab8b9f20184c5882448df7be31701df1cf6f39/audits/2026-01-06-cantina.pdf)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://steakhouse.financial/docs/products/zh/infrastructure/box-vaults/box-vaults-technical.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.