Estándares de Código y Programas
Estándares consistentes reducen el tiempo de revisión y los hallazgos de auditoría: dónde viven los PDA, cómo se nombran los errores, cómo los clientes codifican las cantidades. Esta página define las convenciones del equipo para programas nativos y de Anchor en Agave 4.1.1.
Receta
Tarjeta de referencia rápida - lista para copiar y pegar.
// programs/<name>/src/constants.rs
pub const JUPITER_PROGRAM_ID: Pubkey = pubkey!("JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4");
// programs/<name>/src/error.rs
#[error_code]
pub enum VaultError {
#[msg("El programa está pausado")]
Paused,
}Cuándo consultar esto:
- Incorporación de nuevos ingenieros
- Redacción de reglas de linter y CI
- Lista de verificación de preparación para auditoría
- Referencia para guías de contribuyentes de código abierto
Ejemplo de Trabajo
// Nomenclatura de cuentas: <Entidad><Rol> ej. 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>,
// Aritmética
let new_total = config.total_deposits
.checked_add(amount)
.ok_or(VaultError::Overflow)?;// packages/clients - cantidades como bigint
const amountLamports = parseSolToLamports(userInput); // nunca Number() para tokensLo que esto demuestra:
- IDs de CPI centralizados en
constants.rs - Patrón obligatorio
checked_add - INIT_SPACE para el dimensionamiento de cuentas de Anchor 0.32.1
- Política de enteros para tokens del cliente
Análisis Profundo
Diseño del Repositorio
programs/ Crates de Anchor/nativos
tests/litesvm/ Pruebas de integración
app/ dApp Next.js
packages/idl/ IDL publicado + generación de código
docs/adr/ Decisiones de arquitecturaNomenclatura
| Elemento | Convención |
|---|---|
| Instrucciones | snake_case verbo deposit_sol |
| Cuentas | PascalCase UserPosition |
| Errores | PascalCase enum VaultError |
| PDAs | Semillas documentadas arriba #[account] |
Trampas Comunes
- Números mágicos en semillas - Confusión en auditoría. Solución:
pub const SEED_VAULT: &[u8] = b"vault"; unwrap()en programas - Pánico = superficie de explotación. Solución:?yErrorCode.- Cadenas de ID de programa duplicadas - Desfase cliente/servidor. Solución: Un solo crate de constantes o env de un paquete.
- Omitir
rustfmten CI - Ruido en la revisión. Solución: Se requierecargo fmt --check. - Mezcla de web3.js y kit - Dos pilas RPC. Solución: Solo kit para código nuevo según ADR.
Alternativas
| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
Rust nightly | Necesidad de función inestable | Programas de producción |
allow clippy generalizado | Migración heredada | Código nuevo |
| Subconjunto de Pinocchio | Solo ruta crítica | Todo el equipo no capacitado |
Preguntas Frecuentes
¿Estándares de Anchor vs. nativos?
Las mismas reglas de seguridad; nativo añade una lista de verificación de validación manual.
¿Idioma de los comentarios?
Inglés para consistencia de auditoría y código abierto.
¿`Public` vs `pub(crate)`?
Minimizar la superficie de API pública en los crates del programa.
¿Nomenclatura de pruebas?
test_<ix>_<escenario> en módulos LiteSVM.
¿Incluir verificación de IDL?
Comprometido en packages/idl; hash en CI.
¿Banderas de características en Rust?
cfg(feature = "mainnet") es raro; preferir un booleano de configuración en cadena.
¿Registro (Logging)?
msg! con moderación; sin datos secretos en los registros.
¿Política de dependencias?
Ver página de gobernanza de dependencias; cargo deny en CI.
¿Encabezados de licencia?
Requeridos para repositorios de código abierto; opcionales para internos.
¿Aplicación?
CI + lista de verificación de plantilla de PR + cultura de revisión.
Relacionado
- Gobernanza de Dependencias y Crates - política de crates
- Convenciones de Documentación - documentación junto al código
- Cultura de Revisión de Código - aplicación humana
Versiones de la Pila: Esta página fue 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, y LiteSVM 0.6.x.