> 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/trove-manager.md).

# Troveの状態と遷移

TroveManagerの会計、ポジション状態、ブランチ制限、読み取り関数と統合用イベント。

各担保ブランチの**TroveManager**はTroveの会計を保存し、清算と償還を処理します。ユーザーの作成・調整・クローズは**BorrowerOperations**を経由します。アプリのZapperは、この入口を呼び出す前に担保変換とウォレットのトランザクションを処理します。

## コントラクトの役割

| コントラクト               | 役割                                                 |
| -------------------- | -------------------------------------------------- |
| `BorrowerOperations` | 作成、担保・負債の調整、金利管理、全額返済・クローズ、余剰担保の回収です。              |
| `TroveManager`       | ポジション・バッチ会計、最新の負債・担保の読み取り、清算、償還、状態の変更です。           |
| `TroveNFT`           | ERC-721の所有権です。TroveManagerが作成時に発行し、クローズ・清算時に焼却します。 |
| `SortedTroves`       | 年率による、開いているTroveの償還順です。                            |
| `StabilityPool`      | 清算負債を相殺するUSDHN預入と、それに伴う担保・利回りの会計です。                |
| `CollateralRegistry` | ブランチの登録・状態管理と、複数ブランチへの通常のUSDHN償還の配分です。             |

TroveManagerの`onOpenTrove`、`onAdjustTrove`などの借り手更新関数はBorrowerOperationsからの呼び出しを受けます。ウォレットが直接使う入口ではありません。`batchLiquidateTroves`は公開関数で、通常の`redeemCollateral`はCollateralRegistryから呼び出されます。

[スマートコントラクト](/ja/developers/smart-contracts.md)に従い、選択したデプロイプロファイルとブランチのアドレス・ABIを取得します。`kaia-prod`と`kaia-qa`は同じチェーンID`8217`を使いますが、別のプロファイルです。`kairos-dev`は`1001`を使います。

## Trove IDと所有権

作成時のIDはBorrowerOperations内で計算されます。

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

ここで`msg.sender`はBorrowerOperationsから見た呼び出し元で、Zapperコントラクトなどが該当します。同じ所有者とインデックスでも入口が違えばIDが変わることがあります。作成トランザクションのレシートとNFT発行イベントからIDを取得し、ブランチとともに記録します。

`TroveNFT.Transfer`をインデックスして所有権を追跡します。発行では送信元がゼロアドレス、焼却では受信先がゼロアドレスです。焼却後は`ownerOf`で所有者を取得できないため、履歴に最後の所有者を保持します。

## ポジションの状態

`ITroveManager.Status`のenum順は次のとおりです。

| 値   | 状態                    | 意味                                               |
| --- | --------------------- | ------------------------------------------------ |
| `0` | `nonExistent`         | このIDのポジションは作成されていません。                            |
| `1` | `active`              | ソート済みリストにある開いたポジションです。借り手の操作にはブランチと比率の検査も適用されます。 |
| `2` | `closedByOwner`       | 自主的なクローズです。会計フィールドを消去し、NFTを焼却します。                |
| `3` | `closedByLiquidation` | 清算によるクローズです。会計フィールドを消去し、NFTを焼却します。               |
| `4` | `zombie`              | 償還で負債が`MIN_DEBT`を下回り、通常のソート済みリストから外れた開いたポジションです。 |

### 状態遷移

| 開始状態                | 操作                                                   | 結果                               |
| ------------------- | ---------------------------------------------------- | -------------------------------- |
| `nonExistent`       | `openTrove`または`openTroveAndJoinInterestBatchManager` | `active`、NFTを発行します。              |
| `active`            | 償還後の負債が0を含めて`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`がそのIDを保持し、次の償還で先に処理します。全額償還、復元、クローズでポインターを消去します。

通常の`adjustTrove`はactiveポジションが対象です。Zombieの変更には`adjustZombieTrove`を使い、`MIN_DEBT`の検査、変更の適用、再挿入を行います。`applyPendingDebt`も、最新負債が最低額に達したzombieを復元できます。全額償還されたzombieはUSDHN返済額0でクローズし、担保とガス預託金を回収できます。

清算検査には`active`と`zombie`の両方が含まれます。全額償還済みポジションには清算する負債がありません。すべてのzombieをクローズ済みとして表示すると、所有者の担保がまだ保持されていることが隠れます。

## ブランチの状態とshutdown

TroveManagerは`findCollateralByTroveManager`でブランチを特定し、`CollateralRegistry.collateralConfig(index).status`を読み取ります。

| レジストリの状態     | 新規Trove                | 担保・負債の調整                                       |
| ------------ | ---------------------- | ---------------------------------------------- |
| `Pending`    | 禁止されます。                | 禁止されます。                                        |
| `Active`     | 負債、オラクル、比率の検査を通れば可能です。 | ポジションとブランチの検査を通れば可能です。                         |
| `Deprecated` | 禁止されます。                | 要求した負債増加額が負債減少額より大きいと禁止されます。他の調整にも残りの検査を適用します。 |

`CollateralStatusForbidsOperation()`はレジストリの状態による拒否を示します。Shutdownは別の条件です。

* `shutdownTime() == 0`：ブランチはshutdownしていません。
* `shutdownTime() > 0`：shutdownのタイムスタンプです。
* Shutdown後、BorrowerOperationsは新規借入と通常の調整を禁止します。全額返済とクローズは可能です。
* Shutdown前の利息は`lastDebtUpdateTime`から現在まで累積します。Shutdown後は、最終更新がそれ以前なら`shutdownTime`まで、更新がshutdown以降なら追加の累積期間を0として計算します。
* 通常の償還には、shutdownしていないブランチと`TCR >= SCR`が必要です。`urgentRedemption`はshutdown状態で明示したTrove IDを使います。

Shutdown前の自主的なクローズは、クローズ後に`TCR >= CCR`を維持し、追跡中の他のTroveを少なくとも1つ残す必要があります。Shutdown後の自主的なクローズにはこの2つの制限はありません。清算は最後のTroveを削除できず、`OnlyOneTroveLeft()`でrevertします。

## 最新状態の読み取り

最新の負債・担保表示には`getLatestTroveData(troveId)`を使います。最後の保存値に未反映の利息と再分配を計算します。

| フィールド                                  | 内容                                              |
| -------------------------------------- | ----------------------------------------------- |
| `entireDebt`                           | 記録済み負債に累積利息、再分配USDHN負債、Troveの累積バッチ管理手数料を加えた値です。 |
| `entireColl`                           | 記録済み担保に未反映の再分配担保を加えた値です。                        |
| `recordedDebt`                         | ポジションに記録された、またはバッチのシェアで帰属する負債です。                |
| `accruedInterest`                      | Shutdownを反映した最終会計更新以降の利息です。                     |
| `redistUSDHNDebtGain`、`redistCollGain` | ブランチ再分配で割り当てられた未反映の負債・担保です。                     |
| `annualInterestRate`                   | ポジションの金利または現在のバッチ金利です。                          |
| `weightedRecordedDebt`                 | 記録済み負債に年率を掛けた値です。                               |
| `accruedBatchManagementFee`            | ポジションに帰属する累積バッチ手数料です。                           |
| `lastInterestRateAdjTime`              | ポジション・バッチの最新の関連金利変更時点です。                        |

バッチ加入Troveの負債、利息、管理手数料は`batchDebtShares / totalDebtShares`で配分します。再分配はTroveの担保stakeに従うため、バッチ全体の負債の持分だけでは`entireDebt`の計算を置き換えられません。

| 読み取り関数                                                  | 用途                                           |
| ------------------------------------------------------- | -------------------------------------------- |
| `Troves(troveId)`                                       | 保存済みの負債、担保、stake、状態、時点、金利、バッチマネージャーとシェアです。   |
| `getTroveStatus(troveId)`                               | 状態enumです。                                    |
| `getTroveAnnualInterestRate(troveId)`                   | バッチ金利を含むポジションの適用金利です。                        |
| `getLatestBatchData(batchAddress)`                      | バッチの合計、負債シェア、累積利息と管理手数料です。                   |
| `getCurrentICR(troveId, price)`                         | 最新の負債・担保と入力価格による担保比率です。                      |
| `getTroveIdsCount()`、`getTroveFromTroveIdsArray(index)` | 現在追跡しているID配列です。クローズ時にIDを削除するため、累計作成数ではありません。 |

`getCurrentICR`には該当ブランチの価格とスケールを渡します。価格と比率は`1e18`精度で、`1.2e18`は`120%`を表します。市場見積もりを入力した結果は、その見積もりの比率です。プロトコルのオラクル清算検査とは区別します。

## イベントと履歴

デプロイ済みTroveManagerとBorrowerOperationsのABI、TroveNFTの所有権イベントをインデックスします。イベントのスナップショットは操作時の会計を記録し、その後の累積利息は最新状態の読み取りで反映します。

| イベント                       | 保持する情報                                        |
| -------------------------- | --------------------------------------------- |
| `TroveUpdated`             | Trove ID、記録済み負債・担保、stake、金利、再分配スナップショットです。    |
| `TroveOperation`           | 操作種別と、再分配・前払い手数料・要求操作に分かれた負債・担保の変化です。         |
| `Liquidation`              | 相殺・再分配負債、Stability Pool・再分配担保、報酬、余剰担保、実行価格です。 |
| `Redemption`               | 試行・実際のUSDHN償還額、送付担保、手数料、価格です。                 |
| `RedemptionFeePaidToTrove` | 個別の償還対象Troveの手数料会計です。                         |
| `BatchUpdated`             | バッチ操作、合計、金利、管理手数料、シェア、前払い手数料の変化です。            |
| `BatchedTroveUpdated`      | Troveの担保、stake、負債シェア、バッチマネージャー、再分配スナップショットです。 |
| TroveNFTの`Transfer`        | 作成、所有権移転、焼却です。                                |

イベントの適用時はトランザクション順とブランチを保持します。`closedByOwner`と`closedByLiquidation`は終了状態として扱い、NFT焼却後も履歴を保持します。通常ポジションとバッチポジションの両方のイベント経路を反映し、バッチ負債にはシェア会計を適用します。

## トランザクションの失敗

| Revert                                 | 関連する入力・状態                      |
| -------------------------------------- | ------------------------------ |
| `CollateralStatusForbidsOperation()`   | 選択したブランチでこの作成・調整が許可されません。      |
| `IsShutDown()`                         | Shutdownにより要求した借り手操作が停止しました。   |
| `ICRBelowMCR()`、`ICRBelowMCRPlusBCR()` | 変更後の担保比率が必要な基準を下回ります。          |
| `TCRBelowCCR()`                        | 操作がブランチ全体の担保比率検査に抵触します。        |
| `DebtBelowMin()`                       | 変更後の負債が最低額を下回ります。              |
| `UpfrontFeeTooHigh()`                  | 実行手数料が承認した最大値を超えます。            |
| `NotEnoughUSDHNBalance()`              | 返済の呼び出し元に焼却するUSDHNが不足しています。    |
| `OnlyOneTroveLeft()`                   | 現在のクローズ規則で最後の追跡Troveを削除する操作です。 |

操作画面には該当する数量、ブランチ制限、ポジション状態を表示します。Zapperのルーティング・スリッページ失敗は、そのトランザクション経路で処理します。コントラクトの接続は[技術概要](/ja/developers/technical-overview.md)、API・ウォレットの流れは[統合ガイド](/ja/developers/integrator-kit.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/trove-manager.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.