Essential Crates

Desenvolver na Solana significa montar uma pilha de crates e bibliotecas, não memorizar um único framework. Programas on-chain, clientes off-chain, serialização, assets digitais e harnesses de teste possuem cada um sua camada. Assim que você identificar a qual camada uma dependência pertence, os grafos do Cargo e npm deixarão de parecer ruído e se tornarão um mapa deliberado ao qual você pode se fixar em Agave 4.1.1, Anchor 0.32.1, Rust 1.91.1 e @solana/kit 7.0.0.

Aprofundamentos nesta seção exploram pares e pilhas: solana-program & solana-sdk, anchor-lang & anchor-spl, borsh & bytemuck, pinocchio & steel, mpl-core & mpl-token-metadata, @solana/kit, Codama & gill e litesvm, mollusk & solana-bankrun. Esta página se situa abaixo: como as peças se encaixam, quando cada camada é justificada e como as equipes evitam misturar gerações em um monorepo.

Resumo

• Bibliotecas essenciais da Solana são um mapa de dependência em camadas - crates de programa/SDK da plataforma, frameworks opcionais (Anchor ou Pinocchio/Steel), serialização, crates de produto SPL/MPL, clientes TypeScript (kit/Codama/gill) e harnesses de teste - e cada camada resolve um problema diferente.
• Por que Importa: Escolhas de camada erradas causam falhas de build sBPF, inchaço de CU, desvios de IDL, bugs de encode em mainnet e CI lento; um mapa claro permite escolher pilhas de produto padrão, caminhos nativos críticos para CU e testes correspondentes sem fazer cargo-culting de cada crate em cada binário.
• Conceitos Chave: solana-program vs solana-sdk, Anchor 0.32.1, Pinocchio/Steel, Borsh vs bytemuck, SPL e Metaplex, @solana/kit / Codama / gill, alinhamento de versão.
• Quando Usar: Bootstrapping de um monorepo, escolha entre frameworks nativos vs Anchor vs leves, design de codegen de cliente, padronização de harnesses de teste, ou revisão de higiene de dependência antes de um upgrade de mainnet.
• Limitações / Trade-offs: Mais camadas significam mais pins e superfície de auditoria; frameworks trocam CU e tamanho de ELF por velocidade; zero-copy e pilhas leves exigem disciplina de validação mais rigorosa; harnesses de teste diferem em fidelidade de validadores completos.
• Tópicos Relacionados: anchor-lang/spl, borsh/bytemuck, pinocchio/steel, crates Metaplex, kit/Codama/gill, LiteSVM/Mollusk/Bankrun, melhores práticas de biblioteca.

Fundamentos

O desenvolvimento na Solana é multi-target por design. Crates on-chain compilam para sBPF com cargo build-sbf sob as ferramentas de plataforma da Solana CLI 3.0.10. Rust e TypeScript off-chain se comunicam com RPC, assinam transações e decodificam contas. A serialização define como os bytes de instrução e conta são dispostos. Crates de produto/asset (SPL Token, Metaplex) envolvem programas amplamente implantados. Harnesses de teste aproximam o comportamento do runtime sem sempre iniciar um validador completo.

Trate o ecossistema como camadas, do loader até o aplicativo, não como uma lista de desejos plana de Cargo.toml:

  +----------------------------------------------+
  |  Lógica de produto do App / bot / dApp       |
  +----------------------------------------------+
  |  Clientes TS: @solana/kit, Codama, gill      |  <- JS/TS off-chain
  +----------------------------------------------+
  |  Assets de produto: SPL Token, MPL Core/TM   |  <- CPI + layouts
  +----------------------------------------------+
  |  Framework: anchor-lang / anchor-spl         |
  |             ou pinocchio / steel            |  <- opcional
  +----------------------------------------------+
  |  Codificação: borsh, bytemuck (zero-copy)    |
  +----------------------------------------------+
  |  Plataforma: solana-program (on-chain)       |
  |              solana-sdk + client (off-chain) |
  +----------------------------------------------+
  |  Testes: LiteSVM, Mollusk, Bankrun           |  <- trilha paralela
  +----------------------------------------------+

Crates de plataforma são inegociáveis. solana-program é a biblioteca padrão on-chain (AccountInfo, entrypoints, CPI, sysvars, erros de programa). solana-sdk e crates de cliente relacionados alimentam binários host que constroem, assinam e enviam transações. Mantenha solana-sdk fora dos crates de programa; kit nunca substitui o caminho sBPF.

Crates de framework ficam acima da plataforma. anchor-lang 0.32.1 fornece macros, restrições e IDL; anchor-spl adiciona CPIs SPL tipadas. Esse é o caminho de produto padrão. Pinocchio e Steel são opções nativas leves quando o tamanho do ELF e a CU importam mais do que a ergonomia do Anchor.

A serialização é ortogonal à escolha do framework. Borsh é o padrão flexível (incluindo a maioria dos layouts do Anchor). bytemuck permite casts POD zero-copy quando você controla o alinhamento, preenchimento e validação. A escolha errada aparece como picos de CU ou casts inseguros sem verificações.

Crates de produto (spl-token, helpers ATA, mpl-token-metadata, mpl-core) envolvem programas implantados conhecidos para assets e CPIs. Eles não são um segundo runtime. Escolha Token Metadata vs Core com base no modelo de produto.

Pilha de cliente para TypeScript greenfield: @solana/kit 7.0.0 para RPC, codecs e mensagens; Codama para clientes nativos do kit a partir de IDL do Anchor; gill como açúcar opcional. Evite novos aplicativos em @solana/web3.js v1.

Crates de teste fecham o ciclo: LiteSVM para testes rápidos in-process em Rust, Mollusk para fixtures de instrução/ELF, solana-bankrun para integração em TypeScript. O solana-test-validator completo permanece como opção de smoke test.

Mecânicas e Interações

Plataforma primeiro: programa vs SDK

Todo binário de programa depende de tipos da plataforma. Caminhos nativos e muitos caminhos Pinocchio importam solana-program (ou re-exports compatíveis). O Anchor re-exporta muitos primitivos para que o código do produto raramente os importe diretamente, mas auditorias e trabalho de CU ainda exigem alfabetização na plataforma.

CLIs Rust off-chain e harnesses usam solana-sdk (Pubkey, Instruction, Transaction, signers) com clientes RPC. DApps TypeScript usam kit em vez disso, mas as funções são correspondentes: compor instruções, anexar contas, assinar, submeter, confirmar.

  Binário on-chain                Binário off-chain / dApp
  -----------------               -----------------------
  solana-program                  solana-sdk  OU  @solana/kit
  (+ Anchor ou Pinocchio)         (+ Codama / gill / solders)
           |                                   |
           v                                   v
     Implantação sBPF .so              Envio + decodificação RPC

Escolhendo uma camada de framework de programa

Anchor é o padrão quando você deseja clientes orientados por IDL e validação padrão. Pinocchio/Steel são adequados para CU medida, tamanho de binário ou preferência de auditoria em relação a macros. Misturar frameworks entre programas em um monorepo é aceitável; misturá-los dentro de um único binário sem uma fronteira geralmente não é.

Serialização: Borsh vs bytemuck

Dados de instrução e estado da conta são bytes. Borsh é o padrão determinístico para a maioria dos argumentos e contas (incluindo Anchor). bytemuck reinterpreta memória de conta POD para caminhos de alta performance quando os layouts são validados.

  Estado flexível / em evolução  -->  Borsh (serializar / desserializar)
  POD fixo, sensível a CU       -->  bytemuck (+ verificações rigorosas de init e tamanho)
  Caminhos zero_copy do Anchor    -->  layouts estilo bytemuck sob regras do framework

Prefira Borsh para argumentos e estado em evolução; reserve zero-copy para contas grandes e de alta performance. Nunca faça cast de dados não confiáveis sem verificações de proprietário, tamanho, discriminador e alinhamento.

SPL e Metaplex como camadas de produto

Saldos de token, ATAs e assets digitais vivem em programas implantados. Seu código depende de builders e layouts (spl-token, helpers ATA, mpl-token-metadata, mpl-core), muitas vezes via anchor-spl ou helpers do lado do kit.

Use Token Metadata para metadados clássicos anexados a mint e convenções de marketplace. Use MPL Core quando o modelo Core e seus plugins se adequam melhor à emissão. Fixe os crates à revisão do programa e layout contra os quais você implanta.

Clientes: kit, Codama, gill

Com Anchor, anchor build emite IDL; Codama renderiza builders e decodificadores orientados ao kit. kit 7.0.0 cuida de RPC, mensagens e signers. gill encurta padrões comuns do kit, mas não substitui a saída específica do programa do Codama.

  anchor build --> target/idl/*.json --> Codama render
                                              |
                                              v
                                   Montagem do kit (+ gill opcional)

Aplicativos brownfield podem manter a API Program clássica do TS do Anchor; aplicativos kit greenfield devem preferir Codama + kit. Um aplicativo, uma história de transação primária.

Testes: LiteSVM, Mollusk, Bankrun

Use LiteSVM ou Mollusk para crates de programa e Bankrun ou smoke test de validador para pacotes de cliente. Alinhe os harnesses com a semântica do Agave para que a CI não aprove comportamentos que o mainnet rejeita.

Como as camadas interagem em um único produto

1. Fixe Rust 1.91.1, Agave 4.1.1 / CLI 3.0.10 e Anchor 0.32.1 (se usado).
2. Escolha a camada de framework por binário de programa (padrão Anchor, Pinocchio quando há necessidade medida).
3. Codifique o estado com Borsh, a menos que um caminho de alta performance perfilado necessite de bytemuck/zero-copy.
4. Faça CPI em SPL/MPL com crates com versões alinhadas e IDs de programa corretos por cluster.
5. Gere clientes a partir da IDL via Codama para kit 7.0.0; use gill apenas como açúcar.
6. Teste com LiteSVM/Mollusk em Rust e Bankrun ou smoke test de validador para caminhos TS.
7. Controle os lançamentos com auditorias, higiene de cargo tree e builds verificáveis onde a confiança exigir.

Considerações Avançadas e Aplicações

Receitas de pilha por formato de produto

Alinhamento de versão e cadeia de suprimentos

Crates que compilam juntos ainda podem estar errados se abrangerem gerações de SDK. Fixe solana-program / solana-sdk no canal Agave, mantenha anchor-lang e Anchor CLI em 0.32.1, fixe kit 7.0.0 em todo o monorepo e regenere clientes Codama quando a IDL mudar. Prefira crates de referência Anza, Anchor e Metaplex; execute cargo audit / cargo deny / npm audit. Pule wrappers que apenas re-exportam três linhas de kit ou solana-program. Builds verificáveis provam o artefato; a revisão de dependência é separada. Checklist: Melhores Práticas de Bibliotecas Essenciais.

Conceitos Errôneos Comuns

• "Preciso de todos os crates essenciais em cada programa." Camadas são opcionais; programas precisam da plataforma + codificação + framework escolhido, não Metaplex e Bankrun dentro do mesmo crate sBPF.
• "anchor-lang substitui solana-program." Anchor se baseia em primitivos da plataforma; auditorias e trabalho de CU ainda precisam dessa alfabetização.
• "solana-sdk pertence ao Cargo.toml on-chain." Use solana-program (ou re-exports do framework) on-chain; sdk é para binários host.
• "Pinocchio é sempre mais rápido, então sempre use-o." Meça; muitos produtos são limitados pela velocidade de validação e produto, não pela sobrecarga do framework.
• "Borsh está obsoleto se bytemuck existe." Borsh ainda é o padrão flexível; zero-copy é uma otimização direcionada.
• "kit substitui Anchor." kit é TypeScript off-chain; ele não compila programas nem substitui anchor-lang.
• "Codama e gill são intercambiáveis." Codama gera clientes de programa a partir de IDL; gill é açúcar kit opcional, não seu ABI.
• "LiteSVM significa que nunca preciso de um validador." Harnesses in-process perdem algumas falhas de integração e apenas RPC; mantenha cobertura de smoke test de lançamento.
• "Combinar versões principais é suficiente." Anchor CLI e crates devem compartilhar uma linha; Agave, ferramentas de plataforma e crates SDK devem compartilhar uma geração.

FAQs

Relacionados

• anchor-lang & anchor-spl - crates de framework, IDL e helpers de CPI SPL
• borsh & bytemuck - padrões de serialização e caminhos zero-copy
• litesvm, mollusk & solana-bankrun - harnesses de teste de programa e cliente
• mpl-core & mpl-token-metadata - crates de asset digital Metaplex
• pinocchio & steel - frameworks de programa nativos leves
• @solana/kit, Codama & gill (JS/TS) - pilha de cliente TypeScript moderna

Versões da pilha: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1 e @solana/kit 7.0.0.