Busque em todas as páginas da documentação
Um programa nativo no Solana é um crate Rust que depende de solana-program, tem como alvo SBF como cdylib, e expõe um entrypoint que recebe um ID de programa, uma fatia de AccountInfos e dados de instrução. Não há macro de struct de contas, nenhuma geração automática de restrições e nenhum IDL embutido. Você possui o caminho completo, desde bytes de entrada até mudanças de estado de saída.
Esta página é o mapa da seção. Use-a para posicionar o dispatch do entrypoint, validação manual, (des)serialização, leitura/escrita, criação de conta via CPI, logging e trade-offs de framework em um contínuo antes de seguir as páginas de receitas focadas.
Programas Solana nativos são módulos SBF comuns. O runtime chama process_instruction uma vez por instrução, entrega apenas o que a transação declarou e espera Ok(()) ou um ProgramError.
Sem Anchor, três tarefas caem no seu código. Parsear dados de instrução em um enum estável ou layout de opcode. Validar cada conta que o manipulador usa: signers, writability, owners, igualdade de chaves, seeds de PDA e relacionamentos de negócios. Modificar bytes de contas de propriedade do programa sob as regras de empréstimo do Solana, incluindo CPI do System Program quando uma nova conta deve existir.
Essas tarefas também são a principal superfície de risco. Uma verificação is_signer ausente, uma suposição incorreta de owner, ou um caminho de reinit em uma conta existente é um bug crítico. Frameworks codificam as mesmas regras em macros; código nativo as torna visíveis e fáceis de omitir.
Escolha nativo quando precisar de controle explícito, binários menores, CU base menor, layouts incomuns ou verificações visíveis para auditoria. Escolha Anchor 0.32.1 (ou um wrapper fino como Pinocchio) quando velocidade, geração de IDL/cliente e restrições declarativas forem mais importantes. Muitas equipes prototipam em Anchor, depois reescrevem caminhos quentes como programas nativos compostos via CPI.
Nativo significa que você programa contra a API solana-program sem a camada #[program] / #[account] do Anchor. Você ainda implanta um .so, paga taxas em lamports, declara metadados de conta de clientes como @solana/kit 7.0.0, e constrói com Agave 4.1.1 / Solana CLI 3.0.10 ferramentas SBF. Nativo é uma camada de aplicação mais fina, não uma cadeia diferente.
| Entrada | Papel |
|---|---|
program_id | A chave pública do seu programa; verificações de owner e derivação de PDA |
accounts: &[AccountInfo] | Contas listadas pelo cliente, com flags de signer/writable verificadas pelo runtime |
instruction_data: &[u8] | Bytes opacos que você decodifica em um enum de instrução ou opcode |
O runtime não re-deriva a intenção dos seus tipos Rust. Conta errada no slot 2, dados curtos, ou layout incorreto devem falhar de forma fechada no seu manipulador.
AccountInfo expõe chave, lamports, dados, owner, executável, is_signer e is_writable. Essas flags refletem o que a transação declarou e o runtime verificou para assinaturas. Elas não provam "esta é a vault para este usuário" ou "este é o estado seguro do programa". Essa política é sua: comparações, verificações de PDA e inspeção de campos dentro dos dados.
| Camada | O que adiciona | O que não remove |
|---|---|---|
| Nativo bruto | Controle total de validação, layout, CPI | Verificações corretas e disciplina de esquema do cliente |
| Pinocchio / Estilo Steel | Menos boilerplate, CU próximo ao nativo | Revisão de segurança das verificações |
| Anchor 0.32.1 | Restrições, IDL, ergonomia do cliente | Necessidade de entender o modelo subjacente |
Alfabetização nativa torna todas as opções mais seguras, mesmo quando você envia Anchor para a maior parte da superfície do produto.
Layout típico: cdylib, entrypoint!(process_instruction), módulos para instruction, processor, state, e error, mais solana-program e um serializador (frequentemente Borsh). Um entrypoint por binário; múltiplos tipos de instrução vivem atrás de um match em dados parseados. Noções Básicas de Programa Nativo percorre o esqueleto com exemplos.
Uma instrução é um pipeline fixo: entrar, decodificar, validar, agir (ler/escrever e CPI opcional), logar cuidadosamente, retornar.
Cliente (@solana/kit / CLI / Chamador de CPI)
| Lista AccountMeta + instruction_data
| Assina (ou invoke_signed do chamador)
v
Runtime: carrega contas, verifica sigs e metadados graváveis
|
v
entrypoint! -> process_instruction(program_id, accounts, data)
|
| 1. desserializa instruction_data
| 2. next_account_info / ordem fixa de contas
| 3. valida signers, owners, PDAs, relacionamentos
| 4. pega emprestado/modifica dados, ou CPI System Program
| 5. msg! opcional / sol_log_data
v
Ok(()) confirma | Err(ProgramError) aborta instruçãoValide antes de efeitos colaterais sempre que possível. Uma instrução (ou transação) falha não deixa efeitos parciais do programa desse caminho de falha.
pub fn process_instruction(
program_id: &Pubkey,
accounts: &[AccountInfo],
instruction_data: &[u8],
) -> ProgramResultDesserialize uma vez no topo, então match para os manipuladores. Passe program_id para caminhos de PDA e owner. Mapeie erros de domínio para códigos estáveis ProgramError::Custom para clientes.
Os dados de instrução são o formato de comunicação entre construtores off-chain e código on-chain. Um padrão comum é um enum Borsh (primeiro byte do índice da variante, depois os campos):
#[derive(BorshSerialize, BorshDeserialize)]
pub enum VaultInstruction {
Initialize { bump: u8 },
Deposit { amount: u64 },
}Não reordene variantes ativas. Limite strings e vetores ilimitados. Adicione um byte de versão quando precisar quebrar o layout. Espelhe a mesma codificação em TypeScript com @solana/kit 7.0.0 ou um pipeline Codama/schema compartilhado para que os clientes não possam divergir silenciosamente. Veja Serialização/Desserialização de Dados de Instrução.
A segurança nativa é uma lista de verificação explícita em cada caminho:
| Verificação | Padrão |
|---|---|
| Signer | account.is_signer |
| Gravável | account.is_writable |
| Owner é seu programa | account.owner == program_id |
| Owner é System/Token/etc. | igualdade com o ID do programa esperado |
| Identidade PDA | find_program_address + bump armazenado |
| Relacionamentos | igualdade de chaves; campos de mint/authority nos dados |
| Sysvars | Sysvar::get() ou chaves conhecidas, não falsificações |
Execute verificações de flags baratas antes de CPI ou desserialização pesada. Documente a ordem das contas; consuma com next_account_info. Para contas de token, o owner é o programa Token; a autoridade e o mint vivem dentro dos dados.
if !payer.is_signer {
return Err(ProgramError::MissingRequiredSignature);
}
if vault.owner != program_id {
return Err(ProgramError::IncorrectProgramId);
}
let (expected, bump) = Pubkey::find_program_address(
&[b"vault", payer.key.as_ref()],
program_id,
);
if expected != *vault.key || bump != stored_bump {
return Err(ProgramError::InvalidSeeds);
}Validação Manual de Contas cobre ataques de substituição e listas de verificação reutilizáveis.
O estado de propriedade do programa é um buffer de bytes. Pegue emprestado, analise, modifique, escreva de volta dentro do comprimento da conta.
try_borrow_data / try_borrow_mut_data.let mut data = account.try_borrow_mut_data()?;
let mut state = State::deserialize(&mut &data[..])
.map_err(|_| ProgramError::InvalidAccountData)?;
state.count = state.count.checked_add(1).ok_or(ProgramError::InvalidArgument)?;
state.serialize(&mut &mut data[..])
.map_err(|_| ProgramError::AccountDataTooSmall)?;Detalhe: Lendo e Escrevendo Dados de Conta.
Programas criam contas via CPI para o System Program (create_account ou alocar/atribuir relacionados). O pagador financia lamports isentos de aluguel; space dimensiona o buffer; owner se torna seu program_id para o estado do programa.
PDAs não têm chave privada. Use invoke_signed com seeds e bump exatos:
let rent = Rent::get()?;
let lamports = rent.minimum_balance(State::LEN);
invoke_signed(
&system_instruction::create_account(
payer.key, pda.key, lamports, State::LEN as u64, program_id,
),
&[payer.clone(), pda.clone(), system_program.clone()],
&[&[b"vault", owner.key.as_ref(), &[bump]]],
)?;
// inicializa dados após a criaçãoValide o ID do System Program, suposições de conta vazia/nova e correspondência de seeds. Caminhos de reinit e "conta já existe" são classes clássicas de exploração. Fluxo completo: Criando Contas via CPI.
msg! e helpers relacionados escrevem logs de transação para simulação, exploradores e indexadores. O custo escala com o volume e o tamanho da string. Use breadcrumbs estruturados em desenvolvimento e logs esparsos em produção. Prefira erros customizados tipados para falhas esperadas. Veja Emitindo Logs.
Nativo ainda precisa de uma história de cliente: construtores escritos à mão, um crate compartilhado, ou ferramentas Codama/IDL. Testes devem afirmar falhas de validação (owner errado, signer ausente, PDA ruim), não apenas caminhos felizes. Testes unitários estilo LiteSVM e validadores locais sob Solana CLI 3.0.10 cobrem a velocidade da lógica versus loops completos de deploy RPC.
| Fator | Nativo | Anchor 0.32.1 | Nativo fino (ex: Pinocchio) |
|---|---|---|---|
| Velocidade | Mais lento | Mais rápido para apps | Médio |
| Trilhos de segurança | Listas de verificação manuais | Restrições declarativas | Ajudantes, ainda explícito |
| CU / tamanho do binário | Melhor controle | Baseline mais alto | Próximo ao nativo |
| IDL / clientes | Manual ou externo | Embutido | Varia |
| Visibilidade da auditoria | Linha por linha | Expansão de macro | Superfície fina |
| Melhor ajuste | Caminhos quentes, primitivas, layouts incomuns | A maioria dos programas de app | Estilo nativo sensível a CU |
Nativo não é automaticamente mais seguro. É mais transparente. Transparência só ajuda se a lista de verificação for aplicada todas as vezes.
Prefira nativo quando pelo menos dois se aplicarem: CU da instrução é crítica para o negócio; o layout conflita com contas Anchor; o tamanho do binário é restrito; auditores exigem validação totalmente explícita; ou você envia uma primitiva para a qual outros programas farão CPI.
Não escolha nativo apenas porque "Anchor é lento" sem profiling. Contenção, RPC e algoritmos frequentemente dominam a sobrecarga de macros.
Forma comum: Anchor para admin e instruções de baixa frequência; nativo para o loop apertado (passo de match, tick de jogo, liquidação). Componha com CPI e layouts compartilhados. Documente qual ID de programa possui qual estado.
Para cada instrução pergunte: quem deve assinar; quais contas são escritas e com qual owner; um PDA, mint ou conta de token diferente pode ser substituído; initialize pode ser chamado novamente em dados não vazios; seeds/bumps são canônicos; empréstimos são liberados antes da CPI; o layout da instrução corresponde aos clientes publicados?
Fixe Agave, CLI e solana-program como dependências de aplicação. Documente códigos de erro customizados para consumidores de @solana/kit. Trate mudanças de layout como migrações com portões de versão.
Conceito Errado: Nativo pula a segurança porque o runtime já verificou as contas. O runtime verifica assinaturas e metadados graváveis para as contas listadas. Ele não conhece suas seeds de vault, vinculações de mint ou política de admin.
Conceito Errado: is_writable significa que a conta pode ser tratada como seu estado.
Gravável apenas significa que a transação permitiu mutação. Ainda verifique owner, identidade e discriminadores.
Conceito Errado: Owner igual a Token Program é suficiente para "a conta de token do usuário". Autoridade, mint e quantidade vivem nos dados. Valide campos (e muitas vezes a derivação de ATA) para a ação econômica.
Conceito Errado: Enums de instrução podem ser reordenados se o Rust ainda compilar. Índices de variantes são formato de comunicação. Reordenar quebra clientes antigos e pode mapear opcodes antigos para manipuladores novos.
Conceito Errado: Criar um PDA é um create_account simples sem seeds.
Ações autorizadas por PDA precisam de invoke_signed com as seeds que o runtime espera.
Conceito Errado: Logging é observabilidade gratuita. Logs custam CU e incham metadados. Não são substitutos para erros ou métricas off-chain.
Conceito Errado: Nativo é automaticamente mais seguro que Anchor. Ambos falham sob validação incorreta. Nativo move o padrão de "macro pode omitir" para "autor pode omitir".
Conceito Errado: Programas nativos não precisam de um IDL ou esquema de cliente. Sem uma codificação publicada, os construtores divergem. Envie um esquema, crate compartilhado ou pipeline Codama.
Um crate SBF solana-program com um entrypoint que analisa manualmente dados de instrução, valida AccountInfos e atualiza o estado de propriedade do programa (muitas vezes com CPI do System Program), sem macros Anchor.
Não. Ambos são SBF sob o mesmo runtime Agave. Anchor gera mais cola; a cadeia vê um ID de programa e bytecode de qualquer maneira.
program_id, uma fatia de AccountInfo para contas listadas e uma fatia de bytes de dados de instrução.
Clientes constroem uma lista paralela de AccountMeta. Manipuladores tipicamente consomem contas em ordem fixa com next_account_info. Documente essa ordem ou gere-a a partir de uma única fonte de verdade.
Identidade de negócios: qual PDA, mint e autoridade; se initialize já foi executado; relacionamentos entre contas; e política de owner além da presença de assinatura.
Prefira um layout versionado e documentado (comumente um enum Borsh). Mantenha variantes estáveis, limite tamanhos dinâmicos e espelhe o layout nos clientes.
CPI system_instruction::create_account com lamports isentos de aluguel, espaço desejado e owner = program_id. Use invoke_signed quando o novo endereço for um PDA.
Sempre que um PDA precisar autorizar uma ação porque nenhuma chave privada Ed25519 existe para esse endereço.
Verifique owner e comprimento, pegue emprestado os dados, desserialize ou use uma visualização segura, modifique com aritmética verificada, serialize dentro da capacidade e libere empréstimos antes da CPI na mesma conta.
Não. Use-os para depuração e breadcrumbs esparsos em produção. Prefira valores claros de ProgramError para falhas esperadas.
Construa transações que listem as contas corretas e serialize os mesmos bytes de instrução que o programa espera, usando @solana/kit 7.0.0 ou outros SDKs.
Nativo tem um piso mais baixo e mais controle, mas o CU real depende de verificações, logs, serialização e CPI. Meça instruções quentes.
Sim. Programas separados compostos com CPI é comum: Anchor para superfícies de admin, nativo para lógica central sensível ao desempenho.
Validação incompleta: signer ausente, owner errado, substituição de PDA ou reinicialização em conta existente. Trate cada instrução como entrada hostil.
Comece com Noções Básicas de Programa Nativo, depois aprofunde validação, dados de instrução, criação via CPI, I/O de conta e logs através dos Relacionados abaixo.
invoke_signed de PDAmsg!, custo de CU e disciplina de logging em produçãoVersõ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.
Revisado por Chris St. John·Última atualização: 12 de jul. de 2026