> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://www.steakhouse.financial/docs/api/mcp` to find what you need.

# 技术参考

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

## Box 的作用

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

## 架构

```mermaid
%%{init: {"theme":"base","themeVariables":{"background":"#fffdf1","primaryColor":"#ece7e1","primaryTextColor":"#1a1e20","primaryBorderColor":"#dedcd2","secondaryColor":"#ece7e1","tertiaryColor":"#fffdf1","lineColor":"#515a5e","textColor":"#1a1e20","mainBkg":"#ece7e1","nodeBorder":"#dedcd2","clusterBkg":"#fffdf1","titleColor":"#1a1e20","edgeLabelBackground":"#fffdf1","arrowheadColor":"#086552","fontFamily":"Söhne, ui-sans-serif, system-ui, sans-serif"}}}%%
flowchart LR
  VaultV2[Morpho Vault V2] --> Adapter[BoxAdapter / BoxAdapterCached]
  Adapter --> Box[Box 金库]
  Box --> Swapper[Swapper 集成]
  Box --> Tokens[白名单代币]
  Box --> Funding[资金模块]
  Funding --> Aave[FundingAave]
  Funding --> Morpho[FundingMorpho]
```

Adapter 是 Box 预期使用的 Feeder。Box 份额由 Adapter 持有，并通过 `previewRedeem` 回传给 Vault V2（缓存于 `BoxAdapterCached`）。

## 角色与权限

**Owner**

* 设置 Curator。
* 转移所有权。
* 设置 `skimRecipient`。

**Curator**

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

**Guardian**

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

**Allocator**

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

**Feeder**

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

## 时间锁治理

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

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

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

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

## 配置与兑换安全

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

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

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

```mermaid
%%{init: {"theme":"base","themeVariables":{"background":"#fffdf1","primaryColor":"#ece7e1","primaryTextColor":"#1a1e20","primaryBorderColor":"#dedcd2","secondaryColor":"#ece7e1","tertiaryColor":"#fffdf1","lineColor":"#515a5e","textColor":"#1a1e20","mainBkg":"#ece7e1","nodeBorder":"#dedcd2","clusterBkg":"#fffdf1","titleColor":"#1a1e20","edgeLabelBackground":"#fffdf1","arrowheadColor":"#086552","fontFamily":"Söhne, ui-sans-serif, system-ui, sans-serif"}}}%%
flowchart LR
  Allocator[Allocator] -->|配置| Box[Box 金库]
  Box -->|预言机价格| Oracle[代币预言机]
  Box -->|执行兑换| Swapper[Swapper]
  Swapper -->|返还代币| Box
  Box -->|发出事件| Allocator

```

## 生命周期状态

```mermaid
%%{init: {"theme":"base","themeVariables":{"background":"#fffdf1","primaryColor":"#ece7e1","primaryTextColor":"#1a1e20","primaryBorderColor":"#dedcd2","secondaryColor":"#ece7e1","tertiaryColor":"#fffdf1","lineColor":"#515a5e","textColor":"#1a1e20","mainBkg":"#ece7e1","nodeBorder":"#dedcd2","clusterBkg":"#fffdf1","titleColor":"#1a1e20","edgeLabelBackground":"#fffdf1","arrowheadColor":"#086552","fontFamily":"Söhne, ui-sans-serif, system-ui, sans-serif"}}}%%
stateDiagram-v2
  state "正常" as Normal
  state "关闭" as Shutdown
  state "收尾" as Winddown
  [*] --> Normal
  Normal --> Shutdown: guardian/curator 触发
  Shutdown --> Normal: guardian 在预热期结束前恢复
  Shutdown --> Winddown: shutdownWarmup 已结束
  Winddown --> [*]
```

## 资金模块

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

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

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

### FundingAave（Aave v3）

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

### FundingMorpho（Morpho Blue）

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

## 闪电操作

Allocator（或在收尾阶段的任何人）可以调用 `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)