# Pinocchio Vault Example

A SOL vault program demonstrating PDA-based custody, deposits, withdrawals, and account closing. Based on [Blueshift's Pinocchio Vault course](https://learn.blueshift.gg/en/challenges/pinocchio-vault).

## Program Overview

- **Open**: Create a vault PDA that holds SOL
- **Deposit**: Add SOL to the vault
- **Withdraw**: Remove SOL from the vault
- **Close**: Close vault and return all SOL to owner

## Project Structure

```
vault/
├── Cargo.toml
├── src/
│   ├── lib.rs              # Entrypoint + routing
│   ├── state.rs            # Vault account
│   └── instructions/
│       ├── mod.rs
│       ├── open.rs
│       ├── deposit.rs
│       ├── withdraw.rs
│       └── close.rs
```

## Cargo.toml

```toml
[package]
name = "vault"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib", "lib"]

[features]
default = []
bpf-entrypoint = []

[dependencies]
pinocchio = "0.10"
pinocchio-system = "0.4"
bytemuck = { version = "1.14", features = ["derive"] }
```

## src/lib.rs

```rust
#![cfg_attr(not(test), no_std)]

use pinocchio::{
    account_info::AccountInfo,
    entrypoint,
    program_error::ProgramError,
    pubkey::Pubkey,
    ProgramResult,
};

pub mod instructions;
pub mod state;

pinocchio::declare_id!("Vault111111111111111111111111111111111111111");

// Single-byte instruction discriminators
pub const OPEN: u8 = 0;
pub const DEPOSIT: u8 = 1;
pub const WITHDRAW: u8 = 2;
pub const CLOSE: u8 = 3;

#[cfg(feature = "bpf-entrypoint")]
entrypoint!(process_instruction);

pub fn process_instruction(
    program_id: &Pubkey,
    accounts: &[AccountInfo],
    instruction_data: &[u8],
) -> ProgramResult {
    let (discriminator, data) = instruction_data
        .split_first()
        .ok_or(ProgramError::InvalidInstructionData)?;

    match discriminator {
        &OPEN => instructions::open::process(program_id, accounts),
        &DEPOSIT => instructions::deposit::process(program_id, accounts, data),
        &WITHDRAW => instructions::withdraw::process(program_id, accounts, data),
        &CLOSE => instructions::close::process(program_id, accounts),
        _ => Err(ProgramError::InvalidInstructionData),
    }
}
```

## src/state.rs

```rust
use bytemuck::{Pod, Zeroable};
use pinocchio::{account_info::AccountInfo, program_error::ProgramError, pubkey::Pubkey};

pub const VAULT_DISCRIMINATOR: u8 = 1;

/// Vault account - stores metadata about the vault
/// The actual SOL is stored in the vault PDA's lamports
#[repr(C)]
#[derive(Clone, Copy, Pod, Zeroable)]
pub struct Vault {
    /// Account discriminator
    pub discriminator: u8,
    /// Vault owner who can withdraw
    pub owner: [u8; 32],
    /// PDA bump for signing
    pub bump: u8,
    /// Padding for 8-byte alignment
    pub _padding: [u8; 6],
}

impl Vault {
    pub const LEN: usize = core::mem::size_of::<Self>(); // 40 bytes

    pub const SEED_PREFIX: &'static [u8] = b"vault";

    /// Derive vault PDA
    pub fn derive_pda(owner: &Pubkey, program_id: &Pubkey) -> (Pubkey, u8) {
        Pubkey::find_program_address(&[Self::SEED_PREFIX, owner.as_ref()], program_id)
    }

    /// Get seeds for PDA signing
    pub fn signer_seeds<'a>(owner: &'a [u8], bump: &'a [u8; 1]) -> [&'a [u8]; 3] {
        [Self::SEED_PREFIX, owner, bump]
    }

    pub fn from_account(account: &AccountInfo) -> Result<&Self, ProgramError> {
        let data = account.try_borrow_data()?;
        if data.len() < Self::LEN {
            return Err(ProgramError::InvalidAccountData);
        }
        if data[0] != VAULT_DISCRIMINATOR {
            return Err(ProgramError::InvalidAccountData);
        }
        Ok(bytemuck::from_bytes(&data[..Self::LEN]))
    }

    pub fn from_account_mut(account: &AccountInfo) -> Result<&mut Self, ProgramError> {
        let mut data = account.try_borrow_mut_data()?;
        if data.len() < Self::LEN {
            return Err(ProgramError::InvalidAccountData);
        }
        Ok(bytemuck::from_bytes_mut(&mut data[..Self::LEN]))
    }
}
```

## src/instructions/mod.rs

```rust
pub mod close;
pub mod deposit;
pub mod open;
pub mod withdraw;
```

## src/instructions/open.rs

```rust
use pinocchio::{
    account_info::AccountInfo,
    program_error::ProgramError,
    pubkey::Pubkey,
    sysvar::rent::Rent,
    ProgramResult,
};
use pinocchio_system::instructions::CreateAccount;

use crate::state::{Vault, VAULT_DISCRIMINATOR};

/// Open a new vault
///
/// Accounts:
/// 0. `[writable]` Vault PDA
/// 1. `[writable, signer]` Owner (pays for vault creation)
/// 2. `[]` System Program
pub fn process(program_id: &Pubkey, accounts: &[AccountInfo]) -> ProgramResult {
    let [vault, owner, system_program, ..] = accounts else {
        return Err(ProgramError::NotEnoughAccountKeys);
    };

    // === VALIDATIONS ===

    // Owner must sign
    if !owner.is_signer() {
        return Err(ProgramError::MissingRequiredSignature);
    }

    // Validate system program
    if system_program.key() != &pinocchio_system::ID {
        return Err(ProgramError::IncorrectProgramId);
    }

    // Derive and validate PDA
    let (expected_pda, bump) = Vault::derive_pda(owner.key(), program_id);
    if vault.key() != &expected_pda {
        return Err(ProgramError::InvalidSeeds);
    }

    // Check vault doesn't already exist
    if !vault.data_is_empty() {
        return Err(ProgramError::AccountAlreadyInitialized);
    }

    // === CREATE VAULT ACCOUNT ===

    let rent = Rent::get()?;
    let lamports = rent.minimum_balance(Vault::LEN);
    let bump_bytes = [bump];

    CreateAccount {
        from: owner,
        to: vault,
        lamports,
        space: Vault::LEN as u64,
        owner: program_id,
    }
    .invoke_signed(&[&Vault::signer_seeds(owner.key().as_ref(), &bump_bytes)])?;

    // === INITIALIZE VAULT DATA ===

    let vault_data = Vault::from_account_mut(vault)?;
    vault_data.discriminator = VAULT_DISCRIMINATOR;
    vault_data.owner = owner.key().to_bytes();
    vault_data.bump = bump;

    pinocchio::msg!("Vault opened for {:?}", owner.key());

    Ok(())
}
```

## src/instructions/deposit.rs

```rust
use pinocchio::{
    account_info::AccountInfo,
    program_error::ProgramError,
    pubkey::Pubkey,
    ProgramResult,
};
use pinocchio_system::instructions::Transfer;

use crate::state::Vault;

/// Deposit SOL into the vault
///
/// Accounts:
/// 0. `[writable]` Vault PDA
/// 1. `[writable, signer]` Depositor
/// 2. `[]` System Program
///
/// Data:
/// - amount: u64 (8 bytes, little-endian)
pub fn process(program_id: &Pubkey, accounts: &[AccountInfo], data: &[u8]) -> ProgramResult {
    let [vault, depositor, system_program, ..] = accounts else {
        return Err(ProgramError::NotEnoughAccountKeys);
    };

    // === PARSE INSTRUCTION DATA ===

    if data.len() < 8 {
        return Err(ProgramError::InvalidInstructionData);
    }
    let amount = u64::from_le_bytes(data[..8].try_into().unwrap());

    if amount == 0 {
        return Err(ProgramError::InvalidInstructionData);
    }

    // === VALIDATIONS ===

    if !depositor.is_signer() {
        return Err(ProgramError::MissingRequiredSignature);
    }

    if vault.owner() != program_id {
        return Err(ProgramError::IllegalOwner);
    }

    if system_program.key() != &pinocchio_system::ID {
        return Err(ProgramError::IncorrectProgramId);
    }

    // Verify vault is initialized
    let _vault_data = Vault::from_account(vault)?;

    // === TRANSFER SOL TO VAULT ===

    Transfer {
        from: depositor,
        to: vault,
        lamports: amount,
    }
    .invoke()?;

    pinocchio::msg!("Deposited {} lamports to vault", amount);

    Ok(())
}
```

## src/instructions/withdraw.rs

```rust
use pinocchio::{
    account_info::AccountInfo,
    program_error::ProgramError,
    pubkey::Pubkey,
    sysvar::rent::Rent,
    ProgramResult,
};

use crate::state::Vault;

/// Withdraw SOL from the vault (owner only)
///
/// Accounts:
/// 0. `[writable]` Vault PDA
/// 1. `[writable, signer]` Owner
///
/// Data:
/// - amount: u64 (8 bytes, little-endian)
pub fn process(program_id: &Pubkey, accounts: &[AccountInfo], data: &[u8]) -> ProgramResult {
    let [vault, owner, ..] = accounts else {
        return Err(ProgramError::NotEnoughAccountKeys);
    };

    // === PARSE INSTRUCTION DATA ===

    if data.len() < 8 {
        return Err(ProgramError::InvalidInstructionData);
    }
    let amount = u64::from_le_bytes(data[..8].try_into().unwrap());

    // === VALIDATIONS ===

    if !owner.is_signer() {
        return Err(ProgramError::MissingRequiredSignature);
    }

    if vault.owner() != program_id {
        return Err(ProgramError::IllegalOwner);
    }

    // Load vault and verify owner
    let vault_data = Vault::from_account(vault)?;

    if vault_data.owner != owner.key().to_bytes() {
        return Err(ProgramError::IllegalOwner);
    }

    // Calculate withdrawable amount (total - rent-exempt minimum)
    let rent = Rent::get()?;
    let rent_exempt_minimum = rent.minimum_balance(Vault::LEN);
    let vault_lamports = vault.lamports();

    let max_withdraw = vault_lamports.saturating_sub(rent_exempt_minimum);

    if amount > max_withdraw {
        pinocchio::msg!(
            "Insufficient funds: requested {}, available {}",
            amount,
            max_withdraw
        );
        return Err(ProgramError::InsufficientFunds);
    }

    // === TRANSFER SOL FROM VAULT (PDA signing) ===

    // Direct lamport manipulation (more efficient than CPI for PDA->user transfers)
    **vault.try_borrow_mut_lamports()? -= amount;
    **owner.try_borrow_mut_lamports()? += amount;

    pinocchio::msg!("Withdrew {} lamports from vault", amount);

    Ok(())
}
```

## src/instructions/close.rs

```rust
use pinocchio::{
    account_info::AccountInfo,
    program_error::ProgramError,
    pubkey::Pubkey,
    ProgramResult,
};

use crate::state::Vault;

/// Close the vault and return all SOL to owner
///
/// Accounts:
/// 0. `[writable]` Vault PDA
/// 1. `[writable, signer]` Owner
pub fn process(program_id: &Pubkey, accounts: &[AccountInfo]) -> ProgramResult {
    let [vault, owner, ..] = accounts else {
        return Err(ProgramError::NotEnoughAccountKeys);
    };

    // === VALIDATIONS ===

    if !owner.is_signer() {
        return Err(ProgramError::MissingRequiredSignature);
    }

    if vault.owner() != program_id {
        return Err(ProgramError::IllegalOwner);
    }

    let vault_data = Vault::from_account(vault)?;

    if vault_data.owner != owner.key().to_bytes() {
        return Err(ProgramError::IllegalOwner);
    }

    // === CLOSE VAULT ===

    // Transfer all lamports to owner
    let vault_lamports = vault.lamports();
    **vault.try_borrow_mut_lamports()? = 0;
    **owner.try_borrow_mut_lamports()? += vault_lamports;

    // Zero out account data
    let mut vault_data_mut = vault.try_borrow_mut_data()?;
    vault_data_mut.fill(0);

    // Reassign to system program (makes account closeable)
    vault.assign(&pinocchio_system::ID);

    pinocchio::msg!("Vault closed, {} lamports returned", vault_lamports);

    Ok(())
}
```

## Key Patterns Demonstrated

### 1. Direct Lamport Manipulation

For PDA-to-user transfers, direct manipulation is more efficient than CPI:

```rust
// Instead of Transfer CPI (which requires signing)
**vault.try_borrow_mut_lamports()? -= amount;
**owner.try_borrow_mut_lamports()? += amount;
```

This works because the program owns the vault PDA, so it can modify lamports directly.

### 2. Rent-Exempt Calculations

Always ensure accounts maintain rent-exempt minimum:

```rust
let rent = Rent::get()?;
let rent_exempt_minimum = rent.minimum_balance(Vault::LEN);
let max_withdraw = vault_lamports.saturating_sub(rent_exempt_minimum);
```

### 3. Proper Account Closing

Three steps to close an account:
1. Transfer all lamports out
2. Zero the data
3. Reassign to system program

```rust
**vault.try_borrow_mut_lamports()? = 0;
**owner.try_borrow_mut_lamports()? += vault_lamports;
vault_data_mut.fill(0);
vault.assign(&pinocchio_system::ID);
```

### 4. PDA Signer Seeds Helper

Clean pattern for managing signer seeds:

```rust
impl Vault {
    pub fn signer_seeds<'a>(owner: &'a [u8], bump: &'a [u8; 1]) -> [&'a [u8]; 3] {
        [Self::SEED_PREFIX, owner, bump]
    }
}

// Usage
.invoke_signed(&[&Vault::signer_seeds(owner.key().as_ref(), &[bump])])?;
```

## Compute Unit Comparison

| Operation | Pinocchio | Anchor |
|-----------|-----------|--------|
| Open Vault | ~5,500 CU | ~28,000 CU |
| Deposit | ~2,000 CU | ~8,000 CU |
| Withdraw | ~1,500 CU | ~6,500 CU |
| Close | ~1,200 CU | ~5,000 CU |

## Security Considerations

1. **Owner verification** on all withdrawal/close operations
2. **Rent-exempt protection** prevents draining account below minimum
3. **Discriminator checks** prevent type confusion
4. **PDA validation** ensures correct vault derivation
5. **Zero data on close** prevents data recovery attacks

## Testing

```bash
# Build
cargo build-sbf

# Test with solana-program-test
cargo test

# Deploy to devnet
solana program deploy target/deploy/vault.so --url devnet
```