@solana/kit em Detalhe

@solana/kit 7.0.0 é a stack moderna de cliente TypeScript para Solana: composição funcional, tipos com marca (branded types), módulos que podem ser removidos com tree-shaking e I/O de rede explícito. É o padrão para novos clientes em 2026. O legado @solana/web3.js v1 é uma fonte de migração, não um padrão para novos projetos (greenfield).

Esta página mapeia RPC, subscriptions, keypairs e signers, mensagens de transação, codecs, tabelas de consulta de endereço (ALTs) e o caminho de migração do web3.js v1 antes das páginas focadas em receitas (recipes).

Resumo

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

Signers são a unidade de autorização: KeyPairSigners locais para scripts e testes, signers suportados por carteiras para navegadores, todos compartilhando uma interface para que os pagadores de taxa e autoridades de instrução não sejam strings ad hoc de chave pública. Endereços são strings base58 com marca (branded), validadas na construção. Valores que tocam a chain são lamports bigint, não SOL flutuante e não BN por padrão.

Codecs codificam e decodificam layouts de instrução e conta sem assumir a geração de código (codegen) do Anchor. Mensagens versão 0 mais ALTs encolhem listas de contas quando DeFi multi-hop ou grandes conjuntos de contas restantes excederiam os limites de tamanho. A migração é intencional: porte primeiro as leituras, depois a construção de mensagens e a assinatura pela carteira, depois remova o web3.js para não executar dois modelos mentais de cliente para sempre.

Fundamentos

Para que serve o Kit

@solana/kit é um SDK de cliente, não um framework on-chain. Ele se comunica com nós RPC, constrói transações em formato de rede (wire-format), assina (ou delega a assinatura para uma carteira) e decodifica bytes de conta. A lógica on-chain ainda reside em programas (nativo, Anchor 0.32.1, Pinocchio, etc.).

web3.js v1 vs kit 7.x em resumo

APIs de classe mutáveis incentivavam a edição de um objeto de transação até que funcionasse. O Kit prefere um pipeline: criar mensagem, definir pagador de taxa e tempo de vida, anexar instruções, opcionalmente comprimir com ALTs, assinar, depois enviar e confirmar.

Peças centrais com marca (branded pieces)

• Address: string de chave pública base58 validada para contas e programas.
• Lamports / valores bigint: inteiros voltados para a chain; converta apenas na borda da UI.
• Signer: algo que pode autorizar um papel (pagador de taxa, origem de transferência, autoridade).
• Mensagem de transação: estrutura versionada contendo pagador de taxa, tempo de vida e instruções antes que as assinaturas existam.
• Codec: par codificador/decodificador para um layout de bytes (struct, enum, arrays fixos/variáveis, endereços).

Onde cada página de receita (recipe page) se encaixa

Mecânica

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

Pipeline de cliente ponta a ponta

  App / script / manipulador de rota
       |
       |  1. createSolanaRpc(+ subscriptions)
       |  2. resolver Signer(s) e valores Address
       |  3. buscar blockhash (lifetime) e quaisquer 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 um proxy JSON-RPC tipado. Métodos não atingem a rede até que você chame .send(). Isso torna a construção de requisições, estratégias de batch e testes menos mágicos do que métodos que disparam ao serem chamados (fire-on-call).

Subscriptions usam um cliente separado (createSolanaRpcSubscriptions) via WebSocket. APIs de notificação retornam streams que você consome com for await e cancela com AbortSignal. URLs HTTP e WS devem ter como alvo o mesmo cluster; um bug comum em produção é mainnet HTTPS com WSS ainda em devnet.

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

2. Keypairs e signers

Scripts e testes geram ou carregam material de chave:

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

Aplicativos de navegador não devem embutir chaves secretas. Adaptadores de carteira (wallet adapters) e integrações do Wallet Standard expõem signers que implementam os mesmos papéis sem revelar chaves privadas. Pagadores de taxa (fee payers) usam helpers como setTransactionMessageFeePayerSigner para que a mensagem carregue tanto o endereço quanto a capacidade de assinatura.

A assinatura de mensagem off-chain para autenticação é uma preocupação paralela: mesma identidade, payload diferente. Mantenha a separação de domínio para que assinaturas de login não possam ser confundidas com aprovações de transação.

3. Mensagens de transação

Prefira mensagens versão 0 para trabalho novo. Construa imutavelmente:

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

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

Blockhashes obsoletos expiram. Busque o tempo de vida (lifetime) perto do momento do envio (submit) e projete novas tentativas (retries) para reconstruir mensagens em vez de reutilizar um tempo de vida expirado.

4. Codecs e serialização

Programas se comunicam em bytes. Os codecs do Kit compõem primitivas pequenas em structs:

• Larguras fixas: u8, u32, u64 e similares como codificadores/decodificadores.
• getAddressEncoder / getAddressDecoder para chaves públicas de 32 bytes em layouts.
• getStructEncoder / getStructDecoder para layouts de campos ordenados.
• Discriminadores (frequentemente hashes Anchor de 8 bytes ou tags customizadas) como campos iniciais.

Use codecs quando você não tiver um cliente gerado, ao indexar contas brutas, ou ao validar dados de instrução antes do envio. Prefira clientes gerados por Codama ou Anchor para APIs de programa conhecidas; mantenha codecs feitos à mão para casos de uso nas bordas que os geradores não cobrem.

Endianness, preenchimento (padding) e tags de opção (option tags) devem corresponder ao layout on-chain. Um tipo TypeScript limpo que diverge do layout borsh/bytemuck do programa ainda estará incorreto na rede (wire).

5. Address lookup tables

Listas de contas legadas e excessivamente grandes falham com limites de tamanho ou contagem de contas. Mensagens versão 0 podem referenciar contas através de tabelas de consulta de endereço (address lookup tables): tabelas on-chain de endereços que o runtime expande durante o processamento, de modo que a transação na rede carregue índices compactos em vez de chaves completas para cada conta.

No lado do cliente, busque os dados da conta da tabela,