@solana/kit em detalhe

@solana/kit 7.0.0 é a stack moderna de cliente TypeScript para Solana: composição funcional, tipos com brand, módulos tree-shakable e I/O de rede explícita. É o padrão para novos clientes em 2026. O legado @solana/web3.js v1 é fonte de migração, não padrão greenfield.

Esta página mapeia RPC, subscriptions, keypairs e signers, mensagens de transação, codecs, address lookup tables (ALTs) e o caminho de migração do web3.js v1 antes das páginas de receita focadas.

Resumo

Kit divide o que web3.js v1 empacotava em Connection, Transaction e PublicKey em superfícies menores e tipadas. Você cria cliente RPC para JSON-RPC HTTP, cliente de subscriptions para WebSockets e constrói mensagens de transação com transformações puras (pipe, fee payer, lifetime de blockhash, instruções) antes de assinar e enviar.

Signers são a unidade de autorização: KeyPairSigners locais para scripts e testes, signers de carteira para browsers, todos compartilhando uma interface para fee payer e authorities de instrução não serem strings ad hoc de public key. Addresses são strings base58 com brand validadas na construção. Valores que tocam a chain são lamports bigint, não SOL float e não BN por padrão.

Codecs codificam e decodificam layouts de instrução e conta sem assumir codegen Anchor. Mensagens versão 0 mais ALTs encolhem listas de contas quando DeFi multi-hop ou conjuntos grandes de remaining accounts estourariam limites de tamanho. Migração é intencional: porte leituras primeiro, depois construção de mensagem e assinatura de carteira, depois delete web3.js para não rodar dois modelos mentais de cliente para sempre.

Fundamentos

Para que serve o kit

@solana/kit é um SDK de cliente, não framework on-chain. Ele conversa com nós RPC, constrói transações em formato wire, assina (ou delega assinatura à carteira) e decodifica bytes de conta. Lógica on-chain ainda vive em programas (nativo, Anchor 0.32.1, Pinocchio, etc.).

web3.js v1 vs kit 7.x em resumo

APIs de classe mutável incentivavam editar objeto tx até funcionar. Kit prefere pipeline: criar mensagem, definir fee payer e lifetime, anexar instruções, opcionalmente comprimir com ALTs, assinar, depois enviar e confirmar.

Peças com brand centrais

• Address: string de public key base58 validada para contas e programas.
• Lamports / amounts bigint: inteiros voltados à chain; converta apenas na borda da UI.
• Signer: algo que pode autorizar um papel (fee payer, origem de transferência, authority).
• Mensagem de transação: estrutura versionada com fee payer, lifetime e instruções antes de existirem assinaturas.
• Codec: par encoder/decoder para layout de bytes (struct, enum, arrays fixos/variáveis, addresses).

Onde cada página de receita se encaixa

Mecânica

Um fluxo de cliente produtivo é fixo o suficiente para memorizar; outros fluxos especializam este pipeline.

Pipeline de cliente ponta a ponta

  App / script / route handler
       |
       |  1. createSolanaRpc(+ subscriptions)
       |  2. resolver Signer(s) e valores Address
       |  3. buscar blockhash (lifetime) e leituras de conta
       |  4. createTransactionMessage({ version: 0 })
       |  5. definir fee payer + lifetime + instruções (pipe)
       |  6. opcional: comprimir com address lookup tables
       |  7. signTransactionMessageWithSigners (ou carteira)
       |  8. enviar + confirmar no commitment escolhido
       v
  RPC / cluster classe Agave

1. RPC e subscriptions

createSolanaRpc(url) retorna proxy JSON-RPC tipado. Métodos não atingem a rede até você chamar .send(). Isso torna construção de request, estratégias de batch e testes menos mágicos que métodos fire-on-call.

Subscriptions usam cliente separado (createSolanaRpcSubscriptions) sobre WebSocket. APIs de notificação retornam streams consumidos com for await e cancelados com AbortSignal. URLs HTTP e WS devem mirar o mesmo cluster; bug comum em produção é HTTPS mainnet com WSS ainda na devnet.

Commitment (processed, confirmed, finalized) é opção de primeira classe em leituras e confirmações. UX de produto geralmente espera confirmed; efeitos off-chain irreversíveis devem esperar finalized.

2. Keypairs e signers

Scripts e testes geram ou carregam material de chave:

• generateKeyPairSigner() para identidades Ed25519 efêmeras.
• createKeyPairSignerFromBytes (ou helpers de import relacionados) para arrays JSON solana-keygen.

Apps browser não devem embutir chaves secretas. Wallet adapters e integrações Wallet Standard expõem signers que implementam os mesmos papéis sem revelar chaves privadas. Fee payers usam helpers como setTransactionMessageFeePayerSigner para a mensagem carregar endereço e capacidade de assinatura.

Assinatura de mensagem off-chain para auth é preocupação irmã: mesma identidade, payload diferente. Mantenha separação de domínio para assinaturas de login não serem confundidas com aprovações de transação.

3. Mensagens de transação

Prefira mensagens versão 0 para trabalho novo. Construa de forma imutável:

1. createTransactionMessage({ version: 0 })
2. Defina fee payer (consciente de signer).
3. Defina lifetime a partir de resultado fresco de getLatestBlockhash.
4. Anexe instruções (compute budget primeiro ao definir limite/preço CU).
5. Assine quando mensagem estiver completa.

pipe mantém transformações multi-etapa legíveis. Instruções frequentemente vêm de pacotes com escopo como @solana-program/system (getTransferSolInstruction) em vez de único objeto SystemProgram monolítico. Transações multi-instrução permanecem atômicas on-chain: todas sucedem ou nenhuma confirma.

Blockhashes obsoletos expiram. Busque lifetime perto do submit e projete retries para reconstruir mensagens em vez de reutilizar lifetime morta.

4. Codecs e serialização

Programas falam em bytes. Codecs do kit compõem primitivos pequenos em structs:

• Larguras fixas: u8, u32, u64 e afins como encoders/decoders.
• getAddressEncoder / getAddressDecoder para pubkeys de 32 bytes em layouts.
• getStructEncoder / getStructDecoder para layouts de campos ordenados.
• Discriminators (frequentemente hashes Anchor de 8 bytes ou tags customizadas) como campos iniciais.

Use codecs quando não tem cliente gerado, ao indexar contas brutas ou validar dados de instrução antes do envio. Prefira clientes gerados Codama ou Anchor para APIs de programa conhecidas; mantenha codecs manuais para bordas que geradores não cobrem.

Endianness, padding e tags de option devem combinar layout on-chain. Tipo TypeScript limpo que diverge do layout borsh/bytemuck do programa ainda está errado no wire.

5. Address lookup tables

Listas de contas legadas e oversized falham com limites de tamanho ou contagem. Mensagens versão 0 podem referenciar contas por address lookup tables: tabelas on-chain de endereços que o runtime expande durante processamento para a transação wire carregar índices compactos em vez de chaves completas para cada conta.

No cliente, busque dados da conta de tabela, construa mensagem lógica completa, depois comprima com helpers como compressTransactionMessageUsingAddressLookupTables. Tabelas devem existir e estar ativadas antes do uso em produção; create/extend/freeze é trabalho operacional, não gratuito no submit.

Use ALTs para rotas DeFi grandes, ops NFT em massa e conjuntos repetidos de contas grandes. Pule complexidade ALT para transferências simples de duas contas.

6. Assinar, enviar, confirmar

Após mensagem completa, signTransactionMessageWithSigners resolve signers embutidos. Factories como sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions }) esperam commitment escolhido. Assinatura significa que submissão foi aceita; correção de produto ainda depende de política de confirmação e erros (blockhash expirado, fundos, simulação).

Avançado

Mentalidade de migração do web3.js v1

Não reescreva o app inteiro em um PR se a superfície for grande. Sequência durável:

Converta PublicKey para Address nos boundaries de módulo uma vez. Padronize em bigint para lamports. Substitua hábitos implícitos de confirm por factories e commitment explícitos. Elimine dual stacks com prazo; migração parcial eterna dobra superfície de bugs.

Tree-shaking e limites de pacote

Importe apenas helpers necessários. Prefira builders de instrução @solana-program/* em vez de account metas copiados. Mantenha código de carteira fora de bundles server/edge; carregue keypairs de arquivo apenas em scripts Node dedicados.

Commitment, provedores e confiabilidade

RPCs públicos limitam taxa agressivamente. Produção precisa URL de provedor, endpoints HTTP e WS separados e backoff em 429/5xx. Subscriptions caem; reconecte com backoff e ressincronize por HTTP em vez de assumir stream sem lacunas.

Codecs em sistemas multi-serviço

Compartilhe módulos de layout (ou gere uma vez) entre frontend, workers e indexadores. Parsers manuais divergentes são classe silenciosa de incidente. Versione dados de conta on-chain quando layouts evoluem; decodifique via discriminator ou campos de versão.

ALTs no design de produto

Trate lookup tables como infraestrutura: ownership, authority, cadência de extensão e política de freeze pertencem a runbooks. Evite views cacheadas obsoletas de tabela; meça tamanho wire antes e depois da compressão no CI para rotas críticas.

Postura de testes

Teste unitariamente transformações puras de mensagem e codecs offline. Teste integração send/confirm em validadores locais (Solana CLI 3.0.10 / classe Agave) ou envs estilo Surfpool. Simule antes do envio para capturar erros de meta mais barato que retries mainnet.

Equívocos comuns

Equívoco: Kit é "web3.js com caminhos de import diferentes." O modelo de programação mudou: mensagens imutáveis, tipos com brand, .send() explícito e interfaces Signer. Tratá-lo como rename garante código híbrido desajeitado.

Equívoco: PublicKey e Address são intercambiáveis em todo lugar. Não são o mesmo tipo. Converta nos boundaries; não passe instâncias de classe em APIs kit esperando strings com brand.

Equívoco: Se .send() é chato, pule ou encapsule para sempre. .send() torna I/O explícita. Você pode encapsular finamente para ergonomia do app, mas esconder todos os boundaries de rede tende a recriar a bagunça implícita de Connection antiga.

Equívoco: dapps browser devem enviar KeyPairSigners no bundle. Autoridade do usuário pertence às carteiras. Signers keypair locais são para servidores, CI e testes (com higiene de segredos).

Equívoco: Codecs são só para quem não tem Anchor. Clientes gerados cobrem programas conhecidos. Codecs ainda importam para contas desconhecidas, layouts customizados, migrações e indexadores.

Equívoco: ALTs substituem design cuidadoso de contas. Comprimem referências; não removem contenção de lock, custo CU ou necessidade de metas writable/signer corretas.

Equívoco: String de assinatura significa transferência final. Commitment de confirmação decide durabilidade. Projete UX e efeitos backend em torno dessa escada.

Equívoco: Rodar kit e web3.js lado a lado indefinidamente é ok. Funciona brevemente. A longo prazo você paga peso duplo de dependência e carga cognitiva dupla. Planeje remoção.

FAQs

Relacionados

• RPC e subscriptions - JSON-RPC HTTP tipado e streams de notificação WebSocket
• Keypairs e signers - KeyPairSigner, signers de carteira e papéis de fee payer
• Construindo mensagens de transação - composição pipe, lifetime, instruções, compute budget
• Codecs e serialização - encoders e decoders composáveis para dados de conta e ix
• Address Lookup Tables - compressão v0 com lookup tables on-chain
• Migrando do web3.js v1 - mapa de padrões e remoção em fases de clientes legados

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.