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

# 技術概要

レンディング・USDHN・ステーキング・スワップとウォレット・製品APIの構造

Hann Finance は、レンディング市場、担保を使った USDHN の借入、リキッドステーキング、トークンスワップを提供します。各製品は独立したコントラクトで資産と債務を管理します。アプリは API から製品データを取得し、ユーザーのウォレットから選択したコントラクトへトランザクションを送信します。

## 製品とトランザクションの経路

### 製品データの取得

```mermaid
flowchart TB
  APP[Hann Finance アプリ] -->|製品データの取得| API[製品 API]
  INDEX[インデクサーと<br/>スキャナー] --> API
```

### ウォレットのトランザクション

アプリが署名を要求すると、ウォレットは選択した製品の Lending Pool、CDP Zapper、bKAIA・HNKAIA の Vault、または StableSwap Router にトランザクションを送信します。CDP Zapper は、次の経路で借入とスワップの呼び出しを接続します。

```mermaid
flowchart TB
  APP[Hann Finance アプリ] -->|署名を要求| WALLET[ユーザーのウォレット]
  WALLET --> ZAP[CDP Zapper]
  ZAP --> CDP[BorrowerOperations と<br/>TroveManager]
  ZAP --> FLASH[FlashSwapper と<br/>スワッププール]
  CDP --> USDHN[USDHN と<br/>Stability Pool]
```

API は残高、ポジション、見積もり、履歴、トランザクションの進行状況を返します。コントラクトは所有権、資産の移動、債務の変更、実行上限を適用します。トランザクションレシートに実行結果が記録されると、インデクサーがアカウント履歴とポジションを更新します。

| 製品           | 資産・債務を管理するコントラクト                                | ユーザーが得る結果                                    |
| ------------ | ----------------------------------------------- | -------------------------------------------- |
| Lending      | `lending-core.Pool`、市場ごとの aToken と債務トークン        | 資産の供給、市場の流動性からの借入、返済、引き出し                    |
| USDHN 借入     | 担保ブランチごとの `BorrowerOperations` と `TroveManager` | Trove に担保を預け、USDHN 債務を発行                     |
| Earn         | ブランチごとの `StabilityPool`                         | USDHN を預け、USDHN の利回りと清算担保を受領                 |
| bKAIA ステーキング | `bkaia.LSTVault` と `bkaia.LSTToken`             | KAIA の入金で bKAIA シェアを取得し、引き出しを申請して準備済みチケットを受領 |
| HNKAIA       | `core.HNKAIA` と資産別 Vault                        | 対応するステーキング資産で HNKAIA シェアを取得し、原資産へ償還          |
| スワップと LP     | StableSwap プール、Router、LP トークン、`RewardStaker`    | USDT と USDHN の交換、流動性の供給、LP トークンのステーキング       |

## USDHN の担保ブランチ

生成された CDP インターフェースには `WKAIA`、`HNKAIA`、`EARNUSDT` の3つのブランチがあります。アプリでは WKAIA ブランチを KAIA と表示します。このブランチの Zapper はネイティブ KAIA を WKAIA にラップしてから担保として供給します。EARNUSDT ブランチはラップされた earnUSDT を担保として保有します。

各ブランチは次のコントラクトで構成されます。

* `BorrowerOperations` は Trove の開設・調整・終了と金利設定の変更を行います。
* `TroveManager` は現在の担保と債務を計算し、清算、リデンプション、Trove の状態を管理します。
* `TroveNFT` はポジションの所有者を識別し、`SortedTroves` は金利順にポジションを並べます。
* `ActivePool`、`DefaultPool`、`CollSurplusPool`、`GasPool` は担保を保管し、稼働中の債務、再分配、余剰担保、ガス補償を管理します。
* `StabilityPool` は預けられた USDHN をバーンして清算債務を相殺し、担保を受け取ります。
* `PriceFeed` と `AddressesRegistry` はブランチの価格とコントラクト設定を提供します。

共有の `CollateralRegistry` は、有効かつリデンプション可能なブランチへ USDHN のリデンプションを配分します。`HintHelpers` は挿入位置のヒントを、`RedemptionHelper` はリデンプションの計算を提供します。Trove の現在の債務には、未反映の利息、再分配債務、バッチ管理手数料が含まれます。現在値は `getLatestTroveData()` で取得し、記録済み債務だけを全額返済額として扱わないようにします。

### ポジションの担保状態

債務を持つ開設済み CDP ポジションの担保比率は、担保の米ドル価値を USDHN 債務総額で割った値です。コントラクトの担保・債務・価格・計算結果の比率は、すべて `1e18` 単位を使います。

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

ブランチは `MCR`、`CCR`、`SCR` とバッチ関連の制限を適用します。Lending は担保として有効な資産、適用される清算基準、債務総額からアカウントの health factor を計算します。`Pool.getUserAccountData()` は health factor を `1e18` の精度で返します。両製品はそれぞれの清算ルールを持ちます。

## Zapper とフラッシュ実行

Zapper は使用を承認されたトークンやネイティブ KAIA を受け取り、設定された経路を実行し、残った資産を受取人へ返します。Permit2 の関数は、トークンの Permit2 に対する使用承認と署名を使います。通常のトークン使用承認を使う経路は別にあります。

| コントラクト                   | 担当する動作                                             |
| ------------------------ | -------------------------------------------------- |
| `BaseZapper`             | Registry の参照、トークン移動、Permit2 の処理、管理者権限の検査           |
| `GasCompZapper`          | ガス補償を含む Trove 操作と一時停止の制御                           |
| `WKAIAZapper`            | ネイティブ KAIA と WKAIA の担保操作                           |
| `HNKAIAZapper`           | HNKAIA の担保操作                                       |
| `EarnUSDTZapper`         | earnUSDT のラップとラップ済み担保の操作                           |
| `LeveragedGasCompZapper` | フラッシュ流動性を使ったポジションの開設・拡大・縮小・終了                      |
| `FlashSwapper`           | DEX フラッシュスワップのコールバック、StableSwap の実行、同一トランザクション内の決済 |
| `StableSwapZapper`       | 流動性の供給・回収と LP ステーキング                               |

フラッシュ実行では、コールバック中に認可された FlashSwapper へ Trove の管理権限を渡し、実行後に管理状態を復元します。管理状態には担保追加マネージャー、担保引き出しマネージャー、受取人が含まれます。コールバックの呼び出し元、想定トークン、設定されたフラッシュ手数料上限、最終債務を検査して、送信された操作の範囲を守ります。残高のスナップショットで、経路の残余資産と以前から保有していた残高を区別します。

`openLeveragedTrove`、`leverUpTrove`、`leverDownTrove` は、最終債務総額の上限 `maxDebt` を受け取ります。`closeTroveByCollateral` は担保を売却して債務全額を返済し、残ったステーブルトークンを返します。その引数構造体には `troveId` と `profitReceiver` があり、ユーザーが指定する最低受取量のフィールドはありません。各関数が受け取る制限に合わせてトランザクションを構成します。

## ステーキング・スワップ・チェーン間転送

bKAIA の Vault はエントリーモジュールへ呼び出しを転送します。ウォレットは入金、引き出し申請、受領、参照に対応する ABI を使い、**Vault のアドレス**を呼び出します。引き出し申請はチケットを作成します。`claimMany` は送信したチケットの一部を処理することがあり、レシートのチケット別結果で受領の成功を判定します。

StableSwap は入力額固定・出力額固定の見積もり、流動性の見積もり、実行期限、最低出力額、最大入力額を提供します。Router はプール、許可トークン、受取人を検証します。プールは準備金と手数料を管理し、LP ステーキングと報酬は `RewardStaker` が管理します。

現在の`USDHNToken`はERC-20とpermitを実装します。LayerZero転送では`USDHNOFTAdapter`が基準チェーンのトークンをロック・解除し、`USDHNOFT`が他のチェーンのトークンを発行・焼却します。アプリのBridgeは製品Bridge APIを使い、対応する出発資産USDT・USDCからKaia USDTへ移動するRhino経路を見積もります。この製品経路には別の実行指示と出発チェーンのトランザクションがあります。

## データとデプロイの境界

インデクサーはイベントを反映したアカウント履歴とポジションを管理します。スキャナーは現在の価格、実行準備状態、リスク値を返します。ジョブは定期計算を実行し、キーパーは設定されたプロトコル操作を送信します。`contractViewLive` が対応するトランザクション用の参照は、API 障害中でも `HannFrontendView` を使えます。履歴とトランザクションの反映確認は API 経由のままです。

アドレスと ABI は `artifacts/contracts/<profile>` または `GET /api/v1/contracts/snapshot` から読み込みます。`kaia-prod` と `kaia-qa` のチェーン ID は `8217`、`kairos-dev` は `1001` です。デプロイプロファイルもコントラクトの識別情報に含まれます。Lending・CDP・ステーキング間で、同じシンボルだけを根拠にトークンを同じアドレスと判断しません。

[スマートコントラクト](/ja/developers/smart-contracts.md)にコントラクト ID、関数、イベント、プロダクションプロファイルのアドレスを掲載しています。[統合ガイド](/ja/developers/integrator-kit.md)はウォレット操作とインデックス処理を説明します。Trove の状態遷移は [Trove Manager](/ja/developers/trove-manager.md)、経路実行は [Zapper](/ja/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 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://docs.hann.finance/ja/developers/technical-overview.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.