Coding & Program Standards
Padrões consistentes reduzem tempo de review e achados de auditoria: onde PDAs vivem, como erros são nomeados, como clientes codificam amounts. Esta página define convenções de equipe para programas Anchor e nativos no Agave 4.1.1.
Receita
Cartão de receita para referência rápida - pronto para copiar e colar.
// programs/<name>/src/constants.rs
pub const JUPITER_PROGRAM_ID: Pubkey = pubkey!("JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4");
// programs/<name>/src/error.rs
#[error_code]
pub enum VaultError {
#[msg("Program is paused")]
Paused,
}Quando usar:
- Onboarding de novo engenheiro
- Autoria de regras de linter e CI
- Checklist de prontidão para auditoria
- Referência de guia para contribuidores open-source
Exemplo Prático
// Account naming: <Entity><Role> e.g. UserPosition, PoolConfig
#[account(
init,
payer = user,
space = 8 + UserPosition::INIT_SPACE,
seeds = [b"position", user.key().as_ref(), pool.key().as_ref()],
bump
)]
pub user_position: Account<'info, UserPosition>,
// Arithmetic
let new_total = config.total_deposits
.checked_add(amount)
.ok_or(VaultError::Overflow)?;// packages/clients - amounts as bigint
const amountLamports = parseSolToLamports(userInput); // never Number() for tokensO que isso demonstra:
- IDs de CPI centralizados em
constants.rs - Padrão obrigatório
checked_add - INIT_SPACE para dimensionamento de conta Anchor 0.32.1
- Política de tokens inteiros no cliente
Aprofundamento
Layout do repo
programs/ Anchor/native crates
tests/litesvm/ Integration tests
app/ Next.js dApp
packages/idl/ Published IDL + codegen
docs/adr/ Architecture decisionsNomenclatura
| Item | Convenção |
|---|---|
| Instructions | verbo snake_case deposit_sol |
| Accounts | PascalCase UserPosition |
| Errors | enum PascalCase VaultError |
| PDAs | seeds documentadas acima de #[account] |
Erros comuns
- Números mágicos em seeds - Confusão em auditoria. Correção:
pub const SEED_VAULT: &[u8] = b"vault"; unwrap()em programas - Panic = superfície de exploit. Correção:?eErrorCode.- Strings duplicadas de program ID - Drift cliente/servidor. Correção: crate constants único ou env de um pacote.
- Pular
rustfmtem CI - Ruído em review. Correção:cargo fmt --checkobrigatório. - web3.js e kit misturados - Duas stacks RPC. Correção: só kit para código novo por ADR.
Alternativas
| Alternativa | Use quando | Não use quando |
|---|---|---|
Rust nightly | Necessidade de feature instável | Programas em produção |
allow clippy amplo | Migração legacy | Código novo |
| Subset Pinocchio | Só hot path | Equipe inteira sem treinamento |
FAQs
Padrões Anchor vs nativo?
Mesmas regras de segurança; nativo adiciona checklist de validação manual.
Idioma de comentários?
Inglês para consistência de auditoria e open-source.
public vs pub(crate)?
Minimize superfície de API pública em crates de programa.
Nomenclatura de testes?
test_<ix>_<scenario> em módulos LiteSVM.
IDL versionado?
Commitado em packages/idl; hash em CI.
Feature flags em Rust?
cfg(feature = "mainnet") raro; prefira bool de config on-chain.
Logging?
msg! com moderação; sem dados secretos em logs.
Política de dependências?
Veja página de governança de dependências; cargo deny em CI.
Cabeçalhos de licença?
Obrigatórios para repos open-source; opcional internamente.
Enforcement?
CI + checklist de template de PR + cultura de review.
Relacionados
- Dependency & Crate Governance - política de crates
- Documentation Conventions - docs ao lado do código
- Code Review Culture - enforcement humano
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.