@solana/kit En Detalle

@solana/kit 7.0.0 es la pila de cliente moderna de TypeScript para Solana: composición funcional, tipos de marca, módulos aptos para tree-shaking y E/S de red explícitas. Es la opción predeterminada para nuevos clientes en 2026. El legado @solana/web3.js v1 es una fuente de migración, no un valor predeterminado para desarrollos nuevos.

Esta página mapea RPC, suscripciones, keypairs y signers, mensajes de transacción, codecs, tablas de búsqueda de direcciones (ALT) y la ruta de migración de web3.js v1 antes de las páginas de recetas enfocadas.

Resumen

Kit divide lo que web3.js v1 empaquetaba en Connection, Transaction y PublicKey en superficies más pequeñas y tipadas. Creas un cliente RPC para JSON-RPC HTTP, un cliente de suscripciones para WebSockets y construyes mensajes de transacción con transformaciones puras (pipe, pagador de tarifa, vida útil del bloquehash, instrucciones) antes de firmar y enviar.

Los signers son la unidad de autorización: KeyPairSigner locales para scripts y pruebas, signers respaldados por billetera para navegadores, todos compartiendo una interfaz para que los pagadores de tarifa y las autoridades de instrucciones no sean cadenas de claves públicas ad hoc. Las direcciones son cadenas base58 de marca validadas en la construcción. Las cantidades que tocan la cadena son lamports bigint, no SOL flotantes ni BN por defecto.

Los codecs codifican y decodifican layouts de instrucciones y cuentas sin asumir la generación de código de Anchor. Los mensajes de versión 0 más las ALT reducen las listas de cuentas cuando los conjuntos de cuentas de acceso múltiple DeFi o los conjuntos grandes restantes agotarían los límites de tamaño. La migración es intencional: primero migra las lecturas, luego la construcción de mensajes y la firma de billeteras, luego elimina web3.js para no ejecutar dos modelos mentales de cliente para siempre.

Fundamentos

Para qué sirve kit

@solana/kit es un SDK de cliente, no un framework en cadena. Habla con nodos RPC, construye transacciones en formato de cable, firma (o entrega la firma a una billetera) y decodifica bytes de cuenta. La lógica en cadena todavía vive en programas (nativos, Anchor 0.32.1, Pinocchio, etc.).

web3.js v1 vs kit 7.x de un vistazo

Las API de clase mutable fomentaban la edición de un objeto de transacción hasta que funcionara. Kit prefiere un pipeline: crear mensaje, establecer pagador de tarifa y vida útil, agregar instrucciones, comprimir opcionalmente con ALT, firmar y luego enviar y confirmar.

Piezas de marca principales

• Address: cadena de clave pública base58 validada para cuentas y programas.
• Lamports / cantidades bigint: enteros que miran a la cadena; convertir solo en el borde de la UI.
• Signer: algo que puede autorizar un rol (pagador de tarifa, fuente de transferencia, autoridad).
• Mensaje de transacción: estructura versionada que contiene el pagador de tarifa, la vida útil y las instrucciones antes de que existan las firmas.
• Codec: par codificador/decodificador para un layout de bytes (struct, enum, arrays fijos/variables, direcciones).

Dónde se ubica cada página de recetas

Mecánica

Un flujo de cliente productivo es lo suficientemente fijo como para memorizarlo; otros flujos especializan este pipeline.

Pipeline de cliente de extremo a extremo

  App / script / manejador de ruta
       |
       |  1. createSolanaRpc(+ suscripciones)
       |  2. resolver Signer(s) y valores Address
       |  3. obtener blockhash (vida útil) y cualquier lectura de cuenta
       |  4. createTransactionMessage({ version: 0 })
       |  5. establecer pagador de tarifa + vida útil + instrucciones (pipe)
       |  6. opcional: comprimir con tablas de búsqueda de direcciones
       |  7. signTransactionMessageWithSigners (o billetera)
       |  8. enviar + confirmar con el compromiso elegido
       v
  RPC de clase Agave / clúster

1. RPC y suscripciones

createSolanaRpc(url) devuelve un proxy JSON-RPC tipado. Los métodos no acceden a la red hasta que llamas a .send(). Eso hace que la construcción de solicitudes, las estrategias de agrupación y las pruebas sean menos mágicas que los métodos que se activan al llamar.

Las suscripciones usan un cliente separado (createSolanaRpcSubscriptions) a través de WebSocket. Las API de notificación devuelven flujos que consumes con for await y cancelas con AbortSignal. Las URL HTTP y WS deben apuntar al mismo clúster; un error común de producción es mainnet HTTPS con WSS todavía en devnet.

El compromiso (processed, confirmed, finalized) es una opción de primera clase en lecturas y confirmaciones. La UX del producto generalmente espera en confirmed; los efectos fuera de la cadena irreversibles deben esperar en finalized.

2. Keypairs y signers

Los scripts y las pruebas generan o cargan material de clave:

• generateKeyPairSigner() para identidades efímeras Ed25519.
• createKeyPairSignerFromBytes (o ayudantes de importación relacionados) para arrays JSON de solana-keygen.

Las aplicaciones del navegador no deben incrustar claves secretas. Los adaptadores de billetera y las integraciones de Wallet Standard exponen signers que implementan los mismos roles sin revelar claves privadas. Los pagadores de tarifa utilizan ayudantes como setTransactionMessageFeePayerSigner para que el mensaje lleve tanto la dirección como la capacidad de firma.

La firma de mensajes fuera de la cadena para autenticación es una preocupación paralela: la misma identidad, diferente carga útil. Mantenga la separación de dominios para que las firmas de inicio de sesión no se confundan con las aprobaciones de transacciones.

3. Mensajes de transacción

Prefiere los mensajes de versión 0 para trabajos nuevos. Construye de forma inmutable:

1. createTransactionMessage({ version: 0 })
2. Establece el pagador de tarifa (consciente del signer).
3. Establece la vida útil a partir de un resultado fresco de getLatestBlockhash.
4. Agrega instrucciones (presupuesto de cómputo primero cuando establezcas el límite/precio de CU).
5. Firma una vez que el mensaje esté completo.

pipe mantiene las transformaciones de varios pasos legibles. Las instrucciones a menudo provienen de paquetes con ámbito como @solana-program/system (getTransferSolInstruction) en lugar de un único objeto monolítico SystemProgram. Las transacciones de varias instrucciones siguen siendo atómicas en cadena: todas tienen éxito o ninguna se confirma.

Los blockhashes obsoletos caducan. Obtén la vida útil cerca del envío y diseña reintentos para reconstruir mensajes en lugar de reutilizar una vida útil muerta.

4. Codecs y serialización

Los programas hablan bytes. Los codecs de Kit componen primitivas pequeñas en structs:

• Anchos fijos: u8, u32, u64 y similares como codificadores/decodificadores.
• getAddressEncoder / getAddressDecoder para claves públicas de 32 bytes en layouts.
• getStructEncoder / getStructDecoder para layouts de campos ordenados.
• Discriminadores (a menudo hashes de Anchor de 8 bytes o etiquetas personalizadas) como campos iniciales.

Usa codecs cuando no tengas un cliente generado, cuando indexes cuentas sin procesar o cuando valides datos de instrucciones antes de enviar. Prefiere los clientes generados por Codama o Anchor para APIs de programas conocidas; mantén codecs escritos a mano para los bordes que los generadores no cubren.

El orden de bytes, el relleno y las etiquetas de opción deben coincidir con el layout en cadena. Un tipo TypeScript limpio que difiere del layout borsh/bytemuck del programa sigue siendo incorrecto en el cable.

5. Tablas de búsqueda de direcciones

Las listas de cuentas heredadas y de gran tamaño fallan con límites de tamaño o recuento de cuentas. Los mensajes de versión 0 pueden hacer referencia a cuentas a través de tablas de búsqueda de direcciones: tablas en cadena de direcciones que el runtime expande durante el procesamiento para que la transacción de cable lleve índices compactos en lugar de claves completas para cada cuenta.

En el lado del cliente, obtén los datos de la cuenta de la tabla, construye un mensaje lógico completo y luego comprime con ayudantes como compressTransactionMessageUsingAddressLookupTables. Las tablas deben existir y estar activadas antes del uso en producción; crear/extender/congelar es trabajo operativo, no gratuito en el momento del envío.

Usa ALT para rutas DeFi grandes, operaciones masivas de NFT y conjuntos de cuentas grandes y repetidos. Omite la complejidad de ALT para transferencias simples de dos cuentas.

6. Firmar, enviar, confirmar

Una vez que el mensaje está completo, signTransactionMessageWithSigners resuelve los signers incrustados. Las fábricas como sendAndConfirmTransactionFactory({ rpc, rpcSubscriptions }) esperan el compromiso elegido. Una firma significa que la presentación fue aceptada; la corrección del producto aún depende de la política de confirmación y los errores (blockhash expirado, fondos, simulación).

Avanzado

Mentalidad de migración desde web3.js v1

No reescribas toda la aplicación en una sola PR si la superficie es grande. Una secuencia duradera:

Convierte PublicKey a Address en los límites de los módulos una vez. Estandariza bigint para lamports. Reemplaza los hábitos de confirmación implícitos con fábricas explícitas y compromiso. Elimina las pilas duales en una fecha límite; la migración parcial interminable duplica la superficie de errores.

Tree-shaking y límites de paquetes

Importa solo los ayudantes que necesites. Prefiere los constructores de instrucciones de @solana-program/* sobre las metas de cuenta copiadas. Mantén el código de la billetera fuera de los paquetes del servidor/edge; carga keypairs de archivo solo en scripts de Node dedicados.

Compromiso, proveedores y confiabilidad

Los RPC públicos limitan agresivamente las tasas. La producción necesita una URL de proveedor, puntos finales HTTP y WS separados y retroceso en 429/5xx. Las suscripciones se caen; reconéctate con retroceso y resincroniza desde HTTP en lugar de asumir un flujo sin interrupciones.

Codecs en sistemas multiservicio

Comparte módulos de layout (o genera una vez) entre frontend, workers e indexadores. Los analizadores escritos a mano divergentes son una clase de incidente silencioso. Versiona los datos de la cuenta en cadena cuando evolucionen los layouts; decodifica a través del discriminador o campos de versión.

ALT en el diseño de productos

Trata las tablas de búsqueda como infraestructura: la propiedad, la autoridad, la cadencia de extensión y la política de congelación pertenecen a los manuales de ejecución. Evita vistas de tabla cacheadas obsoletas; mide el tamaño del cable antes y después de la compresión en CI para rutas críticas.

Postura de prueba

Prueba unitariamente las transformaciones de mensajes puras y los codecs sin conexión. Prueba de integración de envío/confirmación en validadores locales (Solana CLI 3.0.10 / clase Agave) o entornos tipo Surfpool. Simula antes de enviar para detectar meta-errores más baratos que los reintentos en mainnet.

Conceptos erróneos comunes

Concepto erróneo: Kit es "web3.js con diferentes rutas de importación". El modelo de programación cambió: mensajes inmutables, tipos de marca, .send() explícito e interfaces de signer. Tratarlo como un cambio de nombre garantiza un código híbrido incómodo.

Concepto erróneo: PublicKey y Address son intercambiables en todas partes. No son el mismo tipo. Convierte en los límites; no pases instancias de clase a las API de kit que esperan cadenas de marca.

Concepto erróneo: Si .send() es molesto, sáltatelo o envuélvelo para siempre. .send() hace que la E/S sea explícita. Puedes envolverlo finamente para la ergonomía de la aplicación, pero ocultar todos los límites de red tiende a recrear el antiguo desorden implícito de Connection.

Concepto erróneo: Las dapps del navegador deberían incluir KeyPairSigners en el paquete. La autoridad del usuario pertenece a las billeteras. Los signers de keypair locales son para servidores, CI y pruebas (con higiene secreta).

Concepto erróneo: Los codecs son solo para personas sin Anchor. Los clientes generados cubren programas conocidos. Los codecs siguen siendo importantes para cuentas desconocidas, layouts personalizados, migraciones e indexadores.

Concepto erróneo: Las ALT reemplazan un diseño de cuenta cuidadoso. Comprimen referencias; no eliminan la contención de bloqueo, el costo de CU ni la necesidad de metadatos correctos de escritura/signer.

Concepto erróneo: Una cadena de firma significa que la transferencia es final. El compromiso de confirmación decide la durabilidad. Diseña la UX y los efectos de backend en torno a esa escalera.

Concepto erróneo: Ejecutar kit y web3.js uno al lado del otro indefinidamente está bien. Funciona brevemente. A largo plazo, pagas el doble de peso de dependencia y el doble de carga cognitiva. Planifica la eliminación.

Preguntas frecuentes

Relacionado

• RPC y Suscripciones - JSON-RPC HTTP tipado y flujos de notificación de WebSocket
• Keypairs y Signers - KeyPairSigner, signers de billetera y roles de pagador de tarifa
• Construcción de Mensajes de Transacción - composición de pipe, vida útil, instrucciones, presupuesto de cómputo
• Codecs y Serialización - codificadores y decodificadores componibles para datos de cuenta e ix
• Tablas de Búsqueda de Direcciones - compresión de versión 0 con tablas de búsqueda en cadena
• Migración desde web3.js v1 - mapa de patrones y eliminación por fases de clientes heredados

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.