> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superearn.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Core components

> High-level architecture and integration surface for SuperEarn

## 1. Architecture at a Glance

SuperEarn is a Kaia‑native stablecoin portfolio that fans out into Kaia DeFi strategies and remote strategies (e.g. on Ethereum), then collapses everything back into a single yield‑bearing token: **EarnUSDT** on Kaia.

From an integrator’s point of view:

* All user deposits and withdrawals happen on **Kaia**.
* Users and protocols hold **EarnUSDT** shares that represent a share of the global portfolio.
* Cross‑chain routing, bridging, and reconciliation are handled internally by **Runespear**, SuperEarn’s CCIP‑based cross‑chain layer.

The system is designed as an **eventually consistent cross‑chain vault**: vaults on each chain are pure local state machines; Runespear keeps multi‑chain accounting conservative and self‑correcting over time.

***

## 1.1 Kaia (Origin Chain)

On Kaia, the on‑chain system is structured in three main layers:

### CooldownVault (user entry / exit pool)

* Users (or integrating protocols) deposit Kaia **USDT** **via the SuperEarnRouter**; the **CooldownVault** itself does **not** expose user‑facing deposit or withdrawal entrypoints.
* The CooldownVault:

  * Wraps USDT into intermediate shares used by the router and Super Vault flow.
  * Enforces short withdrawal waiting periods and loss limits.
  * Acts as a liquidity buffer for slower or delayed‑liquidity strategies (e.g. RWA).

### Super Vault (Kaia aggregation vault)

* When enough liquidity accumulates, the CooldownVault forwards capital into the **Super Vault** on Kaia.
* The Super Vault:

  * Aggregates funds from the CooldownVault.
  * Allocates capital between:

    * Kaia‑native strategies (RWA, lending, etc.).
    * The cross‑chain slice of the portfolio.
  * Keeps the Kaia‑side allocation aligned with portfolio policy and risk constraints.

Conceptually, EarnUSDT is a share of this aggregated Super Vault portfolio.

### OriginVault (Kaia cross‑chain hub, ERC‑7540‑like)

* For the multichain slice, the Super Vault deposits into **OriginVault**, an ERC‑7540‑like asynchronous vault on Kaia (async redemption flow, not a strict ERC‑7540 implementation).
* OriginVault:

  * Holds USDT that is earmarked for remote chains.
  * Manages async deposit / redemption requests for the cross‑chain part of the portfolio.
  * Maintains queued cross‑chain deposits and withdrawals.
  * Speaks only to the Runespear messaging layer (via MessageAgent + Adapter), never directly to bridges.

As an integrator, you normally do **not** interact with OriginVault directly. Your surface is **USDT ↔ EarnUSDT** via the router and the Cooldown / Super Vault stack on Kaia.

***

## 1.2 Remote Chains (e.g. Ethereum)

On each remote chain, SuperEarn exposes a single aggregation vault:

### RemoteVault

* A **RemoteVault** receives bridged stablecoins (USDT/USDC) from Kaia.
* RemoteVault:

  * Keeps a small idle buffer for redemptions.
  * Deploys the rest into whitelisted remote strategies (e.g. lending markets, liquidity vaults, RWA vaults) via a local router.
  * Tracks any **unfulfilled withdrawal amount** when remote strategies have their own cooldowns.
  * Reports back its state (totalAssets, idleAssets, unfulfilled withdrawals, timestamps) through Runespear so that OriginVault and the Super Vault can compute global `totalAssets()` conservatively.

Economically, yield generated remotely is reflected in the EarnUSDT share price on Kaia.

***

## 1.3 Cross‑Chain Coordination: Runespear

**Runespear** is SuperEarn’s cross‑chain “air‑traffic control”, built on Chainlink CCIP plus a bridge provider for the actual asset rail.

Conceptually, the cross‑chain stack has four layers:

1. **Vaults (OriginVault, RemoteVault)** – business logic
2. **MessageAgent (SuperEarnMessageAgent)** – routing logic
3. **CrosschainAdapter** – infrastructure & bridge accounting
4. **Runespear / CCIP + Bridge** – transport (messages + tokens)

Key ideas:

* **Vaults are per‑chain state machines**

  * No direct cross‑chain calls.
  * Only handle local accounting and queues.

* **MessageAgent (SuperEarnMessageAgent)**

  * Encodes/decodes business payloads.
  * Routes commands between vaults and adapters.
  * Can be swapped or upgraded without touching vaults.

* **CrosschainAdapter + BridgeAccountant**

  * Handles all CCIP + bridge operations.
  * Tracks nonces, assets in transit, and overlap between “message path” and “bridge path”.
  * Implements **universal state piggybacking**: every CCIP message carries a full StateSnapshot (vault + bridge state) captured at the same timestamp, so double‑counting is avoided and accounting converges automatically.

* **Runespear / CCIP + Bridge**

  * External transport layer.
  * The protocol is designed so that messages and bridge transfers can arrive in any order; the adapter logic and snapshots keep `totalAssets()` correct over time.

***

## 2. Smart Contracts (Integration Surface)

From a protocol‑integration perspective, you primarily touch two things:

* **Write path:** SuperEarn contracts on Kaia (USDT ↔ EarnUSDT).
* **Read path:** SuperEarn’s public backend data API and dashboard surfaces, powered by indexed on-chain and off-chain processing.

### 2.1 User‑Facing Layer on Kaia

These are the contracts your app or wrapper normally talks to:

* **USDT (Kaia)**
  Base ERC‑20 stablecoin used as the underlying asset.

* **EarnUSDT shares**

  * Yield‑bearing token representing a pro‑rata claim on the Super Vault portfolio.
  * Price‑per‑share model: balances stay constant; redemption value per share increases as yield accrues.

* **SuperEarnRouter**
  Convenience contract for deposits and redemptions:

  * `deposit(superVault, amount, minSharesOut)` — USDT → EarnUSDT
  * `previewDeposit(superVault, amount)` — estimate shares
  * `previewRedeem(superVault, shares)` — estimate USDT
  * `redeem(superVault, shares, receiver, minAssetsOut)` — start a redemption (queue‑based)

The router manages the internal flow through **CooldownVault → Super Vault** so you don’t have to orchestrate those hops.

> For all user‑facing flows, **every deposit / redeem must go through `SuperEarnRouter`** with Kaia USDT and the EarnUSDT Super Vault address; **CooldownVault does not accept direct user deposits or withdrawals.**

***

### 2.2 Aggregation Vaults on Kaia

You rarely call these directly, but they explain how EarnUSDT actually works under the hood:

* **CooldownVault**

  * Entry/exit pool (router‑only) where:

    * User USDT deposits first arrive via `SuperEarnRouter`.
    * USDT is wrapped into CooldownVault shares before the router completes the Super Vault share flow.
  * Enforces withdrawal cooldowns and max‑loss thresholds.
  * Acts as a buffer for connecting to slower or delayed‑liquidity strategies (especially RWA).

* **Super Vault (Kaia aggregation vault)**

  * Receives capital from the CooldownVault.
  * Allocates across:

    * Kaia‑native DeFi strategies.
    * OriginVault for multichain exposure.
  * Think of it as “the portfolio brain on Kaia”; EarnUSDT is a share of this aggregated portfolio.

***

### 2.3 Cross‑Chain Vaults (Origin / Remote)

These are behind the scenes of the EarnUSDT portfolio:

* **OriginVault (Kaia, ERC‑7540‑like)**

  * Cross‑chain hub that:

    * Holds Kaia‑side USDT allocated to remote strategies.
    * Implements asynchronous redemptions (request → fulfill → claim).
    * Only talks to the Runespear messaging stack (via MessageAgent + Adapter).

* **RemoteVault (e.g. Ethereum)**

  * Receives bridged assets from OriginVault.
  * Invests into remote strategies through a local router (lending markets, liquidity vaults, RWA, etc.).
  * Reports `totalAssets`, `idleAssets`, and pending withdrawal amounts back to OriginVault via state snapshots.

Integrators on Kaia typically never call these directly. They matter only in how they drive the EarnUSDT share price and multi‑chain yield behavior.

***

### 2.4 Runespear & Messaging Layer (Internal)

These components live under `v2/messaging` and `v2/core/crosschain` in the core repo and are **not** part of the public integration surface, but you’ll see them in logs, runbooks, and audits:

* **SuperEarnMessageAgent** — routing layer between vaults and adapter.
* **CrosschainAdapter** — handles CCIP messages, bridge calls, and state snapshots.
* **BridgeAccountant / BridgeQueue** — tracks nonces, assets in transit, and reconciles overlap.
* **RunespearProtocol / RunespearSender / RunespearReceiver / RunespearTransceiver** — encode/decode envelopes, store snapshots, manage retries.

They exist so that:

* `totalAssets()` on vaults stays `view`, deterministic, and composable, even when CCIP or the bridge is delayed.
* Asset accounting is conservative and eventually exact, without “stop‑the‑world” behavior when something goes wrong.

***

## 3. Read Layer

For reads, integrators should use SuperEarn’s supported read surfaces rather than scraping raw contract state.

Today that generally means:

* the public docs and dashboard for human-readable protocol information
* the supported backend data APIs and processed views used by product surfaces
* indexed on-chain data behind those APIs

Typical use cases:

* **Vault discovery**

  * List available SuperEarn vaults (e.g. the EarnUSDT Super Vault).
  * Show APY, TVL, allocation breakdown, and high-level risk labels.

* **Position and performance tracking**

  * Fetch per-account EarnUSDT balances for EOAs or integration contracts.
  * Show total value, cumulative earnings, and performance over time.
  * Display pending redemptions and their status.

* **Queue and redemption status**

  * For each `requestId`, show requested shares or assets, creation time, estimated unlock time, and claim status.

The exact public API surface evolves faster than the high-level protocol architecture. Keep endpoint-specific examples in the dedicated developer integration docs.

***

## 4. Keeper & Queue Model (High‑Level)

SuperEarn uses a **queue‑based model plus automation (keepers)** so that user flows stay simple while the protocol coordinates slower liquidity and cross‑chain operations safely.

Very high‑level:

### On Deposit

* `USDT → EarnUSDT` is usually instant, subject to on‑chain confirmation.
* Capital may sit briefly in the CooldownVault before being swept into the Super Vault and onward to strategies.

### On Withdrawal

* `redeem()` on the router creates a redemption request against the CooldownVault / Super Vault and returns a `requestId`.
* That request enters a cooldown queue:

  * User’s shares are burned.
  * The user receives a claim on USDT after the cooldown and any remote withdrawals/bridging are settled.

### Keepers

* **LightKeeper**

  * Batches local `claim()`, `retrieveDebt()`, and similar operations once cooldowns have expired.

* **CrosschainKeeper (per chain)**

  * Runs heavier tasks:

    * Moving liquidity between OriginVault and RemoteVault.
    * Triggering deposits/withdrawals into remote strategies.
    * Sending periodic `SYNC_NOOP` messages via Runespear to keep snapshots fresh.

For integrators:

* You do **not** need to run your own keeper to use EarnUSDT.
* Just:

  * Call `deposit` / `redeem` via the router on Kaia.
  * Use the subgraph to display:

    * current EarnUSDT balance,
    * pending withdrawals (queue entries),
    * when a withdrawal becomes claimable or completed.

The keeper + queue system is an internal automation layer that keeps SuperEarn liquid and consistent across chains, while preserving a simple, single‑chain integration surface on Kaia.