> 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/ko/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의 호출을 받습니다.

[스마트 컨트랙트](/ko/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`를 인덱싱해 소유권을 추적합니다. 발행은 송신자가 0 주소이고 소각은 수신자가 0 주소입니다. 소각 후 `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`가 가리키며 다음 리뎀션에서 먼저 처리합니다. 해당 zombie가 전부 리뎀션되거나 복구·종료되면 포인터를 지웁니다.

일반 `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를 최소 하나 남겨야 합니다. Shutdown 후 자발적인 종료에는 이 두 제한을 적용하지 않습니다. 청산은 마지막 Trove를 제거할 수 없으며 `OnlyOneTroveLeft()`로 revert합니다.

## 최신 상태 조회

최신 부채·담보 표시는 `getLatestTroveData(troveId)`를 사용합니다. 이 함수는 마지막 저장값에 미반영 이자와 재분배를 계산합니다.

| 필드                                      | 내용                                                         |
| --------------------------------------- | ---------------------------------------------------------- |
| `entireDebt`                            | 기록된 부채에 누적 이자, 재분배 USDHN 부채, Trove의 누적 배치 관리 수수료를 더한 값입니다. |
| `entireColl`                            | 기록된 담보에 미반영 재분배 담보를 더한 값입니다.                               |
| `recordedDebt`                          | 포지션에 기록되거나 배치 지분으로 귀속된 부채입니다.                              |
| `accruedInterest`                       | Shutdown 기준을 반영한 마지막 회계 갱신 이후 이자입니다.                       |
| `redistUSDHNDebtGain`, `redistCollGain` | 브랜치 재분배로 배정된 미반영 부채·담보입니다.                                 |
| `annualInterestRate`                    | 포지션 이자율 또는 현재 배치 이자율입니다.                                   |
| `weightedRecordedDebt`                  | 기록된 부채에 연이율을 곱한 값입니다.                                      |
| `accruedBatchManagementFee`             | Trove에 귀속되는 누적 배치 수수료입니다.                                  |
| `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`              | 상쇄·재분배 부채, 스태빌리티 풀·재분배 담보, 보상, 초과 담보, 실행 가격입니다. |
| `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 라우팅·슬리피지 실패는 해당 트랜잭션 경로에서 처리합니다. 컨트랙트 연결은 [기술 개요](/ko/developers/technical-overview.md), API·지갑 흐름은 [통합 가이드](/ko/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/ko/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.