> 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/protocol/zapper.md).

# Zapper

유동성과 Trove 작업의 결합, 토큰 승인, 관리자 권한, 플래시 정산.

Zapper는 서로 연결된 작업을 한 트랜잭션에서 실행하는 컨트랙트입니다. Hann Finance는 담보 래핑, Trove 개설·조정, 유동성 공급과 LP 스테이킹, 플래시 유동성을 이용한 레버리지 조정에 Zapper를 사용합니다. 토큰 승인과 manager·operator 권한 설정은 결합 작업과 별개이며, 앱은 빠진 권한을 먼저 요청합니다.

| 작업             | 컨트랙트 계열                                         | 결합하는 동작                                  |
| -------------- | ----------------------------------------------- | ---------------------------------------- |
| KAIA 담보 차입     | `WKAIAZapper`                                   | 네이티브 KAIA 래핑, Trove 작업, 반환 자산 언래핑.       |
| HNKAIA 담보 차입   | `HNKAIAZapper`                                  | HNKAIA 전송과 Trove 작업.                     |
| earnUSDT 담보 차입 | `EarnUSDTZapper`                                | earnUSDT 수령, wEarnUSDT 담보로 래핑, Trove 작업. |
| 레버리지 조정        | `LeverageWKAIAZapper`, `LeverageEarnUSDTZapper` | 일시 유동성 확보, 담보·USDHN 부채 변경, 플래시 정산.       |
| 예치와 LP 스테이킹    | `StableSwapZapper`                              | USDT·USDHN 유동성 공급과 새 LP 토큰의 스테이킹.        |
| LP 해제와 출금      | `StableSwapZapper`                              | LP 스테이킹 해제, LP 소각, 두 풀 자산 반환.            |

메인넷 앱은 KAIA·earnUSDT 레버리지를 제공합니다. HNKAIA 레버리지는 테스트넷 앱에서 제공하며, 메인넷의 HNKAIA 차입은 일반 Trove 작업을 사용합니다.

## 토큰 승인과 서명

ERC-20 승인은 지정한 컨트랙트가 지갑에서 해당 토큰을 가져갈 수 있는 권한입니다. Permit2는 전송 권한을 서명으로 부여합니다. 지갑에 표시된 토큰, 수량, spender, 만료 시간을 확인하세요. 토큰의 Permit2 사용 한도가 부족하면 서명 전송에 앞서 해당 한도를 승인합니다.

앱은 연결 방식과 작업에 맞는 승인 방법을 선택합니다. StableSwap·LP 작업은 브라우저 지갑 연결에서 Permit2 서명을, 앱의 모바일 연결 모드에서 ERC-20 승인을 사용합니다. 네이티브 KAIA 담보는 트랜잭션의 전송 값에 포함되므로 ERC-20 담보 승인이 없습니다.

다음 두 권한은 서로 다른 작업을 허용합니다.

* **Trove manager 권한**은 Zapper가 선택한 포지션 작업을 수행하도록 허용합니다. 조정이나 담보로 상환하는 종료 작업에서 현재 설정이 맞지 않으면 앱이 올바른 manager 설정을 요청합니다.
* **RewardStaker operator 권한**은 StableSwapZapper가 사용자를 대신해 LP 토큰을 스테이킹하거나 해제하도록 허용합니다. 토큰 사용 승인만으로는 이 권한이 부여되지 않습니다.

## 일반 Trove 작업

Trove는 한 담보 브랜치의 담보와 USDHN 부채를 보관합니다. 일반 Zapper는 개설, 담보 추가·인출, USDHN 차입·상환, 종료를 지원합니다.

1. 포지션 작업을 선택하고 담보 또는 USDHN 수량을 입력합니다.
2. 변경 후 담보, 부채, 연이율, 선취 수수료, 담보비율을 확인합니다.
3. 앱이 요청하는 토큰 승인과 manager 권한 설정을 완료합니다.
4. Trove 트랜잭션을 승인합니다.
5. 변경된 포지션과 지갑으로 반환된 토큰을 확인합니다.

개설에는 해당 브랜치의 담보와 KAIA 가스 보상 예치금이 필요합니다. KAIA 브랜치의 트랜잭션에는 담보 수량과 가스 보상 예치금을 함께 보내고, Zapper가 각각의 용도에 맞춰 래핑합니다. ERC-20 담보 브랜치에서는 가스 보상 예치금을 네이티브 KAIA로 따로 보냅니다. 이 예치금은 네트워크 거래 수수료와 별개이며, 열린 Trove에 남아 있다가 소유자가 정상적으로 종료하면 반환됩니다. 일반 조정에는 개설 예치금을 다시 내지 않습니다.

지갑의 USDHN으로 종료하면 누적 이자를 포함한 현재 부채 전액을 상환하고 담보를 받습니다. KAIA 일반 Zapper는 반환할 WKAIA를 KAIA로 풀고, earnUSDT 일반 Zapper는 wEarnUSDT를 earnUSDT로 풀어 반환합니다.

## 플래시 유동성을 이용한 레버리지

플래시 작업은 일시적으로 유동성을 제공하고 같은 트랜잭션 안에서 정산합니다. 최종 Trove의 부채는 작업 후에도 남고, 일시적으로 빌린 플래시 유동성은 전액 정산됩니다.

| 작업          | 담보 변화                  | USDHN 부채 변화                  |
| ----------- | ---------------------- | ---------------------------- |
| 개설·레버리지 확대  | 요청한 담보 노출을 추가합니다.      | 정산에 필요한 USDHN을 차입합니다.        |
| 레버리지 축소     | 포지션의 담보 일부를 정산에 사용합니다. | 일시 유동성으로 USDHN을 상환합니다.       |
| 담보로 상환하고 종료 | 담보를 부채 전액 상환에 사용합니다.   | 현재 부채 전액을 상환하고 Trove를 종료합니다. |

담보와 작업에 따라 정산 경로가 다릅니다.

| 경로             | 정산 방식                                                                                                                                       |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| KAIA           | 설정된 WKAIA/USDT V3 풀이 일시 담보나 USDT를 제공합니다. USDHN/USDT StableSwap 교환으로 정산 자금이나 부채 상환 자금을 확보합니다.                                                |
| earnUSDT 개설·확대 | StableSwap이 출력 수량 고정 콜백으로 USDT를 보냅니다. SuperEarnRouter에 예치해 earnUSDT를 받고 wEarnUSDT로 래핑한 뒤 Trove에 넣습니다. 차입한 USDHN으로 StableSwap의 입력 금액을 지급합니다. |
| earnUSDT 축소·종료 | 설정된 earnUSDT/USDT V3 풀이 USDT를 제공합니다. StableSwap에서 USDHN으로 교환해 상환하고, 담보를 풀어 얻은 earnUSDT로 V3 작업을 정산합니다.                                       |

브랜치에 설정된 경로를 사용하며, 사용자가 임의의 라우터나 수령 토큰을 지정하지 않습니다.

실행 중에는 필요한 Trove manager 권한을 FlashSwapper로 넘기고 정산 후 기존 관리 상태로 복원합니다. 정산 후 남은 토큰은 지정된 수령자에게 반환합니다. 앱은 포지션 소유자의 지갑을 수령자로 사용합니다.

### 실행 한도

개설과 레버리지 조정은 최종 부채 상한 `maxDebt`를 전달합니다. 실행 후 부채가 이 값보다 커지면 트랜잭션이 실패합니다. 컨트랙트는 담보 변화량, 플래시 풀·토큰, 설정된 StableSwap 풀, 플래시 수수료 상한, manager·receiver 상태도 확인합니다.

담보로 상환하는 종료는 현재 부채 전액과 별도로 설정된 종료 수수료 상한을 사용합니다. 이 종료 화면은 슬리피지 한도를 `100%`로 표시하며, 컨트랙트 호출에는 사용자가 정한 최소 수령량이 없습니다. 표시된 순수령량은 예상치이며 실제 반환 토큰은 정산 결과에 따라 결정됩니다.

결합 트랜잭션이 실패하면 그 트랜잭션 안의 담보·부채 변경과 토큰 이동이 되돌아갑니다. 앞선 트랜잭션에서 확정된 토큰 승인, operator 승인, manager 설정은 유지되며 실패한 거래에도 네트워크 가스가 사용됩니다.

## 토큰과 가스 보상 예치금의 반환

* 일반 종료는 USDHN 부채 전액을 상환한 뒤 담보를 반환합니다.
* 담보로 상환하는 종료는 플래시 정산에 필요한 담보를 사용하고 남은 담보·경로 토큰을 반환합니다. KAIA Zapper는 반환할 WKAIA를 KAIA로 풀고, earnUSDT 경로는 담보를 풀어 정산한 뒤 남은 earnUSDT를 반환합니다.
* 종료하면 가스 보상 예치금이 해제되어 해당 브랜치의 지급 방식으로 수령자에게 전달됩니다.
* LP Zapper는 작업 시작 잔액과 비교해 이번 작업에서 추가로 남은 token0·token1·LP 잔액을 반환합니다.

반환 방식은 해당 브랜치의 토큰 처리 규칙을 따릅니다. Zapper가 사용자가 고른 모든 토큰으로 변환하는 기능은 없습니다.

## 유동성 결합 작업

`/earn/usdt`에서 LP 토큰을 바로 스테이킹하기를 선택하면 두 풀 자산을 StableSwapZapper로 보냅니다. Zapper는 라우터의 유동성 공급을 호출하고 `minLiquidity`를 확인한 뒤 새 LP 토큰을 RewardStaker에 스테이킹합니다. 언스테이킹과 동시에 출금은 LP 토큰의 스테이킹을 해제하고 유동성을 회수한 뒤 토큰별 최소 수량을 확인해 USDT·USDHN을 지갑으로 보냅니다.

두 결합 작업 모두 거래 기한과 RewardStaker operator 권한을 확인합니다. LP를 스테이킹해도 풀 자산의 가치 변동은 그대로 반영됩니다. Trove 자동화에도 해당 브랜치의 담보비율·청산 규칙이 적용됩니다.

앱 사용 순서는 [교환·브리지·유동성 공급](/ko/protocol/stableswap-dex.md)과 [레버리지 포지션](/ko/protocol/loops.md)에서, Trove 부채와 담보비율은 [차입과 청산](/ko/protocol/borrowing-and-liquidation.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/protocol/zapper.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.