Crates Esenciales

Desplegar en Solana significa ensamblar una pila de crates y librerías, no memorizar un único framework. Los programas on-chain, los clientes off-chain, la serialización, los activos digitales y los harnesses de prueba tienen cada uno su capa. Una vez que veas a qué capa pertenece una dependencia, los grafos de Cargo y npm dejarán de parecer ruido y empezarán a parecer un mapa deliberado al que puedes fijar Agave 4.1.1, Anchor 0.32.1, Rust 1.91.1 y @solana/kit 7.0.0.

Las inmersiones profundas en esta sección se centran en pares y pilas: solana-program & solana-sdk, anchor-lang & anchor-spl, borsh & bytemuck, pinocchio & steel, mpl-core & mpl-token-metadata, @solana/kit, Codama & gill, y litesvm, mollusk & solana-bankrun. Esta página se sitúa debajo: cómo encajan las piezas, cuándo se justifica cada capa y cómo los equipos evitan mezclar generaciones en un monorepo.

Resumen

• Las librerías esenciales de Solana son un mapa de dependencias en capas - crates de programa/SDK de plataforma, frameworks opcionales (Anchor o Pinocchio/Steel), serialización, crates de producto SPL/MPL, clientes TypeScript (kit/Codama/gill) y harnesses de prueba - y cada capa resuelve un problema diferente.
• Por Qué Importa: Las elecciones incorrectas de capa causan fallos de compilación sBPF, hinchazón de CU, deriva de IDL, errores de codificación en mainnet y CI lenta; un mapa claro te permite elegir pilas de productos por defecto, rutas nativas críticas para la CU y pruebas coincidentes sin hacer cargo-culting de cada crate en cada binario.
• Conceptos Clave: solana-program vs solana-sdk, Anchor 0.32.1, Pinocchio/Steel, Borsh vs bytemuck, SPL y Metaplex, @solana/kit / Codama / gill, alineación de versiones.
• Cuándo Usar: Para iniciar un monorepo, elegir frameworks nativos vs Anchor vs ligeros, diseñar la generación de código de cliente, estandarizar harnesses de prueba o revisar la higiene de dependencias antes de una actualización de mainnet.
• Limitaciones / Compensaciones: Más capas significan más pines y superficie de auditoría; los frameworks intercambian CU y tamaño de ELF por velocidad; las pilas de cero copia y ligeras exigen una disciplina de validación más estricta; los harnesses de prueba difieren en fidelidad de los validadores completos.
• Temas Relacionados: anchor-lang/spl, borsh/bytemuck, pinocchio/steel, crates de Metaplex, kit/Codama/gill, LiteSVM/Mollusk/Bankrun, mejores prácticas de librerías.

Fundamentos

El desarrollo de Solana es multi-target por diseño. Las crates on-chain compilan a sBPF con cargo build-sbf bajo las herramientas de plataforma de Solana CLI 3.0.10. Los off-chain Rust y TypeScript hablan con RPC, firman transacciones y decodifican cuentas. La serialización define cómo se organizan los bytes de instrucciones y cuentas. Las crates de activos de producto (SPL Token, Metaplex) envuelven programas ampliamente desplegados. Los harnesses de prueba aproximan el comportamiento del runtime sin iniciar siempre un validador completo.

Trata el ecosistema como capas desde el cargador hasta la aplicación, no como una lista de deseos plana de Cargo.toml:

  +----------------------------------------------+
  |  Lógica de producto de la App / bot / dApp   |
  +----------------------------------------------+
  |  Clientes TS: @solana/kit, Codama, gill      |  <- JS/TS off-chain
  +----------------------------------------------+
  |  Activos de producto: SPL Token, MPL Core/TM |  <- CPI + layouts
  +----------------------------------------------+
  |  Framework: anchor-lang / anchor-spl         |
  |             o pinocchio / steel              |  <- opcional
  +----------------------------------------------+
  |  Codificación: borsh, bytemuck (zero-copy)   |
  +----------------------------------------------+
  |  Plataforma: solana-program (on-chain)       |
  |            solana-sdk + client (off-chain)   |
  +----------------------------------------------+
  |  Pruebas: LiteSVM, Mollusk, Bankrun          |  <- track paralelo
  +----------------------------------------------+

Las crates de plataforma son innegociables. solana-program es la librería estándar on-chain (AccountInfo, puntos de entrada, CPI, sysvars, errores de programa). solana-sdk y las crates de cliente relacionadas potencian los binarios host que construyen, firman y envían transacciones. Mantén solana-sdk fuera de las crates de programa; kit nunca sustituye a la ruta sBPF.

Las crates de framework se sitúan por encima de la plataforma. anchor-lang 0.32.1 proporciona macros, restricciones e IDL; anchor-spl añade CPIs tipadas de SPL. Esa es la ruta de producto por defecto. Pinocchio y Steel son opciones nativas ligeras cuando el tamaño de ELF y la CU importan más que la ergonomía de Anchor.

La serialización es ortogonal a la elección del framework. Borsh es el default flexible (incluyendo la mayoría de los layouts de Anchor). bytemuck permite casts POD de cero copia cuando controlas la alineación, el padding y la validación. La elección incorrecta se manifiesta como picos de CU o casts inseguros sin comprobaciones.

Las crates de producto (spl-token, helpers de ATA, mpl-token-metadata, mpl-core) envuelven programas conocidos desplegados para activos y CPIs. No son un segundo runtime. Elige Token Metadata vs Core según el modelo de producto.

La pila de clientes para TypeScript greenfield: @solana/kit 7.0.0 para RPC, codecs y mensajes; Codama para clientes nativos de kit a partir de IDL de Anchor; gill como azúcar opcional. Evita nuevas aplicaciones sobre @solana/web3.js v1.

Los harnesses de prueba cierran el ciclo: LiteSVM para pruebas rápidas de Rust in-process, Mollusk para fixtures de instrucciones/ELF, solana-bankrun para integración en TypeScript. El solana-test-validator completo sigue siendo la opción de humo.

Mecánicas e Interacciones

Plataforma primero: programa vs SDK

Cada binario de programa depende de los tipos de plataforma. Las rutas nativas y muchas de Pinocchio importan solana-program (o re-exportaciones compatibles). Anchor re-exporta muchos primitivos para que el código de producto rara vez los importe directamente, pero las auditorías y el trabajo de CU todavía requieren alfabetización en la plataforma.

Los CLIs y harnesses de Rust off-chain usan solana-sdk (Pubkey, Instruction, Transaction, signers) con clientes RPC. Las dApps de TypeScript usan kit en su lugar, pero los roles coinciden: componer instrucciones, adjuntar cuentas, firmar, enviar, confirmar.

  Binario on-chain                Binario / dApp off-chain
  -----------------               -----------------------
  solana-program                  solana-sdk  O  @solana/kit
  (+ Anchor o Pinocchio)          (+ Codama / gill / solders)
           |                                   |
           v                                   v
     Despliegue sBPF .so              Envío RPC + decodificación

Elección de una capa de framework de programa

Anchor es el default cuando quieres clientes impulsados por IDL y validación estándar. Pinocchio/Steel son adecuados para CU medida, tamaño de binario o preferencia de auditoría frente a macros. Mezclar frameworks entre programas en un monorepo está bien; mezclarlos dentro de un mismo binario sin una frontera generalmente no lo está.

Serialización: Borsh vs bytemuck

Los datos de instrucciones y el estado de las cuentas son bytes. Borsh es el default determinista para la mayoría de argumentos y cuentas (incluyendo Anchor). bytemuck reinterpreta la memoria de cuentas POD para rutas hot paths cuando los layouts se validan.

  Estado flexible / en evolución  -->  Borsh (serializar / deserializar)
  POD fijo, sensible a CU        -->  bytemuck (+ comprobaciones estrictas de inicialización y tamaño)
  Rutas zero_copy de Anchor      -->  layouts estilo bytemuck bajo reglas de framework

Prefiere Borsh para argumentos y estado en evolución; reserva zero-copy para cuentas grandes y hot paths. Nunca hagas cast de datos no confiables sin comprobaciones de propietario, tamaño, discriminador y alineación.

SPL y Metaplex como capas de producto

Los saldos de tokens, ATAs y activos digitales residen en programas desplegados. Tu código depende de builders y layouts (spl-token, helpers de ATA, mpl-token-metadata, mpl-core), a menudo a través de anchor-spl o helpers del lado del kit.

Usa Token Metadata para metadatos clásicos adjuntos a mint y convenciones de marketplace. Usa MPL Core cuando el modelo Core y sus plugins se ajusten mejor a la emisión. Fija las crates a la revisión del programa y al layout contra los que despliegas.

Clientes: kit, Codama, gill

Con Anchor, anchor build emite IDL; Codama genera builders y decodificadores orientados a kit. kit 7.0.0 gestiona RPC, mensajes y firmantes. gill acorta patrones comunes de kit pero no reemplaza la salida específica del programa de Codama.

  anchor build --> target/idl/*.json --> renderizado por Codama
                                              |
                                              v
                                   ensamblaje con kit (+ gill opcional)

Las aplicaciones brownfield pueden mantener la API clásica de Program de TS de Anchor; las aplicaciones kit greenfield deberían preferir Codama + kit. Una aplicación, una historia de transacciones principal.

Pruebas: LiteSVM, Mollusk, Bankrun

Usa LiteSVM o Mollusk para las crates de programa y Bankrun o la prueba de humo del validador para los paquetes de cliente. Alinea los harnesses con la semántica de Agave para que la CI no apruebe comportamientos que mainnet rechaza.

Cómo interactúan las capas en un producto

1. Fija Rust 1.91.1, Agave 4.1.1 / CLI 3.0.10 y Anchor 0.32.1 (si se usa).
2. Elige la capa de framework por binario de programa (default Anchor, Pinocchio cuando exista necesidad medida).
3. Codifica el estado con Borsh a menos que una ruta hot path perfilada necesite bytemuck/zero-copy.
4. Haz CPI a SPL/MPL con crates con versiones emparejadas y los IDs de programa correctos por clúster.
5. Genera clientes a partir de IDL vía Codama en kit 7.0.0; usa gill solo como azúcar.
6. Prueba con LiteSVM/Mollusk en Rust y Bankrun o prueba de humo del validador para rutas TS.
7. Controla los lanzamientos con auditorías, higiene de cargo tree y compilaciones verificables donde la confianza lo requiera.

Consideraciones Avanzadas y Aplicaciones

Recetas de pila por forma de producto

Alineación de versiones y cadena de suministro

Las crates que compilan juntas aún pueden estar mal si abarcan generaciones de SDK. Fija solana-program / solana-sdk al canal de Agave, mantén anchor-lang y Anchor CLI en 0.32.1, fija kit 7.0.0 en todo el monorepo y regenera los clientes de Codama cuando cambien los IDL. Prefiere las crates de referencia de Anza, Anchor y Metaplex; ejecuta cargo audit / cargo deny / npm audit. Omite wrappers que solo re-exportan tres líneas de kit o solana-program. Las compilaciones verificables prueban el artefacto; la revisión de dependencias es aparte. Lista de verificación: Mejores Prácticas de Librerías Esenciales.

Conceptos Erróneos Comunes

• "Necesito cada crate esencial en cada programa." Las capas son opcionales; los programas necesitan plataforma + codificación + framework elegido, no Metaplex y Bankrun dentro del mismo crate sBPF.
• "anchor-lang reemplaza a solana-program." Anchor se basa en primitivos de plataforma; las auditorías y el trabajo de CU todavía necesitan esa alfabetización.
• "solana-sdk pertenece al Cargo.toml on-chain." Usa solana-program (o re-exportaciones del framework) on-chain; sdk es para binarios host.
• "Pinocchio es siempre más rápido, así que úsalo siempre." Mide; muchos productos están limitados por la validación y la velocidad del producto, no por la sobrecarga del framework.
• "Borsh está obsoleto si existe bytemuck." Borsh sigue siendo el default flexible; zero-copy es una optimización específica.
• "kit reemplaza a Anchor." kit es TypeScript off-chain; no compila programas ni reemplaza anchor-lang.
• "Codama y gill son intercambiables." Codama genera clientes de programa a partir de IDL; gill es azúcar kit opcional, no tu ABI.
• "LiteSVM significa que nunca necesito un validador." Los harnesses in-process pierden algunas integraciones y fallos solo de RPC; mantén cobertura de pruebas de humo para lanzamientos.
• "Emparejar versiones mayores es suficiente." Anchor CLI y las crates deben compartir una línea; Agave, las herramientas de plataforma y las crates de SDK deben compartir una generación.

Preguntas Frecuentes

Relacionado

• anchor-lang & anchor-spl - crates de framework, IDL y helpers de CPI de SPL
• borsh & bytemuck - defaults de serialización y rutas zero-copy
• litesvm, mollusk & solana-bankrun - harnesses de prueba de programas y clientes
• mpl-core & mpl-token-metadata - crates de activos digitales de Metaplex
• pinocchio & steel - frameworks de programas nativos ligeros
• @solana/kit, Codama & gill (JS/TS) - pila moderna de clientes TypeScript

Versiones de la pila: Esta página fue escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1 y @solana/kit 7.0.0.