Boas Práticas de Fundamentos de Solana
Os fundamentos para internalizar antes de escrever programas, clientes ou infraestrutura no Agave 4.1.1.
Como Usar Esta Lista
- Percorra A até C antes do seu primeiro deploy de programa
- Revise D ao integrar novos membros da equipe vindos de backgrounds EVM
- Trate E como um gate pré-mainnet - cada item deve passar
A - Modelo Mental
- O estado vive em contas, não em programas. Programas são executáveis sem estado que leem/escrevem contas passadas a eles.
- Toda entidade é uma conta. Carteiras, programas, mints de token e structs de dados são todas contas com lamports, owner e campos de data.
- Transações declaram todas as contas antecipadamente. O Sealevel usa essa lista para agendamento paralelo e enforcement de locks.
- Apenas o programa proprietário escreve dados da conta. Segurança segue regras de ownership, não de endereços ocultos.
B - Moeda e Precisão
- Armazene e transmita lamports como inteiros. Use
bigintem TypeScript; evite castsf64em programas Rust. - Converta SOL para lamports na borda da UI. Faça parse de strings decimais com matemática inteira, não ponto flutuante.
- Leia decimals SPL separadamente de SOL. Valores de token usam decimals específicos do mint, não 1e9.
- Financie novas contas até o mínimo isento de rent. Consulte
getMinimumBalanceForRentExemptionantes deinit.
C - Clusters e Ambiente
- Use devnet como padrão para desenvolvimento de aplicativos. Use validador local (Surfpool 0.12.0 ou
solana-test-validator) para CI. - Fixe URL de RPC, config da CLI e rede da carteira no mesmo cluster. Incompatibilidades geram erros "account not found".
- Nunca faça airdrop ou teste com keypairs de mainnet. Use arquivos de keypair separados por ambiente.
- Verifique o genesis hash ao depurar problemas de cluster.
solana genesis-hashconfirma que você está na rede pretendida.
D - Chaves e Assinatura
- Nunca faça commit de JSON de keypair no controle de versão. Adicione arquivos
*.jsonde chave ao.gitignore; use gerenciadores de secrets em produção. - Marque toda conta signatária com
isSigner: true. Flags de signatário ausentes causam rejeição em runtime. - Use PDAs para endereços controlados pelo programa. Usuários assinam; programas assinam por PDAs via seeds.
- Mantenha o fee payer financiado, mas não superfinanciado. Carteiras de serviço guardam SOL mínimo apenas para taxas.
E - Transações e Confirmação
- Use commitment
confirmedpara a maioria das ações de dapp. Reservefinalizedpara liquidações de alto valor. - Atualize o blockhash em cada retry. Blockhashes expirados causam descartes silenciosos.
- Simule antes de enviar durante o desenvolvimento. Decodifique erros de programa a partir dos logs de simulação.
- Assine notificações de signature em vez de polling. WebSockets reduzem carga de RPC e latência.
- Leia logs do explorer para transações com falha. Erros on-chain estão nos logs do programa, não só nos códigos de erro de RPC.
FAQs
Qual é a mudança de modelo mental mais importante?
O estado vive em contas, não dentro de programas. Projete layouts de contas antes de escrever lógica de instrução.
Devo usar devnet ou localnet para CI?
Localnet. Surfpool 0.12.0 ou solana-test-validator evitam rate limits e instabilidade de cluster.
Por que floats são perigosos para valores de SOL?
number em JavaScript não representa todos os valores de lamport com exatidão. Use bigint de ponta a ponta.
Qual nível de commitment uma UI de swap deve usar?
confirmed para exibição. Considere finalized antes de liberar fundos de escrow.
Como compartilho uma transação com segurança com um colega?
Link do explorer com parâmetro ?cluster= correspondente à rede onde a tx foi enviada.
Quando devo ler a página de comparação com EVM?
Antes de projetar qualquer padrão "um contrato armazena tudo". A Solana precisa de design conta-por-entidade.
Quais versões de ferramentas devo fixar?
Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, @solana/kit 7.0.0 conforme o manifest deste site.
Commitment processed é seguro para UX?
Não. Transações podem ser descartadas ou reordenadas em processed. Aguarde pelo menos confirmed.
Como valido o setup de um novo colega?
solana config get, solana balance, solana airdrop 1, envie 0.001 SOL, confirme no explorer com o parâmetro de cluster correto.
Devo usar web3.js v1 em projetos novos?
Não. Use @solana/kit 7.0.0 para novos clientes TypeScript. web3.js v1 é legado.
Qual é o primeiro comando CLI que todo desenvolvedor deve executar?
solana config set --url devnet && solana airdrop 2Como slots se relacionam com latência voltada ao usuário?
Slots (~400 ms) dirigem a produção de blocos. Confirmação do usuário deve acompanhar níveis de commitment, não contagens de slot.
Relacionado
- Noções Básicas de Solana - exemplos práticos de orientação
- O Modelo Mental da Solana vs. EVM - a mudança de modelo mais profunda
- Como uma Transação Flui - boas práticas de confirmação em contexto
Versões da stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0 e LiteSVM 0.6.x.