Busque em todas as páginas da documentação
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.
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.
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| Caminho | Crates primários | Você ganha | Você paga | Melhor ajuste |
|---|---|---|---|---|
| Anchor | anchor-lang, anchor-spl 0.32.1 | Restrições, IDL, clientes do ecossistema | Tamanho do framework, acoplamento de versão | A maioria dos programas de produto + UI web |
| Plataforma Nativa | solana-program | Controle total, menos macros | Validação manual, clientes manuais | Aprendizado, loaders especializados |
| Pinocchio / Steel | pinocchio, pilha Steel | ELF menor, CU mais baixo | Menos IDL/ferramentas padrão | Programas sensíveis a CU e tamanho |
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 é.
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 frameworkPrefira 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.
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.
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.
| Harness | Linguagem | Força | Lacuna |
|---|---|---|---|
| LiteSVM | Rust | Testes rápidos in-process de SVM | Não é um cluster completo de múltiplos validadores |
| Mollusk | Rust | Fixtures de instrução/ELF, foco em CU | Mais restrito que fluxos de aplicativo completos |
| Bankrun | TypeScript | Integração em TS semelhante a validador | Mais pesado que testes unitários puros |
| test-validator | CLI | Smoke test de cluster local completo | Caminho de CI mais lento |
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.
cargo tree e builds verificáveis onde a confiança exigir.| Receita | On-chain | Cliente | Testes | Notas |
|---|---|---|---|---|
| dApp de produto padrão | Anchor 0.32.1 + anchor-spl + Borsh | Codama + kit 7.0.0 (+ gill opcional) | LiteSVM + Bankrun ou smoke test de validador | Caminho mais rápido para a maioria das equipes |
| Programa crítico de CU | Pinocchio/Steel + Borsh/bytemuck cuidadoso | Hand codecs ou história de Shank/IDL que você possui | Mollusk + LiteSVM, orçamentos de CU na CI | Documente por que Anchor foi pulado |
| App de NFT / asset digital | Anchor ou nativo + mpl-core ou token-metadata | kit + Metaplex/helpers DAS conforme necessário | Fixtures de contas para metadados/Core | Combine o provedor DAS com o caminho de leitura |
| Aprendizado / tooling nativo | apenas solana-program | CLI solana-sdk ou scripts kit | LiteSVM primeiro | Constrói intuição sob Anchor |
| Monorepo misto | Programa A Anchor, Programa B Pinocchio | App kit compartilhado com Codama por programa | Harnesses por binário | Um framework por binário, pins compartilhados |
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.
solana-program (ou re-exports do framework) on-chain; sdk é para binários host.anchor-lang.Trate as bibliotecas como camadas (plataforma, framework, codificação, assets, clientes, testes) e puxe apenas crates que servem à camada que cada binário realmente possui.
solana-program para programas sBPF on-chain; solana-sdk (e crates de cliente relacionados) para Rust off-chain que constrói e assina transações.
Não. Programas nativos solana-program ou Pinocchio/Steel são válidos. Anchor 0.32.1 é o padrão de produto comum devido às restrições, IDL e ecossistema de clientes.
Quando a CU medida, o tamanho do binário ou as restrições de superfície do framework dominam, e sua equipe pode cuidar da validação, documentação de layout e geração de clientes sem os padrões do Anchor.
Borsh é o caminho usual de codificação de instrução e conta; os padrões de conta zero-copy do Anchor usam layouts POD estilo bytemuck sob regras do framework para contas de alta performance.
Geralmente não. Escolha Core ou o clássico Token Metadata com base no modelo de asset e nos requisitos do marketplace; muitos aplicativos padronizam em um padrão primário.
Totalmente off-chain. Kit 7.0.0 lida com RPC, codecs e transações em TypeScript; a compilação do programa permanece Rust mais cargo build-sbf (e muitas vezes Anchor).
Codama transforma a IDL do Anchor em builders e decodificadores nativos do kit tipados para que os frontends não precisem empacotar manualmente discriminadores e metadados de conta.
Não. Use kit sozinho com clientes de programa gerados pelo Codama se preferir; gill é um açúcar opcional.
Comece com LiteSVM para testes de programa Rust; adicione Mollusk para casos de instrução/ELF; use Bankrun ou test-validator quando a fidelidade da integração TypeScript importar.
Sim, entre diferentes binários de programa. Documente a escolha por programa e mantenha os pins compartilhados de Agave, Rust e cliente alinhados.
Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1 e @solana/kit 7.0.0, com crates de SDK de programa da mesma geração Agave.
A toolchain cobre binários e caminhos de instalação (agave-install, avm, cargo build-sbf). Esta página cobre dependências de biblioteca que você declara assim que essas ferramentas são instaladas.
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.
Revisado por Chris St. John·Última atualização: 15 de jul. de 2026