Mejores Prácticas para Bibliotecas Esenciales

Los repositorios de Solana acumulan docenas de crates y paquetes npm. Estas reglas mantienen las dependencias alineadas con Agave 4.1.1, Anchor 0.32.1 y @solana/kit 7.0.0, al tiempo que reducen el riesgo de cadena de suministro y auditoría.

Cómo Usar Esta Lista

• Ejecutar durante el arranque del repositorio y antes de cada actualización de programa a mainnet.
• Aplicar por separado a Cargo.toml on-chain, Rust off-chain y paquetes cliente TS.
• Emparejar con cargo audit, npm audit y verificaciones de compilación verificables.

A - Alineación de Versiones

• Fijar crates SDK alineados con el validador. solana-program, solana-sdk y CLI 3.0.10 comparten una generación.
• Hacer coincidir anchor-lang y Anchor CLI en 0.32.1. Previene la deriva de IDL y macros.
• Fijar @solana/kit a 7.0.0 en todos los paquetes del monorepo. Evita duplicados de versiones principales en una misma aplicación.
• Documentar Agave 4.1.1 en README/archivos de toolchain. Los nuevos contribuyentes reproducen las compilaciones.
• Regenerar clientes Codama cuando cambie la IDL. CI falla en carpetas generadas sucias.

B - Higiene de Dependencias On-Chain

• Auditar cargo tree para dependencias std-only en programas. Rompe o hincha las compilaciones sBPF.
• Preferir crates SPL/MPL mantenidos sobre copias vendidas. Recibe parches de seguridad.
• Minimizar flags de características en anchor-lang. Cada característica puede expandir el tamaño del ELF.
• Registrar por qué se eligió Pinocchio/Steel si se omite Anchor. ADR para registro de auditoría.
• Verificar las versiones de crates MPL/CPI contra los IDs de programa desplegados. Token-2022 vs SPL clásico difieren.

C - Bibliotecas Cliente

• No iniciar nuevas aplicaciones en @solana/web3.js v1. Usar kit + Codama/gill.
• Mantener los locks de Python solders/solana-py para bots. Envíos reproducibles entre despliegues.
• Separar constantes de ID de programa por clúster. Tablas de devnet/mainnet en un módulo.
• Usar las crates de ix oficiales @solana-program/* con kit. Menos layouts empaquetados manualmente.
• Tratar los ayudantes de DAS como específicos del proveedor. No todas las URLs RPC implementan DAS.

D - Crates de Pruebas y Herramientas

• Estandarizar en LiteSVM 0.6.x para pruebas unitarias de Rust. CI rápida con semántica compatible con Agave.
• Añadir pruebas de humo de Bankrun o validador para brechas de integración. Capturar problemas solo de RPC.
• Fijar Surfpool 0.12.0 para simulaciones de fork. Documentar cuándo se ejecutan las pruebas de fork en CI.
• Cargar explícitamente los blobs del programa SPL Token en las pruebas de harness. Evitar falsos positivos.
• Rastrear pruebas de regresión de CU para instrucciones críticas de rendimiento.

E - Cadena de Suministro y Gobernanza

• Habilitar cargo deny o equivalente para registros desconocidos. Bloquear crates con errores tipográficos.
• Revisar los mantenedores de crates MPL/comunitarias nuevos. Comprobar la cadencia de lanzamiento y la propiedad.
• Preferir crates usadas en las plantillas de referencia de Anza/Anchor. Valores predeterminados probados en batalla.
• Registrar el hash de compilación verificable con el artefacto desplegado. Coincide con el flujo de trabajo de solana-verify.
• Programar una actualización trimestral de dependencias con una matriz de pruebas completa. No saltos de versiones principales por impulso.

Preguntas Frecuentes

Relacionados

• solana-program & solana-sdk - crates principales
• @solana/kit, Codama & gill - stack TS
• Gobernanza de Dependencias y Crates - política de la organización
• Descripción General de Toolchain - pines de versión

Versiones del stack: 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.