Skip to content

Architecture Overview

1. System Architecture

King's Vault operates across three execution layers connected by Chainlink CCIP:

Ethereum Mainnet (L1)          CCIP Bridge           HyperEVM (L2)           HyperCore (L1)
┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐     ┌──────────────┐
│   KingsVault     │     │  Chainlink CCIP  │     │  HyperStrategy   │     │   HLP Pool   │
│  (ERC-4626/7540) │────>│  + Circle CCTP   │────>│  (CCIP Receiver) │────>│  (Yield Src) │
│                  │<────│  (USDC Burn/Mint)│<────│  (CCIP Sender)   │<────│              │
├──────────────────┤     └──────────────────┘     ├──────────────────┤     └──────────────┘
│   KPortfolio     │                              │  CoreWriter      │
│  (Fund Router)   │                              │  (0x333...333)   │
├──────────────────┤                              ├──────────────────┤
│  EarnPool:Aave   │                              │  L1Read          │
│  EarnPool:Morpho │                              │  (0x000...800+)  │
└──────────────────┘                              └──────────────────┘

Layer Responsibilities

Layer Role Contracts
Ethereum Mainnet User entry point, share accounting, PPS settlement, performance-fee collection. KingsVault, KPortfolio, AaveEarnPool, ERC4626EarnPool
CCIP / CCTP Cross-chain transport for USDC (burn-and-mint) and encoded instructions. Chainlink Router, OnRamp, OffRamp, Token Pool
HyperEVM Strategy-execution layer. Receives CCIP messages, interacts with HyperCore via system contracts. HyperStrategy (CCIP Receiver/Sender)
HyperCore Final yield destination. HLP liquidity pool and spot account. HLP Vault, Spot Ledger

2. Trust Model & Roles

This system is not fully trustless. It operates under a trusted-administrator model.

2.1 Trusted Actors

Role Trust Level Responsibilities Risk if Compromised
VaultOwner Critical Pause/unpause contracts, change fee rates, confirm settlement, initiate emergency liquidation (windingUp). Can lock funds, manipulate fee parameters, or rug via malicious upgrades.
Accountant High Trigger settle() to recalculate NAV and PPS. Can delay settlement (stale pricing) or manipulate fee-collection timing.
PoolManager High Whitelist/remove EarnPool adapters via enablePool/disablePool. Can whitelist a malicious contract that steals deposited funds.
Trader Medium Move funds between whitelisted pools via depositPool/withdrawPool. Cannot steal funds directly (restricted to whitelisted pools), but may make poor allocation decisions leading to losses.
Keeper / Bot Medium Trigger cross-chain settlement reports, monitor CCIP message status. Delayed or missed settlement triggers.

2.2 Untrusted Participants

  • Users (Depositors): Users do not need to be trusted by the system but must pass whitelist verification (KYC). Due to the manual settlement design, users cannot manipulate share pricing.

2.3 External Trust Assumptions

Dependency Trust Assumption
Chainlink DON Correctly relays cross-chain messages without censorship or forgery.
Circle (USDC / CCTP) USDC remains redeemable 1:1; CCTP burn-and-mint operates without interruption.
Hyperliquid Validators HyperCore state and HyperEVM execution are honest and available.
Aave V3 / Morpho Underlying protocol contracts are secure; balanceOf correctly reflects deposited value.

3. Design Decisions

3.1 Centralized Settlement

Aspect Detail
What PPS is not dynamically computed from real-time on-chain balances on every user interaction.
How PPS is fixed at the value determined by the most recent settle() call.
Impact Deposits and withdrawals execute at a stale PPS (from the last settlement). This prevents flash-loan price manipulation but relies on frequent Accountant updates for user fairness.

3.2 Inflationary Fee Model

Aspect Detail
What Performance fees are not deducted from underlying USDC. New shares are minted to the Manager (treasury) address.
Formula FeeShares = (PPS_current - PPS_HWM) * TotalSupply * feeRate / PPS_current
Impact Existing holders experience mild PPS dilution proportional to the fee.

3.3 Dual-Contract Architecture

Aspect Detail
What User interface (KingsVault) is separated from fund management (KPortfolio).
Why Enables upgrading strategy logic without migrating user positions. KingsVault only knows about KPortfolio; it never interacts with EarnPools directly.

3.4 Oracle-Free Valuation

Aspect Detail
What No Chainlink or external price oracles are used for NAV calculation.
How settle() queries underlying protocols (Aave balanceOf, Morpho balanceOf, HLP vaultEquity via precompile) for current balances.
Risk If an underlying protocol reports incorrect balances, the NAV will be wrong.

3.5 Asynchronous Redemption (ERC-7540)

Aspect Detail
What Withdrawals are non-instant due to cross-chain fund retrieval latency (~20-30 min).
How Users call requestRedeem() to lock shares and receive a requestId. A Keeper executes the request off-chain (cross-chain retrieval). Users then call redeem() to claim USDC.
States Pending → Executed → Claimed.

4. Asset Compatibility

Property Value
Supported Asset USDC (Circle-issued stablecoin)
Asset Decimals 6
Share Decimals 12 (6 asset + 6 virtual offset)
Virtual Offset 10^6 — inflates share precision to prevent first-depositor inflation attacks
Token Restrictions Standard ERC-20 only. No ERC-777 or tokens with transfer hooks (prevents reentrancy via callbacks).

5. Total Asset Calculation

The protocol's Total Value Locked (TVL) is the sum of all capital across all layers:

TotalAssets = Vault_Idle + Portfolio_Idle + Σ(EarnPool_i.balanceOf) + HyperCore_Equity + Pending_CCIP
Component Source
Vault_Idle USDC balance held in KingsVault contract on Ethereum
Portfolio_Idle USDC balance held in KPortfolio contract on Ethereum
EarnPool_i.balanceOf Value reported by each enabled Aave/Morpho EarnPool adapter
HyperCore_Equity HLP vault equity + spot balance, read via 0x800 precompile on HyperEVM
Pending_CCIP In-flight USDC in the CCIP bridge (tracking mechanism TBD)

6. Non-Functional Requirements

6.1 Security

  • Reentrancy Protection: All state-changing functions (withdraw, settle, depositPool, withdrawPool) must use reentrancy guards.
  • Access Control: Strict RBAC checks on all administrative functions.
  • Cross-Chain Validation: CCIP receiver must verify sourceChainSelector and senderAddress to accept only messages from authorized counterpart contracts.

6.2 Precision & Rounding

  • Calculations favor the vault (protocol) over the user:
    • Deposit: shares rounded down (user receives fewer shares).
    • Withdrawal: assets rounded down (user receives less USDC).
  • Particular care required for USDC 6-decimal to HyperCore 8-decimal conversions.

6.3 Gas Efficiency

  • settle() must bound iteration over active pools to prevent out-of-gas reverts.
  • Maximum number of active EarnPools should be capped.

6.4 Availability

  • If Aave, Morpho, or HLP pauses, the vault's liquidity-retrieval mechanism must revert gracefully with clear error messages rather than silently failing.
  • If CCIP is congested, requestRedeem should still be callable (the delay is in execution, not in request submission).