Smart Contracts

Contract surface overview for integrators (no addresses) — what to call, what to index, and how to source deployment metadata safely

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.

No addresses here — Contract addresses must be sourced from official deployment artifacts, on-chain registries (if exposed), or verified explorers linked from official channels.

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)

Names differ across implementations. Use official ABIs and verified explorers for the exact contract names and entrypoints in the deployed system.

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)

Treat names above as a mental model. Always confirm the exact deployed contracts and interfaces via official deployment artifacts and deployed ABIs.

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

Event names vary — Use the deployed ABIs (or verified explorers) to confirm the exact event signatures you should index.

Next reads

• Architecture: Technical Overview

• Practical integration: Integrator Guide

• Trove lifecycle + statuses: Trove Manager (State Machine)

• Security process: Audits & Security