Blueprint da Toolchain
A toolchain de programa e dApp Solana é uma stack de binários com versão gerenciada que transformam Rust (e frequentemente TypeScript) em sBPF deployável, clients IDL e hashes on-chain verificáveis. Quando você vê qual camada cada ferramenta possui, "funciona na minha máquina", cargo build-sbf quebrado e drift misterioso Anchor/CLI param de parecer falhas aleatórias e começam a parecer mismatches de stack.
Visão Geral da Toolchain é a entrada orientada a receita; Gerenciamento de Versão (agave-install / avm), Construindo Programas (cargo build-sbf), create-solana-dapp, Mucho CLI, Configuração de Editor e rust-analyzer e Verifiable Builds (solana-verify) cada um aprofunda uma peça. Esta página fica por baixo: como as peças se encaixam, o que você fixa e qual caminho seguir do primeiro programa à verificação de produção.
Resumo
- Desenvolvimento Solana é toolchain em camadas - ferramentas de linguagem Rust, platform tools e CLI Agave, Anchor opcional (via avm), CLIs scaffold, análise de editor e verifiable builds opcionais - e toda camada deve ser fixada e alinhada para compile e deploy reproduzíveis.
- Por que importa: Versões Agave, Anchor e crate desalinhadas causam falhas falsas de "Solana é difícil"; mapa claro permite escolher trabalho CLI mínimo, scaffold full-stack ou verifiable builds nível CI sem adivinhar qual binário realmente compila seu
.so. - Conceitos-chave: agave-install, Solana CLI / platform tools, cargo build-sbf, avm / Anchor, scaffolding (create-solana-dapp, Mucho), rust-analyzer, solana-verify, pins de stack.
- Quando usar: Onboarding builders, projetar CI de repo, depurar drift de versão, escolher nativo vs Anchor vs scaffold full-stack, ou decidir quando verifiable builds se tornam obrigatórios.
- Limitações / trade-offs: Mais camadas significam mais pins e disciplina PATH; scaffolds aceleram setup mas ainda dependem do mesmo Agave e Anchor por baixo; verifiable builds adicionam Docker ou ambientes controlados e ciclos release mais lentos.
- Tópicos relacionados: visão geral toolchain, gerenciamento de versão, cargo build-sbf, create-solana-dapp, verifiable builds, setup editor.
Fundamentos
Solana não oferece um único "install IDE Solana" que possua todo o pipeline. Oferece ferramentas composáveis que respondem uma pergunta cada: qual compilador de linguagem, qual sysroot de plataforma, quais macros framework e IDL, qual layout de projeto, qual feedback de editor e qual prova de que bytes on-chain correspondem à fonte.
Essa composição é deliberada. Platform tools (cargo build-sbf, CLI voltada ao loader) acompanham runtime e ambiente BPF. Anchor acompanha contratos framework e IDL. Scaffolds acompanham layout de produto. Clients como @solana/kit acompanham RPC e transações off-chain. Misturar versões entre essas costuras é a principal fonte de dor de build team-wide.
Pense na stack como camadas da linguagem até atestação:
+------------------------------------------+
| Verifiable builds (solana-verify) | <- prova produção opcional
+------------------------------------------+
| Scaffold / monorepo (create-solana-dapp,|
| Mucho, workspace manual) |
+------------------------------------------+
| Framework (Anchor CLI via avm) | <- opcional mas comum
+------------------------------------------+
| Platform tools + Solana CLI (Agave) | <- cargo build-sbf, deploy, ops RPC
+------------------------------------------+
| Rust (rustup / rust-toolchain.toml) | <- rustc, cargo, analyzer
+------------------------------------------+
| Editor (rust-analyzer, tooling TS) | <- loop feedback, não caminho deploy
+------------------------------------------+Rust é a camada de linguagem para programas on-chain e muitos serviços off-chain. Fixe com rustup e rust-toolchain.toml commitado para CI e laptops compartilharem o mesmo rustc (este site visa Rust 1.91.1).
Agave é a linhagem validator e tooling mantida pela Anza que envia bundle Solana CLI e platform tools voltados ao desenvolvedor. agave-install seleciona canal de release para solana, solana-keygen e cargo-build-sbf chegarem ao PATH juntos. Este site fixa Agave 4.1.1 com Solana CLI 3.0.10.
cargo build-sbf é a entrada cross-compile que transforma crate programa Solana em ELF sBPF .so usando sysroots específicos Solana. Programas nativos chamam diretamente; Anchor chama sob anchor build.
Anchor (CLI via avm, crates como anchor-lang) adiciona macros validação de conta, geração IDL e fluxo padrão test/deploy. Versão CLI e versão crate devem mover juntas (este site fixa Anchor 0.32.1).
Scaffolds (create-solana-dapp, Mucho CLI, ou layouts manuais) não substituem Agave ou Anchor. Geram pastas, scripts e wiring client para você começar de forma programa-mais-app funcional.
Editores e rust-analyzer encurtam loop de feedback para macros, tipos e refactors. Não enviam platform tools nem provam hashes on-chain.
solana-verify reconstrói programas em ambiente controlado e compara hashes executáveis com bytes de programa on-chain para auditores e DAOs confiarem que mainnet corresponde a fonte pública.
Clients TypeScript off-chain (este site: @solana/kit 7.0.0) ficam ao lado do pipeline de programa para RPC e transações; não compilam sBPF nem fazem deploy de programas.
Mecânica e interações
Gerenciamento de versão é a espinha dorsal
Todo o resto assume pins alinhados. agave-install init (ou script install Anza para release) coloca CLI e platform tools sob release ativa compartilhada. avm install / avm use troca binário anchor. rust-toolchain.toml trava Rust. anchor_version em Anchor.toml e versões crate em Cargo.toml mantêm superfícies framework honestas.
rust-toolchain.toml --> rustc / cargo
agave-install --> solana CLI + cargo-build-sbf + bins validator
avm + Anchor.toml --> anchor CLI
Cargo.toml --> anchor-lang / deps programa
imagem CI / Docker --> mesmos pins que laptopSe qualquer camada derivar, sintomas aparecem como cargo-build-sbf ausente, IDL que não corresponde a macros, ou deploys que funcionam para um engenheiro apenas. Gerenciamento de Versão (agave-install / avm) é o deep dive operacional; aqui, lembre que ordem PATH importa tanto quanto números de versão (Homebrew ou scripts install antigos frequentemente sombreiam bins Agave).
Como programa vira .so
Fonte é Rust ordinário com restrições programa Solana (caminhos no_std, crates restritos, alvo sBPF). cargo build-sbf aplica sysroot de plataforma e emite target/deploy/<name>.so mais caminho keypair programa para identidade deploy.
Anchor encapsula esse pipeline: macros expandem em checagens de conta e entrypoints de instrução, anchor build executa build sBPF e artefatos IDL alimentam TypeScript ou outros clients. Por baixo o passo compile ainda é build-sbf; valor framework é estrutura, validação e codegen, não segundo formato bytecode.
programs/foo/src/lib.rs
|
v
[anchor build] -----> cargo build-sbf -----> target/deploy/foo.so
| |
+------> IDL / types +------> solana program deployTimes nativos pulam Anchor e chamam cargo build-sbf (e frequentemente LiteSVM ou testes estilo Mollusk) diretamente. Times de produto frequentemente começam com Anchor porque IDL e constraints cortam boilerplate. Detalhes em Construindo Programas (cargo build-sbf).
Scaffolding fica acima dos binários
create-solana-dapp gera layout full-stack: programa Anchor (ou escolhido por template), app Next.js, hooks wallet e scripts. Mucho CLI é superset orientado Foundation que encapsula fluxos comuns init, build, test e deploy. Ambos assumem que você ainda tem Agave, Rust e geralmente Anchor instalados corretamente por baixo.
Scaffold para forma monorepo conhecida; faça manual para arquitetura multi-programa ou customizada. Trate saída scaffold como ponto de partida, depois fixe versões nesta stack antes de trabalho team-wide.
Loop editor vs loop deploy
rust-analyzer indexa crates, expande macros onde configurado e mostra erros antes de anchor build completo. Configure rust-toolchain.toml, linke manifests programa Anchor em monorepos e habilite build scripts para superfícies Anchor geradas resolverem. Veja Configuração de Editor e rust-analyzer.
O loop deploy permanece orientado CLI: build, opcionalmente teste contra solana-test-validator ou crates SVM in-process, depois solana program deploy ou anchor deploy contra URL cluster e keypair. Sucesso no editor nunca substitui build release limpo em tools fixadas.
Verifiable builds fecham lacuna de confiança
cargo build-sbf local pode produzir .so deployável que ainda difere do artefato de outra máquina se toolchains, flags ou resolução de dependência diferirem. solana-verify reconstrói a partir de fonte em ambiente controlado, faz hash do executável e compara esse hash com programa on-chain via RPC.
fonte pública + tools fixadas
|
v
solana-verify build --> hash executável local
|
v
RPC get-program-hash -------> atestação match / mismatchUse verificação quando upgrade authorities, auditorias ou governança se importam que bytecode mainnet iguala commit taggeado. Detalhes: Verifiable Builds (solana-verify).
Como as peças interagem em um dia de trabalho
- Instale ou troque Agave 4.1.1 e confirme
solana --version/cargo-build-sbf. - Instale Rust 1.91.1 via arquivo toolchain; abra programa em editor com rust-analyzer.
avm use 0.32.1(se Anchor); garanta crates correspondentes.- Scaffold ou abra workspace; edite instruções e contas.
anchor buildoucargo build-sbf; execute testes.- Deploy para localnet ou devnet com config CLI.
- Para releases produção, execute solana-verify e publique hash mais commit.
Trabalho client com @solana/kit pode prosseguir quando IDL ou layouts estabilizam; nunca substitui caminho build sBPF.
Considerações avançadas e aplicações
Times não precisam de toda camada no dia um. Corresponda risco, tamanho do time e rigor de release a um caminho, depois adicione camadas quando custo de drift ou desconfiança exceder custo de tooling.
| Caminho | O que você instala e executa | Pontos fortes | Fraquezas | Melhor encaixe |
|---|---|---|---|---|
| CLI mínima | rustup, agave-install, cargo build-sbf, solana program deploy | Poucas peças móveis; controle total crates e layout | Sem IDL/framework; mais validação e clients escritos à mão | Programas nativos/pinocchio, crates críticos CU, aprender plataforma nu |
| Scaffold Anchor | Acima + avm/Anchor 0.32.1 + create-solana-dapp ou templates Mucho | Loop produto rápido; IDL; testes padrão; defaults full-stack | Acoplamento versão framework; opiniões scaffold para descascar depois | Maioria times produto enviando programa + web UI |
| CI verifiable-build completo | Caminho Anchor ou nativo + imagem CI locked + solana-verify + gates hash | Artefatos reproduzíveis; atestações prontas auditoria/governança | Pipelines mais lentos; disciplina Docker/pin tooling necessária | Programas mainnet com upgrade authority, DAOs, apps regulados ou alto TVL |
Caminho CLI mínimo é tabela verdade para compilação Solana: se build-sbf funciona, platform tools estão saudáveis. Use para depurar issues "Anchor falha" isolando se falha é framework ou plataforma.
Caminho scaffold Anchor otimiza para shipping. Fixe CLI Anchor, crates e Agave juntos; trate scripts template como wrappers do mesmo story deploy.
CI verifiable-build completo trata artefato release como produto. CI instala versões exatas Agave/Anchor/Rust, build com solana-verify, falha em mismatch hash após deploy e armazena commit SHA com atestação.
Dicas monorepo: linke Cargo.toml programa para rust-analyzer; fixe Node para kit 7.x em .nvmrc; nunca deixe install global "latest" reescrever PATH no meio do sprint sem changelog.
Não confunda camadas: kit não é deploy, scaffolds não são agave-install, analyzer verde não é CU release, e hash local casual não é verificação comunitária.
Para design reviews, responda primeiro: qual caminho, quais versões exatas, ownership PATH, upgrade authority após deploy e se release exige solana-verify.
Equívocos comuns
- "Só preciso Anchor; Solana CLI é opcional." Anchor build e deploy ainda dependem de platform tools Agave e Solana CLI no PATH.
- "create-solana-dapp instala toolchain inteira." Scaffold arquivos de projeto; você ainda instala Rust, Agave e geralmente avm/Anchor.
- "cargo build-sbf é coisa do Anchor." É caminho compile plataforma; Anchor encapsula, programas nativos chamam diretamente.
- "Qualquer rustc recente serve para programas." Platform tools esperam toolchain stable compatível; fixe 1.91.1 (ou pin documentado do time) com
rust-toolchain.toml. - "Corresponder CLI Anchor basta."
anchor-lange crates relacionados devem corresponder linha major/minor CLI ou macros e geração IDL quebram. - "Verifiable builds são só para pesquisadores de segurança." Qualquer programa com confiança pública, upgrade authority compartilhada ou requisitos auditoria se beneficia de atestação hash.
- "Erros de editor igualam prontidão on-chain." Análise ajuda velocidade de edição; prontidão deploy é build release, testes, config cluster e frequentemente verificação.
- "Mucho substitui solana e anchor." Mucho orquestra fluxos comuns; binários subjacentes permanecem Agave CLI e Anchor.
FAQs
Qual é a ideia mais importante na toolchain Solana?
Trate desenvolvimento como ferramentas em camadas com versão fixada (Rust, plataforma/CLI Agave, Anchor opcional, scaffolds, verify) que devem alinhar para toda máquina produzir mesmo comportamento build e deploy.
O que agave-install realmente gerencia?
Instala e troca artefatos release Agave para binários Solana CLI e platform tools como cargo-build-sbf compartilharem uma release ativa no PATH.
Como Agave se relaciona com Solana CLI?
Agave é linhagem validator e tooling mantida; comandos voltados ao operador permanecem com marca solana e vêm com aquela release (este site: CLI 3.0.10 com Agave 4.1.1).
Para que serve avm?
Anchor Version Manager instala e seleciona versões CLI Anchor como nvm seleciona Node, para múltiplos repos exigirem linhas Anchor diferentes sem caos global.
Preciso Anchor para lançar programa?
Não. Programas nativos build com cargo build-sbf e deploy com Solana CLI. Anchor é framework opcional e tooling IDL preferido por muitos times produto.
De onde vem cargo build-sbf?
Vem com platform tools Agave instaladas junto ao bundle CLI; se ausente, reinstale ou corrija PATH em vez de inventar caminho package manager separado.
Quando usar create-solana-dapp vs Mucho vs repo manual?
Use create-solana-dapp para starts produto estilo Next.js full-stack, Mucho para fluxos workshop Foundation com scripts, e layouts manuais quando arquitetura multi-programa ou customizada domina.
Scaffolding fixa Agave e Anchor para mim?
Geralmente não completamente. Alinhe versões após geração scaffold com agave-install, avm e arquivos toolchain commitados para template não derivar silenciosamente.
Qual papel rust-analyzer desempenha?
Fornece análise IDE, navegação e erros antecipados para código programa Rust; não substitui platform tools, builds Anchor ou pipelines release verificáveis.
Como solana-verify se encaixa no mapa mental?
É camada de atestação acima de builds ordinários: reconstrua sob condições controladas, hash ELF e compare com bytes programa on-chain para confiança supply-chain.
Por que builds laptop e CI discordam?
Versões Agave/Anchor/Rust diferentes, sombras PATH, feature flags ou dependências não locked mudam artefato; fixe toda camada e prefira CI hermético para release.
@solana/kit faz parte do caminho compile on-chain?
Não. Kit é stack client TypeScript para RPC e transações (este site: 7.0.0). Compile programa permanece Rust mais cargo build-sbf (e opcionalmente Anchor).
O que novo engenheiro deve instalar primeiro?
Rust via rustup com pin toolchain do repo, depois Agave/Solana CLI via agave-install, depois avm/Anchor se repo usa Anchor, depois abra editor com rust-analyzer antes de scaffolds extras.
Quando caminho CI verifiable-build completo vale a pena?
Quando upgrades mainnet, auditorias ou governança exigem prova de que bytecode deployado corresponde a commit público específico, não apenas que máquina de desenvolvedor uma vez produziu .so.
Como sei se minha stack corresponde aos pins deste site?
Execute rustc --version, solana --version, anchor --version e confirme kit em manifests de pacote contra Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1 e @solana/kit 7.0.0.
Relacionados
- Visão Geral da Toolchain - card receita e mapa stack para tools fixadas
- Gerenciamento de Versão (agave-install / avm) - fixar versões Agave/CLI e Anchor
- create-solana-dapp - scaffolding programa + Next.js full-stack
- Construindo Programas (cargo build-sbf) - pipeline compile sBPF e artefatos
- Verifiable Builds (solana-verify) - builds reproduzíveis e checagens hash on-chain
- Configuração de Editor e rust-analyzer - loop IDE para crates programa
Versões da stack: 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.