> 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/technical-overview.md).

# 技术概览

借贷、USDHN、质押和兑换的公开合约、资产记账与钱包交易

Hann Finance 整合借贷市场、抵押借入 USDHN、流动性质押和兑换。各产品有自己的资产余额、债务及所有权合约。集成通过所选链 RPC 读取合约，并从用户钱包提交交易。

## 合约读取与钱包交易

### 读取合约状态

```mermaid
flowchart TB
  INTEGRATION[集成应用] -->|只读调用| RPC[链 RPC]
  RPC --> CONTRACTS[产品公开合约]
```

### 钱包交易

集成准备合约调用，钱包签名并提交。目标按操作为 Lending Pool、CDP Zapper、bKAIA 或 HNKAIA 金库、StableSwap Router。CDP Zapper 协调下方借款和兑换调用。

```mermaid
flowchart TB
  APP[集成应用] -->|请求签名| WALLET[用户钱包]
  WALLET --> ZAP[CDP Zappers]
  ZAP --> BO[BorrowerOperations]
  ZAP --> FLASH[FlashSwapper]
  BO --> TM[TroveManager]
  BO -->|铸造或销毁| USDHN[USDHNToken]
  TM -->|抵销清算债务| SP[StabilityPool]
  FLASH --> POOL[兑换池]
```

只读调用返回余额、仓位、价格和报价。合约执行所有权、转账、债务变化及执行限制检查。模拟按拟定调用评估结果，交易回执和日志记录实际执行。确认后读取最终余额与仓位。

| 产品       | 记账合约                                                 | 用户操作                        |
| -------- | ---------------------------------------------------- | --------------------------- |
| 借贷       | `Pool`、储备 aToken 和债务代币                               | 供应、借款、还款和提取                 |
| USDHN 借款 | 各分支独立的 `BorrowerOperations` 和 `TroveManager`         | 在 Trove 锁定抵押品，铸造 USDHN 债务   |
| Earn     | 各分支 `StabilityPool`                                  | 存入 USDHN，接收利息和清算抵押品         |
| bKAIA 质押 | `LSTVault`、`LSTToken`                                | 存入 KAIA 获得 bKAIA，申请提取并领取票据  |
| HNKAIA   | `HNKAIA`、`HNKAIAAssetVault`                          | 存入支持的质押资产换份额，赎回底层资产         |
| 兑换与 LP   | `StableSwap`、`StableSwapRouter`、LP 代币、`RewardStaker` | 兑换 USDT 与 USDHN，提供流动性并质押 LP |

## USDHN 抵押分支

USDHN 借款有 KAIA、HNKAIA、earnUSDT 分支。KAIA 分支持有 WKAIA，zapper 在供入前封装原生 KAIA。earnUSDT 分支持有封装抵押代币 wEarnUSDT。

各分支包含：

* `BorrowerOperations`：开立、调整、关闭 Trove 和修改利率设置。
* `TroveManager`：计算当前债务与抵押品，处理清算、赎回及状态。
* `TroveNFT` 标识所有人；`SortedTroves` 按利率排序。
* `ActivePool`、`DefaultPool`、`CollSurplusPool`、`GasPool`：持有抵押品，记录活跃债务、再分配、剩余抵押品和 Gas 补偿。
* `StabilityPool`：销毁存入 USDHN 抵销清算债务并接收抵押品。
* `PriceFeed`、`AddressesRegistry`：提供分支价格和合约配置。

共享的 `CollateralRegistry` 向启用且可赎回的分支路由赎回。`HintHelpers` 提供插入提示，`RedemptionHelper` 提供赎回计算。最新债务包含待计利息、再分配和批量管理费。用 `getLatestTroveData()` 读取当前完整仓位。

### 仓位健康

开放且有债务的 CDP 抵押率为抵押品美元价值除以完整 USDHN 债务。合约的抵押品、债务、价格及比率使用 `1e18` 单位：

```
ICR18 = entireColl × price18 / entireDebt
```

分支对单仓位执行 `MCR`，对分支借款及提取执行 `CCR`，关闭使用 `SCR`，批量借款还需额外限制。CDP 清算条件为 `ICR < MCR`。普通赎回先检查记录的小额债务 Trove，再由低利率开始减少债务和抵押品，赎回费留在 Trove。清算通过稳定池抵销债务，剩余部分在分支内再分配。

借贷账户健康因子根据已启用抵押品、适用清算阈值和总债务计算。`Pool.getUserAccountData()` 返回 `1e18` 精度健康因子，低于 `1e18` 时可被借贷清算。CDP 与借贷各自维护债务和清算规则。

## Zapper 与闪电执行

Zapper 接收授权代币或原生 KAIA，执行配置路径并将剩余资产转给接收者。Permit2 入口结合签名和代币对 Permit2 的授权额度；普通额度路径单独提供。

| 合约                                                                    | 操作                             |
| --------------------------------------------------------------------- | ------------------------------ |
| `WKAIAZapper`                                                         | 原生 KAIA 与 WKAIA 抵押操作           |
| `HNKAIAZapper`                                                        | HNKAIA 抵押操作                    |
| `EarnUSDTZapper`                                                      | earnUSDT 封装与封装抵押品操作            |
| `LeverageWKAIAZapper`、`LeverageHNKAIAZapper`、`LeverageEarnUSDTZapper` | 用对应抵押品开立、增加、降低或关闭闪电辅助仓位        |
| `FlashSwapper`                                                        | DEX 闪电兑换回调、StableSwap 执行及交易内结算 |
| `StableSwapZapper`                                                    | 流动性与 LP 质押                     |

闪电执行在回调期间把 Trove 管理交给授权 FlashSwapper，之后恢复。管理状态包含 add manager、remove manager 和 receiver。回调授权、代币校验、闪电费上限和最终债务检查将路径绑定到提交操作。余额快照用于区分路径剩余量和原有余额。

`openLeveragedTrove`、`leverUpTrove`、`leverDownTrove` 接受最大完整债务 `maxDebt`。`closeTroveByCollateral` 卖出抵押品偿清债务并返还剩余稳定代币，参数结构为 `troveId`、`profitReceiver`，没有用户提供的最低输出字段。按各入口实际限制准备交易。

## 质押、兑换与跨链

bKAIA 的存款、提取申请、领取和读取使用 **`LSTVault` 地址**。`requestUnstakeByShares` 按节点接受量生成票据，未处理份额留在钱包。各票据有独立就绪和领取时间。`claimMany` 处理提交票据，可能返回部分结果。`RequestUnstake`、`ClaimPayout`、`TicketStatusUpdated`、`ClaimManySummary` 记录申请、支付、状态和批次总量。

HNKAIA 代表支持的质押代币份额。`redeemProRata` 销毁 HNKAIA，按金库余额比例支付各代币，并按整数单位向下取整。篮子赎回无赎回费，按价存款和单资产赎回暂停时仍可用。`RedeemProRata`、`RedeemProRataAsset` 记录份额及各输出。

StableSwap 提供精确输入／输出报价、流动性报价、期限、最低输出和最高输入。`StableSwapRouter` 验证池子、代币允许名单和收款人。池子记录储备和费用；LP 质押与奖励由 `RewardStaker` 管理。`LiquidityAdded`、`LiquidityRemoved` 记录路由流动性操作；`Stake`、`Unstake`、`Claim` 记录奖励合约操作。

`USDHNToken` 实现 ERC-20 和 permit。`USDHNOFTAdapter` 为 LayerZero 转账锁定、解锁原生代币；`USDHNOFT` 在远端链铸造和销毁。应用 Bridge 通过 Rhino.fi 将支持的 USDT 或 USDC 转为 Kaia USDT。发送链回执确认发送交易，目标交付有自己的交易和状态。

## 读取、模拟、提交与确认

1. 从[智能合约参考](/zh/developers/smart-contracts.md)选择链、地址和 ABI。以链和地址标识各资产、凭证及债务代币。
2. 读取余额、授权、仓位、价格和报价。Trove 用最新完整债务；借贷用账户级抵押品、债务和健康因子。
3. 准备所需代币授权、Permit2 签名、借款委托或管理／操作权限。先完成权限，再执行资产或仓位变化。
4. 按实际发送者、calldata、原生 value、接收者、期限和数量限制模拟。模拟到执行之间的状态变化可能引发回滚。
5. 从钱包提交并保存哈希，在同链检查回执。回滚后保留原操作状态，仍消耗 Gas；此前成功的授权继续有效。
6. 用发出日志合约的地址和 ABI 解码，再读取最终仓位。对质押票据和赎回逐项检查实际处理量。

## 网络与合约地址

Kaia 主网 chain ID 为 `8217`，Kairos 为 `1001`。Hann Finance 主网合约尚未部署。[智能合约](/zh/developers/smart-contracts.md)分别维护主网和测试网地址。按目标网络使用记录地址，并结合产品及合约地址识别代币。

[智能合约参考](/zh/developers/smart-contracts.md)列出公开名称、函数、事件、部署状态和地址。[集成指南](/zh/developers/integrator-kit.md)介绍钱包交易与事件处理。[TroveManager](/zh/developers/trove-manager.md)说明状态变化，[Zapper](/zh/protocol/zapper.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/technical-overview.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.