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

# 기술 개요

대출·USDHN·스테이킹·교환을 지갑과 제품 API에 연결하는 구조

Hann Finance는 대출 시장, 담보 기반 USDHN 차입, 유동성 스테이킹, 토큰 교환을 제공합니다. 각 제품은 별도의 컨트랙트에서 자산과 부채를 관리합니다. 앱은 API로 제품 데이터를 조회하고, 사용자의 지갑에서 선택한 컨트랙트로 트랜잭션을 전송합니다.

## 제품과 트랜잭션 경로

### 제품 데이터 조회

```mermaid
flowchart TB
  APP[Hann Finance 앱] -->|제품 데이터 조회| API[제품 API]
  INDEX[인덱서와 스캐너] --> API
```

### 지갑 트랜잭션

앱이 서명을 요청하면 지갑은 선택한 제품의 Lending Pool, CDP Zapper, bKAIA·HNKAIA 금고 또는 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`와 자산별 금고                        | 지원하는 스테이킹 자산으로 HNKAIA 지분 발행, 기초 자산으로 환매 |
| 교환과 LP     | StableSwap 풀·라우터·LP 토큰, `RewardStaker`       | USDT와 USDHN 교환, 유동성 공급, LP 토큰 스테이킹      |

## USDHN 담보 브랜치

생성된 CDP 인터페이스에는 `WKAIA`, `HNKAIA`, `EARNUSDT`의 세 브랜치가 있습니다. 앱은 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`             | 레지스트리 조회, 토큰 전송, 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 금고는 진입 모듈로 호출을 전달합니다. 지갑은 예치·인출 요청·수령·조회에 맞는 ABI를 사용해 **금고 주소**를 호출합니다. 인출 요청은 티켓을 만들고, `claimMany`는 제출한 티켓 중 일부를 처리할 수 있습니다. 영수증의 티켓별 결과로 수령 성공 여부를 판정합니다.

StableSwap은 입력량·출력량 고정 견적, 유동성 견적, 실행 기한, 최소 출력량, 최대 입력량을 제공합니다. 라우터는 풀, 허용 토큰, 수령자를 검증합니다. 풀은 준비금과 수수료를 관리하며 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`의 체인 ID는 `1001`입니다. 배포 프로필은 컨트랙트 식별 정보에 포함됩니다. Lending·CDP·스테이킹의 토큰은 심볼만으로 동일한 주소라고 판단하지 않습니다.

[스마트 컨트랙트](/ko/developers/smart-contracts.md)에는 컨트랙트 ID, 함수, 이벤트, 프로덕션 프로필 주소가 있습니다. [통합 가이드](/ko/developers/integrator-kit.md)는 지갑 트랜잭션과 인덱싱 절차를 설명합니다. Trove 상태 전이는 [Trove Manager](/ko/developers/trove-manager.md), 경로 실행은 [Zapper](/ko/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/ko/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.