Essential Libraries Best Practices

Q: How many crates is too many?

If cargo tree depth hides program logic - consolidate internal helpers.

Q: Who owns lockfiles?

Committed Cargo.lock for binaries; programs follow workspace policy.

Q: Rust 1.91.1 pin?

Match rust-toolchain.toml across program and client workspaces.

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-lang and Anchor CLI at 0.32.1. Prevents IDL and macro drift.
Pin @solana/kit to 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 tree for std-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.js v1. 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 deny or 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-verify workflow.
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.

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.

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-lang and Anchor CLI at 0.32.1. Prevents IDL and macro drift.
Pin @solana/kit to 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 tree for std-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.js v1. 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 deny or 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-verify workflow.
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.

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.

Essential Libraries Best Practices

Search Documentation

Essential Libraries Best Practices