> 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/smart-contracts.md).

# 智能合约

网络、合约地址、公开函数、事件和账户状态

Hann Finance 合约覆盖 USDHN 借款、借贷市场、质押和兑换。集成时使用对应网络和抵押品的地址及 ABI。

## 网络与地址

| 网络         | Chain ID |
| ---------- | -------- |
| Kaia 主网    | `8217`   |
| Kairos 测试网 | `1001`   |

### Kaia 主网

Hann Finance 合约尚未部署至 chain ID `8217` 的 Kaia 主网。

### Kairos 测试网地址

网络：**Kairos**，chain ID `1001`。

| 合约                 | 地址 | 浏览器链接 |
| ------------------ | -- | ----- |
| USDHN 代币           | —  | —     |
| CollateralRegistry | —  | —     |
| HNKAIA 代币与资产篮子     | —  | —     |
| Lending Pool       | —  | —     |
| KAIA Gateway       | —  | —     |
| bKAIA 金库           | —  | —     |
| bKAIA 代币           | —  | —     |
| StableSwap Router  | —  | —     |
| USDHN–USDT 池       | —  | —     |

`—` 表示尚未填写。每个地址应同时记录对应 Kairos 合约浏览器链接。

使用浏览器已验证合约条目的 ABI。代理使用代理地址和实现 ABI。借贷储备数据提供底层资产、aToken 和债务代币地址，用于供应、提取、借款和还款。

## CDP 核心

每个分支有自己的 BorrowerOperations、TroveManager、TroveNFT、池子和价格源。通过 CollateralRegistry 的代币及 TroveManager 引用选择 KAIA、HNKAIA 或 earnUSDT 分支。

| 合约                             | 公开接口与状态                                                                                                                                                 |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| USDHN 代币                       | 余额、额度、转账和 permit：`balanceOf`、`allowance`、`approve`、`transfer`、`permit`                                                                                  |
| CollateralRegistry             | `collateralConfig`、`getToken`、`getTroveManager`、`isCollateralActive`、赎回费 getter、`redeemCollateral`                                                      |
| BorrowerOperations             | `openTrove`、`openTroveAndJoinInterestBatchManager`、`addColl`、`withdrawColl`、`withdrawUSDHN`、`repayUSDHN`、`adjustTrove`、`adjustZombieTrove`、`closeTrove` |
| TroveManager                   | `getLatestTroveData`、`getTroveStatus`、`getCurrentICR`、`getLatestBatchData`、`batchLiquidateTroves`、`urgentRedemption`                                    |
| TroveNFT                       | ERC-721 `ownerOf`、所有权转移及 `Transfer` 事件                                                                                                                  |
| SortedTroves                   | 利率排序与插入提示                                                                                                                                               |
| AddressesRegistry              | 分支合约引用和配置参数                                                                                                                                             |
| PriceFeed                      | 获取价格、最后有效价格和预言机状态                                                                                                                                       |
| ActivePool / DefaultPool       | 活跃抵押品及债务、再分配抵押品及债务                                                                                                                                      |
| CollSurplusPool / GasPool      | 可领取剩余抵押品与清算 Gas 补偿                                                                                                                                      |
| HintHelpers / MultiTroveGetter | 费用和插入提示计算、批量仓位读取                                                                                                                                        |
| RedemptionHelper               | `simulateRedemption`、`truncateRedemption`、带各分支最低输出的赎回                                                                                                   |

### 借款、利率与赎回参数

`BorrowerOperations.openTrove` 接受所有人、所有人索引、抵押数量、申请 USDHN、上下插入提示、年利率、最高一次性费用、add manager、remove manager 和 receiver。`openTroveAndJoinInterestBatchManager` 的参数结构用 batch manager 代替个体利率。

利率控制使用 `adjustTroveInterestRate`、`setInterestIndividualDelegate`、`setInterestBatchManager`、`removeFromBatch`、`switchBatchManager`。`addManagerOf` 和 `removeManagerReceiverOf` 返回委托操作及收款设置。从分支 BorrowerOperations 读取 `MCR`、`CCR`、`SCR`、`BCR`。

普通跨分支赎回入口是 `CollateralRegistry.redeemCollateral(usdhnAmount, maxIterationsPerCollateral, maxFeePercentage)`。Registry 选择启用且可赎回的分支，销毁实际处理量。迭代上限 `0` 表示不限遍历，应用使用该值；限定遍历可能只赎回部分。TroveManager 的五参数 `redeemCollateral` 由 registry 调用，关闭后赎回使用 `urgentRedemption`。

`RedemptionHelper.redeemCollateral(usdhnAmount, maxIterationsPerCollateral, maxFeePercentage, minCollRedeemed)` 增加每分支最低抵押输出。Helper 通过 `transferFrom` 转入 USDHN，调用者须授予额度。最低输出数组按 helper 分支顺序排列，未满足则回滚，剩余 USDHN 退回。`simulateRedemption` 和 `truncateRedemption` 读取价格时可能更新缓存，属于 non-view 函数，使用 RPC 模拟获取预览。

### Trove 状态与最新债务

| 值   | 状态                    | 含义                   |
| --- | --------------------- | -------------------- |
| `0` | `nonExistent`         | 该 ID 没有仓位            |
| `1` | `active`              | 开放并参与普通操作            |
| `2` | `closedByOwner`       | 所有人关闭                |
| `3` | `closedByLiquidation` | 清算关闭                 |
| `4` | `zombie`              | 仍开放，但移出普通排序；使用专用调整路径 |

`getLatestTroveData` 返回 `entireDebt`、`entireColl`、再分配收益、累计利息、已记录债务、年利率、加权债务、累计管理费和最后调息时间。当前健康计算使用 `entireDebt`、`entireColl`。

索引 `TroveUpdated`、`TroveOperation`、`BatchedTroveUpdated`、`BatchUpdated`、`Liquidation`、`Redemption`、`RedemptionFeePaidToTrove`，结合分支 NFT 的 `Transfer` 维护所有权及历史。

## Earn：稳定池

各分支 StabilityPool 接受 USDHN 存款，分配清算抵押品和 USDHN 收益。

| 操作       | 函数                                                                                |
| -------- | --------------------------------------------------------------------------------- |
| 存入       | `provideToSP(uint256 amount, bool doClaim)`                                       |
| 提取       | `withdrawFromSP(uint256 amount, bool doClaim)`                                    |
| 领取累计抵押品  | `claimAllCollGains()`                                                             |
| 读取剩余存款   | `getCompoundedUSDHNDeposit(address depositor)`                                    |
| 读取抵押品与收益 | `getDepositorCollGain`、`getDepositorYieldGain`、`getDepositorYieldGainWithPending` |
| 读取池记账    | `getTotalUSDHNDeposits`、`P`、`currentScale`、`scaleToS`、`scaleToB`                  |

`deposits()` 是存储的初始值，当前存款 getter 计入清算损失。`DepositUpdated` 记录新存款和累积器快照；`DepositOperation` 记录操作、损失、金额变化、收益与抵押品。`P_Updated`、`S_Updated`、`B_Updated`、`ScaleUpdated` 记录累积器变化。`offset`、`triggerUSDHNRewards` 由协议控制调用。

## 借贷

Lending Pool 管理储备、抵押设置和账户债务。储备配置提供底层资产、aToken 及浮动债务代币地址。

| 操作       | Pool 函数                                                                                                              |
| -------- | -------------------------------------------------------------------------------------------------------------------- |
| 供应       | `supply(address asset, uint256 amount, address onBehalfOf, uint16 referralCode)`                                     |
| 提取       | `withdraw(address asset, uint256 amount, address to)`                                                                |
| 借款       | `borrow(address asset, uint256 amount, uint256 interestRateMode, uint16 referralCode, address onBehalfOf)`           |
| 还款       | `repay(address asset, uint256 amount, uint256 interestRateMode, address onBehalfOf)`                                 |
| 抵押开关     | `setUserUseReserveAsCollateral(address asset, bool useAsCollateral)`                                                 |
| 选择 eMode | `setUserEMode(uint8 categoryId)`                                                                                     |
| 账户与储备读取  | `getUserAccountData`、`getUserConfiguration`、`getReserveData`、`getConfiguration`、`getReservesList`                    |
| 清算       | `liquidationCall(address collateralAsset, address debtAsset, address user, uint256 debtToCover, bool receiveAToken)` |

应用借款和还款使用浮动模式 `2`。原生 KAIA 操作使用 `WKaiaGateway.depositKAIA`、`withdrawKAIA`、`borrowKAIA`、`repayKAIA`。原生提取使用 aWKAIA 额度；原生借款使用对 gateway 的浮动债务委托。

索引 `Supply`、`Withdraw`、`Borrow`、`Repay`、`LiquidationCall`、`ReserveDataUpdated`、`ReserveUsedAsCollateralEnabled`、`ReserveUsedAsCollateralDisabled`、`UserEModeSet`。`PoolConfigurator` 和 `ACLManager` 提供管理员控制的储备及角色设置。

## 质押代币与金库入口

存款、提取、领取和读取使用 **bKAIA 金库地址**与公开 ABI。

| bKAIA 操作 | 入口                                                                          |
| -------- | --------------------------------------------------------------------------- |
| 存原生 KAIA | Payable `deposit(address receiver, uint256 minShares)`                      |
| 预览份额和资产  | `previewDeposit`、`convertToShares`、`convertToAssets`                        |
| 申请提取     | `requestUnstakeByShares(uint256 shares)` 或 `requestUnstake(uint256 assets)` |
| 领取票据     | `claim(uint256 ticketId)`、`claimMany(uint256[] ticketIds)`                  |
| 处理取消申请   | `settleCanceled(uint256 ticketId)`                                          |
| 读取票据     | `requests(uint256 ticketId)` 及金库 view helper                                |

`claimMany` 返回 `processed`、`totalPaid`、`totalFee`。`Requested`、`RequestedBatch`、`TicketStatusUpdated`、`ClaimPayout`、`ClaimManySummary`、`ClaimRetryQueued` 说明进度和支付。一批成功后仍可能有票据待处理。

HNKAIA 提供 `supportedAssets`、`assets`、`previewDeposit`、`deposit`、`previewRedeemProRata`、`redeemProRata` 和各资产赎回读取。份额与底层资产各有单位，使用所选资产精度及匹配预览。

## StableSwap 与 Zapper

USDHN–USDT 池持有储备，记录 LP 份额、兑换费用和放大系数。读取 `getReserves`、`getDy`、`getDx`、`quoteAddLiquidity`、`quoteRemoveLiquidity`、`getVirtualPrice`。`Swap`、`Mint`、`Burn` 记录交易与流动性变化。

Router 提供 `getAmountsOut`、`getAmountsIn`、`swapExactTokensForTokens`、`swapTokensForExactTokens`、`addLiquidity`、`removeLiquidity` 及 permit 变体。精确输入设最低输出，精确输出设最高输入。参数含路径、收款人和期限。StableSwap Lens 提供详细报价；RewardStaker 记录 LP 质押余额和待领收益。

分支 Zapper 封装资产并执行 Trove。杠杆 Zapper 提供 `openLeveragedTrove`、`leverUpTrove`、`leverDownTrove`、`closeTroveByCollateral`。前三者执行 `maxDebt`；关闭结构含 `troveId` 和 `profitReceiver`，没有用户最低输出字段。FlashSwapper 回调只接受配置池和当前操作，结算闪电兑换并返还剩余量。

钱包调用、授权和索引见[集成指南](/zh/developers/integrator-kit.md)。合约与资产流见[技术概览](/zh/developers/technical-overview.md)。


---

# 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/smart-contracts.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.