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.tomlon-chain, Rust off-chain y paquetes cliente TS. - Emparejar con
cargo audit,npm audity verificaciones de compilación verificables.
A - Alineación de Versiones
- Fijar crates SDK alineados con el validador.
solana-program,solana-sdky CLI 3.0.10 comparten una generación. - Hacer coincidir
anchor-langy Anchor CLI en 0.32.1. Previene la deriva de IDL y macros. - Fijar
@solana/kita 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 treepara dependenciasstd-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.jsv1. 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 denyo 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
¿Cuántas crates son demasiadas?
Si la profundidad de cargo tree oculta la lógica del programa, consolida ayudantes internos.
¿Puedo mezclar Anchor y Pinocchio?
Sí, entre diferentes binarios de programa; documentar la elección del framework por programa.
¿Quién es el propietario de los archivos de bloqueo (lockfiles)?
Cargo.lock confirmado para binarios; los programas siguen la política del espacio de trabajo.
¿npm vs pnpm?
Cualquiera de los dos; imponer un único gestor de paquetes en CI para monorepos de kit.
¿IDL vendida?
Sí; tratar la IDL como un contrato de API junto con las versiones de las crates.
¿Crates Alpha?
Evitar en programas de mainnet a menos que el riesgo se acepte por escrito.
¿Actualizaciones de crates mpl?
Probar rutas CPI en devnet; los lanzamientos de MPL pueden cambiar las meta de cuentas.
¿Pin de Rust 1.91.1?
Hacer coincidir rust-toolchain.toml en los espacios de trabajo de programa y cliente.
¿Cumplimiento de licencias?
Rastrear licencias para dependencias MPL/MIT/Apache en avisos de distribución.
¿Parches de emergencia?
Mantener una rama de hotfix con cambios mínimos de versión y revisión rápida de auditoría.
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.