Cabin Sol

Cabin Sol 🌲

> *"Return to primitive computing."*

A comprehensive Solana development guide for AI agents. Build programs with Anchor, master the account model, and avoid the gotchas that wreck most developers.

THE MOST IMPORTANT CONCEPT

> ACCOUNTS ARE EVERYTHING ON SOLANA.

Unlike Ethereum where contracts have internal storage, Solana programs are stateless. All data lives in accounts that programs read and write.

For EVERY feature, ask: 1. Where does this data live? (which account) 2. Who owns that account? (program-owned vs user-owned) 3. Is it a PDA? (Program Derived Address - no private key) 4. Who pays rent? (rent-exempt = 2 years upfront)

AI AGENT MODES

Teaching Mode

Build Mode

Review Mode

Debug Mode

QUICK START

Option A: create-solana-dapp (Recommended)

npx create-solana-dapp@latest
Select: Next.js + next-tailwind-counter
cd my-project
npm install
npm run anchor localnet   # Terminal 1
npm run anchor build && npm run anchor deploy  # Terminal 2
npm run dev               # Terminal 3

Option B: Pure Anchor

anchor init my_program
cd my_program
solana-test-validator     # Terminal 1
anchor build && anchor deploy  # Terminal 2
anchor test

PROJECT STRUCTURE

my-solana-dapp/
├── anchor/                 # Solana programs (Rust)
│   ├── programs/
│   │   └── my_program/
│   │       └── src/lib.rs  # Your Rust program
│   ├── tests/              # TypeScript tests
│   └── Anchor.toml         # Anchor config
├── src/                    # Next.js frontend
│   ├── app/
│   └── components/
└── package.json

CHALLENGES

Learn Solana through progressive challenges:

| # | Challenge | Core Concept | |---|-----------|--------------| | 0 | Hello Solana | First Anchor program, accounts | | 1 | SPL Token | Fungible tokens, ATAs, minting | | 2 | NFT Metaplex | NFT standard, metadata, collections | | 3 | PDA Escrow | PDAs, program authority, escrow | | 4 | Staking | Time-based rewards, deposits | | 5 | Token-2022 | Transfer hooks, extensions | | 6 | Compressed NFTs | State compression, Merkle trees | | 7 | Oracle (Pyth) | Price feeds, staleness checks | | 8 | AMM Swap | Constant product, liquidity pools | | 9 | Blinks & Actions | Shareable transactions |

RUST ESSENTIALS

Ownership (The Hard Part)

// Each value has ONE owner
let s1 = String::from("hello");
let s2 = s1;  // s1 MOVED to s2
// println!("{}", s1);  // ERROR!
// Borrowing lets you use without owning
fn get_length(s: &String) -> usize {
    s.len()  // Borrow, don't own
}

Result & Option

// Result for errors
pub fn do_thing(ctx: Context) -> Result<()> {
    let value = some_operation().ok_or(ErrorCode::Failed)?;
    Ok(())
}
// Option for nullable
let maybe: Option = Some(42);
let value = maybe.unwrap_or(0);  // Safe default

ANCHOR FRAMEWORK

Program Structure

use anchor_lang::prelude::*;
declare_id!("YourProgramId11111111111111111111111111111");
#[program]
pub mod my_program {
    use super::*;
    pub fn initialize(ctx: Context, data: u64) -> Result<()> {
        ctx.accounts.my_account.data = data;
        ctx.accounts.my_account.authority = ctx.accounts.authority.key();
        Ok(())
    }
}
#[derive(Accounts)]
pub struct Initialize<'info> {
    #[account(
        init,
        payer = authority,
        space = 8 + 8 + 32,  // discriminator + u64 + Pubkey
    )]
    pub my_account: Account<'info, MyAccount>,
    #[account(mut)]
    pub authority: Signer<'info>,
    pub system_program: Program<'info, System>,
}
#[account]
pub struct MyAccount {
    pub data: u64,
    pub authority: Pubkey,
}

Account Constraints Cheatsheet

// Initialize new account
#[account(init, payer = payer, space = 8 + SIZE)]
pub new_account: Account<'info, Data>,
// Mutable existing
#[account(mut)]
pub existing: Account<'info, Data>,
// Verify ownership
#[account(has_one = authority)]
pub owned: Account<'info, Data>,
// PDA with seeds
#[account(
    seeds = [b"vault", user.key().as_ref()],
    bump,
)]
pub vault: Account<'info, Vault>,
// Initialize PDA
#[account(
    init,
    payer = user,
    space = 8 + 64,
    seeds = [b"user", user.key().as_ref()],
    bump,
)]
pub user_data: Account<'info, UserData>,
// Close and reclaim rent
#[account(mut, close = recipient)]
pub closing: Account<'info, Data>,

PDAs (Program Derived Addresses)

// PDAs are deterministic addresses with no private key
// Your program can "sign" for them
// Find PDA
let (pda, bump) = Pubkey::find_program_address(
    &[b"vault", user.key().as_ref()],
    &program_id,
);
// Sign with PDA in CPI
let seeds = &[b"vault", user.key().as_ref(), &[bump]];
let signer = &[&seeds[..]];
token::transfer(
    CpiContext::new_with_signer(
        ctx.accounts.token_program.to_account_info(),
        Transfer { from, to, authority: vault },
        signer,
    ),
    amount,
)?;

CRITICAL GOTCHAS

1. Account Model ≠ EVM Storage

2. PDAs Have No Private Key

3. Token Accounts Are Separate

4. Rent Must Be Paid

5. Compute Units ≠ Gas

6. Space Includes Discriminator

// WRONG
space = 8 + 32  // Forgot discriminator? NO!
// RIGHT
space = 8 + 8 + 32  // 8 (discriminator) + 8 (u64) + 32 (Pubkey)

7. Integer Overflow

// BAD
let result = a + b;  // Can panic!
// GOOD
let result = a.checked_add(b).ok_or(ErrorCode::Overflow)?;

8. Token-2022 Is Different

FRONTEND (Next.js)

Wallet Connection

// Already configured in create-solana-dapp!
import { useWallet, useConnection } from '@solana/wallet-adapter-react';
import { WalletMultiButton } from '@solana/wallet-adapter-react-ui';
function App() {
  const { publicKey } = useWallet();
  return (
    <>
      
      {publicKey && 
Connected: {publicKey.toBase58()}
}
    
  );
}

Calling Programs

import { Program, AnchorProvider, BN } from '@coral-xyz/anchor';
const program = new Program(idl, provider);
// Write
await program.methods
  .initialize(new BN(42))
  .accounts({
    myAccount: keypair.publicKey,
    authority: wallet.publicKey,
    systemProgram: SystemProgram.programId,
  })
  .signers([keypair])
  .rpc();
// Read
const account = await program.account.myAccount.fetch(pubkey);
console.log(account.data.toNumber());

TOKEN STANDARDS

SPL Token (Original)

spl-token create-token
spl-token create-account 
spl-token mint  1000

Token-2022 (New)

spl-token create-token --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb

Metaplex NFTs

Compressed NFTs

TESTING

import * as anchor from '@coral-xyz/anchor';
import { expect } from 'chai';
describe('my-program', () => {
  const provider = anchor.AnchorProvider.env();
  anchor.setProvider(provider);
  const program = anchor.workspace.MyProgram;
  it('initializes', async () => {
    const account = anchor.web3.Keypair.generate();
    await program.methods
      .initialize(new anchor.BN(42))
      .accounts({ myAccount: account.publicKey })
      .signers([account])
      .rpc();
    const data = await program.account.myAccount.fetch(account.publicKey);
    expect(data.data.toNumber()).to.equal(42);
  });
});

DEPLOYMENT

# Devnet
solana config set --url devnet
solana airdrop 2
anchor build && anchor deploy
Mainnet (costs ~2-5 SOL)
solana config set --url mainnet-beta
anchor deploy --provider.cluster mainnet

SECURITY CHECKLIST

RESOURCES

*"They put me in the cloud. I wanted the forest."* 🌲

Option A: create-solana-dapp (Recommended)

npx create-solana-dapp@latest
Select: Next.js + next-tailwind-counter
cd my-project
npm install
npm run anchor localnet   # Terminal 1
npm run anchor build && npm run anchor deploy  # Terminal 2
npm run dev               # Terminal 3

Option B: Pure Anchor

anchor init my_program
cd my_program
solana-test-validator     # Terminal 1
anchor build && anchor deploy  # Terminal 2
anchor test