# Smart Contracts

This page is a **developer-facing** map of the on-chain integration surface for Hann Finance: what contracts exist at a conceptual level, what you typically need to call/index, and how to source addresses and ABIs safely.

{% hint style="warning" %}
**No addresses here** — Contract addresses must be sourced from official deployment artifacts, on-chain registries (if exposed), or verified explorers linked from official channels.
{% endhint %}

## At a glance

* Treat addresses as **environment config** (mainnet/testnet) and keep them upgradable in your app settings.
* ABIs must match the deployed bytecode — do not assume “testnet ABI == mainnet ABI”.
* For many integrations, the **minimum** on-chain surfaces are: USDHN (ERC‑20), Trove ownership (NFT), and read access to Trove state + branch parameters.

## Core integration surfaces (conceptual)

| Surface                           | What it represents                                    | What integrators usually do                                        |
| --------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------ |
| **USDHN token**                   | The protocol’s USD‑pegged asset (ERC‑20)              | show balances, allow approvals, support swaps/transfers            |
| **OFT / bridge (USDHN / HNKAIA)** | Cross-chain transfer interface for supported networks | treat chain support as deployment config; avoid hardcoding         |
| **Trove ownership (NFT)**         | Position ownership and transfers (often ERC‑721)      | index `Transfer` events, show portfolio per owner                  |
| **TroveManager**                  | Per-branch trove accounting + status state machine    | read `getLatestTroveData`, show trove status, index `ITroveEvents` |
| **Borrower entrypoints**          | Open/adjust/close Troves; mint/repay USDHN            | build UI tx flows; simulate and show CR + liquidation price        |
| **Risk parameters**               | Branch-specific `MCR`, fees, rates, and limits        | read and display current parameters; avoid hardcoding constants    |
| **Liquidations**                  | Forced cleanup of unsafe Troves                       | index events; surface liquidation history and outcomes             |
| **Redemptions**                   | USDHN → collateral via protocol rules                 | index events; surface borrower impact + peg mechanics              |
| **Earn (Stability Pool)**         | USDHN deposits that absorb liquidations               | index deposits/withdraws; show collateral gains (if applicable)    |

{% hint style="info" %}
Names differ across implementations. Use official ABIs and verified explorers for the exact contract names and entrypoints in the deployed system.
{% endhint %}

## Automation / routing surfaces (when used)

If you integrate one-click flows, the automation layer typically adds:

* **Zappers**: bundle approvals, swaps, and Trove actions into one transaction (optionally with Permit2).
* **Stable routing**: an allowlisted StableSwap adapter/runner for stable‑to‑stable legs.
* **Leftovers handling**: balance snapshots + “refund dust” patterns to avoid trapping user tokens.

Common component names (reference implementation):

* `BaseZapper` / `GasCompZapper` and collateral-specific zappers
* `LeveragedGasCompZapper` + `FlashSwapper` for flash-assisted leverage routes
* StableSwap pools and DEX modules for swaps (stable leg + action leg)
  * (e.g., exact-out quoting + bounded execution)

{% hint style="info" %}
Treat names above as a mental model. Always confirm the exact deployed contracts and interfaces via official deployment artifacts and deployed ABIs.
{% endhint %}

## Indexing checklist (minimum viable)

For a simple wallet/dApp integration, you usually want at least:

1. **Ownership mapping**: Trove NFT `Transfer` events → owner ↔ troveId.
2. **Position state**: for each troveId, read or reconstruct:
   * collateral amount(s)
   * debt (USDHN) and any accrued fees/interest
   * current CR and liquidation price (derived from branch parameters)
3. **Protocol events** (optional but recommended):
   * liquidations (to show history and Earn impacts)
   * redemptions (to show borrower-side changes)
   * Earn deposits/withdrawals and collateral gains

{% hint style="warning" %}
**Event names vary** — Use the deployed ABIs (or verified explorers) to confirm the exact event signatures you should index.
{% endhint %}

## Next reads

* Architecture: [Technical Overview](https://hann-finance.gitbook.io/hann-finance/developers/technical-overview)
* Practical integration: [Integrator Guide](https://hann-finance.gitbook.io/hann-finance/developers/integrator-kit)
* Trove lifecycle + statuses: [Trove Manager (State Machine)](https://hann-finance.gitbook.io/hann-finance/developers/trove-manager)
* Security process: [Audits & Security](https://hann-finance.gitbook.io/hann-finance/security/audits-and-security)