> 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/integrator-kit.md). # 統合ガイド Hann Finance 統合のためのコントラクト選択、ウォレット操作、イベントのインデックス処理 統合には、選択したデプロイプロファイル、一致するコントラクト ABI、ウォレット操作、結果を表示する製品データを使います。コントラクト ID と公開関数は[スマートコントラクト](/ja/developers/smart-contracts.md)に掲載しています。 ## 1. ネットワークとコントラクトバンドルを選ぶ | プロファイル | ネットワーク | チェーン ID | 用途 | | ------------ | ------ | ------- | ----------------------- | | `kaia-prod` | Kaia | `8217` | メインネットのプロダクション設定、デプロイ予定 | | `kaia-qa` | Kaia | `8217` | メインネットの QA 設定 | | `kairos-dev` | Kairos | `1001` | テストネットへデプロイした開発環境 | Hann Finance ワークスペースの `@hann/contract-artifacts/registry` は、`HANN_CONTRACT_ARTIFACTS_PROFILE` でプロファイルを選択します。ブラウザビルドは `NEXT_PUBLIC_HANN_CONTRACT_ARTIFACTS_PROFILE` と対応する `NEXT_PUBLIC_CHAIN_ID` を使います。パッケージは import 時にコントラクトを初期化するため、先にプロファイルを設定します。 非公開のワークスペースパッケージは `getAddress(id)`、`getAbi(id)`、`getContractSnapshot()` とドメイン別モジュールを公開します。外部統合は選択したプロファイルの JSON スナップショットを読み込み、各 `abiRef` を `artifacts/contracts` からの相対パスとして解決できます。`GET /api/v1/contracts/snapshot` は API のデプロイ環境が選択したスナップショットを返します。`activeProfile`、`activeChainId`、`contracts`、`aliases`、`runtime`、ソース情報を含み、ABI 本体は `abiRef` で参照します。 プロファイル、チェーン、コントラクト ID、アドレス、ABI をひと組で管理します。RPC とウォレットのチェーン ID を `activeChainId` と照合し、CDP の担保と Lending 市場の資産はそれぞれの項目から解決します。`contracts/deploy/runs` の実行別出力と `docs/imported` の過去資料は、選択されたランタイムバンドルと区別します。 ### USDHN の残高を取得する 次の TypeScript 関数は Hann ワークスペース内で選択済みのアーティファクトパッケージを使います。現在のテストネットデプロイには `kairos-dev` を選択します。呼び出し側は RPC URL とウォレットアドレスを渡します。 ```ts import { createPublicClient, http, type Address } from "viem"; import { getAbi, getAddress, getContractSnapshot, } from "@hann/contract-artifacts/registry"; export async function getUsdhnBalance(rpcUrl: string, user: Address) { const client = createPublicClient({ transport: http(rpcUrl) }); const snapshot = getContractSnapshot(); const rpcChainId = await client.getChainId(); if (rpcChainId !== snapshot.activeChainId) { throw new Error("RPC chain does not match the selected contract profile"); } return client.readContract({ address: getAddress("core.USDHN"), abi: getAbi("core.USDHN"), functionName: "balanceOf", args: [user], }); } ``` USDHN の小数桁数は18です。コントラクトの数量は `bigint` で保持し、画面表示時に単位を変換します。 ## 2. 操作と承認先を結び付ける | 操作 | トランザクション先 | 承認または署名 | | ----------------- | --------------------------------------- | ----------------------------------------------------------------------- | | CDP 借入 | ブランチの `BorrowerOperations` または Zapper | 担保の使用承認、選択した Zapper 関数の Permit2 経路 | | CDP リデンプション | `CollateralRegistry.redeemCollateral` | Registry が呼び出し元の USDHN を直接バーンするため、使用承認は消費しない | | Earn 入金 | ブランチの `StabilityPool.provideToSP` | 登録済み Stability Pool が `sendToPool` で USDHN を移動するため、直接入金に ERC-20 使用承認は不要 | | Lending の供給・返済 | `lending-core.Pool` | 原資産トークンの Pool への使用承認 | | ネイティブ KAIA の供給・返済 | `lending-core.WKaiaGateway` | `msg.value` で KAIA を送信 | | ネイティブ KAIA の引き出し | `WKaiaGateway.withdrawKAIA` | aWKAIA の Gateway への使用承認 | | ネイティブ KAIA の借入 | `WKaiaGateway.borrowKAIA` | 変動金利債務トークンから Gateway への `approveDelegation` | | bKAIA の入金・引き出し申請 | 対応するエントリーモジュール ABI を使う `bkaia.LSTVault` | 入金はネイティブ KAIA、`requestUnstakeByShares` は保有シェアを使用 | | スワップ・LP 操作 | StableSwap Router または Zapper | 入力トークン・LP の使用承認、選択した permit 関数の Permit2 署名 | ERC-20 の使用承認、Permit2 の署名、債務の委任は異なる権限です。現在の承認量または委任量を取得し、操作に必要な数量を要求してから、承認トランザクションの確認後に次へ進みます。Zapper はプロトコル操作と経路実行をまとめます。トークンの使用承認トランザクションは先に別途実行することがあります。 `BorrowerOperations` の直接呼び出しでは、Trove のパラメータとマネージャー設定を構成します。Zapper はネイティブトークンのラップ、Permit2、経路実行を加えます。`BorrowerOperations` で直接開設したポジションにレバレッジ管理下の終了経路を使うには、対応する管理権限を先に引き渡します。 ## 3. 現在の状態からトランザクションを構成する 1. ポジション、所有者、ブランチ・市場のパラメータ、資産の小数桁数、利用可能な残高を取得します。 2. 選択した ABI で呼び出しを構成します。Trove には挿入位置のヒントと前払い手数料上限を用意します。Lending の変動金利呼び出しには、アプリと同じ金利モード `2` を使います。 3. 関数に対応する実行上限を設定します。StableSwap は最低出力額または最大入力額と期限、Zapper は `maxDebt`、借入操作は適用される前払い手数料上限を使います。 4. 送信者、引数、ネイティブ送金額をそのまま使い、呼び出しをシミュレーションします。ウォレット署名前に結果の担保・債務・受取額・手数料・担保状態を表示します。 5. ウォレットで送信し、レシートを読みます。revert したトランザクションはプロトコル状態を変更しません。成功した bKAIA の一括受領にも、チケット別の失敗や再試行が含まれることがあります。 6. 変更された製品データを更新します。レシート確認と API・インデクサーへの反映は、新しいデータが取得されるまで別の状態として管理します。 CDP の担保状態には `getLatestTroveData().entireDebt`、`entireColl`、現在のブランチ価格と制限を使います。Lending には `getUserAccountData()` と市場設定を使い、担保の有効化と eMode を反映します。ポジション値の横に、その製品の清算条件を表示します。 ### フラッシュ流動性を使う経路 認可された Zapper と FlashSwapper は、実行中に Trove の担保追加マネージャー、担保引き出しマネージャー、受取人を制御します。フラッシュコールバックはスワップを決済して Trove を更新し、DEX プールに返済してから管理状態を復元します。見積もりは設定済みのプールとトークンを使います。コントラクトはフラッシュ手数料上限と最終債務を検査し、経路の残余資産を返します。 `closeTroveByCollateral({troveId, profitReceiver})` は担保を売却して現在の債務全額を返済します。この ABI にはユーザーが指定する `minOut` がありません。通常の上限付きスワップや USDHN で返済する終了操作と、それぞれの実行結果を区別して表示します。 ## 4. ポジションと結果をインデックス化する | 対象 | イベントと現在値の取得 | | ------------ | ---------------------------------------------------------------------------------------------------------- | | Trove の所有権 | ブランチの `TroveNFT.Transfer`、`ownerOf(troveId)` | | Trove の担保・債務 | `TroveUpdated`、`TroveOperation`、`BatchedTroveUpdated`、`BatchUpdated`、`getLatestTroveData`、`getTroveStatus` | | 清算・リデンプション | TroveManager の `Liquidation`、`Redemption`、`RedemptionFeePaidToTrove` | | Earn | `DepositUpdated`、`DepositOperation`、現在の預入残高・担保利益・USDHN 利回りの取得 | | Lending | `Supply`、`Withdraw`、`Borrow`、`Repay`、`LiquidationCall`、`ReserveDataUpdated`、市場・アカウントの取得 | | StableSwap | プールの `Swap`、`Mint`、`Burn`、Router の `LiquidityAdded`、`LiquidityRemoved`、返却イベント | | bKAIA | `Deposit`、`RequestedBatch`、`Requested`、`TicketStatusUpdated`、`ClaimPayout`、`ClaimManySummary`、再試行イベント | ログはチェーン ID、ブロックハッシュ、トランザクションハッシュ、ログインデックスで識別します。Trove ID と一緒に発行元コントラクトとブランチを保存します。債務イベントに加えて NFT の移転を追跡し、所有権の変更をポートフォリオへ反映します。削除・置換されたブロックを処理してから、新しいデータを反映します。 イベントはそのブロックで行われた操作を記録します。利息と価格はアカウントの追加操作なしでも変化するため、履歴と現在値を組み合わせて残高と担保状態を表示します。bKAIA は処理済みチケット ID と支払イベントから受領結果を更新します。トランザクションの成功だけで、全チケットの支払完了と判断しません。 ## 製品データとブリッジ実行 アプリは製品データに生成された `@hann/api-client` スキーマを、ウォレット呼び出しに `@hann/contract-artifacts` を使います。対応する API 項目は障害中もコントラクトの直接参照からトランザクションに必要な値を取得できます。派生履歴、ポイント、トランザクションの反映確認は API を使います。 Bridge API は対応チェーン、トークン、承認先アドレス、見積もり、出発チェーンの実行指示を返します。製品の Rhino 経路は対応する USDT・USDC を受け取り、Kaia USDT を届けます。見積もりに結び付いた承認情報と commitment で `depositWithId` を送信し、出発チェーンでの確認と到着チェーンでの完了を追跡します。USDHN OFT の `send` は独自の peer と手数料設定を使う別のトークンインターフェースです。 --- # 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/integrator-kit.md?ask=&goal= ``` `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.