Skip to content

Introduction

1. Executive Summary

King's Vault is a permissioned DeFi gateway that provides whitelisted (KYC-verified) users with a simplified interface to directly deploy their Stablecoin into on-chain protocols. With additional products and integrations under development, the protocol currently operates across two networks:

  • Ethereum Mainnet — the user-facing accounting hub, hosting the KingsVaultV2 / KingsVaultV2Async vaults and the Controller coordinator contract.
  • HyperEVM (Hyperliquid L2) — the cross-chain strategy execution layer, where capital is deployed into Hyperliquid's HLP liquidity pool via HyperCoreAllocator and HyperCoreRouter.

Unlike fully automated vaults, King's Vault employs a two-phase NAV settlement model with active strategy management. Capital is dispatched through the Controller contract to registered Strategy adapters by an authorized Keeper role. Net Asset Value (NAV) is updated through a commit-and-confirm on-chain workflow rather than in real time, preventing flash-loan manipulation.

2. Architecture Layers

Layer 1 — Vault (User Entry Points)

The vault layer accepts investor deposits and manages share issuance using a dual-pricing model.

Component Description
KingsVaultV2 ERC-4626 vault with synchronous deposits and withdrawals. Triggers a liquidity waterfall from strategies when idle cash is insufficient.
KingsVaultV2Async Asynchronous withdrawal variant. Shares are escrowed on withdraw(); a Keeper executes the batch, then investors claim() their assets.

Layer 2 — Controller (System Coordinator)

The Controller is a UUPS-upgradeable proxy contract acting as the central coordinator for all vaults. It manages role-based access control, strategy registration, NAV settlement, and performance fee collection.

Component Description
Controller UUPS-upgradeable proxy. Manages RBAC, vault registry, NAV epochs (proposeValues / confirmValues), performance fee minting, fund invest/divest, and emergency procedures.

Layer 3 — Strategies (Yield Adapters)

Strategy adapters implement the IStrategy interface (invest / divest / harvest / exit) and are registered with the Controller on Ethereum Mainnet. The Controller treats every strategy as a black box — it only cares about totalAssets() and the standardized interface. This abstraction allows the protocol to seamlessly coordinate entry and exit strategies across different yield sources.

Ethereum Mainnet Strategies

Strategy Description
AaveV3Strategy Deposits and withdraws USDC from the Aave V3 lending pool.
ERC4626Strategy Generic wrapper for any ERC-4626-compatible vault (e.g., Morpho).
HyperStrategy Cross-chain bridge strategy registered on Ethereum. Manages USDC flows to/from HyperEVM via Circle CCTP V2. See below for full flow.

HyperStrategy — Cross-Chain Bridge (Ethereum Mainnet)

HyperStrategy is a standard IStrategy adapter that lives on Ethereum Mainnet and is registered with — and managed by — the Ethereum Controller. It is the cross-chain gateway between the Ethereum vault and the HyperEVM execution environment.

Invest flow (Ethereum → HyperEVM):

  1. Keeper calls Controller.fundInvest(vault, strategy, amount).
  2. Vault transfers USDC to HyperStrategy via pushFund.
  3. HyperStrategy.invest(amount) calls ITokenMessengerV2.depositForBurn — burning USDC on Ethereum and issuing a CCTP V2 attestation.
  4. Keeper calls HyperCoreAllocator.handleInvestMessage(message, attestation) on HyperEVM, minting USDC and issuing internal shares. This function emits an UpdatedStateMessage via CCTP sendMessage for the Keeper to relay.
  5. Keeper calls HyperStrategy.updateRemoteState(stateMessage, attestation) on Ethereum, triggering handleReceiveFinalizedMessage on HyperStrategy which updates the cached _totalAssets / _totalSupply.

Divest flow (HyperEVM → Ethereum):

  1. Keeper calls Controller.fundDivest(vault, strategy, amount).
  2. HyperStrategy.divest(amount) sends a CCTP RedeemMessage to HyperCoreAllocator specifying how many remote shares to redeem.
  3. HyperCoreAllocator processes the request, burns USDC on HyperEVM, and includes an UpdatedStateMessage as hook data in the burn message.
  4. Keeper calls HyperStrategy.completeDivest(message, attestation) — the CCTP transmitter mints USDC back to HyperStrategy on Ethereum, the hook data updates the cached _totalAssets / _totalSupply, and USDC is forwarded to the vault.

NAV tracking: HyperStrategy.totalAssets() returns a cached value (_totalAssets + _processingAssets + local balance) updated by CCTP callbacks. It does not perform live cross-chain reads — this is the value the Keeper snapshots when calling proposeValues.

HyperEVM Contracts (Not Managed by Ethereum Controller)

These contracts are deployed on HyperEVM and are not registered as strategies with the Ethereum Controller. They are the counterparts to HyperStrategy and contain the actual capital allocation logic inside Hyperliquid.

HyperCoreAllocator — Cross-Chain Entry Point (HyperEVM)

HyperCoreAllocator is a UUPS-upgradeable contract that acts as the HyperEVM-side counterpart to HyperStrategy. It maintains internal share accounting (ERC-4626 style) and coordinates asset routing to one or more HyperCoreRouter instances.

Invest flow (receiving USDC from Ethereum):

  1. Keeper calls HyperCoreAllocator.handleInvestMessage(message, attestation) on HyperEVM, relaying the Circle attestation from HyperStrategy.invest().
  2. CCTP MessageTransmitter mints USDC to HyperCoreAllocator on HyperEVM.
  3. Allocator mints internal shares proportional to the deposited amount (ERC-4626 virtual offset formula).
  4. Allocator emits an UpdatedStateMessage (new totalAssets, totalSupply) via CCTP sendMessage. The Keeper fetches this attestation and relays it to Ethereum, allowing HyperStrategy.handleReceiveFinalizedMessage() to update its cached NAV.
  5. Keeper calls HyperCoreAllocator.allocate(routerIdx, amount) to push USDC to a specific HyperCoreRouter.

Divest flow (sending USDC back to Ethereum):

  1. HyperStrategy.divest() sends a RedeemMessage (number of shares to redeem) to HyperCoreAllocator via CCTP.
  2. CCTP MessageTransmitter delivers the message; HyperCoreAllocator.handleReceiveFinalizedMessage() decodes it and increments pendingRedeemShares.
  3. Keeper calls HyperCoreAllocator.collect(routerIdx, amount) to pull USDC from the router back to the allocator's idle balance.
  4. Keeper calls HyperCoreAllocator.executeRedeem() — burns the pending shares, calls depositForBurnWithHook to bridge USDC back to HyperStrategy on Ethereum with an UpdatedStateMessage as hook data.
  5. Keeper calls HyperStrategy.completeDivest(message, attestation) on Ethereum to finalize — USDC lands at HyperStrategy, hook data updates the cached state, and USDC is forwarded to the vault.
HyperCoreRouter — 3-Stage Asset Pipeline (HyperEVM ↔ HyperCore L1)

HyperCoreRouter is the bridge between HyperEVM ERC-20 balances and HyperCore L1's internal accounting layers. It exposes independent step functions so the Keeper can move funds through each stage atomically, and uses HyperCore system precompiles at 0x3333...3333 (CoreWriter) to send raw L1 actions.

Total assets: balance() (ERC-20 idle) + balanceSpot() (L1 spot) + balancePerp() (L1 perp margin) + vaultEquity() (HLP equity).

Unit note: HyperCore L1 internally uses 8-decimal "wei" units. Spot balances from precompiles are divided by 100 to convert to 6-decimal USD. A 1 USDC reserve is always deducted from the router's total asset to cover the HyperCore withdrawal fee.

Invest path — EVM → Spot → Perp → HLP Vault:

Step Function Action
1 depositToSpot(amount) Approves and deposits ERC-20 USDC into CoreDepositWallet, moving it from HyperEVM to the router's L1 spot balance.
2 spotToPerp(amount) Sends a USD_CLASS_TRANSFER action via CoreWriter — moves funds from L1 spot into perp margin.
3 perpToVault(amount) Sends a VAULT_TRANSFER (deposit) action via CoreWriter — deposits perp margin into the HLP vault.

Divest path — HLP Vault → Perp → Spot → EVM:

Step Function Action
1 vaultToPerp(amount) Sends a VAULT_TRANSFER (withdraw) action via CoreWriter — withdraws from HLP vault into perp margin.
2 perpToSpot(amount) Sends a USD_CLASS_TRANSFER action via CoreWriter — moves perp margin back to L1 spot.
3 withdrawFromSpot(amount) Sends a SPOT_SEND action via CoreWriter to the base system address, triggering withdrawal back to HyperEVM ERC-20.

3. Key Design Principles

  1. Dual-Pricing (Protocol-Favorable): Every deposit and withdrawal is priced at the rate most favorable to the protocol. Deposits issue the minimum shares possible (anti-dilution); withdrawals send the minimum assets (anti-drain). This is derived from both the live spot price and the last confirmed NAV simultaneously.

  2. Two-Phase NAV Settlement: The Keeper proposes a new NAV snapshot (proposeValues), which the Admin then confirms (confirmValues). Only upon confirmation are performance fees minted and the new epoch activated. This two-phase commit model prevents single-point-of-failure manipulation.

  3. Inflationary Fee Model: Performance fees are collected by minting new shares directly to the feeReceiver address. Fees are only charged when the current epoch's NAV exceeds the previous epoch's NAV (i.e., when a profit is recognized).

  4. Liquidity Waterfall: The vault does not hold permanent idle capital. When a synchronous withdrawal exceeds available idle cash, the KingsVaultV2 automatically recalls assets from all registered strategies via Controller.fundReplenishOnlyForVault(vault, shortage), ensuring minimal capital inefficiency.

  5. Hub-and-Spoke Architecture: Ethereum is the accounting and user-facing hub; HyperEVM is a cross-chain strategy execution spoke. All share accounting, NAV calculations, and fee minting occur on Ethereum. HyperEVM reports asset balances back to Ethereum via off-chain accounting to update the confirmed NAV.

  6. Oracle-Free Valuation: The protocol does not rely on external price oracles for NAV calculation. Instead, proposeValues snapshots the actual on-chain balances of all registered strategies (Aave, Morpho, HyperCoreAllocator, etc.) as the source of truth.

4. Terminology

Term Definition
NAV Net Asset Value = totalAssets across all strategies + vault idle cash. The basis for share pricing.
Dual-Price The protocol-favorable pricing model: deposits issue MIN(spotShares, markedShares), withdrawals return MIN(spotAssets, markedAssets).
Epoch A settled NAV snapshot. Each confirmValues call advances the epoch counter and locks in the new NAV as the confirmed mark.
Strategy An adapter contract that deploys vault capital into an external yield protocol behind a standardized invest / divest interface.
Keeper The authorized operator role that proposes NAV, invests/divests funds, sets fee rates, and executes async redemptions.
proposeValues Called by the Keeper to snapshot totalAssets + totalSupply as a pending NAV epoch.
confirmValues Called by the Admin to promote the pending epoch to confirmed, minting performance fee shares if a profit is recognized.
CCTP V2 Circle Cross-Chain Transfer Protocol V2 — enables native USDC burn-and-mint across supported chains (used by HyperStrategy).
HLP Hyperliquid Liquidity Pool — the liquidity-provider vault on HyperCore; the primary yield source for the cross-chain strategy.
HyperCoreAllocator HyperEVM contract that receives USDC from CCTP and allocates it into HyperCore.
Liquidity Waterfall The fundReplenishOnlyForVault mechanism that automatically and proportionally recalls capital from synchronous strategies when vault idle cash is insufficient during a user withdrawal.
emergencyRedeem Post-shutdown function allowing investors to burn shares and receive a pro-rata share of remaining idle vault cash.