Skip to main content

​
1. Architecture Overview

See How SuperEarn Works and Core components.

​
2. Deployed Contract Addresses

​
Kaia Contracts

ContractDescriptionAddress
SuperEarnRouterUnified router for user deposits/withdrawals0x7437892A3e2E658038758dD7CA638334C0c2006C
CooldownVaultManages withdrawal cooldown periods0x4E4654cE4Ca7ff0ba66a0A4a588A4bd55A6f9A33
OriginVaultCross-chain hub (ERC-7540‑like) that holds USDT earmarked for remote deployment0x3B37DB3AC2a58f2daBA1a7d66d023937d61Fc95b
StrategyOriginVaultSuper Vault strategy that routes capital into OriginVault0x3a04592462e16B85a4F3999a0255171a135BD920
OriginAdapterCross-chain adapter + bridge entry (Rhino + CCIP)0x8E53CdAa89381c203a074fB3388f65936358f200
BridgeDepositHandles bridge deposit transactions0x80cf92840cd12365c8a292967c30cc4040008eac
OriginAgentCross-chain message/bridge agent for Kaia side0xd8acFF2E2B8B1Cf052aca4Ba331743F73C569E68
OriginAccountantBridge accountant tracking assets in transit0x55CEd8F290256E165d3f50EDa0b60E261ec38f55
PriceConverterAsset price converter with Orakl oracle integration0xC090e88bDAA823B7C1dd8d9e24CbacB0f35f2675
RegistryVault and strategy registry0xea8e1872aDCE77eFBe5d6FE37b5C257Cc86eC786
Super VaultAggregation vault on Kaia (EarnUSDT token; underlying = CooldownVault shares)0x2e4e573D86c70688cD97D76bc5DDc1Bb265bF5D6
CrosschainKeeperManages crosschain asset lifecycle0x40FB0F9084828ADBc3dcd71840eA545BF243cD0F
LightKeeperPerforms strategy harvesting, CooldownVault repayment, and user claiming0x8c82B2feC291a43e41aA87669eaEf01F4efaA3B2

​
Ethereum Contracts

ContractDescriptionAddress
SuperEarnRouterRouter used by RemoteVault/keepers for remote Super Vault flows0xd8acFF2E2B8B1Cf052aca4Ba331743F73C569E68
BridgeDepositHandles bridge deposit transactions0xc8a0b9d1c394d052214d030a5ecb8641960802fe
RemoteVaultVault that receives and manages cross-chain assets from Kaia0x8c82B2feC291a43e41aA87669eaEf01F4efaA3B2
CooldownVaultRemote CooldownVault (USDC) backing the Ethereum Super Vault0x8E53CdAa89381c203a074fB3388f65936358f200
Super VaultRemote aggregation vault (underlying = Remote CooldownVault shares)0x9E3E70f4d09bcfe08F456C426EB90f7aA6F70dF2
MorphoStrategy (Core)Super Vault strategy targeting MetaMorpho Core0xe38e6Fa8E0A443e8E8d5Fb0EA30098861b054284
MorphoStrategy (Frontier)Super Vault strategy targeting MetaMorpho Frontier0x3a04592462e16B85a4F3999a0255171a135BD920
MorphoStrategy (Prime)Super Vault strategy targeting MetaMorpho Prime0x8D09EF609EfE8A35db51bC6F99573D33CDf1Feb6
AdapterCross-chain adapter + bridge entry (Rhino + CCIP)0xC090e88bDAA823B7C1dd8d9e24CbacB0f35f2675
AgentCross-chain message/bridge agent for Ethereum side0x4AFd6Ad5b924CD29513d1fb9b66728C4C5A1bd3e
AccountantBridge accountant tracking assets in transit0x40FB0F9084828ADBc3dcd71840eA545BF243cD0F
PriceConverterAsset price converter with oracle integration0x57B71db8c039aD34b28c289272EFa09b5A870c20
RegistryVault and strategy registry0x0Becde49394d537B240c0272A7C5fEfC932691fe
UniversalSwapRouterUnified DEX swap router0x519a0609762C3546b857d78F9B1A7D3d6731b324
SwapQuoterSwap price quotation provider0xc08a98433d66C7a903998fCe613C4ae47cf6190c
CrosschainKeeperManages crosschain asset lifecycle0x1D68a6CEFeD44101eD79a830e8a5ad5c0A52D8De
LightKeeperPerforms strategy harvesting, CooldownVault repayment, and user claiming0xd064f89A9A95EA86A706543449D0d97557fAF929
Integrator note: Treat addresses as constants in production, but keep them configurable for upgrades if needed.

​
3. Core Interfaces

This subsection lists only the parts of each interface that integrators typically need. Full ABIs are available from the protocol’s published JSON artifacts (ISuperEarnRouter, ICooldownVault, IVault) and standard OpenZeppelin ABIs.

​
3.1 ISuperEarnRouter (SuperEarnRouter)

Purpose Single entrypoint for deposits and redeems. Handles the full flow between USDT, CooldownVault, and Super Vault. All user/integrator writes must go through this router; CooldownVault deposits/redeems are restricted to protocol contracts. Claims are permissionless but typically executed by keepers. Key events 
event Deposited(
    address indexed sender,
    address indexed receiver,
    address indexed SuperVault,
    uint256 underlyingAmount,
    uint256 yShares
);

event Redeemed(
    address indexed sender,
    address indexed receiver,
    address indexed SuperVault,
    uint256 yShares,
    uint256 ySharesFilled,
    uint256 requestId,
    uint256 underlyingAmount
);
Key read function 
function registry() external view returns (address);
Returns the registry contract used to resolve / validate vaults. Deposit functions 
// Basic deposit: receiver = msg.sender
function deposit(
    address SuperVault,
    uint256 amount,
    uint256 minSharesOut
) external returns (uint256 yShares);

// Deposit for arbitrary receiver
function deposit(
    address SuperVault,
    uint256 amount,
    address receiver,
    uint256 minSharesOut
) external returns (uint256 yShares);

// Single‑tx deposit using EIP‑2612 permit on underlying token
function depositWithPermit(
    address SuperVault,
    uint256 amount,
    address receiver,
    uint256 minSharesOut,
    uint256 deadline,
    uint8 v,
    bytes32 r,
    bytes32 s
) external returns (uint256 yShares);
  • amount – USDT amount (6 decimals).
  • minSharesOut – minimal acceptable SuperVault shares (slippage protection).
  • receiver – address that receives SuperVault shares (optional overload).
Redeem / preview functions 
// Estimate yShares → underlying
function previewDeposit(address SuperVault, uint256 amount)
    external
    view
    returns (uint256 yShares);

function previewRedeem(address SuperVault, uint256 yShares)
    external
    view
    returns (uint256 assets);

function previewWithdraw(address SuperVault, uint256 assets)
    external
    view
    returns (uint256 ySharesNeeded);

// Initiate cooldown redemption
function redeem(
    address SuperVault,
    uint256 yShares,
    uint256 minAssetsOut
) external returns (uint256 requestId);

function redeem(
    address SuperVault,
    uint256 yShares,
    address receiver,
    uint256 minAssetsOut
) external returns (uint256 requestId);
  • previewRedeem returns the expected underlying after cooldown, given current share price.
  • previewWithdraw returns the Super Vault shares required for a target asset amount.
  • redeem burns SuperVault shares and creates a CooldownVault redeem request; the ID is returned as requestId and also emitted in Redeemed.
Vault discovery 
function endorsedVault(address token) external view returns (address SuperVault);
Returns the governance‑approved SuperVault for a given underlying token (e.g. USDT). Returns address(0) if no endorsed vault exists. Claim preview 
function previewClaim(address SuperVault, uint256 requestId)
    external
    view
    returns (bool isClaimable, uint256 maxAssetsOut);
Lets integrators check whether a cooldown request has matured and the maximum claimable amount given current CooldownVault liquidity. Notable custom errors (may appear in revert messages)
  • error InsufficientShares(uint256 shortfall); – actual yShares < minSharesOut.
  • error InsufficientAssets(uint256 shortfall); – redeem would return less than minAssetsOut.
  • error InvalidReceiver(); – zero receiver or other invalid receiver condition.
  • error InvalidPrice(); – sanity check on share price failed.
  • error Unauthorized(); – caller blocked when remoteVault gating is enabled.

​
3.2 ICooldownVault

Purpose A vault with cooldown‑based withdrawals and governance‑controlled risk parameters. It is the asset of the SuperVault and the place where redeem requests are tracked. Core structs 
struct RedeemRequest {
    address receiver;
    uint256 assets;
    uint256 cooldownRequestedTime;
    uint256 cooldownPeriod;
    bool claimed;
}

struct PredepositRequest {
    address strategy;
    uint256 shares;
    uint256 debtAssets;
    uint256 cooldownRequestedTime;
    uint256 cooldownPeriod;
    bool claimed;
}
other core (standard; not repeated here)
  • asset(), totalAssets() (shares and assets are 1:1 inside CooldownVault)
  • deposit, mint, withdraw, redeem (restricted to whitelisted protocol contracts)
  • previewDeposit, previewMint, previewWithdraw, previewRedeem (all 1:1)
Integrators usually rely on these via view calls and Super Vault pricing, not for direct user flows (those go through the router); do not call deposit / redeem directly. Claims are permissionless but are typically batched by protocol keepers. Cooldown & redeem‑queue helpers 
// Global cooldown parameter
function cooldownPeriod() external view returns (uint256);

// Detailed info for a given redeem request
function redeemRequests(uint256 requestId)
    external
    view
    returns (
        address receiver,
        uint256 assets,
        uint256 cooldownRequestedTime,
        uint256 cooldownPeriod,
        bool claimed
    );

// List of unclaimed redeem requests (global)
function getUnclaimedRedeemRequestIds()
    external
    view
    returns (uint256[] memory requestIds);

function getUnclaimedRedeemRequestIds(uint256 limit, uint256 skip)
    external
    view
    returns (uint256[] memory requestIds);
These functions let you:
  • Inspect cooldown status for a specific requestId.
  • Enumerate unclaimed requests for monitoring or backfill.
  • Track current liquidity via assetBalance() / idleBalance().
Claiming cooled‑down redemptions Implementation provides a claim(requestId, maxLossBps) function (name may vary slightly) that:
  • Transfers underlying assets to the receiver (anyone can call as long as maxLossBps is within the configured threshold, otherwise only the receiver).
  • Applies a maxLossBps bound (basis points of tolerated loss vs expected assets).
  • Emits a Claimed event on success.
Governance & safety controls (view / admin, not for normal user flows)
  • Two‑step governance transfer:
    • submitGovernanceTransfer(address newGovernance)
    • acceptGovernanceTransfer()
  • Two‑step cooldown update:
    • submitCooldownPeriod(uint256 newCooldownPeriod)
    • acceptCooldownPeriod()
  • Emergency & risk:
    • pause(), unpause()
    • setMaxLossThresholdBps(uint256) and maxLossThresholdBps()
    • recover() – emergency asset recovery to governance
Integrators don’t call these, but should be aware they exist (e.g. to monitor events and detect emergency states).

​
3.3 IVault (SuperVault / kSuperVault)

Purpose Vault that wraps the CooldownVault shares. Users hold SuperVault shares as their EarnUSDT position. Selected view functions 
// ERC20
function name() external view returns (string memory);
function symbol() external view returns (string memory);
function decimals() external view returns (uint256);
function totalSupply() external view returns (uint256);
function balanceOf(address) external view returns (uint256);

// Vault specifics
function token() external view returns (address);      // Underlying = CooldownVault
function totalAssets() external view returns (uint256);
function pricePerShare() external view returns (uint256);
Integrator usage:
  • Portfolio display: use balanceOf(user) on the Super Vault and multiply by pricePerShare() (scaled by 10 ** decimals()) to convert shares to underlying USDT notionals.
  • Price checks: totalAssets(), totalSupply(), and pricePerShare() to compute share value.
Governance / strategy functions IVault exposes a rich set of strategy and governance functions (setPerformanceFee, setDepositLimit, setEmergencyShutdown, strategies(...), etc.), but these are reserved for protocol governance and should not be called by integrators. They are useful for protocol‑level monitoring.

​
3.4 Strategies (IStrategyCooldownAware, StrategyERC7540, etc.)

Strategy interfaces define how CooldownVault interacts with external vaults (predeposit, redeem, claim, supply caps). They emit their own events (Preminted, PredepositDebtRepaid, AdjustPosition, …). Integrators do not need to call strategies directly. They are relevant only if you’re running protocol‑level analytics or risk monitoring.

​
4. Events to Monitor

Events are the primary way to track user‑level and system‑level changes from off‑chain services, indexers, and alerting systems.

​
4.1 SuperEarnRouter (ISuperEarnRouter)

From seprojectrouter-events.md: 
event Deposited(
    address indexed sender,
    address indexed receiver,
    address indexed SuperVault,
    uint256 underlyingAmount,
    uint256 yShares
);

event Redeemed(
    address indexed sender,
    address indexed receiver,
    address indexed SuperVault,
    uint256 yShares,
    uint256 ySharesFilled,
    uint256 requestId,
    uint256 underlyingAmount
);
Recommended usage:
  • Track deposits: listen to Deposited and index by sender/receiver.
  • Track redemption requests:
    • Redeemed.requestId → later join with CooldownVault’s redeem queue and Claimed events.
    • yShares / underlyingAmount for expected notional.

​
4.2 CooldownVault (ICooldownVault)

From cooldownvault-events.md: Core user‑facing events: 
event RedeemRequested(
    address indexed caller,
    address indexed receiver,
    uint256 indexed requestId,
    uint256 assets,
    uint256 shares,
    uint256 requestedTime
);

event Claimed(
    address indexed caller,
    uint256 indexed requestId,
    uint256 assets,
    uint256 claimable
);

event InstantRedemption(
    address indexed caller,
    uint256 shares,
    uint256 assets
);
Governance / system events (for monitoring only): 
event CooldownPeriodUpdated(uint256 newCooldownPeriod);
event CooldownPeriodSubmitted(uint256 newCooldownPeriod);

event GovernanceTransferred(address indexed previousGovernance, address indexed newGovernance);
event GovernanceTransferSubmitted(address indexed newGovernance);

event MaxLossThresholdUpdated(uint256 oldThreshold, uint256 newThreshold);
event Recovered(address indexed to, uint256 assets, uint256 shares);
event StrangeCooldownPeriod(uint256 maxCooldownPeriod, uint256 newCooldownPeriod);

// Strategy management
event StrategyAdded(address indexed strategy);
event StrategyRemoved(address indexed strategy);
event PredepositRequested(
    address indexed strategy,
    uint256 indexed predepositId,
    uint256 shares,
    uint256 debtAssets,
    uint256 cooldownPeriod
);
event DebtRetrieved(
    address indexed strategy,
    uint256 indexed predepositId,
    uint256 debtAssets,
    uint256 debtPayment
);
Recommended usage:
  • User‑level tracking:
    • RedeemRequested + Claimed to build a full view of pending and completed withdrawals per user.
  • Risk / governance monitoring:
    • CooldownPeriodUpdated, MaxLossThresholdUpdated, and Emergency‑style events to detect parameter changes.
Standard ERC‑20 events emitted by CooldownVault: 
event Transfer(address indexed from, address indexed to, uint256 value);
event Approval(address indexed owner, address indexed spender, uint256 value);

event Deposit(address indexed sender, address indexed owner, uint256 assets, uint256 shares);
event Withdraw(address indexed sender, address indexed receiver, address indexed owner, uint256 assets, uint256 shares);
These are useful if you want to reconstruct all share‑level movements at the CooldownVault layer.

​
4.3 SuperVault (IVault)

From vault-events.md: Vault‑level operations: 
event Deposit(address indexed recipient, uint256 shares, uint256 amount);
event Withdraw(address indexed recipient, uint256 shares, uint256 amount);
event Sweep(address indexed token, uint256 amount);
Strategy & governance events (aggregated behavior of all underlying strategies): 
event StrategyAdded(address indexed strategy, uint256 debtRatio, uint256 minDebtPerHarvest,
                    uint256 maxDebtPerHarvest, uint256 performanceFee);
event StrategyReported(address indexed strategy, uint256 gain, uint256 loss,
                       uint256 debtPaid, uint256 totalGain, uint256 totalLoss,
                       uint256 totalDebt, uint256 debtAdded, uint256 debtRatio);
event StrategyRevoked(address indexed strategy);
// ... plus FeeReport, StrategyUpdate*, EmergencyShutdown, UpdateDepositLimit, etc.
For most integrators:
  • User PnL / position tracking can be done directly from SuperVault share balances and price per share; you rarely need to decode strategy events.
  • Advanced analytics may ingest these strategy events to understand how the vault is allocating capital and generating yield.

​
5. ABI & Integration Checklist

For an EarnUSDT integrator, the minimum on‑chain surface you typically need is:
  1. ABIs
    • ISuperEarnRouter
    • IVault (SuperVault / kSuperVault)
    • ICooldownVault
    • Standard IERC20 / IERC20Permit (USDT, SuperVault, CooldownVault share token)
  2. Write functions you actually call
    • SuperEarnRouter.deposit(...) / depositWithPermit(...)
    • SuperEarnRouter.redeem(...)
    • (Claims on CooldownVault are permissionless but typically run by protocol keepers to bundle redemptions.)
  3. View functions you rely on
    • SuperEarnRouter.previewRedeem(...), previewDeposit(...)
    • SuperEarnRouter.endorsedVault(USDT)
    • IVault.balanceOf(user), IVault.pricePerShare()
    • ICooldownVault.redeemRequests(requestId) and getUnclaimedRedeemRequestIds(...) (for cooldown state)
  4. Events you index
    • SuperEarnRouter.Deposited / Redeemed
    • CooldownVault.RedeemRequested / Claimed / InstantRedemption
    • IVault.Deposit / Withdraw (optional, for deeper tracing)