Understanding
Solana Internals

The Mental Model

If you only take one thing from this guide, take this: Solana is a database of accounts. Everything — wallets, tokens, NFTs, smart contracts, on-chain state — is just an account. Programs read and write to accounts. That is the entire model.

This distinction has profound implications. On Ethereum, you call a contract and it reads its own storage. On Solana, you tell the runtime which accounts to load, then the program processes them. This means the runtime can schedule non-overlapping transactions in parallel — if Transaction A writes to Account 1 and Transaction B writes to Account 2, they execute simultaneously.

Why This Matters for You

As a Rust developer building on Solana, your entire job boils down to three things:

Accounts Deep Dive

An account is Solana's atomic unit of state. Every single byte of data that exists on-chain lives inside an account. Understanding their structure and rules is non-negotiable.

The Five Iron Rules of Accounts

These rules are enforced by the Solana runtime. Violating them causes your transaction to fail. Understand them deeply — they define what is and is not possible on Solana.

Account Types in Practice

Data Serialization — How Bytes Map to Structs

Solana accounts store raw bytes. Your program must serialize (write) and deserialize (read) structs to/from those bytes. The standard is Borsh (Binary Object Representation Serializer for Hashing) — a deterministic, schema-based binary format.

Rust
// Your Anchor account struct
#[account]
#[derive(InitSpace)]
pub struct Vault {
    pub owner: Pubkey,       // 32 bytes
    pub balance: u64,       // 8 bytes
    pub created_at: i64,    // 8 bytes
    pub is_locked: bool,    // 1 byte
    pub bump: u8,           // 1 byte
}
// Total: 8 (discriminator) + 32 + 8 + 8 + 1 + 1 = 58 bytes
// The Anchor discriminator (first 8 bytes) = SHA256("account:Vault")[..8]
// Rent-exempt minimum ≈ 58 × 6,960 = ~403,680 lamports ≈ 0.0004 SOL

Programs & Execution

A Solana program is a stateless function: it takes in a list of accounts and instruction data, executes logic, mutates account state, and returns success or failure. That's it.

The Raw Entrypoint vs Anchor

You can write programs at two levels. The raw entrypoint gives you maximum control. Anchor gives you maximum productivity. Here's the same logic at both levels:

Raw Solana
// Raw entrypoint — you handle EVERYTHING manually
use solana_program::{
    account_info::{next_account_info, AccountInfo},
    entrypoint, entrypoint::ProgramResult,
    msg, program_error::ProgramError, pubkey::Pubkey,
};

entrypoint!(process_instruction);

fn process_instruction(
    program_id: &Pubkey,
    accounts: &[AccountInfo],
    instruction_data: &[u8],
) -> ProgramResult {
    let accounts_iter = &mut accounts.iter();
    let vault = next_account_info(accounts_iter)?;
    let user = next_account_info(accounts_iter)?;

    // YOU must manually check: is the user a signer?
    if !user.is_signer {
        return Err(ProgramError::MissingRequiredSignature);
    }
    // YOU must check: does this program own the vault?
    if vault.owner != program_id {
        return Err(ProgramError::IncorrectProgramId);
    }
    // YOU must deserialize, validate, process, serialize...
    msg!("Processing instruction");
    Ok(())
}

Anchor
// Anchor — declarative constraints handle validation automatically
use anchor_lang::prelude::*;

#[program]
pub mod vault {
    use super::*;

    pub fn deposit(ctx: Context<Deposit>, amount: u64) -> Result<()> {
        // Signer check? Anchor did it (Signer type).
        // Owner check? Anchor did it (Account type).
        // PDA derivation? Anchor did it (seeds + bump).
        // Deserialization? Anchor did it.
        // You just write the business logic:
        ctx.accounts.vault.balance = ctx.accounts.vault.balance
            .checked_add(amount)
            .ok_or(VaultError::Overflow)?;
        Ok(())
    }
}

#[derive(Accounts)]
pub struct Deposit<'info> {
    #[account(
        mut,
        seeds = [b"vault", user.key().as_ref()],
        bump = vault.bump,
    )]
    pub vault: Account<'info, Vault>,
    #[account(mut)]
    pub user: Signer<'info>,
    pub system_program: Program<'info, System>,
}

Native Programs — Solana's Built-in Infrastructure

Solana ships with programs that handle core functionality. Your programs interact with them via CPI.

Transactions

A transaction is an atomic bundle of instructions. All succeed or all fail. Understanding their structure, limits, and lifecycle is critical for building production systems.

Transaction Lifecycle

Account Tags — The Key to Parallelism

Every account referenced in a transaction is tagged with metadata. The runtime uses these tags to schedule parallel execution:

Versioned Transactions & Address Lookup Tables

Consensus — PoH & Tower BFT

Solana doesn't use a single consensus mechanism. It uses a combination of Proof of History (a verifiable clock), Tower BFT (a PBFT variant), and several propagation innovations to achieve sub-second block times.

The Eight Innovations

PDAs & Cross-Program Invocations

PDAs and CPIs are the composability primitives of Solana. PDAs let programs own accounts autonomously. CPIs let programs call other programs. Together, they enable the entire DeFi stack.

Rust — PDA in Anchor
// Finding a PDA: deterministic from seeds + program_id
let (vault_pda, bump) = Pubkey::find_program_address(
    &[b"vault", user.key().as_ref()],
    program_id,
);

// Anchor constraint — validates PDA derivation automatically
#[account(
    init,
    payer = user,
    space = 8 + Vault::INIT_SPACE,
    seeds = [b"vault", user.key().as_ref()],
    bump,
)]
pub vault: Account<'info, Vault>,

// On subsequent calls, verify the PDA:
#[account(
    mut,
    seeds = [b"vault", user.key().as_ref()],
    bump = vault.bump, // stored bump for efficiency
)]
pub vault: Account<'info, Vault>,

Rust — CPI Token Transfer from PDA
use anchor_spl::token::{self, Transfer, Token};

pub fn withdraw_tokens(ctx: Context<Withdraw>, amount: u64) -> Result<()> {
    // PDA signer seeds — the runtime verifies these derive the PDA
    let seeds = &[
        b"vault",
        ctx.accounts.user.key.as_ref(),
        &[ctx.accounts.vault.bump],
    ];
    let signer = &[&seeds[..]];

    // CPI: call Token Program's transfer instruction
    let cpi_ctx = CpiContext::new_with_signer(
        ctx.accounts.token_program.to_account_info(),
        Transfer {
            from: ctx.accounts.vault_token_account.to_account_info(),
            to: ctx.accounts.user_token_account.to_account_info(),
            authority: ctx.accounts.vault.to_account_info(), // PDA authority
        },
        signer, // PDA seeds prove the vault authorizes this
    );
    token::transfer(cpi_ctx, amount)?;
    Ok(())
}

SPL Tokens & NFTs

Unlike Ethereum, Solana uses a single shared Token Program for ALL tokens. This means token logic is not duplicated across thousands of contracts — it's one battle-tested program managing every fungible and non-fungible token through separate accounts.

NFTs on Solana

Security — The Hard Part

The majority of Solana exploits share one root cause: insufficient account validation. Your program receives arbitrary accounts from arbitrary callers. If you don't verify every single assumption about those accounts, attackers will pass in crafted accounts that subvert your logic.

The Vulnerability Catalog

Vulnerable
// BAD: Anyone can call this, no signer verification
pub fn withdraw(ctx: Context<Withdraw>, amount: u64) -> Result<()> {
    let vault = &mut ctx.accounts.vault;
    vault.balance -= amount; // ← No check that the caller owns this vault!
    Ok(())
}

Secure
// GOOD: Anchor verifies signer + has_one constraint
#[derive(Accounts)]
pub struct Withdraw<'info> {
    #[account(
        mut,
        seeds = [b"vault", owner.key().as_ref()],
        bump = vault.bump,
        has_one = owner @ VaultError::Unauthorized, // ← verifies vault.owner == owner.key()
    )]
    pub vault: Account<'info, Vault>,
    #[account(mut)]
    pub owner: Signer<'info>, // ← must have signed the TX
}

Safe Arithmetic
// ALWAYS use checked math on-chain
vault.balance = vault.balance
    .checked_sub(amount)
    .ok_or(VaultError::Overflow)?;

user_balance = user_balance
    .checked_add(amount)
    .ok_or(VaultError::Overflow)?;

// For complex math, use u128 intermediate values
let fee = (amount as u128)
    .checked_mul(fee_bps as u128).unwrap()
    .checked_div(10_000).unwrap() as u64;

Security Checklist

Optimization

Solana programs run in a constrained environment: limited compute units, limited stack, limited transaction size. Optimized programs are cheaper, faster, and less likely to hit runtime limits.

Compute Unit Costs — Know Your Budget

Optimization Techniques

1. Store the PDA Bump

Rust
// SLOW: re-derives bump every time (~1,500 CU)
let (pda, bump) = Pubkey::find_program_address(&[b"vault", user.as_ref()], pid);

// FAST: use stored bump (~20 CU)
let pda = Pubkey::create_program_address(
    &[b"vault", user.as_ref(), &[stored_bump]],
    pid
)?;

2. Zero-Copy Deserialization for Large Accounts

Rust
// Normal: copies entire account data into a struct (~1,000 CU for big accounts)
#[account]
pub struct BigState { /* fields */ }

// Zero-copy: maps directly onto the account data buffer (near-zero CU)
#[account(zero_copy)]
#[repr(C)]  // Required: C memory layout, no padding surprises
pub struct BigState {
    pub entries: [Entry; 256],  // Fixed-size arrays, no Vec
}

// In account constraint:
#[account(mut)]
pub state: AccountLoader<'info, BigState>, // Not Account, but AccountLoader

3. Pack Multiple Values Into Fewer Bytes

Rust
// Instead of separate bools (1 byte each):
pub is_initialized: bool,  // 1 byte
pub is_locked: bool,       // 1 byte
pub is_frozen: bool,       // 1 byte = 3 bytes total

// Pack into a single u8 bitflag (1 byte total, saves rent):
pub flags: u8,  // bit 0 = initialized, bit 1 = locked, bit 2 = frozen

// Helpers:
const INITIALIZED: u8 = 1 << 0;
const LOCKED: u8 = 1 << 1;
fn is_initialized(&self) -> bool { self.flags & INITIALIZED != 0 }

4. Reduce Transaction Size

5. Minimize CPI Calls

Rust
// BAD: Two separate CPIs (~9,000 CU)
token::transfer(ctx1, amount_a)?;  // ~4,500 CU
token::transfer(ctx2, amount_b)?;  // ~4,500 CU

// BETTER: Single CPI if your architecture allows it
// Or use direct lamport manipulation for SOL transfers:
**source.try_borrow_mut_lamports()? -= amount;
**dest.try_borrow_mut_lamports()? += amount;
// This costs ~200 CU vs ~4,500 for CPI

Building Real Programs

Here is a complete, production-style vault program demonstrating every concept from this guide: accounts, PDAs, CPIs, security validation, and optimization.

Environment Setup

Shell
# Install Rust, Solana CLI, and Anchor
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"
cargo install --git https://github.com/coral-xyz/anchor avm --force
avm install latest && avm use latest

# Configure for devnet
solana config set --url devnet
solana-keygen new
solana airdrop 5

# Create project
anchor init sol-vault && cd sol-vault

Complete Vault Program

Rust — programs/sol-vault/src/lib.rs
use anchor_lang::prelude::*;
use anchor_lang::system_program;

declare_id!("YOUR_PROGRAM_ID");

#[program]
pub mod sol_vault {
    use super::*;

    pub fn initialize(ctx: Context<Initialize>) -> Result<()> {
        let vault = &mut ctx.accounts.vault;
        vault.owner = ctx.accounts.owner.key();
        vault.balance = 0;
        vault.created_at = Clock::get()?.unix_timestamp;
        vault.bump = ctx.bumps.vault;
        Ok(())
    }

    pub fn deposit(ctx: Context<Deposit>, amount: u64) -> Result<()> {
        require!(amount > 0, VaultError::ZeroAmount);

        // CPI to System Program to transfer SOL
        system_program::transfer(
            CpiContext::new(
                ctx.accounts.system_program.to_account_info(),
                system_program::Transfer {
                    from: ctx.accounts.owner.to_account_info(),
                    to: ctx.accounts.vault.to_account_info(),
                },
            ),
            amount,
        )?;

        let vault = &mut ctx.accounts.vault;
        vault.balance = vault.balance
            .checked_add(amount)
            .ok_or(VaultError::Overflow)?;
        Ok(())
    }

    pub fn withdraw(ctx: Context<Withdraw>, amount: u64) -> Result<()> {
        require!(amount > 0, VaultError::ZeroAmount);
        let vault = &mut ctx.accounts.vault;
        require!(vault.balance >= amount, VaultError::InsufficientBalance);

        vault.balance = vault.balance
            .checked_sub(amount)
            .ok_or(VaultError::Overflow)?;

        // Direct lamport transfer from PDA — cheaper than CPI
        **vault.to_account_info().try_borrow_mut_lamports()? -= amount;
        **ctx.accounts.owner.to_account_info().try_borrow_mut_lamports()? += amount;

        Ok(())
    }

    pub fn close_vault(ctx: Context<CloseVault>) -> Result<()> {
        // Anchor's close constraint handles:
        // 1. Zeroing the account data
        // 2. Transferring all lamports to owner
        // 3. Setting discriminator to closed state
        Ok(())
    }
}

// ═══════════ ACCOUNT VALIDATION STRUCTS ═══════════

#[derive(Accounts)]
pub struct Initialize<'info> {
    #[account(
        init,
        payer = owner,
        space = 8 + Vault::INIT_SPACE,
        seeds = [b"vault", owner.key().as_ref()],
        bump,
    )]
    pub vault: Account<'info, Vault>,
    #[account(mut)]
    pub owner: Signer<'info>,
    pub system_program: Program<'info, System>,
}

#[derive(Accounts)]
pub struct Deposit<'info> {
    #[account(
        mut,
        seeds = [b"vault", owner.key().as_ref()],
        bump = vault.bump,
        has_one = owner @ VaultError::Unauthorized,
    )]
    pub vault: Account<'info, Vault>,
    #[account(mut)]
    pub owner: Signer<'info>,
    pub system_program: Program<'info, System>,
}

#[derive(Accounts)]
pub struct Withdraw<'info> {
    #[account(
        mut,
        seeds = [b"vault", owner.key().as_ref()],
        bump = vault.bump,
        has_one = owner @ VaultError::Unauthorized,
    )]
    pub vault: Account<'info, Vault>,
    #[account(mut)]
    pub owner: Signer<'info>,
}

#[derive(Accounts)]
pub struct CloseVault<'info> {
    #[account(
        mut,
        seeds = [b"vault", owner.key().as_ref()],
        bump = vault.bump,
        has_one = owner @ VaultError::Unauthorized,
        close = owner, // ← zeros data + sends lamports to owner
    )]
    pub vault: Account<'info, Vault>,
    #[account(mut)]
    pub owner: Signer<'info>,
}

// ═══════════ STATE ═══════════

#[account]
#[derive(InitSpace)]
pub struct Vault {
    pub owner: Pubkey,        // 32 bytes
    pub balance: u64,        //  8 bytes
    pub created_at: i64,     //  8 bytes
    pub bump: u8,            //  1 byte  = 49 + 8 discriminator = 57 bytes
}

// ═══════════ ERRORS ═══════════

#[error_code]
pub enum VaultError {
    #[msg("Insufficient vault balance")]
    InsufficientBalance,
    #[msg("Arithmetic overflow")]
    Overflow,
    #[msg("Unauthorized: you do not own this vault")]
    Unauthorized,
    #[msg("Amount must be greater than zero")]
    ZeroAmount,
}

TypeScript Client

TypeScript
import * as anchor from "@coral-xyz/anchor";
import { PublicKey, SystemProgram } from "@solana/web3.js";

const provider = anchor.AnchorProvider.env();
anchor.setProvider(provider);
const program = anchor.workspace.SolVault;
const owner = provider.wallet.publicKey;

// Derive PDA client-side — deterministic, no RPC call needed
const [vaultPda, bump] = PublicKey.findProgramAddressSync(
    [Buffer.from("vault"), owner.toBuffer()],
    program.programId
);

// Initialize
await program.methods.initialize()
    .accounts({ vault: vaultPda, owner, systemProgram: SystemProgram.programId })
    .rpc();

// Deposit 1 SOL
await program.methods.deposit(new anchor.BN(1_000_000_000))
    .accounts({ vault: vaultPda, owner, systemProgram: SystemProgram.programId })
    .rpc();

// Withdraw 0.5 SOL
await program.methods.withdraw(new anchor.BN(500_000_000))
    .accounts({ vault: vaultPda, owner })
    .rpc();

// Read state
const vault = await program.account.vault.fetch(vaultPda);
console.log(`Balance: ${vault.balance.toNumber() / 1e9} SOL`);

Essential Resources