> 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/developers/smart-contracts.md).

# Smart contracts

Networks, contract addresses, public functions, events, and account state

Hann Finance contracts cover USDHN borrowing, lending markets, staking, and swaps. Use the contract address and ABI for the network and collateral you are integrating.

## Networks and addresses

| Network        | Chain ID |
| -------------- | -------- |
| Kaia mainnet   | `8217`   |
| Kairos testnet | `1001`   |

### Kaia mainnet

Hann Finance contracts are not deployed on Kaia mainnet, chain ID `8217`.

### Kairos testnet addresses

Network: **Kairos**, chain ID `1001`.

| Contract                | Address | Explorer link |
| ----------------------- | ------- | ------------- |
| USDHN token             | —       | —             |
| CollateralRegistry      | —       | —             |
| HNKAIA token and basket | —       | —             |
| Lending Pool            | —       | —             |
| KAIA Gateway            | —       | —             |
| bKAIA vault             | —       | —             |
| bKAIA token             | —       | —             |
| StableSwap Router       | —       | —             |
| USDHN–USDT pool         | —       | —             |

`—` marks an unfilled field. Record each address with a link to that contract's Kairos explorer page.

Use the ABI published with the contract's verified explorer entry. For a proxy, call the proxy address with its implementation ABI. Lending's reserve data identifies the underlying asset, aToken, and debt token; use those addresses for supply, withdrawal, borrowing, and repayment.

## CDP core

Each collateral branch has its own BorrowerOperations, TroveManager, TroveNFT, pools, and price feed. Select the branch for KAIA, HNKAIA, or earnUSDT through CollateralRegistry's token and Trove Manager references.

| Contract                       | Public interface and state                                                                                                                                          |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| USDHN token                    | Token balance, allowance, transfers, and permit: `balanceOf`, `allowance`, `approve`, `transfer`, `permit`                                                          |
| CollateralRegistry             | `collateralConfig`, `getToken`, `getTroveManager`, `isCollateralActive`, redemption fee getters, and `redeemCollateral`                                             |
| BorrowerOperations             | `openTrove`, `openTroveAndJoinInterestBatchManager`, `addColl`, `withdrawColl`, `withdrawUSDHN`, `repayUSDHN`, `adjustTrove`, `adjustZombieTrove`, and `closeTrove` |
| TroveManager                   | `getLatestTroveData`, `getTroveStatus`, `getCurrentICR`, `getLatestBatchData`, `batchLiquidateTroves`, and `urgentRedemption`                                       |
| TroveNFT                       | ERC-721 `ownerOf`, ownership transfers, and `Transfer` events                                                                                                       |
| SortedTroves                   | Interest-rate ordering and insertion hints                                                                                                                          |
| AddressesRegistry              | Branch contract references and configured parameters                                                                                                                |
| PriceFeed                      | Price fetching, last-good price, and oracle state                                                                                                                   |
| ActivePool / DefaultPool       | Active collateral and debt; redistributed collateral and debt                                                                                                       |
| CollSurplusPool / GasPool      | Claimable collateral surplus and liquidation gas compensation                                                                                                       |
| HintHelpers / MultiTroveGetter | Fee and insertion-hint calculations; batch position reads                                                                                                           |
| RedemptionHelper               | `simulateRedemption`, `truncateRedemption`, and redemption with per-branch minimum outputs                                                                          |

### Borrowing, interest, and redemption parameters

`BorrowerOperations.openTrove` takes the owner, owner index, collateral amount, requested USDHN amount, upper and lower hints, annual interest rate, maximum upfront fee, add manager, remove manager, and receiver. `openTroveAndJoinInterestBatchManager` replaces the individual interest-rate field with a batch manager in its parameter struct.

Interest control uses `adjustTroveInterestRate`, `setInterestIndividualDelegate`, `setInterestBatchManager`, `removeFromBatch`, and `switchBatchManager`. `addManagerOf` and `removeManagerReceiverOf` expose delegated operation and receiver settings. Read `MCR`, `CCR`, `SCR`, and `BCR` from the branch's BorrowerOperations.

Ordinary cross-branch redemption enters through `CollateralRegistry.redeemCollateral(usdhnAmount, maxIterationsPerCollateral, maxFeePercentage)`. The registry selects active, redeemable branches and burns the amount actually redeemed. An iteration limit of `0` means unlimited traversal, as used by the app; a bounded traversal can produce a partial redemption. TroveManager's five-argument `redeemCollateral` is called by the registry; shutdown redemption uses `urgentRedemption`.

`RedemptionHelper.redeemCollateral(usdhnAmount, maxIterationsPerCollateral, maxFeePercentage, minCollRedeemed)` adds minimum collateral outputs for each branch. This helper pulls USDHN with `transferFrom`, so its caller grants USDHN allowance to the helper. The minimum-output array follows the helper's branch order; unmet bounds revert the transaction, and remaining USDHN is refunded. `simulateRedemption` and `truncateRedemption` are non-view functions because price reads can update cached state; use RPC simulation to obtain their previews.

### Trove status and latest debt

| Value | Status                | Meaning                                                                              |
| ----- | --------------------- | ------------------------------------------------------------------------------------ |
| `0`   | `nonExistent`         | No position exists for the ID                                                        |
| `1`   | `active`              | Open position participating in normal operations                                     |
| `2`   | `closedByOwner`       | Position closed by its owner                                                         |
| `3`   | `closedByLiquidation` | Position closed through liquidation                                                  |
| `4`   | `zombie`              | Open position removed from normal sorted ordering; use its dedicated adjustment path |

`getLatestTroveData` returns `entireDebt`, `entireColl`, redistribution gains, accrued interest, recorded debt, annual interest rate, weighted recorded debt, accrued batch-management fee, and the last rate-adjustment time. `entireDebt` and `entireColl` are the position values used for current health calculations.

Index TroveManager's `TroveUpdated`, `TroveOperation`, `BatchedTroveUpdated`, `BatchUpdated`, `Liquidation`, `Redemption`, and `RedemptionFeePaidToTrove`. Couple them with the branch NFT's `Transfer` events to maintain ownership and position history.

## Earn: Stability Pool

Each branch's StabilityPool accepts USDHN deposits and distributes liquidation collateral and USDHN yield.

| Operation                    | Function                                                                            |
| ---------------------------- | ----------------------------------------------------------------------------------- |
| Deposit                      | `provideToSP(uint256 amount, bool doClaim)`                                         |
| Withdraw                     | `withdrawFromSP(uint256 amount, bool doClaim)`                                      |
| Claim accumulated collateral | `claimAllCollGains()`                                                               |
| Read remaining deposit       | `getCompoundedUSDHNDeposit(address depositor)`                                      |
| Read collateral and yield    | `getDepositorCollGain`, `getDepositorYieldGain`, `getDepositorYieldGainWithPending` |
| Read pool accounting         | `getTotalUSDHNDeposits`, `P`, `currentScale`, `scaleToS`, `scaleToB`                |

`deposits()` is the stored initial value; the compounded-deposit getter accounts for liquidation losses. `DepositUpdated` records the new deposit and accumulator snapshot. `DepositOperation` records the action, deposit loss, amount change, yield, and collateral gains. `P_Updated`, `S_Updated`, `B_Updated`, and `ScaleUpdated` expose accumulator changes. `offset` and `triggerUSDHNRewards` are protocol-controlled calls.

## Lending

The Lending Pool manages reserves, collateral settings, and account debt. Reserve configuration supplies the underlying asset, aToken, and variable debt token addresses.

| Action                    | Pool function                                                                                                        |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Supply                    | `supply(address asset, uint256 amount, address onBehalfOf, uint16 referralCode)`                                     |
| Withdraw                  | `withdraw(address asset, uint256 amount, address to)`                                                                |
| Borrow                    | `borrow(address asset, uint256 amount, uint256 interestRateMode, uint16 referralCode, address onBehalfOf)`           |
| Repay                     | `repay(address asset, uint256 amount, uint256 interestRateMode, address onBehalfOf)`                                 |
| Toggle collateral         | `setUserUseReserveAsCollateral(address asset, bool useAsCollateral)`                                                 |
| Select eMode              | `setUserEMode(uint8 categoryId)`                                                                                     |
| Account and reserve reads | `getUserAccountData`, `getUserConfiguration`, `getReserveData`, `getConfiguration`, `getReservesList`                |
| Liquidate                 | `liquidationCall(address collateralAsset, address debtAsset, address user, uint256 debtToCover, bool receiveAToken)` |

The app's borrow and repay paths use variable-rate mode `2`. Native KAIA operations use `WKaiaGateway.depositKAIA`, `withdrawKAIA`, `borrowKAIA`, and `repayKAIA`. Native withdrawals spend the account's aWKAIA allowance; native borrowing uses variable debt token delegation to the gateway.

Index `Supply`, `Withdraw`, `Borrow`, `Repay`, `LiquidationCall`, `ReserveDataUpdated`, `ReserveUsedAsCollateralEnabled`, `ReserveUsedAsCollateralDisabled`, and `UserEModeSet`. `PoolConfigurator` and `ACLManager` expose administrator-controlled reserve and role settings.

## Staking tokens and vault entrypoints

Deposit, withdrawal, claim, and view calls use the **bKAIA vault address** and its published ABI.

| bKAIA operation           | Entrypoint                                                                   |
| ------------------------- | ---------------------------------------------------------------------------- |
| Deposit native KAIA       | Payable `deposit(address receiver, uint256 minShares)`                       |
| Preview shares and assets | `previewDeposit`, `convertToShares`, `convertToAssets`                       |
| Request withdrawal        | `requestUnstakeByShares(uint256 shares)` or `requestUnstake(uint256 assets)` |
| Claim tickets             | `claim(uint256 ticketId)` and `claimMany(uint256[] ticketIds)`               |
| Resolve canceled request  | `settleCanceled(uint256 ticketId)`                                           |
| Read ticket               | `requests(uint256 ticketId)` and the vault view helpers                      |

`claimMany` returns `processed`, `totalPaid`, and `totalFee`. The events `Requested`, `RequestedBatch`, `TicketStatusUpdated`, `ClaimPayout`, `ClaimManySummary`, and `ClaimRetryQueued` describe ticket progress and payouts. A batch can succeed while leaving individual tickets pending.

HNKAIA exposes `supportedAssets`, `assets`, `previewDeposit`, `deposit`, `previewRedeemProRata`, `redeemProRata`, and per-asset redemption reads. Its share and underlying-asset amounts have different units; use the selected asset's decimals and the matching preview.

## StableSwap and Zappers

The USDHN–USDT pool holds reserves and accounts for LP shares, swap fees, and amplification. Read `getReserves`, `getDy`, `getDx`, `quoteAddLiquidity`, `quoteRemoveLiquidity`, and `getVirtualPrice`. Its `Swap`, `Mint`, and `Burn` events record trades and liquidity changes.

The router exposes `getAmountsOut`, `getAmountsIn`, `swapExactTokensForTokens`, `swapTokensForExactTokens`, `addLiquidity`, `removeLiquidity`, and their permit variants. Exact-input execution sets a minimum output; exact-output execution sets a maximum input. Parameter structs include the route, recipient, and deadline. StableSwap Lens adds detailed quotes, and RewardStaker accounts for staked LP balances and pending rewards.

Branch Zappers wrap assets and execute Trove operations. Leverage Zappers expose `openLeveragedTrove`, `leverUpTrove`, `leverDownTrove`, and `closeTroveByCollateral`. The first three enforce submitted `maxDebt`. The close struct contains `troveId` and `profitReceiver` and supplies no user minimum-output field. FlashSwapper callbacks accept the configured pool and active operation, settle the flash swap, and return route leftovers to the receiver.

For wallet calls, approvals, and event indexing, use the [Integrator Guide](https://docs.hann.finance/developers/integrator-kit.md). Contract and asset flows are covered in the [Technical Overview](https://docs.hann.finance/developers/technical-overview.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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hann.finance/developers/smart-contracts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
