Essential Libraries Best Practices
Solana repos accumulate dozens of crates and npm packages. These rules keep dependencies aligned with Agave 4.1.1, Anchor 0.32.1, and @solana/kit 7.0.0 while reducing supply-chain and audit risk.
How to Use This List
- Run during repo bootstrap and before every mainnet program upgrade.
- Apply separately to on-chain
Cargo.toml, off-chain Rust, and TS client packages. - Pair with
cargo audit,npm audit, and verifiable build checks.
A - Version Alignment
- Pin validator-aligned SDK crates.
solana-program,solana-sdk, and CLI 3.0.10 share one generation. - Match
anchor-langand Anchor CLI at 0.32.1. Prevents IDL and macro drift. - Pin
@solana/kitto 7.0.0 across monorepo packages. Avoid duplicate majors in one app. - Document Agave 4.1.1 in README/toolchain files. New contributors reproduce builds.
- Regenerate Codama clients when IDL changes. CI fails on dirty generated folders.
B - On-Chain Dependency Hygiene
- Audit
cargo treeforstd-only deps in programs. Breaks or bloats sBPF builds. - Prefer maintained SPL/MPL crates over vendored copies. Receive security patches.
- Minimize features flags on
anchor-lang. Each feature can expand ELF size. - Record why Pinocchio/Steel chosen if skipping Anchor. ADR for audit trail.
- Verify MPL/CPI crate versions against deployed program IDs. Token-2022 vs classic SPL differ.
C - Client Libraries
- Do not start new apps on
@solana/web3.jsv1. Use kit + Codama/gill. - Keep Python solders/solana-py locks for bots. Reproducible sends across deploys.
- Separate program ID constants per cluster. Devnet/mainnet tables in one module.
- Use official
@solana-program/*ix crates with kit. Fewer hand-packed layouts. - Treat DAS helpers as provider-specific. Not all RPC URLs implement DAS.
D - Testing & Tooling Crates
- Standardize on LiteSVM 0.6.x for Rust unit tests. Fast CI with Agave-compatible semantics.
- Add Bankrun or validator smoke tests for integration gaps. Catch RPC-only issues.
- Pin Surfpool 0.12.0 for fork simulations. Document when fork tests run in CI.
- Load SPL Token program blobs explicitly in harness tests. Avoid false positives.
- Track CU regression tests for performance-critical instructions.
E - Supply Chain & Governance
- Enable
cargo denyor equivalent for unknown registries. Block typosquat crates. - Review new MPL/community crate maintainers. Check release cadence and ownership.
- Prefer crates used in Anza/Anchor reference templates. Battle-tested defaults.
- Record verifiable build hash with deployed artifact. Matches
solana-verifyworkflow. - Schedule quarterly dependency refresh with full test matrix. Not drive-by major bumps.
FAQs
How many crates is too many?
If cargo tree depth hides program logic - consolidate internal helpers.
Can I mix Anchor and Pinocchio?
Yes across different program binaries; document per-program framework choice.
Who owns lockfiles?
Committed Cargo.lock for binaries; programs follow workspace policy.
npm vs pnpm?
Either - enforce single package manager in CI for kit monorepos.
Vendor IDL?
Yes - treat IDL as API contract alongside crate versions.
Alpha crates?
Avoid on mainnet programs unless risk accepted in writing.
mpl crate updates?
Test CPI paths on devnet; MPL releases can change account metas.
Rust 1.91.1 pin?
Match rust-toolchain.toml across program and client workspaces.
License compliance?
Track licenses for MPL/MIT/Apache deps in distribution notices.
Emergency patches?
Maintain hotfix branch with minimal version bumps and fast audit review.
Related
- solana-program & solana-sdk - core crates
- @solana/kit, Codama & gill - TS stack
- Dependency & Crate Governance - org policy
- Toolchain Overview - version pins
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.