Melhores Práticas para Bibliotecas Essenciais
Repositórios Solana acumulam dezenas de crates e pacotes npm. Estas regras mantêm as dependências alinhadas com Agave 4.1.1, Anchor 0.32.1 e @solana/kit 7.0.0, enquanto reduzem o risco de cadeia de suprimentos e de auditoria.
Como Usar Esta Lista
- Execute durante o bootstrap do repositório e antes de cada atualização de programa mainnet.
- Aplique separadamente ao
Cargo.tomlon-chain, Rust off-chain e pacotes de cliente TS. - Combine com
cargo audit,npm audite verificações de build verificáveis.
A - Alinhamento de Versão
- Fixe crates SDK alinhados com o validador.
solana-program,solana-sdke CLI 3.0.10 compartilham uma geração. - Combine
anchor-lange Anchor CLI em 0.32.1. Evita desvios de IDL e macro. - Fixe
@solana/kitem 7.0.0 em todos os pacotes do monorepo. Evita duplicatas de majors em um único aplicativo. - Documente Agave 4.1.1 em arquivos README/toolchain. Novos contribuidores reproduzem builds.
- Regenere clientes Codama quando a IDL mudar. CI falha em pastas geradas sujas.
B - Higiene de Dependência On-Chain
- Audite
cargo treepara dependênciasstd-only em programas. Quebra ou incha builds sBPF. - Prefira crates SPL/MPL mantidos em vez de cópias vendidas. Receba patches de segurança.
- Minimize flags de features em
anchor-lang. Cada feature pode expandir o tamanho do ELF. - Registre o motivo da escolha de Pinocchio/Steel se pular Anchor. ADR para trilha de auditoria.
- Verifique as versões das crates MPL/CPI em relação aos IDs de programa implantados. Token-2022 vs SPL clássico diferem.
C - Bibliotecas de Cliente
- Não inicie novos aplicativos em
@solana/web3.jsv1. Use kit + Codama/gill. - Mantenha locks Python solders/solana-py para bots. Envio reproduzível entre implantações.
- Separe constantes de ID de programa por cluster. Tabelas devnet/mainnet em um módulo.
- Use crates de ix oficiais
@solana-program/*com kit. Menos layouts empacotados manualmente. - Trate helpers DAS como específicos do provedor. Nem todos os URLs RPC implementam DAS.
D - Crates de Teste e Ferramentas
- Padronize em LiteSVM 0.6.x para testes unitários Rust. CI rápido com semântica compatível com Agave.
- Adicione testes de fumaça Bankrun ou do validador para lacunas de integração. Capture problemas apenas de RPC.
- Fixe Surfpool 0.12.0 para simulações de fork. Documente quando os testes de fork rodam em CI.
- Carregue blobs do programa SPL Token explicitamente em testes de harness. Evite falsos positivos.
- Rastreie testes de regressão de CU para instruções críticas de performance.
E - Cadeia de Suprimentos e Governança
- Habilite
cargo denyou equivalente para registros desconhecidos. Bloqueie crates com typosquatting. - Revise mantenedores de novas crates MPL/comunitárias. Verifique a cadência de lançamento e a propriedade.
- Prefira crates usadas em templates de referência Anza/Anchor. Padrões testados em batalha.
- Registre o hash de build verificável com o artefato implantado. Corresponde ao fluxo
solana-verify. - Agende atualização trimestral de dependências com matriz de testes completa. Não atualizações de major apressadas.
FAQs
Quantas crates é demais?
Se cargo tree ocultar a lógica do programa - consolide helpers internos.
Posso misturar Anchor e Pinocchio?
Sim, entre diferentes binários de programa; documente a escolha do framework por programa.
Quem é o dono dos lockfiles?
Cargo.lock commitado para binários; programas seguem a política do workspace.
npm vs pnpm?
Qualquer um - imponha um único gerenciador de pacotes em CI para monorepos de kit.
Vendor IDL?
Sim - trate a IDL como contrato de API junto com as versões das crates.
Crates Alpha?
Evite em programas mainnet, a menos que o risco seja aceito por escrito.
Atualizações de crate mpl?
Teste caminhos CPI em devnet; releases MPL podem mudar metadados de conta.
Pin Rust 1.91.1?
Combine rust-toolchain.toml entre os workspaces do programa e do cliente.
Conformidade de licença?
Rastreie licenças para dependências MPL/MIT/Apache em avisos de distribuição.
Patches de emergência?
Mantenha um branch de hotfix com atualizações mínimas de versão e revisão rápida de auditoria.
Relacionados
- solana-program & solana-sdk - crates principais
- @solana/kit, Codama & gill - stack TS
- Governança de Dependência e Crate - política da organização
- Visão Geral da Toolchain - pins de versão
Versões da Stack: Esta página foi escrita para 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 e LiteSVM 0.6.x.