# Technical Overview

This page gives developers a map of the system: **CDP core**, **StableSwap routing**, and the **Zapper automation stack**.

{% hint style="warning" %}
This document is a technical overview. It does not include contract addresses. Addresses must be sourced from official deployments.
{% endhint %}

## At a glance

* CDP core: Troves, USDHN minting/repayment, liquidation, redemptions, and Earn (Stability Pool).
* Automation: Zappers bundle multi-step flows; routes can include swaps, wraps, and Trove actions.
* Leverage flows can use a **FlashSwapper** that relies on DEX flash swaps (callback-based, in-tx settlement).
* Zapper safety relies heavily on the **manager/receiver state machine** plus strict “budget” checks (fee caps, final debt/collateral bounds, unexpected-token guards).
* This page describes components by **role**. Use deployed ABIs for exact contract names and entrypoints.

## System map (conceptual)

{% @mermaid/diagram content="flowchart TB
UI\[Front-end / Integrator] --> Z\[Zappers]
UI --> CORE\[CDP core contracts]

Z --> CORE
Z --> FS\[FlashSwapper]
Z --> POOL\[StableSwap pools]
Z --> DEX\[External DEX pools / routers]

CORE --> USDHN\[USDHN token - OFT]
CORE --> SP\[Earn: Stability Pool]
CORE --> REG\[CollateralRegistry + price feeds]

style UI fill:#B0BBF4,color:#333,stroke:#4C5FD5,stroke-width:2px
style Z fill:#4C5FD5,color:#fff,stroke:#3A49C5,stroke-width:2px
style CORE fill:#EEFBA0,color:#333,stroke:#D1F24A,stroke-width:2px
style POOL fill:#D1F24A,color:#333,stroke:#B8DA2C,stroke-width:2px
style USDHN fill:#EEFBA0,color:#333,stroke:#D1F24A,stroke-width:2px
style SP fill:#D1F24A,color:#333,stroke:#B8DA2C,stroke-width:2px
style DEX fill:#EEFBA0,color:#333,stroke:#D1F24A,stroke-width:2px
style FS fill:#3A49C5,color:#fff,stroke:#4C5FD5,stroke-width:2px
style REG fill:#EEFBA0,color:#333,stroke:#D1F24A,stroke-width:2px" %}

## CDP core (high level)

The CDP core implements the user-facing primitives:

* **Trove positions** (open/adjust/close)
* **USDHN** minting and repayment
* **Liquidations** and **Earn (Stability Pool)**
* **Redemptions** as a peg-defense mechanism

{% hint style="warning" %}
**\[TBD] Full contract map for core** — Publish a complete CDP core contract map (contracts, roles, events, and ABIs) once finalized.
{% endhint %}

## Zappers and routing (components)

Zappers follow a common pattern:

1. pull tokens from the user (optionally using Permit2)
2. execute a route (swaps/wraps/Trove actions)
3. refund leftovers to the receiver

### Main Zapper contracts

| Contract                 | Role                                                                                         |
| ------------------------ | -------------------------------------------------------------------------------------------- |
| `BaseZapper`             | Shared base: registry access, token handling utilities, admin checks                         |
| `GasCompZapper`          | Base for collateral-specific zappers; includes pausing and gas-comp patterns                 |
| `LeveragedGasCompZapper` | Flash-assisted leverage / deleverage wrapper around GasComp flows                            |
| `HNKAIAZapper`           | HNKAIA collateral branch zapper (and leveraged variant)                                      |
| `WKAIAZapper`            | WKAIA / KAIA collateral branch zapper (and leveraged variant)                                |
| `EarnUSDTZapper`         | Zapper for a yield-bearing USDT receipt token (SuperEarn integration)                        |
| `StableSwapZapper`       | Adds/removes StableSwap liquidity and can stake LP on behalf of users                        |
| `FlashSwapper`           | Executes DEX flash swaps and settles within a single transaction (used by leveraged zappers) |

### Swap + flash building blocks (conceptual)

Implementations differ, but the common building blocks are:

* **StableSwap leg:** stable-to-stable swaps in a known StableSwap pool.
* **DEX action leg:** swaps / wraps / un-wraps for non-stable steps (when configured).
* **FlashSwapper:** uses DEX flash swaps (callback-based) to temporarily source liquidity for leverage routes.
* **Quoting and bounds:** routes enforce input/output bounds and fee caps so the tx reverts if execution is worse than expected.
* **Leftovers sweep:** snapshot-based refunds so user tokens aren’t trapped in the zapper after execution.

## Security controls (selected)

* **Manager/receiver state machine:** leverage entrypoints require a strict manager state, then temporarily hand over to the FlashSwapper inside the flash callback, then restore.
* **Fee caps and final-state bounds:** leverage routes can enforce caps (e.g., flash fee caps, max final debt, min final collateral) to prevent overshoot.
* **Unexpected-token guards:** routes can revert if an intermediate step yields a token that is not expected.
* **Refund leftovers pattern:** routes snapshot balances and return dust/leftovers to the receiver (reduces trapped tokens).

For reporting issues, see: [Audits & Security](https://hann-finance.gitbook.io/hann-finance/security/audits-and-security).

## Next reads

* Integration checklist: [Integrator Guide](https://hann-finance.gitbook.io/hann-finance/developers/integrator-kit)
* Core status state machine: [Trove Manager (State Machine)](https://hann-finance.gitbook.io/hann-finance/developers/trove-manager)
* One-click UX: [Zapper Guide](https://hann-finance.gitbook.io/hann-finance/protocol/zapper)
* Risk summary: [Risk Disclosure](https://hann-finance.gitbook.io/hann-finance/risks/risk-disclosure)