Architecture Best Practices
Design implications of each component for builders.
How to Use This List
- Review before mainnet launch and after incidents
- Check off items per release train
A - Foundations
- Pin Agave 4.1.1 toolchain. CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1 aligned in CI.
- Use @solana/kit 7.0.0 for new clients. Avoid web3.js v1 for greenfield work.
- Match RPC, wallet, and explorer cluster. Prevent false "account not found" errors.
B - Reliability
- Confirm at
confirmedorfinalized. Do not treatprocessedas final. - Refresh blockhash on retry. Expired transactions are dropped silently.
- Simulate and read logs. Decode program errors before resubmitting.
C - Economics & Security
- Budget priority fees under congestion. Local fee markets need Compute Budget instructions.
- Validate signers and account owners. Missing constraints are critical vulnerabilities.
- Close unused accounts to reclaim rent. Return lamports to users when lifecycle ends.
FAQs
How does this apply on Agave 4.1.1?
Agave 4.1.1 underpins every item—pin CLI 3.0.10, Anchor 0.32.1, and validator version together in CI.
What Solana CLI version should I use?
Use Solana CLI 3.0.10, which pairs with Agave 4.1.1. Install with agave-install init 4.1.1 (or your team's pin file), then verify with solana --version and agave-install --version.
Should I use @solana/kit or web3.js?
Use @solana/kit 7.0.0 for new TypeScript—typed RPC methods, smaller API surface, and examples on this page already use Kit. Keep web3.js only for legacy codebases; migrate RPC calls and transaction building incrementally.
What commitment level is recommended?
Use confirmed for dashboards and finalized before withdrawals or cross-system callbacks.
How do I debug related failures?
Follow checklist item B: simulate txs, read logMessages, and decode program errors before retry.
Does this work on devnet?
Yes—point CLI and RPC to https://api.devnet.solana.com. Behavior matches mainnet; only account data and economics differ.
How do compute units affect this?
Checklist C covers priority fees and CU—always set Compute Budget instructions under congestion.
What is the Anchor 0.32.1 pattern?
Anchor 0.32.1 uses #[program], Context<T>, and #[derive(Accounts)] with explicit mut/signer constraints—run anchor build and anchor test on 0.32.1 via avm use 0.32.1.
How do I test with Surfpool 0.12.0?
Start Surfpool 0.12.0, point RPC to its port, and run anchor test or client integration scripts against forked accounts.
Can LiteSVM 0.6.x cover this?
Use LiteSVM for fast program checks; use Surfpool when you need mainnet-fork realism.
What changed in the Agave era?
The validator client rebranded to Agave (4.1.1), CLI 3.0.10 aligns with it, and Alpenglow work is changing finality—pin versions and read release notes each upgrade.
Where do I find related RPC methods?
simulateTransaction, getTransaction, getSignatureStatuses, and getAccountInfo cover most checklist validations.
Related
- See sibling pages in this section for topic-specific depth.
Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.