Skip to main content

​
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, a fungible ERC‑20 that represents 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:
    • Mints and burns EarnUSDT as the share token.
    • 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: The official SuperEarn subgraphs (vaults, positions, queues).

​
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 (ERC‑20 share token)
    • 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.
      • EarnUSDT shares are minted and burned (not directly callable by users on CooldownVault).
    • 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. Subgraphs (Read Path)

For reads, integrators are expected to use the official SuperEarn subgraphs, not any private backend or internal APIs. The subgraphs index on‑chain events from:
  • CooldownVault / Super Vault (Kaia)
  • OriginVault / RemoteVault and their queues
  • SuperEarnRouter deposit / redeem events
  • High‑level cross‑chain state (keeper executions, bridge events)
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 & performance tracking
    • Fetch per‑account EarnUSDT balances (EOAs or contracts).
    • Show total value in USD, cumulative earnings, and performance over time.
    • Display pending redemptions and their status (in cooldown, claimable, claimed).
  • Queue / redemption status
    • For each requestId, show:
      • requested shares / assets,
      • creation timestamp,
      • estimated unlock time,
      • claimed vs unclaimed status.
    • Use this to power “pending withdrawal” UIs without hammering contracts on every refresh.
This Core Components page only defines the role subgraphs play in the architecture; the detailed schema and query examples live in the dedicated Subgraphs developer documentation.

​
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.