CPI Integration Guide - Voltr Documentation

This guide covers Cross-Program Invocation (CPI) integration with the Voltr Vault program. If your protocol needs to deposit into or withdraw from Voltr vaults on-chain, use these CPI instructions.

When to use CPI vs. the TypeScript SDK: CPI is for on-chain programs that need to interact with Voltr vaults programmatically (e.g., a router or aggregator). If you are building off-chain automation or a frontend, use the TypeScript SDK instead.

Building with a coding agent? The Voltr Agent Skill ships a cpi-integration.md reference with verified discriminators and drop-in Rust CPI wrappers for all five vault instructions in examples/cpi/.

How It Works

Users deposit assets into a vault and receive LP tokens representing their share. Withdrawals follow a two-step process to ensure vault stability and manage liquidity:

Request withdrawal — locks LP tokens into an escrow receipt
Claim withdrawal — after the vault’s waiting period, burns the locked LP tokens and returns the underlying assets

Alternatively, vaults with a zero waiting period support instant withdrawal, which combines both steps into a single transaction. Users can also cancel a pending withdrawal request to reclaim their LP tokens.

Deposit:          User Assets ──► Vault ──► LP Tokens to User

Withdraw:         LP Tokens ──► Escrow Receipt ──(waiting period)──► Assets to User

Cancel Withdraw:  Escrow Receipt ──► LP Tokens back to User

Instant Withdraw: LP Tokens ──► Assets to User (single transaction)

Deployed Address

Network	Program Address
Mainnet	`vVoLTRjQmtFpiYoegx285Ze4gsLJ8ZxgFKVcuvmG1a8`

CPI Instructions

Instruction	Purpose	Reference
`deposit_vault`	Deposit assets and receive LP tokens	Deposit
`request_withdraw_vault`	Lock LP tokens into an escrow receipt	Request Withdraw
`withdraw_vault`	Claim assets after the waiting period	Withdraw
`cancel_request_withdraw_vault`	Cancel a pending withdrawal request	Cancel Withdraw
`instant_withdraw_vault`	Withdraw assets instantly (zero waiting period vaults)	Instant Withdraw

PDA Derivation

All PDAs are derived from the Voltr Vault program (vVoLTRjQmtFpiYoegx285Ze4gsLJ8ZxgFKVcuvmG1a8):

Account	Seeds
`protocol`	`["protocol"]`
`vault_asset_idle_auth`	`["vault_asset_idle_auth", vault_key]`
`vault_lp_mint_auth`	`["vault_lp_mint_auth", vault_key]`
`request_withdraw_vault_receipt`	`["request_withdraw_vault_receipt", vault_key, user_key]`

Your program does not need to provide PDA signer seeds for the vault’s internal PDAs. The Voltr Vault program handles its own invoke_signed calls internally. You only need to pass the correct PDA addresses in the account list.

Error Handling

Your program should handle the following errors from the Voltr Vault program:

Error	Cause
`InvalidAmount`	Input amount is zero or invalid
`MaxCapExceeded`	Deposit would exceed the vault’s maximum capacity
`WithdrawalNotYetAvailable`	`withdraw_vault` called before the waiting period has passed
`InstantWithdrawNotAllowed`	`instant_withdraw_vault` called on a vault with a non-zero waiting period
`OperationNotAllowed`	The protocol has globally disabled the attempted operation

Reference Repository

Full reference implementations are available at github.com/voltrxyz/vault-cpi.

​How It Works

​Deployed Address

​CPI Instructions

​PDA Derivation

​Error Handling

​Reference Repository

How It Works

Deployed Address

CPI Instructions

PDA Derivation

Error Handling

Reference Repository