Skip to content

Withdraw And Redeem Flow

King's Vault V2 supports two distinct variants of withdrawal mechanics depending on whether the investor interacts with the synchronous vault or the asynchronous vault.

Current Mainnet Product Withdrawal Model
Ethereum Network Lending Synchronous KingsVaultV2 withdrawal, subject to available liquidity and vault status.
AAVE GHO Saving Synchronous KingsVaultV2 withdrawal in USDC, subject to liquidity and any required GHO-to-USDC swap on Fluid (or GSM conversion on the secondary route).
Hyperliquidity Provider (HLP) KingsVaultV2Async: request, wait for execution, then claim.

Synchronous Withdraw And Redeem Flow

KingsVaultV2 attempts to complete redemptions in the same transaction. If idle assets within the vault are insufficient to cover the withdrawal, it automatically triggers the Controller's liquidity waterfall. Completion is subject to available liquidity and applicable vault, strategy, and external protocol restrictions.

sequenceDiagram
    participant Investor
    participant Vault
    participant Controller
    participant Strategy

    Investor->>Vault: withdraw(assets, receiver, owner) / redeem(shares, receiver, owner)
    Vault->>Vault: check INVESTOR, not paused, not shutdown
    Vault->>Vault: check assets >= MIN_WITHDRAW
    alt idleAssets < requested assets
        Vault->>Controller: fundReplenishOnlyForVault(vault, shortage)
        Controller->>Strategy: replenish(pro-rata amount)
        Strategy-->>Vault: asset transfer
    end
    Vault->>Vault: burn shares
    Vault-->>Investor: transfer assets to receiver

Liquidity Waterfall

If the requested withdrawal amount exceeds idleAssets:

  1. Vault calculates the missing amount: shortage = requestedAssets - idleAssets.
  2. Vault calls Controller.fundReplenishOnlyForVault(address(this), shortage).
  3. Controller loops over all registered strategies.
  4. Strategies with zero assets are skipped.
  5. The shortage is allocated pro-rata according to each active strategy's totalAssets().
  6. If a strategy reverts during replenish(), the Controller removes it from the in-memory retry set and retries with the remaining strategies.
  7. Each successful withdrawal proportionally decreases the Controller's book value through _decreaseBookValue().

  8. The Controller returns min(actualWithdraw, shortage); the vault settles the withdrawal for idleAssets + returned against the originally computed shares.

The flow reverts with InsufficientStrategyAssets only when every strategy has been removed from the retry set (all reverted or hold zero assets). If strategies respond but return less than the shortage, the withdrawal does not revert: it settles for the amount actually recovered, and the shares computed for the requested amount are burned.

GHO Saving Withdrawals

Users redeem King's Vault shares for USDC. If the underlying position needs to be unwound, the strategies convert sGHO → GHO → USDC: the current adapter (GhoSavingFluidStrategy) sells GHO on the Fluid DEX GHO/USDC pool with a minimum output of the 1:1 amount minus its slippage bound (currently 1%); the earlier adapter sells through the Aave GSM. The quoted amount is an estimate; swap fees and the GHO price at execution decide the final figure.

Fluid swap costs, Aave/GSM route costs and network gas are external costs, not King's Vault fees (see Fees); the final amount depends on execution-time conditions.

Liquidity in practice. A withdrawal up to the vault's idle USDC (idleAssets()) settles in the same transaction. A larger withdrawal triggers the liquidity waterfall (Controller.fundReplenishOnlyForVault), which calls replenish on every attached strategy pro rata to its totalAssets(): the Fluid adapters sell GHO on the Fluid GHO/USDC pool within their slippage bound, and the legacy adapter sells through the Aave GSM. A strategy whose route cannot fill — the pool price outside the bound, or the GSM without inventory — reverts and is dropped from that attempt; the Controller retries the remaining strategies. The withdrawal reverts whole with InsufficientStrategyAssets only when no strategy can serve it, and then no shares are burned. In that case the Keeper restores idle liquidity (for example Controller.fundDivest, or on the GSM route pre-filling the GSM through the GhoGsmLiquidityHelper in one atomic transaction), after which the user can withdraw normally. Users should therefore expect instant withdrawals within available liquidity, and a Keeper-assisted delay for larger amounts; the interface shows this on the redeem form.

sGHO savings has no Umbrella staking cooldown or slashing mechanism. However, redeeming sGHO for GHO is not the same as receiving USDC from King's Vault. Withdrawal still depends on vault status, underlying liquidity, route capacity, available quotes, and successful execution. The absence of a staking cooldown does not guarantee immediate liquidity or principal protection.

Asynchronous Withdrawal Flow

KingsVaultV2Async changes the withdrawal semantics. withdraw() and redeem() do not immediately transfer assets back to the user. Instead, they escrow the shares within the vault and create a pending redemption request. It becomes claimable only after the Keeper executes the applicable round with sufficient idle assets.

sequenceDiagram
    participant Investor
    participant AsyncVault
    participant Keeper

    Investor->>AsyncVault: withdraw/redeem
    AsyncVault->>AsyncVault: transfer shares from owner to vault
    AsyncVault->>AsyncVault: add RedeemRequest(owner, receiver)
    Note over Keeper,AsyncVault: Pending until execution and sufficient idle assets
    Keeper->>AsyncVault: executeRedeem()
    AsyncVault->>AsyncVault: snapshot pending shares/assets
    Note over Investor,AsyncVault: Request is now claimable
    Investor->>AsyncVault: claim(receiver)
    AsyncVault->>AsyncVault: burn escrowed shares
    AsyncVault-->>Investor: transfer reserved assets

Request Phase

Step Detail
Validate Caller must have Roles.INVESTOR, vault must not be paused or shutdown, amount must meet MIN_WITHDRAW.
Allowance If caller is not owner, _spendAllowance(owner, caller, shares) is verified and spent.
Escrow Shares move from the owner to the vault contract.
Merge An existing request for the same (owner, receiver) pair is merged into the current execId.
Auto-claim If an old request for the same pair is already executable, _claim() runs before storing the new request.

Execution Phase

  1. The Keeper calls executeRedeem().
  2. The Vault converts all _pendingRedeemShares to assets using the current preview price.
  3. The Vault verifies that execAssets <= idleAssets().
  4. The Vault writes an ExecSnapshot.
  5. Shares move from pending to claimable.
  6. Assets become reserved in _claimableAssets.
  7. _execId increments, advancing the round.

Claim Phase

  1. Investor calls claim(receiver).
  2. The request is claimable only if request.execId < _execId.
  3. Assets are calculated pro-rata from the execution snapshot of that specific round.
  4. Escrowed shares are burned from the vault balance.
  5. Assets transfer to the receiver.

HLP Timing And Estimates

The HLP portal currently displays a processing-time estimate of 96 hours. This is not a guaranteed completion time measured from the user's redemption request.

The underlying HLP position has a four-day lock-up measured from its most recent deposit. That clock belongs to the underlying Hyperliquid position, not the King's Vault user's request. Hyperliquid's official HLP documentation describes this lock-up rule.

King's Vault redemption also depends on underlying liquidity, HyperCore execution, Keeper operations, CCTP completion, and sufficient idle USDC in the Ethereum vault. Subsequent deposits into the underlying HLP position can affect its unlock time, so a user's request does not establish a fixed redemption deadline. See the cross-chain flow.

During the pending phase, a preview is an estimate, not a locked payment amount. The execution round determines the reserved assets, and each claim uses that round's snapshot.