# Solana — full corpus # LLM Wiki An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions. ## How It Works The system has three layers: ``` raw/ Sources you collect (articles, transcripts, notes, PDFs) wiki/ LLM-written & maintained pages (summaries, concepts, entities, syntheses) CLAUDE.md Schema that tells the LLM how to structure everything ``` Three operations drive the workflow: | Operation | Trigger | What happens | |-----------|---------|--------------| | **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log | | **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights | | **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest | ## Quick Start 1. **Clone this repo** ```bash git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base cd my-knowledge-base ``` 2. **Customize CLAUDE.md** for your domain - Update the Purpose section with your topic - Replace the placeholder tagging taxonomy with your own categories - Adjust confidence level descriptions if needed - Everything else (workflows, page formats, linking rules) works as-is 3. **Drop sources into `raw/`** - Text files, transcripts, articles, notes — any plain text - These are immutable once added; the LLM never modifies them 4. **Tell the LLM to ingest** ``` ingest raw/my-first-source.txt ``` The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index. 5. **Ask questions** ``` What are the key differences between X and Y? ``` The LLM answers from the wiki, citing specific pages. 6. **Run health checks** ``` lint ``` The LLM audits the wiki and fixes issues. ## Directory Structure ``` . ├── CLAUDE.md # Schema — the LLM's instructions ├── raw/ # Your source documents (immutable) └── wiki/ ├── index.md # Master catalog of all pages ├── log.md # Append-only activity log ├── dashboard.md # Dataview dashboard (Obsidian) ├── analytics.md # Charts View analytics (Obsidian) ├── flashcards.md # Spaced repetition cards ├── summaries/ # One page per source document ├── concepts/ # Concept and framework pages ├── entities/ # People, tools, organizations, etc. ├── syntheses/ # Cross-cutting analyses and comparisons ├── journal/ # Research/session journal entries │ └── template.md # Journal entry template └── presentations/ # Marp slide decks ``` ## Enhancements This template includes several extras beyond the core wiki pattern: ### Dataview Dashboard (`wiki/dashboard.md`) Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin. ### Charts View Analytics (`wiki/analytics.md`) Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin. ### Mermaid Diagrams Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub. ### Marp Slides (`wiki/presentations/`) Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory. ### Research Journal (`wiki/journal/`) Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries. ### Spaced Repetition (`wiki/flashcards.md`) Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page. ### MCP Server This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically. ## Customizing for Your Domain The schema in `CLAUDE.md` is domain-agnostic. To adapt it: 1. **Purpose** — Describe your knowledge domain in one paragraph 2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`) 3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards 4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.) 5. **Journal template** — Customize `wiki/journal/template.md` for your workflow Everything else — page format, linking conventions, workflows, rules — is universal and works across domains. ## Example Domains This template works for any knowledge-intensive topic: - **Research notes** — papers, experiments, methodologies - **Book analysis** — themes, characters, author techniques - **Competitive analysis** — companies, products, market trends - **Course notes** — lectures, readings, key concepts - **Personal development** — frameworks, habits, book summaries - **Technical documentation** — APIs, architectures, design patterns - **Hobby deep-dives** — any subject you want to master ## License MIT --- title: "Knowledge Base Index" type: index updated: 2026-06-10 --- # Knowledge Base Index Master catalog of all wiki pages. Every page in the wiki must have an entry here. ## Concepts | Page | Tags | Confidence | Updated | |------|------|------------|---------| | [accounts-model](concepts/accounts-model.md) | accounts, state, rent, lamports | high | 2026-06-10 | | [transactions-and-instructions](concepts/transactions-and-instructions.md) | transactions, lookup-tables, durable-nonces | high | 2026-06-10 | | [fees-and-compute](concepts/fees-and-compute.md) | fees, priority-fees, compute-budget | high | 2026-06-10 | | [programs-and-deployment](concepts/programs-and-deployment.md) | programs, sbpf, loaders, precompiles | high | 2026-06-10 | | [pdas-and-cpi](concepts/pdas-and-cpi.md) | pda, cpi, invoke-signed, seeds | high | 2026-06-10 | | [tokens-and-spl](concepts/tokens-and-spl.md) | tokens, spl, token-2022, mint | high | 2026-06-10 | | [staking-and-consensus](concepts/staking-and-consensus.md) | staking, consensus, tower-bft, validators | high | 2026-06-10 | | [rpc-and-clusters](concepts/rpc-and-clusters.md) | rpc, json-rpc, websocket, clusters | high | 2026-06-10 | | [dev-environment](concepts/dev-environment.md) | installation, cli, quickstart, playground | high | 2026-06-10 | ## Entities | Page | Tags | Updated | |------|------|---------| | [anchor](entities/anchor.md) | anchor, framework, rust | 2026-06-10 | | [client-sdks](entities/client-sdks.md) | sdk, web3js, rust, python | 2026-06-10 | ## Summaries | Page | Source | Key Topics | Created | |------|--------|------------|---------| | [docs-catalog](summaries/docs-catalog.md) | solana.com llms.txt corpus | docs map, raw-source locator | 2026-06-10 | ## Syntheses | Page | Pages Compared | Created | |------|----------------|---------| | [agave-issues-casebook](syntheses/agave-issues-casebook.md) | 8 agave tracker issues | 2026-06-10 | ## Statistics - **Total pages**: 13 - **Concepts**: 9 - **Entities**: 2 - **Summaries**: 1 - **Syntheses**: 1 - **Sources ingested**: 111 (1 llms.txt index, 84 solana.com docs, 1 anchor readme, 25 agave issues) - **High confidence**: 12 - **Medium confidence**: 1 - **Low confidence**: 0 --- title: "The Account Model" type: concept tags: [accounts, state, rent, lamports, core-concepts] updated: 2026-06-10 confidence: high sources: [raw/llms_txt_doc-accounts.md, raw/llms_txt_doc-terminology.md] --- # The Account Model An **account** is Solana's fundamental data unit: the network stores *all* state in a key-value store where each key is a **32-byte address** and each value is an account. ## Structure Every account has the same **five fields**: - `lamports` — balance (the funds unit; like a bank account holds dollars) - `data` — arbitrary bytes (program state, or executable code) - `owner` — the program allowed to modify it - `executable` — flag marking program accounts - `rent_epoch` — legacy of the rent state machine Addresses are either ordinary public keys or PDAs ([pdas-and-cpi](pdas-and-cpi.md)). ## Account types - **Program accounts** — executable code ([programs-and-deployment](programs-and-deployment.md)) - **Data accounts** — program state (programs are stateless; state lives here) - **System accounts** — plain wallets owned by the System Program - **Sysvars** — cluster-wide state exposed as accounts ## Modification rules The runtime enforces rules on who may change lamports, data, owner, and the executable flag, plus borrow rules during execution; account loading is validated and data is (de)serialized through the BPF format on each instruction. This model is the biggest mental shift coming from EVM chains: contract code and contract storage are *separate accounts*, and every account a transaction touches must be declared up front ([transactions-and-instructions](transactions-and-instructions.md)). --- title: "Dev Environment & Quick Start" type: concept tags: [installation, cli, quickstart, playground, tooling] updated: 2026-06-10 confidence: high sources: [raw/llms_txt_doc-installation.md, raw/llms_txt_doc-quick-start.md] --- # Dev Environment & Quick Start ## Installation One command sets up the full local stack — **Rust, the Solana CLI, and Anchor** — on Windows (**via WSL**), Linux, and macOS; individual installs are documented too. Windows note: native Windows isn't the supported path; use WSL. ## Quick start without installing **Solana Playground (Solpg)** is the browser-based path: the official quick-start teaches accounts, sending transactions, and deploying programs entirely in Playground, no local setup needed — useful for first contact regardless of experience. ## Where next - Program development: [Anchor](../entities/anchor.md) or native Rust ([programs-and-deployment](programs-and-deployment.md)) - Client development: [client-sdks](../entities/client-sdks.md) - The full course/track layout (bootcamp, crashcourse, program patterns, production readiness): [docs-catalog](../summaries/docs-catalog.md) --- title: "Fees, Priority Fees & Compute Budget" type: concept tags: [fees, priority-fees, compute-units, compute-budget] updated: 2026-06-10 confidence: high sources: [raw/llms_txt_doc-fees-on-solana.md, raw/llms_txt_doc-add-priority-fees.md, raw/llms_txt_doc-transaction-fees.md] --- # Fees, Priority Fees & Compute Budget Every transaction pays a fee in SOL, with two components: ## Base fee Per-signature, compensating validators for signature verification. Split **50% burned / 50% to the validator**. ## Prioritization fee Optional; raises the chance the current leader schedules your transaction ahead of competitors: ``` priority_fee = ceil(compute_unit_price * compute_unit_limit / 1,000,000) ``` Set it by invoking the **Compute Budget Program** instructions (`ComputeBudgetInstruction` variants for unit limit and unit price) — examples exist for Kit, legacy web3.js, Rust, and Python clients. ## Compute budget Each transaction runs under a **compute unit limit**; the scheduler uses a cost model with block-level limits and fixed execution budget constants. Setting an accurate (not default) compute unit limit lowers your priority fee cost for the same `compute_unit_price` and helps scheduling. Practical consequences: - Failed transactions still pay ([transactions-and-instructions](transactions-and-instructions.md)). - CPIs have their own cost formula and serialization costs ([pdas-and-cpi](pdas-and-cpi.md)). --- title: "PDAs & Cross-Program Invocation" type: concept tags: [pda, cpi, invoke-signed, composability, seeds] updated: 2026-06-10 confidence: high sources: [raw/llms_txt_doc-program-derived-addresses.md, raw/llms_txt_doc-cross-program-invocation.md] --- # PDAs & Cross-Program Invocation ## Program Derived Addresses PDAs are 32-byte addresses **deterministically derived from a program ID + seeds**, guaranteed to be **off the Ed25519 curve** — no private key exists. Derivation: hash the seeds + program ID; if the result lands on the curve, the derivation fails and a different **bump seed** is tried (the first working bump is the *canonical bump*; `findProgramAddress` returns it). - Same seeds + program ID ⇒ same address, always (great for lookups: derive instead of store). - Only the deriving program can "sign" for its PDAs — via `invoke_signed` during CPIs. - Accounts can be *created at* PDA addresses; Anchor has first-class patterns for this. ## Cross-Program Invocation (CPI) A CPI is one program calling an instruction on another during execution — the composability primitive: any program's instructions are callable by any other program. - **Without PDA signers**: `invoke` (native Rust) / `CpiContext` (Anchor). - **With PDA signers**: `invoke_signed` with signer seeds, letting a program authorize actions for accounts it derives. - **Privileges**: an 11-step execution flow governs privilege extension (signer/writable flags propagate to callees under defined rules), reentrancy limits, and account validation. - **Costs**: CPIs have their own cost formula including serialization costs, plus account-data synchronization and return-data mechanics — relevant when budgeting compute ([fees-and-compute](fees-and-compute.md)). PDAs + CPI together are the core pattern behind escrows and authority delegation in Solana program design ([programs-and-deployment](programs-and-deployment.md)). --- title: "Programs: Execution, Deployment, Core Programs" type: concept tags: [programs, sbpf, deployment, loaders, precompiles, smart-contracts] updated: 2026-06-10 confidence: high sources: [raw/llms_txt_doc-programs.md, raw/llms_txt_doc-smart-contracts.md] --- # Programs: Execution, Deployment, Core Programs A Solana **program** (smart contract) is an account containing executable **sBPF bytecode** with its `executable` flag set. Programs are **stateless** — all mutable state lives in separate data accounts passed in via instructions ([accounts-model](accounts-model.md)). ## Execution Programs are written in Anchor or native Rust, compiled to sBPF, and run in the sBPF VM under the **compute unit model** ([fees-and-compute](fees-and-compute.md)), with syscalls for runtime services and a program cache for hot programs. ## Deployment Programs are deployed, upgraded, and verified through **loader programs** (Loader-v3 has its own instruction reference). Upgradability is a property of the loader/authority setup. Deploy-time failure modes are catalogued in the [agave-issues-casebook](../syntheses/agave-issues-casebook.md). ## Core programs Native programs every developer touches: - **System Program** — account creation, SOL transfers (with instruction reference) - **Vote / Stake / Config** — consensus and delegation plumbing - **Compute Budget** — fee/limit instructions - **Address Lookup Table** — versioned-transaction support - **ZK ElGamal Proof** — confidential-transfer support ## Precompiles Signature-verification precompiles: **Ed25519, Secp256k1, Secp256r1**. The **SPL** (Solana Program Library) sits on top — most notably the token programs ([tokens-and-spl](tokens-and-spl.md)); the de-facto dev framework is [Anchor](../entities/anchor.md). --- title: "RPC, WebSocket & Clusters" type: concept tags: [rpc, json-rpc, websocket, clusters, devnet, mainnet] updated: 2026-06-10 confidence: high sources: [raw/llms_txt_doc-rpc-endpoints.md, raw/llms_txt_doc-http-methods.md, raw/llms_txt_doc-websocket-methods.md] --- # RPC, WebSocket & Clusters ## Clusters Solana runs several validator groups (**clusters**) — each purpose-specific (mainnet-beta, testnet, devnet) with dedicated API nodes serving JSON-RPC. Individual nodes are third-party-operated; each cluster has a public endpoint (production workloads use dedicated providers). ## HTTP methods JSON-RPC 2.0 over HTTP POST. The method reference is one page per method (parameters, examples, response details), with shared response objects factored into a separate **JSON Structures Reference**. Validator-setup docs and the [agave-issues-casebook](../syntheses/agave-issues-casebook.md) cover RPC-node operation. ## WebSocket methods JSON-RPC 2.0 over a persistent WebSocket for subscriptions (account/program/signature/slot streams); each method page documents request parameters, notification payloads, and **unsubscription behavior**. Client reports of mid-use disconnections exist (see casebook) — production consumers should auto-reconnect and resubscribe. Submitting transactions and priority-fee mechanics: [transactions-and-instructions](transactions-and-instructions.md), [fees-and-compute](fees-and-compute.md). Client libraries: [client-sdks](../entities/client-sdks.md). --- title: "Staking & Consensus" type: concept tags: [staking, delegation, consensus, tower-bft, poh, validators] updated: 2026-06-10 confidence: high sources: [raw/llms_txt_doc-staking.md, raw/llms_txt_doc-what-is-staking.md, raw/llms_txt_doc-consensus.md] --- # Staking & Consensus ## Staking Stake SOL by **delegating to validators** who process transactions and run the network — a shared-risk/shared-reward model paying roughly **5–7% annual rewards** (in SOL terms; the docs explicitly make no claim about monetary value). Delegation helps secure the network; rewards favor tokens delegated for longer periods. ## Consensus: Solana vs Ethereum Both are PoS, but throughput differs dramatically (the learning docs cite ~30 TPS Ethereum vs ~4000 TPS Solana) because of how consensus is structured: - **Ethereum** uses **Gasper** = Casper-FFG (finality gadget) + LMD-GHOST (fork choice via attestation voting), layered on Nakamoto-style block production inherited from its PoW origin (longest-chain rule; the Merge was Aug 2022). - **Solana** uses **Tower BFT** supporting PoS — its answer to both finality and fork choice, built around Proof of History as a clock (covered in the course's consensus chapter). ## Operating a validator Validator setup guidance targets **testnet first** (stress-tested daily, good practice ground), then operational best practices before mainnet; the same guide adapts to mainnet/devnet. Real-world operational failure modes (snapshots, identity swaps, kernel issues) are catalogued in the [agave-issues-casebook](../syntheses/agave-issues-casebook.md). Cluster/RPC layout: [rpc-and-clusters](rpc-and-clusters.md). --- title: "Tokens: SPL Token & Token Extensions (Token-2022)" type: concept tags: [tokens, spl, token-2022, token-extensions, mint, nft] updated: 2026-06-10 confidence: high sources: [raw/llms_txt_doc-introduction-to-tokens.md, raw/llms_txt_doc-token-basics.md, raw/llms_txt_doc-token-extensions.md] --- # Tokens: SPL Token & Token Extensions (Token-2022) SOL is the native currency; **tokens** represent everything else — stablecoins (USDC), project tokens, NFTs. ## SPL Token basics The basics shared by the original **Token Program** and the **Token Extensions Program (Token-2022)**: - **Create a token mint** — configure decimals, mint authority, freeze authority. - Token *accounts* hold balances of a mint per owner; basic instructions cover minting, transferring, and burning. - **Metadata** (names, images) is handled via Metaplex — the official docs defer to Metaplex documentation for attaching metadata to SPL tokens. ## Token Extensions (Token-2022) Optional per-mint / per-token-account features added as extra instructions ("extensions"). Each extension adds specific state, generally **initialized at mint/account creation** — you enable the extensions you want simultaneously when initializing. This is the modern path for transfer hooks, confidential transfers, and other policy features; the [docs-catalog](../summaries/docs-catalog.md) lists per-topic pages (e.g. `transfer-hook`). Account-model context (mints and token accounts are just data accounts owned by the token program): [accounts-model](accounts-model.md). --- title: "Transactions, Versioned Formats & Durable Nonces" type: concept tags: [transactions, instructions, lookup-tables, durable-nonces, blockhash] updated: 2026-06-10 confidence: high sources: [raw/llms_txt_doc-transactions.md, raw/llms_txt_doc-lookup-tables.md, raw/llms_txt_doc-durable-nonces.md] --- # Transactions, Versioned Formats & Durable Nonces ## Anatomy A transaction = one or more **instructions** + **signatures** of authorizing accounts + a **recent blockhash**. Execution is **atomic**: if any instruction fails, the whole transaction reverts — but **fees are still charged on failure**. The message format packs a header, account addresses, the blockhash, and compiled instructions into a size-budgeted binary encoding; processing runs an 8-stage pipeline from receive to commit. ## Versioned transactions & Address Lookup Tables Legacy vs **V0** format: V0 adds **Address Lookup Tables (ALTs)** — onchain tables that compress account addresses so a transaction can reference far more accounts than fit in the size budget. Workflow: create a lookup table, add addresses to it, fetch it, then build a V0 transaction that resolves addresses through it. ## Durable nonces (offline signing) A recent blockhash expires quickly, which breaks offline/delayed signing. **Durable nonces** replace the blockhash with a value stored in a **nonce account**: the transaction's first instruction advances the nonce, giving replay protection (the double-spend defense recent blockhashes normally provide) without the expiry window. Used for offline signing, custody flows, and scheduled transactions. Fees and prioritization: [fees-and-compute](fees-and-compute.md). RPC submission paths: [rpc-and-clusters](rpc-and-clusters.md). --- title: "Anchor (Solana Program Framework)" type: entity tags: [anchor, framework, rust, programs, tooling] updated: 2026-06-10 confidence: high sources: [raw/llms_txt_doc-anchor-framework.md, raw/github_doc-readme-md.md] --- # Anchor (Solana Program Framework) **Anchor** is the dominant framework for writing Solana programs (smart contracts) — it streamlines writing, testing, deploying, and interacting with programs, and reduces vulnerability surface through built-in security features (account validation, discriminators, constraint macros). - Docs/tutorials: anchor-lang.com; the official Solana docs ship an Anchor installation + quickstart track. - Repo: `solana-foundation/anchor` (community forks like otter-sec maintain audited variants). - Installed as part of the standard one-command dev setup ([dev-environment](../concepts/dev-environment.md)). ## Why it matters Native Rust programs hand-roll account deserialization, ownership checks, and signer validation — historically the major source of program exploits. Anchor turns these into declarative constraints, and its `CpiContext` pattern wraps `invoke`/`invoke_signed` for CPIs and PDA signing ([pdas-and-cpi](../concepts/pdas-and-cpi.md)). ## Ecosystem position Anchor defines the de-facto IDL convention that client SDKs ([client-sdks](client-sdks.md)) and tooling consume; "Anchor vs native Rust" is the standard first decision in [programs-and-deployment](../concepts/programs-and-deployment.md). --- title: "Client SDKs: JS/TS, Rust, Python" type: entity tags: [sdk, web3js, kit, rust, python, clients] updated: 2026-06-10 confidence: high sources: [raw/llms_txt_doc-javascript-typescript-sdk.md, raw/llms_txt_doc-rust-sdk.md, raw/llms_txt_doc-python-sdk.md] --- # Client SDKs: JS/TS, Rust, Python ## JavaScript / TypeScript `@solana/client` — the headless Solana runtime bundling **RPC, wallets, transactions, and subscriptions in one store**; the docs' package tables cover the modern Kit-era packages alongside legacy web3.js (fee/priority-fee examples in the docs are shown in both "Kit" and "Legacy" variants — see [fees-and-compute](../concepts/fees-and-compute.md)). React integration comes via Solana React hooks (and a Next.js hooks guide). ## Rust Client crates led by `solana-sdk` (core SDK), each with docs + GitHub links in the official crate table. Rust doubles as the program-side language ([programs-and-deployment](../concepts/programs-and-deployment.md)). ## Python `solana.py` — the base Python library for building transactions and talking to the JSON RPC API ([rpc-and-clusters](../concepts/rpc-and-clusters.md)), paired in the docs with a second helper package. ## Choosing Frontend/dapp → JS/TS; bots and infra → Rust or Python; programs themselves → Rust (with [Anchor](anchor.md)). All clients ultimately speak the same JSON-RPC HTTP/WebSocket surface. --- title: "Activity Log" type: log --- # Activity Log Append-only record of all wiki changes. ## Format Each entry follows this format: ``` ### YYYY-MM-DD HH:MM — [Action Type] - **Source/Trigger**: what initiated the action - **Pages created**: list of new pages - **Pages updated**: list of updated pages - **Notes**: any contradictions flagged, decisions made ``` --- ### 2026-04-08 00:00 — Setup - **Source/Trigger**: Repository initialized - **Pages created**: index.md, log.md, dashboard.md, analytics.md, flashcards.md - **Pages updated**: none - **Notes**: Empty knowledge base ready for first source ingestion ### 2026-06-10 00:00 — Initial curation (medium rung) - **Source/Trigger**: 111 raw sources (solana.com llms.txt + anchor readme + agave issues) - **Pages created**: 9 concepts, 2 entities (anchor, client-sdks), 1 summary (docs-catalog), 1 synthesis (agave-issues-casebook) - **Pages updated**: index.md - **Notes**: Medium rung. Payments/x402, EVM-migration, and vertical tracks left as raw-only, mapped in docs-catalog. agave-issues-casebook confidence:medium (community reports). --- ## 2026-06-10 — removed Obsidian scaffolding from the served wiki Deleted `analytics.md`, `dashboard.md`, `flashcards.md` (Obsidian plugin pages — Dataview/Charts View/Spaced Repetition markup, unusable when served as plain Markdown to agents) and the `journal/` scaffold (template only). `CLAUDE.md` directory layout updated: production/planning material lives at repo root, never under `wiki/` (everything under `wiki/` is served publicly). --- title: "Official Docs Catalog (solana.com)" type: summary tags: [catalog, docs, map, reference] updated: 2026-06-10 confidence: high sources: [raw/llms_txt-llms-txt-index.md, raw/llms_txt_doc-terminology.md] --- # Official Docs Catalog (solana.com) Map of the solana.com corpus (published via llms.txt; 84 pages mirrored as `raw/llms_txt_doc-.md`). Use it to locate raw sources; the wiki distills the core. | Area | Raw slugs (selection) | Wiki coverage | |---|---|---| | Core concepts | accounts, transactions, programs, program-derived-addresses, cross-program-invocation, fees-on-solana, terminology | [accounts-model](../concepts/accounts-model.md), [transactions-and-instructions](../concepts/transactions-and-instructions.md), [programs-and-deployment](../concepts/programs-and-deployment.md), [pdas-and-cpi](../concepts/pdas-and-cpi.md), [fees-and-compute](../concepts/fees-and-compute.md) | | Tokens | introduction-to-tokens, token-basics, token-extensions, transfer-hook, create-mint, what-are-nfts | [tokens-and-spl](../concepts/tokens-and-spl.md) | | Learning course | what-is-solana, what-is-a-wallet, what-is-staking, transaction-fees, consensus, sending-and-receiving-sol, staying-safe | [staking-and-consensus](../concepts/staking-and-consensus.md) + course chapters in raw/ | | Dev setup & SDKs | installation, quick-start, anchor-framework, rust-sdk, javascript-typescript-sdk, python-sdk, solana-client, solana-react-hooks, next-js-solana-react-hooks, solana-web3-compat | [dev-environment](../concepts/dev-environment.md), [anchor](../entities/anchor.md), [client-sdks](../entities/client-sdks.md) | | RPC | rpc-endpoints, http-methods, websocket-methods | [rpc-and-clusters](../concepts/rpc-and-clusters.md) | | Cookbook how-tos | create-account, create-keypair, get-balance, send-sol, add-priority-fees, lookup-tables, durable-nonces | [transactions-and-instructions](../concepts/transactions-and-instructions.md), [fees-and-compute](../concepts/fees-and-compute.md) | | Payments & x402 | payments-overview, how-payments-work, accept-payments, send-payments, solana-pay, commerce-kit, introduction-to-x402, build-an-x402-facilitator, kora, eip-2612 | raw/ only (commerce vertical) | | EVM developers | solana-for-evm-developers, client-differences, erc20/erc721/erc3643/erc4337/erc4626 comparisons | raw/ only (migration vertical) | | Verticals & tracks | depin, depin-getting-started, game-development-quickstart, solana-gaming-sdks, ai-tools-on-solana, actions-and-blinks, attestations, bootcamp, solana-crashcourse, program-patterns, production-readiness, shipping-production | raw/ only | | Validators | validator-setup, staking | [staking-and-consensus](../concepts/staking-and-consensus.md), [agave-issues-casebook](../syntheses/agave-issues-casebook.md) | --- title: "Agave Validator & Tooling Issues Casebook" type: synthesis tags: [agave, validator, operations, troubleshooting, casebook] updated: 2026-06-10 confidence: medium sources: [raw/github_issue-validator-wont-start-on-kernel-5-15-with-agave-v3-0-0.md, raw/github_issue-incremental-snapshot-cleanup-is-not-working-as-expected.md, raw/github_issue-gossip-set-identity-may-hang-indefinitely-due-to-rwlock-cont.md, raw/github_issue-long-blockstore-open-times-for-secondary-process.md, raw/github_issue-solana-1-18-8-hangs-when-deploying.md, raw/github_issue-poh-performance-degradation-with-rust-1-87.md, raw/github_issue-rpc-node-memory-leak-frequently.md, raw/github_issue-websocket-disconnection-while-actively-using-websocket.md] --- # Agave Validator & Tooling Issues Casebook High-engagement reports from the `anza-xyz/agave` tracker. Confidence medium — community reports; verify against current releases. ## Validator operations - **Won't start on kernel 5.15 (agave v3.0.0)** — `IO error: Resource temporarily unavailable (os error 11)` unpacking genesis/snapshot on Ubuntu 22's 5.15 kernel; resolved by upgrading to kernel 6.8. Lesson: kernel version is part of the supported stack. - **Incremental snapshot cleanup retains stale files** — with `--maximum-incremental-snapshots-to-retain 2`, a stale incremental tied to the previous full snapshot survives, inflating disk usage until the device fills and crashes the node. Watch disk headroom around full-snapshot creation. - **`set-identity` can hang indefinitely** — hot-swapping validator identity stalls inside `ClusterInfo::set_keypair` (RwLock contention), roughly once per 50–100 automated runs. Failover automation needs a timeout/retry around it. - **Secondary-process blockstore opens take hours** — `agave-ledger-tool` (e.g. `bounds`) opening the blockstore while the validator runs took 6,000–9,800s in reports. Don't put ledger-tool in latency-sensitive paths on a live node. - **RPC node memory leak** — recurring reports of RPC-serving nodes leaking memory over time; operators typically mitigate with monitored restarts. ## Developer-facing - **`solana program deploy` hangs (v1.18.8)** — deploy stalls resending transactions without the previous 5-retry bail-out; the buffer-account seed phrase is never printed, leaving `solana program close` as the cleanup path. - **WebSocket disconnections during active use** — subscriptions drop mid-stream; build auto-reconnect/resubscribe into clients ([rpc-and-clusters](../concepts/rpc-and-clusters.md)). ## Upstream engineering - **PoH performance regression on Rust 1.87** — `solana_sha256_hasher::hashv` codegen changed (extra dynamic calls vs 1.86's single `sha2` compress call), degrading Proof-of-History throughput and blocking compiler upgrades — an example of how performance-critical the PoH loop is.