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

# Technical overview

How lending, USDHN, staking, and swaps connect to the wallet and product API

Hann Finance combines lending markets, collateral-backed USDHN borrowing, liquid staking, and swaps. Each product has its own accounting contracts. The app reads product data through the API and sends transactions from the user's wallet to the selected contract.

## Product and transaction paths

### Product data

```mermaid
flowchart TB
  APP[Hann Finance app] -->|Read product data| API[Product API]
  INDEX[Indexer and scanner] --> API
```

### Wallet transactions

The app requests a wallet signature. The wallet submits the transaction to the selected product's Lending Pool, CDP Zapper, bKAIA or HNKAIA vault, or StableSwap Router. CDP Zappers coordinate the borrowing and swap calls below.

```mermaid
flowchart TB
  APP[Hann Finance app] -->|Request signature| WALLET[User wallet]
  WALLET --> ZAP[CDP Zappers]
  ZAP --> CDP[BorrowerOperations<br/>and TroveManager]
  ZAP --> FLASH[FlashSwapper<br/>and swap pools]
  CDP --> USDHN[USDHN and<br/>Stability Pools]
```

The API supplies balances, positions, quotes, history, and transaction progress. Contracts enforce ownership, asset transfers, debt changes, and execution limits. A wallet receipt records the transaction result; the indexer then updates the product's account history and positions.

| Product         | Accounting owner                                                              | User result                                                                     |
| --------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Lending         | `lending-core.Pool`, reserve aTokens, and debt tokens                         | Supply assets, borrow from market liquidity, repay, and withdraw                |
| USDHN borrowing | A separate `BorrowerOperations` and `TroveManager` for each collateral branch | Lock collateral in a Trove and mint USDHN debt                                  |
| Earn            | Each branch's `StabilityPool`                                                 | Deposit USDHN; receive USDHN yield and collateral from liquidations             |
| bKAIA staking   | `bkaia.LSTVault` and `bkaia.LSTToken`                                         | Deposit KAIA for bKAIA shares; request withdrawals and claim ready tickets      |
| HNKAIA          | `core.HNKAIA` and asset vaults                                                | Deposit supported staking assets for HNKAIA shares and redeem underlying assets |
| Swap and LP     | StableSwap pool, router, LP token, and `RewardStaker`                         | Exchange USDT and USDHN, supply liquidity, and stake LP tokens                  |

## USDHN collateral branches

The generated CDP interface contains three branches: `WKAIA`, `HNKAIA`, and `EARNUSDT`. The app displays the WKAIA branch as KAIA; its Zapper wraps native KAIA before supplying collateral. The EARNUSDT branch holds wrapped earnUSDT collateral.

Each branch contains:

* `BorrowerOperations`, which opens, adjusts, and closes Troves and changes their interest-rate settings.
* `TroveManager`, which calculates current debt and collateral, handles liquidations and redemptions, and records Trove status.
* `TroveNFT`, which identifies the owner of each position, and `SortedTroves`, which orders positions by interest rate.
* `ActivePool`, `DefaultPool`, `CollSurplusPool`, and `GasPool`, which hold collateral and account for active debt, redistribution, surplus collateral, and gas compensation.
* `StabilityPool`, which burns deposited USDHN to offset liquidation debt and receives collateral.
* `PriceFeed` and `AddressesRegistry`, which supply the branch's price and contract configuration.

The shared `CollateralRegistry` routes USDHN redemptions across active, redeemable branches. `HintHelpers` supplies insertion hints; `RedemptionHelper` supplies redemption calculations. A Trove's latest debt includes pending interest, redistribution, and batch-management fees. Read `getLatestTroveData()` for current position values rather than treating its recorded debt as the full amount owed.

### Position health

For an open CDP position with debt, collateral ratio is collateral's USD value divided by the Trove's entire USDHN debt. The contract uses `1e18` units for collateral, debt, price, and the resulting ratio:

```
ICR18 = entireColl × price18 / entireDebt
```

The branch enforces its `MCR`, `CCR`, `SCR`, and batch-related limits. Lending uses the account's health factor, calculated from enabled collateral, applicable liquidation thresholds, and total debt. `Pool.getUserAccountData()` returns that health factor at `1e18` precision. These two products have separate liquidation rules.

## Zappers and flash execution

A Zapper collects the user's approved tokens or native KAIA, executes its configured route, and returns route leftovers to the receiver. Permit2 entrypoints use a signature alongside the token's allowance to Permit2; ordinary allowance paths remain separate.

| Contract                 | Operation                                                                    |
| ------------------------ | ---------------------------------------------------------------------------- |
| `BaseZapper`             | Registry access, token transfers, Permit2 handling, and administrator checks |
| `GasCompZapper`          | Trove operations with gas-compensation handling and pause controls           |
| `WKAIAZapper`            | Native KAIA and WKAIA collateral operations                                  |
| `HNKAIAZapper`           | HNKAIA collateral operations                                                 |
| `EarnUSDTZapper`         | earnUSDT wrapping and wrapped-collateral operations                          |
| `LeveragedGasCompZapper` | Open, increase, reduce, or close a flash-assisted position                   |
| `FlashSwapper`           | DEX flash-swap callback, StableSwap execution, and in-transaction settlement |
| `StableSwapZapper`       | Liquidity operations and LP staking                                          |

Flash-assisted execution hands Trove management to the authorized FlashSwapper for the callback and restores the management state afterward. The managed state includes the add manager, remove manager, and receiver. Callback authorization, expected-token checks, configured flash-fee caps, and final-debt checks bind the route to the submitted operation. Balance snapshots separate route leftovers from balances that were already present.

`openLeveragedTrove`, `leverUpTrove`, and `leverDownTrove` take `maxDebt`, the maximum final entire debt. `closeTroveByCollateral` sells collateral to repay the entire debt and returns remaining stable tokens; its parameter struct contains `troveId` and `profitReceiver`, with no user-supplied minimum-output field. Use each entrypoint's actual limits when preparing a transaction.

## Staking, swaps, and cross-chain transfers

bKAIA's vault routes calls through entry modules. The wallet calls the **vault address** using the ABI for the selected deposit, withdrawal, claim, or view entrypoint. Withdrawal requests create tickets; `claimMany` can process a subset of the submitted tickets. The receipt's ticket results determine which claims succeeded.

StableSwap provides exact-input and exact-output quotes, liquidity quotes, execution deadlines, minimum outputs, and maximum inputs. The router validates its pools, token allowlist, and recipients. The pool accounts for reserves and fees; LP staking and rewards belong to `RewardStaker`.

The current `USDHNToken` implements ERC-20 and permit. `USDHNOFTAdapter` locks and unlocks the canonical token for LayerZero transfers; `USDHNOFT` mints and burns the remote-chain token. The app's Bridge flow uses the product Bridge API to quote Rhino routes from supported USDT or USDC source assets into Kaia USDT. That product route has a separate execution instruction and source transaction.

## Data and deployment boundaries

The indexer owns event-complete account histories and projections. The scanner supplies current prices, readiness, and risk values. Jobs produce scheduled calculations; keepers submit their configured protocol operations. Transaction-critical reads covered by `contractViewLive` can use `HannFrontendView` during an API outage. History and transaction acknowledgements retain their API-backed paths.

Addresses and ABIs come from `artifacts/contracts/<profile>` or `GET /api/v1/contracts/snapshot`. `kaia-prod` and `kaia-qa` use chain `8217`; `kairos-dev` uses chain `1001`. The profile is part of the contract identity. A token symbol alone does not identify a contract across Lending, CDP, and staking.

The [Smart Contracts reference](/developers/smart-contracts.md) lists contract IDs, calls, events, and production-profile addresses. The [Integrator Guide](/developers/integrator-kit.md) connects those interfaces to wallet transactions and indexing. Trove status transitions are described in [Trove Manager](/developers/trove-manager.md), and route behavior in [Zapper](/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/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.