Lifecycle and safety modes

A vault has a phase, a safety mode and a deposit-window flag. The phase tracks the trading and capital cycle. The safety mode blocks operations: frozen stops new risk, closing stops standard activity, and so on. The deposit window opens and closes intake.

Normal cycle

PhaseTransitionConditions
idleOpen the first position → activeIdle capital is unpriced, intake is closed, and the delegate holds trading permission under the policy. The position sets the active expiry.
activeReach expiry → settlingNew risk closes at the expiry cutoff. The contract reads chain time.
active / settlingClose the last position → processing_capitalAll positions are closed and funding is settled. Capital starts uncomputed.
processing_capitalCompute equityRequires fresh prices from the route’s brick accounts and no open staging slot. The boundary becomes computed.
processing_capitalFinalize the cycle → idleEquity is computed and the deposit and withdrawal queues are empty. Idle capital becomes unpriced again.

idle capital is unpriced, accepting deposits, or priced. When the manager closes the deposit window, it can start trading from unpriced idle capital. Priced idle capital lets the manager process requests but not open a position.

Request processing

Deposits enter during idle intake or during active before expiry. Withdrawals enter in idle or in active before expiry. closing has its own withdrawal path.

The manager normally prices capital and drains the queues. If it does not, anyone can process requests after capital_fallback_delay_seconds (default 43,200 seconds, maximum 259,200 seconds):

  • In idle, a request becomes publicly processable at created_at + delay, once capital is priced. Under withdraw_only, idle requests are processable immediately.
  • In processing_capital, public processing opens at active_expiry_ts + delay.
  • A public processor can price unpriced idle capital only to process an aged withdrawal. A queue holding only deposits cannot force an idle equity checkpoint.

Public processing requires settled positions, validated prices and valid recipient accounts.

Deposit and withdrawal cancellation closes once idle capital is priced and at the active expiry cutoff. Deposit refunds under emergency_unwind and withdraw_only have their own instructions. In closing, withdrawals can be requested and cancelled at any phase and time.

Staged assets

A swap can leave an intermediate asset in a vault-owned account between two transactions. This is an open staging slot, separate from the phase and safety mode. HTTP returns it in staging; null means no slot is open.

While the slot is open, VaultStagingActive blocks equity processing, cycle finalization, final redemption, recovery conversion, shutdown and vault closure. Priced manager top-ups and fee changes also wait. Complete the unstage before pricing capital. Deposit refunds and request cancellations keep their own eligibility rules.

In TypeScript, capital rules take staging. processEquityBlock, processIdleWithdrawalBlock and finalizeCycleBlock return "staged"; nextCapitalStep does not propose equity or finalization while staged. See Two-stage swaps and Staging recovery.

Safety modes

ModeBehavior
normalTrading and capital operations run under the phase rules.
frozenNo new positions. Settlement and capital processing continue.
emergency_unwindRegular capital processing stops. Deposits can be refunded and open positions and funding are unwound.
withdraw_onlyHolders withdraw after the unwind completes. No new positions.
closingStandard activity stops. The vault converts assets, computes equity and finalizes, then moves to withdrawal-only operation.

FreezeVault accepts the protocol cold authority or the guardian. UnfreezeVault and EmergencyStartUnwind require the cold authority. Vault governance runs StartVaultShutdown and FinalizeVaultShutdown.

See Shares, equity and fees for valuation and final redemption.