> 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/protocol/zapper.md). # Zappers Combined liquidity and Trove actions, token approvals, manager permissions, and flash settlement. A zapper contract combines related actions in one transaction. Hann Finance uses zappers to wrap collateral, open or adjust a Trove, add liquidity and stake LP tokens, and settle flash-assisted leverage changes. Token approvals and manager or operator permissions are separate from the combined action; the app requests missing permissions first. | Task | Contract family | What it combines | | ----------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------- | | Borrow against KAIA | `WKAIAZapper` | Wrap native KAIA, perform the Trove action, and unwrap payouts. | | Borrow against HNKAIA | `HNKAIAZapper` | Transfer HNKAIA and perform the Trove action. | | Borrow against earnUSDT | `EarnUSDTZapper` | Receive earnUSDT, wrap it as wEarnUSDT collateral, and perform the Trove action. | | Change leverage | `LeverageWKAIAZapper`, `LeverageEarnUSDTZapper` | Borrow temporary liquidity, change collateral and USDHN debt, and settle the flash operation. | | Deposit and stake LP | `StableSwapZapper` | Add USDT and USDHN liquidity, then stake the new LP tokens. | | Unstake and withdraw LP | `StableSwapZapper` | Unstake LP tokens, burn them, and return both pool assets. | The mainnet app exposes KAIA and earnUSDT leverage. HNKAIA leverage is enabled in the testnet app, while mainnet HNKAIA borrowing uses standard Trove actions. ## Approvals and signatures ERC-20 approval gives a named contract permission to transfer a token from your wallet. Permit2 uses a signed authorization for that transfer. Review the token, amount, spender, and expiry shown by the wallet. If the token's allowance to Permit2 is insufficient, approve that allowance before the signature-based transfer. The app chooses the authorization method for the wallet connection and action. For StableSwap and LP flows, browser-wallet connections use Permit2 signatures and the app's mobile connection mode uses ERC-20 approvals. KAIA supplied as native collateral travels with the transaction value and needs no ERC-20 collateral approval. Two other permissions have distinct roles: * **Trove manager permission** lets a zapper perform the selected position action. The app requests the correct manager setting before an adjustment or collateral-funded close when the current setting does not match. * **RewardStaker operator permission** lets StableSwapZapper stake or unstake LP tokens on your behalf. Token approval alone does not grant this permission. ## Standard Trove actions A Trove holds collateral and USDHN debt for one collateral branch. Standard zappers support opening, adding or withdrawing collateral, borrowing or repaying USDHN, and closing. 1. Choose the position action and enter the collateral or USDHN amount. 2. Review the resulting collateral, debt, annual interest rate, upfront fee, and collateral ratio. 3. Complete the token authorization and manager permission requested by the app. 4. Confirm the Trove transaction. 5. Check the updated position and the tokens returned to your wallet. Opening requires the branch's collateral plus the KAIA gas-compensation deposit. For the KAIA branch, the transaction includes both the collateral amount and gas compensation; the zapper wraps them as required. For ERC-20 collateral branches, gas compensation is supplied separately as native KAIA. This deposit is separate from the network transaction fee, stays with the open Trove, and is returned on a successful owner close. Ordinary adjustments do not require a new opening deposit. Closing with wallet-held USDHN repays the full live debt, including accrued interest, and returns the collateral. The KAIA standard zapper unwraps WKAIA payouts to KAIA; the earnUSDT standard zapper unwraps wEarnUSDT to earnUSDT. ## Flash-assisted leverage A flash operation supplies temporary liquidity and settles it within the same transaction. The resulting Trove debt remains open after that transaction; the temporary flash obligation is fully settled. | Operation | Collateral change | USDHN debt change | | ------------------------- | ----------------------------------------------------- | ----------------------------------------------- | | Open or increase leverage | Add the requested collateral exposure. | Borrow the USDHN required for settlement. | | Decrease leverage | Use part of the position's collateral for settlement. | Repay USDHN with the temporary liquidity. | | Close using collateral | Use collateral to fund the full repayment. | Repay the entire live debt and close the Trove. | The routes differ by collateral and action: | Route | How it settles | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | KAIA | The configured WKAIA/USDT V3 pool supplies the temporary collateral or USDT. The USDHN/USDT StableSwap leg funds the corresponding settlement or debt repayment. | | earnUSDT open or increase | StableSwap sends USDT through an exact-output callback. SuperEarnRouter deposits it for earnUSDT, which is wrapped as wEarnUSDT and added to the Trove. Borrowed USDHN pays the StableSwap input. | | earnUSDT decrease or close | The configured earnUSDT/USDT V3 pool supplies USDT. StableSwap converts it to USDHN for repayment, and unwrapped earnUSDT collateral settles the V3 operation. | These are branch-configured routes; the user does not provide an arbitrary router or output token. During execution, the zapper hands the required Trove manager control to FlashSwapper and restores the prior managed state after settlement. Token balances that remain after settlement are returned to the configured receiver. The app uses the position owner's wallet as that receiver. ### Execution limits Opening and leverage adjustments pass a final debt cap, `maxDebt`. If execution would leave more debt than this cap, the transaction reverts. The contracts also check the collateral change, flash pool and token, configured StableSwap pool, flash-fee cap, and manager/receiver state. The collateral-funded close uses the current full debt and a separately configured close-fee cap. The app displays a `100%` slippage limit for this close flow, and its contract call carries no user-selected minimum received. The displayed net return is an estimate. Actual returned tokens depend on the executed settlement. A failed combined transaction reverts its collateral, debt, and internal token movements. A token approval, operator approval, or manager-setting transaction confirmed beforehand remains in force, and the failed transaction still consumes network gas. ## Returned tokens and gas compensation * Standard closing returns collateral after full USDHN repayment. * Collateral-funded closing uses the collateral needed to settle the flash operation and returns the remaining collateral and route tokens. The KAIA zapper converts its returned WKAIA to KAIA; the earnUSDT route returns remaining earnUSDT after unwrapping its collateral. * The gas-compensation deposit is released on closing and passed to the receiver through the branch's payout handling. * The LP zapper returns any excess token0, token1, or LP balance produced by the current operation, measured against its starting balances. These payouts follow the branch's token handling. A zapper does not offer conversion into any token a user chooses. ## Combined LP actions On `/earn/usdt`, **Deposit and stake** sends both pool assets to StableSwapZapper. It calls the router's add-liquidity operation, checks `minLiquidity`, and stakes the new LP tokens through RewardStaker. **Unstake and withdraw** releases the staked LP tokens, removes liquidity, checks each token's minimum amount, and sends USDT and USDHN to your wallet. Both combined actions check the deadline and the required RewardStaker operator permission. LP staking keeps exposure to the pool's assets. Trove automation keeps the branch's collateral-ratio and liquidation rules. For the app steps, see [Swap, bridge, and liquidity](/protocol/stableswap-dex.md) and [Leverage positions](/protocol/loops.md). [Borrowing and liquidation](/protocol/borrowing-and-liquidation.md) explains the resulting Trove debt and collateral ratio. --- # 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/protocol/zapper.md?ask=&goal= ``` `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.