Instructions

An instruction is one call to a Solana program. A transaction can contain several. This page lists every instruction of akashi_vault, groups them by who may call them, and walks through the three flows that matter most: depositing, withdrawing and investing.

This page is reference material for developers and for readers who want to check exactly what the program allows. Instruction, argument and account names are exactly as they appear in the program's public interface. Amounts are in USDC base units, where 1 USDC = 1,000,000 base units, because USDC and the share mints have 6 decimals. Argument types such as u8, u16 and u64 are unsigned whole numbers of 1, 2 and 8 bytes; i64 is a signed one; bps means basis points, where 10,000 is 100%.

Who can call whatCopy Anchor Link

Table: the roles that may sign each instruction; guardian-or-admin actions can only reduce risk, so they take effect at once.

The rule behind the table: anything that can only make a vault safer is instant, and anything that can make it riskier waits for the timelock (see Governance changes).

Holder instructionsCopy Anchor Link

Table: the four instructions a holder signs.

Tranche is an enum: Senior (0) or Junior (1).

Deposit: accountsCopy Anchor Link

Table: the accounts of deposit, in the order the instruction expects them.

Deposit: checks, in orderCopy Anchor Link

1. No trade bracket is open (TradeOpen).
2. The vault is Active (VaultNotActive).
3. Every pending queued action has been re-valued (PendingClaim).
4. Deposits are not paused (Paused).
5. amount > 0 and amount is at least the vault's minimum deposit (AmountTooSmall).
6. Every leg is fresh (StaleValuation). The vault then books gains and losses since the last update (the same step as sync_vault) and checks it is still Active.
7. NAV plus amount stays within the vault's deposit cap (VaultCapExceeded).
8. Shares to mint are above 0 (ZeroShares) and at least min_shares (MinSharesNotMet).
9. Coverage after the deposit is valid (CoverageViolation): a Senior deposit must keep Junior at least the vault's minimum coverage of the total; a Junior deposit must keep it at most the vault's maximum coverage, where 0 means no maximum.

Then the USDC moves into idle, the shares are minted, and the Deposited event is emitted.

sequenceDiagram
    participant W as Holder wallet
    participant C as Akashi app (client)
    participant K as Akashi API
    participant V as akashi_vault
    participant T as SPL Token
    C->>K: refresh request (warm-up; the app sends at most one every 20 seconds)
    K->>V: refresh_leg for each leg
    C->>W: ask to sign deposit(tranche, amount, min_shares)
    W->>V: deposit
    V->>V: checks, legs fresh, book gains and losses, price at the high band
    V->>T: CPI transfer amount: user_usdc to idle_account (signed by user)
    V->>T: CPI mint_to shares: share_mint to user_shares (signed by vault authority)
    V-->>W: Deposited event

Figure: the app first makes sure every leg is fresh, then one deposit instruction moves the USDC and mints the shares.

The takeaway: the app's warm-up call is a convenience, not a requirement. If a leg is stale, the deposit fails with StaleValuation and can simply be retried after a refresh.

Withdrawal flowCopy Anchor Link

A withdrawal has three steps, and only the first needs your signature.

sequenceDiagram
    participant W as Holder wallet
    participant V as akashi_vault
    participant T as SPL Token
    participant K as Anyone (executor, app or you)
    W->>V: request_withdrawal(tranche, shares, min_usdc_out)
    V->>T: CPI transfer shares: owner_shares to escrow
    V->>V: create WithdrawalRequest, eligible_at = now + delay
    Note over V: wait until eligible_at
    K->>V: fund_withdrawal
    V->>V: checks, legs fresh, book gains and losses, price at the low band
    V->>T: CPI burn shares from escrow
    V->>T: CPI transfer USDC: idle_account to payout_account
    K->>V: claim_withdrawal
    V->>T: CPI transfer USDC: payout_account to owner_usdc
    V->>V: close the request when fully funded and paid

Figure: shares are escrowed when you request, burned and priced when the request is funded, and the USDC is paid to you when anyone claims it.

Request statesCopy Anchor Link

stateDiagram-v2
    [*] --> Waiting: request_withdrawal
    Waiting --> Eligible: eligible_at passes
    Eligible --> PartlyFunded: fund_withdrawal (not enough idle, brake or coverage)
    PartlyFunded --> PartlyFunded: fund_withdrawal again
    Eligible --> Funded: fund_withdrawal (all shares)
    PartlyFunded --> Funded: fund_withdrawal (rest)
    Waiting --> Closed: cancel_withdrawal
    Eligible --> Closed: cancel_withdrawal
    PartlyFunded --> FundedPart: cancel_withdrawal returns unfunded shares
    FundedPart --> Closed: claim_withdrawal
    Funded --> Closed: claim_withdrawal pays everything

Figure: a request can be funded in several parts and cancelled at any time before it is fully funded; USDC already funded always stays claimable.

Fund: checks, in orderCopy Anchor Link

1. No trade bracket is open, and withdrawals are open: the vault is Active or Recovery and not frozen (VaultFrozen, VaultNotActive).
2. Pending queued actions are re-valued (PendingClaim), and funding is not paused (Paused).
3. The request is eligible (NotEligibleYet) and not already funded (AlreadyFunded).
4. Every leg is fresh, gains and losses are booked, and withdrawals are still open.
5. The price is the tranche's value at the cautious low band.
6. The amount is limited by the vault's idle cash. For Senior, also by the outflow brake when it is on (OutflowLimitReached). For Junior, also by the USDC that waiting Senior requests need (InsufficientIdle) and by the coverage floor (CoverageViolation).
7. If not everything fits, the request is funded in part. The part must still meet min_usdc_out pro rata (BelowMinUsdcOut).

Then the shares are burned, the USDC moves from idle to the payout account, and the vault's reserved payouts grow by that amount.

Withdraw: accountsCopy Anchor Link

Table: the accounts of each withdrawal instruction; fund_withdrawal and claim_withdrawal need no signer from the vault's side, so anyone can send them.

Investing flow (executor)Copy Anchor Link

Table: the executor's instructions; the _v2 versions are for legs configured with configure_v2_leg.

sequenceDiagram
    participant E as Executor
    participant V as akashi_vault
    participant T as SPL Token
    participant A as Adapter
    participant P as Protocol
    E->>V: allocate(amount, min_value_increase) + bound accounts
    V->>V: Active, not paused, leg Active, legs fresh, book gains and losses
    V->>T: CPI transfer amount: idle_account to leg_transit (signed by vault authority)
    V->>A: CPI aai_deposit(amount) (signed by leg authority)
    A->>P: CPI deposit into the protocol
    A-->>V: ValuationReport
    V->>V: leg_transit back to its old balance? (TransitBalanceMismatch)
    V->>V: value grew by amount minus the leg's slippage allowance? (ValueIncreaseTooLow)
    V->>V: leg cap, leg weight, idle minimum (LegCapExceeded, LegWeightExceeded, IdleBelowMinimum)
    V->>V: book gains and losses

Figure: an allocation passes USDC through the leg's own transit account, and the vault checks afterwards that exactly that amount left and the leg's value grew by it.

The takeaway: the executor chooses when and how much to invest, but it cannot choose where the money goes. It can only reach the leg's adapter and the accounts bound to it, and every allocation is checked against the leg's limits.

Token flowsCopy Anchor Link

flowchart LR
    U[Holder USDC account] -->|deposit| I[Idle account PDA]
    I -->|allocate| TR[Leg transit account]
    TR -->|aai_deposit| P[Protocol position]
    P -->|aai_withdraw| TR
    TR -->|deallocate| I
    I -->|fund_withdrawal| PO[Payout account PDA]
    PO -->|claim_withdrawal| U
    PO -->|settle_shares| U
    S[Holder share account] -->|request_withdrawal| ES[Escrow PDA]
    ES -->|fund_withdrawal: burn| X[Burned]
    ES -->|cancel_withdrawal| S
    M[Share mint PDA] -->|deposit: mint| S

Figure: USDC moves from your wallet to idle, out to legs and back, then through the payout account to you; shares move from your wallet to escrow and are burned when funded.

The key point is the payout account. Once a request is funded, its USDC is moved out of idle into the payout account and recorded as a reserved payout. From then on it cannot be invested or used to absorb losses. It belongs to the request owner.

Maintenance (anyone)Copy Anchor Link

Table: instructions anyone can send to keep a vault's numbers current.

Guardian and admin actionsCopy Anchor Link

Table: the safety and incident instructions.

Governance changesCopy Anchor Link

Changes that could increase risk on a live vault go through queue_change(change: ConfigChange). Each creates a PendingChange that anyone can execute with execute_change once its delay has passed, within a 7-day window set by the program. During the delay, the guardian or admin can cancel it.

Table: every timelocked change; by default the governance delay is 86,400 seconds (1 day) and the add-leg delay is 172,800 seconds (2 days).

The program caps both delays at 30 days. AddLeg is not applied by execute_change; it authorises the admin's add_leg for exactly that adapter, those parameters and that account list.

In Recovery and Settlement, only role changes (SetExecutor, SetGuardian), RepinAdapter and, in Recovery only, RaiseMark can be executed. Anything else fails with VaultNotActive.

Parameters and limitsCopy Anchor Link

Table: the limits the program enforces on every setting, and the program's defaults where it has them.

The program has no fee setting: no vault setting is a fee, and no instruction pays a fee to the curator or to Akashi. See Fees and execution costs.

Advanced detailsCopy Anchor Link

• The program adds a tolerance of 2 base units to the slippage allowance on allocations, to absorb protocol rounding.
• Share math uses virtual offsets of 1,000,000 shares and 1,000,000 base units, which stops the first depositor from manipulating the share price. See NAV and share pricing.
• An instruction that would leave a trade bracket open fails: begin_trade must be followed by end_trade in the same transaction (MissingEndTrade), and must be a top-level instruction (NotTopLevel).