> For the complete documentation index, see [llms.txt](https://docs.hann.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hann.finance/zh/developers/trove-manager.md).

# Trove 生命周期

TroveManager 记账、仓位状态、分支限制、读取方法和集成事件

各抵押分支的 **TroveManager** 保存仓位记账并处理清算和赎回。用户开立、调整和关闭通过 **BorrowerOperations** 进入。应用 Zapper 在调用前完成抵押品转换和钱包流程。

## 合约职责

| 合约                   | 职责                               |
| -------------------- | -------------------------------- |
| `BorrowerOperations` | 开仓、抵押品／债务调整、利率管理、全额还款关闭、剩余抵押品领取。 |
| `TroveManager`       | 仓位和批量记账、最新债务／抵押读取、清算、赎回和生命周期更新。  |
| `TroveNFT`           | ERC-721 所有权；开仓铸造，关闭或清算销毁。        |
| `SortedTroves`       | 按年利率维护实时赎回顺序。                    |
| `StabilityPool`      | 抵销清算债务的 USDHN 存款及相应抵押品和收益记账。     |
| `CollateralRegistry` | 分支注册、状态及普通跨分支赎回路由。               |

`onOpenTrove`、`onAdjustTrove` 等借款更新方法仅接受 BorrowerOperations 调用。`batchLiquidateTroves` 公开开放，普通 `redeemCollateral` 接受 CollateralRegistry 调用。

使用[智能合约](/zh/developers/smart-contracts.md)中对应网络和分支的地址与 ABI。Kaia 主网为 `8217`，Kairos 为 `1001`。

## Trove 标识与所有权

BorrowerOperations 内部按以下方式计算开仓 ID：

```solidity
troveId = uint256(keccak256(abi.encode(msg.sender, owner, ownerIndex)));
```

`msg.sender` 是 BorrowerOperations 看到的调用者，例如 Zapper。相同 owner 和索引通过不同入口可得到不同 ID。保存开仓回执和 NFT 铸造事件中的 ID 及分支。

索引 `TroveNFT.Transfer` 跟踪所有权。铸造的发送者为零地址，销毁的接收者为零地址。销毁后 `ownerOf` 将无法返回所有人，因此历史中保留最后所有人。

## 仓位状态

`ITroveManager.Status` 的枚举顺序：

| 值   | 状态                    | 含义                               |
| --- | --------------------- | -------------------------------- |
| `0` | `nonExistent`         | 该 ID 尚未开仓。                       |
| `1` | `active`              | 开放并在排序列表中，操作需通过分支及比率检查。          |
| `2` | `closedByOwner`       | 主动关闭，清空记账字段并销毁 NFT。              |
| `3` | `closedByLiquidation` | 清算关闭，清空记账字段并销毁 NFT。              |
| `4` | `zombie`              | 赎回使债务低于 `MIN_DEBT`，仓位仍开放但移出普通排序。 |

### 状态转移

| 初始状态                | 操作                                                   | 结果                            |
| ------------------- | ---------------------------------------------------- | ----------------------------- |
| `nonExistent`       | `openTrove` 或 `openTroveAndJoinInterestBatchManager` | `active`，铸造 NFT。              |
| `active`            | 赎回使债务低于 `MIN_DEBT`，包括零                               | `zombie`，移出 `SortedTroves`。   |
| `zombie`            | `adjustZombieTrove` 满足债务和比率要求                        | `active`，按排序提示插入。             |
| `zombie`            | `applyPendingDebt` 后债务至少为 `MIN_DEBT`                 | `active`，按排序提示插入。             |
| `active` 或 `zombie` | `closeTrove` 结清当前债务                                  | `closedByOwner`，销毁 NFT。       |
| `active` 或 `zombie` | 当前 `ICR < MCR` 时清算                                   | `closedByLiquidation`，销毁 NFT。 |

`MIN_DEBT` 是借款与赎回记账使用的最低债务，读取所选网络和分支的实际值。

### Zombie 记账

Zombie 保留 NFT、抵押品和剩余债务。将小额仓位移出普通列表可减少重复遍历。新 zombie 仍有债务时，`lastZombieTroveId` 指向它，供下次赎回优先处理；全额赎回、恢复或关闭后清除指针。

普通 `adjustTrove` 要求 active。用 `adjustZombieTrove` 恢复时，检查 `MIN_DEBT`、应用变更并重新插入。更新后债务达到下限时，`applyPendingDebt` 也可恢复。全额赎回的 zombie 可用零 USDHN 还款关闭，取回抵押品和 Gas 押金。

`active` 和 `zombie` 都可检查清算资格，债务为零时无债务可清算。界面需将 zombie 的剩余抵押品继续显示为所有人的资产。

## 分支状态与关闭

TroveManager 通过 `findCollateralByTroveManager` 解析分支，读取 `CollateralRegistry.collateralConfig(index).status`。

| 注册状态         | 新 Trove           | 抵押品／债务调整                |
| ------------ | ----------------- | ----------------------- |
| `Pending`    | 禁止。               | 禁止。                     |
| `Active`     | 通过债务、预言机和比率检查后允许。 | 通过仓位和分支检查后允许。           |
| `Deprecated` | 禁止。               | 请求增债大于减债时禁止；其余仍需通过其他检查。 |

`CollateralStatusForbidsOperation()` 表示注册状态拒绝。关闭另行判断：

* `shutdownTime() == 0`：分支仍未关闭。
* `shutdownTime() > 0`：值为关闭时间戳。
* 关闭后 BorrowerOperations 停止新增借款和普通调整，仍支持全额还款关闭。
* 关闭前，利息从 `lastDebtUpdateTime` 累计至当前；关闭后，早于关闭的更新时间累计至 `shutdownTime`，处于或晚于关闭的更新时间无后续计息区间。
* 普通赎回要求未关闭且 `TCR >= SCR`；`urgentRedemption` 要求已关闭，并传入明确 Trove ID。

关闭前主动平仓须保留 `TCR >= CCR` 且至少另有一个受跟踪 Trove。分支关闭后解除这两项限制。清算仍不能移除最后一个 Trove，`OnlyOneTroveLeft()` 会回滚。

## 当前状态读取

用 `getLatestTroveData(troveId)` 展示当前债务和抵押品，其结果计入待累计和再分配。

| 字段                                     | 内容                                 |
| -------------------------------------- | ---------------------------------- |
| `entireDebt`                           | 已记录债务、累计利息、再分配 USDHN 债务及仓位累计管理费之和。 |
| `entireColl`                           | 已记录抵押品加待分配抵押品。                     |
| `recordedDebt`                         | 已记录或按批量份额归属的债务。                    |
| `accruedInterest`                      | 按关闭规则计算的上次记账以来利息。                  |
| `redistUSDHNDebtGain`、`redistCollGain` | 分支再分配的待计债务与抵押品。                    |
| `annualInterestRate`                   | 仓位利率或当前批量利率。                       |
| `weightedRecordedDebt`                 | 已记录债务乘年利率。                         |
| `accruedBatchManagementFee`            | 仓位分摊的累计批量管理费。                      |
| `lastInterestRateAdjTime`              | 相关仓位或批量的最后调息时间。                    |

批量 Trove 的债务、利息和管理费按 `batchDebtShares / totalDebtShares` 分摊。再分配按 Trove 抵押 stake 计算，两者一起构成完整债务。

| 方法                                                      | 用途                                   |
| ------------------------------------------------------- | ------------------------------------ |
| `Troves(troveId)`                                       | 原始字段：债务、抵押品、stake、状态、时间、利率、管理人和批量份额。 |
| `getTroveStatus(troveId)`                               | 状态枚举。                                |
| `getTroveAnnualInterestRate(troveId)`                   | 有效利率，包含批量利率。                         |
| `getLatestBatchData(batchAddress)`                      | 批量总量、债务份额、累计利息及管理费。                  |
| `getCurrentICR(troveId, price)`                         | 按最新债务／抵押品与给定价格计算 CR。                 |
| `getTroveIdsCount()`、`getTroveFromTroveIdsArray(index)` | 当前受跟踪 ID 数组；关闭时移除对应 ID。              |

`getCurrentICR` 应使用正确分支价格和单位。价格与比率精度为 `1e18`，`1.2e18` 表示 `120%`。协议清算检查使用预言机价格；市场报价可用于独立情景计算。

## 事件与历史

按已部署 TroveManager、BorrowerOperations ABI 和 TroveNFT 事件索引。事件快照记录操作当时记账，后续利息由当前读取补充。

| 事件                         | 保留内容                               |
| -------------------------- | ---------------------------------- |
| `TroveUpdated`             | ID、记录债务／抵押品、stake、利率、再分配快照。        |
| `TroveOperation`           | 操作类型，以及再分配、一次性费用和请求操作各自造成的债务／抵押变化。 |
| `Liquidation`              | 抵销和再分配债务、稳定池及再分配抵押品、补偿、剩余量、执行价格。   |
| `Redemption`               | 请求与实际赎回 USDHN、转出抵押品、费用和价格。         |
| `RedemptionFeePaidToTrove` | 各 Trove 赎回费记账。                     |
| `BatchUpdated`             | 批量操作、总量、利率、管理费、份额、一次性费用变化。         |
| `BatchedTroveUpdated`      | Trove 抵押品、stake、债务份额、管理人及再分配快照。    |
| TroveNFT 的 `Transfer`      | 创建、所有权转移和销毁。                       |

应用事件时保留交易顺序和分支标识。`closedByOwner`、`closedByLiquidation` 为终止状态，NFT 销毁后保留历史。普通及批量路径都需解析；批量债务使用份额记账。

## 交易失败

| 回滚错误                                     | 相关输入或状态                  |
| ---------------------------------------- | ------------------------ |
| `CollateralStatusForbidsOperation()`     | 分支不允许创建或调整此仓位。           |
| `IsShutDown()`                           | 关闭后停止所请求借款操作。            |
| `ICRBelowMCR()` 或 `ICRBelowMCRPlusBCR()` | 调整后的 CR 低于要求。            |
| `TCRBelowCCR()`                          | 操作违反分支总抵押率要求。            |
| `DebtBelowMin()`                         | 调整后债务低于最低值。              |
| `UpfrontFeeTooHigh()`                    | 执行费用超过接受上限。              |
| `NotEnoughUSDHNBalance()`                | 还款调用者 USDHN 不足以销毁。       |
| `OnlyOneTroveLeft()`                     | 按当前关闭规则，操作将移除最后一个 Trove。 |

在操作流程中显示受影响金额、分支限制或仓位状态。Zapper 路由和滑点错误按其交易路径处理。[技术概览](/zh/developers/technical-overview.md)连接各合约，[集成指南](/zh/developers/integrator-kit.md)介绍 API 与钱包流程。


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hann.finance/zh/developers/trove-manager.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.