This guide covers Cross-Program Invocation (CPI) integration with the Ranger Earn Vault program. If your protocol needs to deposit into or withdraw from Ranger Earn 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 Ranger Earn vaults programmatically (e.g., a router or aggregator). If you are building off-chain automation or a frontend, use the TypeScript SDK instead. 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 Ranger Earn 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 Ranger Earn 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 Ranger Earn 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/ranger-finance/vault-cpi. 
