Integrator Guide

Integration checklist and reference notes for wallets, dApps, and indexers integrating Hann Finance

This page is a practical checklist for integrating Hann Finance into a wallet, dApp, or backend service.

No addresses here — Contract addresses must be sourced from official address sources. Do not copy addresses from third parties.

At a glance

• Decide what you integrate: Trove UI, USDHN, Earn, StableSwap, or Zappers.

• Use a reliable source of truth for addresses (deployment files / registry).

• Indexing Troves usually requires tracking Trove ownership (NFT) and position state.

• If you integrate zapper-based leverage, account for DEX flash swaps and the manager/receiver state machine.

• For the full contract surface map (no addresses): Smart Contracts.

• For Trove lifecycle + statuses (including “zombie”): Trove Manager (State Machine).

What you can integrate

User-facing features

• Open/adjust/close Troves

• Mint/repay USDHN

• Deposit/withdraw Earn

• Swap / LP on StableSwap

• One-click flows via Zappers

Infra / analytics

• Index Trove ownership and health

• Track USDHN supply and peg indicators

• Monitor liquidation/redemption events

• Track StableSwap pool liquidity and swaps

Where to get contract addresses

Preferred sources (in order):

1. Official address bundle published by the team

2. On-chain registry contracts (if exposed)

3. Verified explorer pages linked from official channels

[TBD] Publish address bundle — Add links or a page that lists the canonical address sources for each chain.

Integration checklist

1

Step 1: Resolve addresses and ABIs

You need:

• core protocol contract addresses

• USDHN token address

• Earn / Stability Pool addresses (per collateral branch)

• StableSwap router/pool addresses (if you integrate swaps)

• Zapper addresses (if you integrate one-click)

ABIs must match deployed bytecode. Do not assume testnet ABIs are identical to mainnet.

2

Step 2: Pick your interaction surface

• Direct core calls: best for full control; more UI work.

• Zapper calls: best UX; more composability and routing considerations.

User doc reference: Zapper Guide

3

Step 3: Index the state you need

Common indexer needs:

• Trove creation and ownership changes (NFT transfers)

• Collateral and debt changes per Trove

• Liquidation and redemption events

• Earn deposit/withdraw events

4

Step 4: Add safety rails

• display CR and liquidation risk clearly

• default to conservative slippage and deadlines

• warn users about depegs, liquidations, and smart contract risks

Flash + swap components (conceptual)

If you integrate the automation stack, the key moving parts to understand are:

• Manager/receiver controls: leverage entrypoints typically require a strict manager state, then temporarily hand over inside flash callbacks, then restore.

• FlashSwapper: uses DEX flash swaps (callback-based) so leverage routes can source temporary liquidity and settle it within one transaction.

• StableSwap pools: stable-to-stable legs (USDHN and other stable assets).

• External DEX venues: spot swaps / wraps / un-wraps for non-stable steps (when configured).

• Leftovers sweep: snapshot-based refunds so user tokens aren’t trapped after execution.

Component and function names can differ by implementation. Rely on deployed ABIs for exact names.

Minimal example (TypeScript pseudocode)

// Pseudocode only. Replace with official addresses + ABIs.
const addresses = {
  usdhn: "0x...",       // [TBD]
  borrowerOps: "0x...", // [TBD]
  troveNft: "0x...",    // [TBD]
};

async function getUsdhnBalance(user: string) {
  const usdhn = new ethers.Contract(addresses.usdhn, USDHN_ABI, provider);
  return await usdhn.balanceOf(user);
}

[TBD] ABI and schema package — Publish a stable ABI package or a versioned JSON schema so integrators can pin to a release.

Next reads

• Architecture: Technical Overview

• Risk framing: Risk Disclosure