> 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/integrator-kit.md).

# 통합 가이드

Hann Finance 통합을 위한 컨트랙트 선택, 지갑 트랜잭션, 이벤트 인덱싱

통합에 사용하는 배포 프로필, 컨트랙트 ABI, 지갑 트랜잭션, 결과를 표시할 제품 데이터를 함께 연결합니다. 컨트랙트 ID와 공개 함수는 [스마트 컨트랙트](/ko/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` | 레지스트리가 호출자의 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의 게이트웨이 사용 승인                                                     |
| 네이티브 KAIA 차입    | `WKaiaGateway.borrowKAIA`             | 변동금리 부채 토큰에서 게이트웨이에 `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`, 라우터의 `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/ko/developers/integrator-kit.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.