Desarrollo Local en Detalle
El desarrollo local de Solana no es "saltarse la red y esperar". Es una elección deliberada de fidelidad: cuánta del estado de mainnet, superficie de RPC y realismo multi-partes necesitas para la pregunta que estás respondiendo hoy.
Esta página es el mapa conceptual de la sección. Úsala para ubicar solana-test-validator, Surfpool, clonación, fixtures, logs locales, pruebas unitarias de LiteSVM y devnet en un continuo antes de seguir las páginas de recetas.
Resumen
La mayoría del trabajo de programas y clientes debe comenzar en un clúster local en la máquina. Tú controlas la génesis, los airdrops, los IDs de programas y el reinicio del ledger. Nada compite contigo por los slots, y CI puede volver a ejecutar la misma génesis en cada PR.
solana-test-validator (incluido con Agave / Solana CLI) es el clúster local estándar de un solo nodo. Expone JSON-RPC (por defecto http://127.0.0.1:8899), un faucet generoso y ejecución completa de programas BPF/SBF para que los clientes Anchor, CLI y @solana/kit se comporten como clientes RPC remotos.
Cuando necesites layouts de producción, clona cuentas seleccionadas en el test validator o usa un espacio de trabajo de bifurcación de mainnet con Surfpool 0.12.0. Los clones son instantáneas estáticas al inicio. Las herramientas de bifurcación mantienen una superposición similar a la vida real para que los gráficos DeFi sigan siendo útiles sin listas interminables de --clone.
Debajo del RPC local completo se encuentra LiteSVM 0.6.x para pruebas unitarias de Rust sub-segundo sin un clúster HTTP. Por encima de localnet se encuentran las sondas de devnet y mainnet para demos compartidas, IDs de programas multi-portátil y señales débiles sobre efectos de red reales.
La compensación es fija. Más rápido y determinista significa menos realismo compartido. Más realista significa más coste de configuración y estado externo inestable. Elige la menor fidelidad que aún responda a la pregunta.
Fundamentos
Qué significa "local" en Solana
Un entorno local es cualquier superficie de ejecución que no depende de un clúster público para la inclusión. Eso incluye un validador local completo, un simulador de bifurcación con RPC y un arnés SVM en memoria dentro de un binario de prueba de Rust.
Los clientes siguen hablando Solana: blockhashes recientes, metadatos de cuentas, firmas, presupuestos de cómputo y logs de programas. No estás inventando una API falsa. Estás reduciendo o sustituyendo el clúster detrás de los mismos contratos de cliente.
Por qué existe lo local como un bucle de primera clase
Los clústeres públicos penalizan la iteración rápida. Los faucets se limitan, los programas compartidos cambian bajo tu control y las cuotas de RPC rompen CI. Lo local hace que el bucle interno de construir, cargar, enviar, afirmar, reiniciar, y mantiene privados los experimentos de actualización o acuñación sin gastar SOL real.
Las piezas de una pila local
| Pieza | Rol |
|---|---|
| Agave / Solana CLI | Instala solana-test-validator, ayudantes de faucet, herramientas de despliegue y cuenta |
| Ledger local | Estado del disco bajo algo como test-ledger/ a menos que reinicies |
| RPC + WebSocket | Cómo CLI, Anchor, wallets y @solana/kit hablan con el clúster |
| Faucet | SOL de prueba ilimitado para alquiler y tarifas |
| Ruta de carga de programas | Despliega, --bpf-program, o descarga/carga binarios .so |
| Ruta de semilla de estado | Fixtures (--account), clones (--clone), o hidratación de bifurcación |
| Ruta de logs | Salida estándar del validador, solana logs, metadatos de transacciones, contadores de CU |
| Ejecutores de pruebas | anchor test, clientes TS/JS personalizados, pruebas de Rust LiteSVM |
Pines de la cadena de herramientas para esta guía
Trata las versiones como un contrato de equipo. Esta guía asume Agave 4.1.1, Solana CLI 3.0.10, Surfpool 0.12.0, LiteSVM 0.6.x, Anchor 0.32.1, Rust 1.91.1, y @solana/kit 7.0.0. Fija CLI y Anchor como fijas las dependencias de Cargo.toml.
Localnet vs "solo pruebas unitarias"
LiteSVM ejecuta la lógica del programa en proceso para corrección de instrucciones, diseño de cuentas y matemáticas de PDA sin RPC. No es un sustituto para adaptadores de wallet, suscripciones WebSocket, experiencia de usuario de confirmación, o scripts multi-cliente que necesitan un endpoint JSON-RPC real.
Mecánica
Piensa en el desarrollo local como un bucle cerrado: sembrar estado, apuntar clientes a localhost, ejercitar programas, observar logs, reiniciar o mutar, repetir.
Bucle de desarrollo local ASCII
[ Fuente ]
programa Rust (Anchor / nativo)
cliente TS/JS (@solana/kit, Anchor TS)
fixtures / listas de clones / configuración de bifurcación
|
| compilar .so + generar clientes / IDLs
v
+------------------+ opcional: pruebas unitarias LiteSVM
| cargo / anchor |----> aserciones SVM en proceso (sin RPC)
| build |
+------------------+
|
| iniciar backend del clúster
v
+------------------------------------------+
| A) solana-test-validator |
| --reset, --bpf-program, --clone, |
| --account fixtures |
| B) Surfpool (espacio de trabajo mainnet-fork) |
+------------------------------------------+
|
| RPC http://127.0.0.1:8899 (típico)
| faucet para SOL local
v
+------------------+
| config solana |
| Anchor.toml |
| cliente RPC app |
+------------------+
|
| desplegar / airdrop / enviar txs / ejecutar pruebas
v
+------------------+
| ejecución prog. |
| CPI en clones |
| mutaciones estado|
+------------------+
|
| logs, meta, CU, volcados de cuentas
v
+------------------+
| solana logs |
| confirm -v |
| aserciones |
+------------------+
|
| éxito -> promover a devnet / sondas mainnet
| fallo -> arreglar, reiniciar ledger, ajustar fixtures
v
[ siguiente iteración ]
Etapa 1 - Compilación e identidad
Compilas el bytecode del programa (.so) y fijas los IDs de programa a través de keypairs y declare_id!. Los clientes deben llamar a la misma clave pública que el clúster cargó. Las discrepancias se ven como "cuenta no ejecutable" o llamadas a direcciones vacías entre despliegue, --bpf-program y superposiciones de Surfpool.
Etapa 2 - Elegir un backend
solana-test-validator es el clúster local de nodo único predeterminado ajustado por Agave para la velocidad del desarrollador: épocas cortas, inclusión inmediata, restricciones de operaciones relajadas.
Surfpool es la opción moderna orientada a bifurcaciones cuando necesitas estado con forma de mainnet sin una gran lista de clones. Se hidrata desde un RPC de mainnet upstream para que puedas simular contra gráficos de programas realistas.
LiteSVM se sitúa junto a la ruta RPC para pruebas unitarias puras de programas cuando no necesitas HTTP, wallets o concurrencia multi-cliente.
Etapa 3 - Sembrar estado
La génesis local vacía funciona cuando tu programa crea todas las cuentas. El trabajo de integración casi siempre necesita semillas.
Los fixtures son volcados JSON cargados al inicio (--account): deterministas, amigables con git, ideales para CI. Los clones obtienen cuentas en vivo al arrancar (--clone con --url), capturan layouts y bytecode reales, y luego se congelan hasta que las transacciones locales los mutan. Los espacios de trabajo de bifurcación (clase Surfpool) reducen la necesidad de listar cada cuenta dependiente para mallas DeFi u oráculos.
Siembra solo lo que tus instrucciones tocan. El tiempo de arranque y la carga cognitiva escalan con el tamaño de la semilla.
Etapa 4 - Apuntar el mundo al clúster
CLI, URL del proveedor de Anchor, RPC del frontend y RPC personalizado de la wallet deben estar de acuerdo. Un fallo clásico es anchor test desplegando en devnet mientras CLI hace airdrops en localhost.
Para sesiones largas, inicia el validador tú mismo y adjunta las pruebas. Para CI, prefiere --reset en cada trabajo para que la deriva del ledger no haga inestables las suites.
Etapa 5 - Ejercitar y observar
Envía transacciones de la misma manera que lo harías remotamente. La inclusión local es rápida, por lo que la retroalimentación es sobre la lógica del programa y la configuración, no sobre la suerte del mempool.
Inicia los suscriptores de logs antes del tráfico. Usa solana logs, confirmaciones detalladas y metadatos para logMessages y computeUnitsConsumed. La simulación local ilimitada supera a los RPC públicos limitados en tasa para el diagnóstico.
Etapa 6 - Reiniciar o promover
Reinicia para obtener determinismo. Persiste el ledger solo para sesiones exploratorias largas, y documenta esa elección. Promueve cuando necesites IDs de demostración compartidos, experiencia de usuario de wallet pública, coordinación multi-equipo, o sondas de mainnet con tarifas reales.
Avanzado
Usa esta tabla al elegir un entorno, no al discutir qué herramienta es "la mejor" en abstracto.
| Entorno | Fidelidad | Velocidad | Mejor para | Débil en |
|---|---|---|---|---|
| Pruebas unitarias LiteSVM 0.6.x | Lógica del programa + cuentas inyectadas | Sub-segundo | Pruebas de instrucciones Rust, bordes de PDA/matemáticas, micro-puertas de CI | Clientes JSON-RPC completos, wallets, aplicaciones multi-proceso |
| solana-test-validator (básico) | Clúster local completo, génesis vacío o con fixtures | Arranque rápido, inclusión rápida | Bucle predeterminado Anchor/CLI, integración de clientes, CI | Gráficos de pools en vivo sin semillas |
| test-validator + clones/fixtures | Clúster completo + estado con forma de producción congelado | Medio (coste de obtención de clones) | CPI en programas reales, layouts de oráculo/acuñación fijos | Gráficos de dependencia enormes; precios obsoletos después del arranque |
| Surfpool 0.12.0 | Realismo de bifurcación de mainnet con superposición local | Más ligero que el validador básico | Simulaciones DeFi, metadatos de cuentas complejas, pruebas preliminares de mainnet | CI más ligero; velocidad de unidad pura; demos sin dependencias |
| Devnet | Clúster público compartido | Más lento, fricción de faucet/RPC | Demos de wallet, IDs de programas compartidos, QA multi-portátil | CI determinista, airdrops ilimitados, estado de terceros estable |
| Mainnet (sondas mínimas) | Realidad de producción | Costoso, riesgo irreversible | Aterrizaje bajo carga, tarifas reales, comprobaciones finales | Desarrollo diario, experimentación amplia |
Cómo se compone la escalera
Un equipo saludable usa más de un peldaño. LiteSVM detecta regresiones lógicas en milisegundos. El validador local detecta el cableado del cliente y CPI. Surfpool o clones enriquecidos detectan sorpresas en el layout de producción. Devnet comparte un despliegue. Las sondas de mainnet validan las tarifas y el aterrizaje que no puedes simular.
Saltarse peldaños crea una falsa confianza. Un LiteSVM verde por sí solo no demuestra la experiencia de usuario de confirmación de wallet. Un localnet verde por sí solo no demuestra los mercados de tarifas de prioridad.
Clonación vs. bifurcación vs. fixtures
Los fixtures son artefactos creados o exportados: los más reproducibles, los menos "en vivo". Los clones son fixtures automatizados obtenidos una vez al inicio: reproducibles en sesión, luego derivan a medida que los mercados se mueven. Las herramientas estilo bifurcación se mantienen más cerca de mainnet para simulación, cuestan más recursos, dependen de la calidad del RPC upstream, y aún así no garantizan la inclusión o la realidad de MEV.
Logs, cableado y observabilidad
Lo local gana porque la observabilidad es gratuita: transmite logs, resimula, vuelca cuentas sin cuotas. Prefiere lo local para el diagnóstico, luego reproduce un caso mínimo en devnet cuando necesites un artefacto compartido.
La URL del proveedor en Anchor.toml es parte del diseño del entorno, incluyendo si anchor test posee el validador o se adjunta al tuyo. Los clientes en @solana/kit 7.0.0 tratan el RPC local como cualquier endpoint HTTP. La parte difícil es la higiene entre shells, .env y configuraciones de wallet, no la forma de la llamada SDK.
Conceptos erróneos comunes
Concepto erróneo: Localnet es un juguete que no cuenta como Solana real. Ejecuta el mismo modelo de programa y reglas de cuenta. Carece de dinámicas de consenso multi-validador, congestión pública y adversarios económicos compartidos.
Concepto erróneo: Un entorno puede servir para pruebas unitarias, CI, demos y pruebas preliminares de mainnet. Diferentes preguntas requieren diferente fidelidad. Forzar todo a devnet o todo a LiteSVM falla de maneras opuestas.
Concepto erróneo: Clonar mainnet una vez mantiene tu clúster local "sincronizado". Los clones son instantáneas. Los precios y las reservas divergen inmediatamente. Actualiza, re-exporta fixtures, o usa herramientas de bifurcación cuando la frescura importe.
Concepto erróneo: Surfpool reemplaza a solana-test-validator para todo el trabajo. Surfpool brilla para la simulación de bifurcación de mainnet. El test-validator básico sigue siendo la opción ligera predeterminada para bucles de programas y muchos trabajos de CI.
Concepto erróneo: Una simulación local exitosa significa que una transacción de mainnet aterrizará. El éxito local significa ejecución contra esa vista de estado, no capacidad del líder, mercados de tarifas o propagación real.
Concepto erróneo: La congestión de devnet es igual a la congestión de mainnet. Devnet enseña campos de tarifas y experiencia de usuario de confirmación. Es un proxy débil para los mercados de prioridad de mainnet y MEV.
Concepto erróneo: Deberías clonar cada cuenta que puedas necesitar. Los conjuntos de semillas mínimos arrancan más rápido y fallan más claramente. Expande cuando los logs muestren una cuenta faltante.
Concepto erróneo: Los fixtures son un pulido opcional. Sin fixtures o reinicios, el estado local se convierte en conocimiento tribal y CI inestable.
Concepto erróneo: LiteSVM es solo para personas que odian TypeScript. Es la herramienta adecuada para la velocidad de las unidades de programa. Mantén las pruebas de integración TS/JS en un RPC de validador cuando esa sea la superficie del producto.
Preguntas frecuentes
¿Cuál es la mejor opción predeterminada para el trabajo diario de programas?
solana-test-validator con --reset para ejecuciones limpias, más fixtures o un pequeño conjunto de clones solo cuando tus pruebas los necesiten.
¿Cuándo debería introducir Surfpool?
Cuando los clones estáticos se conviertan en una carga de mantenimiento o necesites simulación continua de bifurcación de mainnet para gráficos tipo DeFi. Mantente en test-validator para bucles mínimos solo de programas.
¿Cómo se diferencia LiteSVM de solana-test-validator?
LiteSVM es una SVM en proceso para pruebas rápidas de Rust sin HTTP. El test validator es un clúster local completo con RPC, faucet y acceso multi-cliente.
¿Necesito devnet si localnet funciona?
Sí, para demos compartidas, IDs de programas multi-persona y algunos flujos de wallet. No como opción predeterminada para cada PR y cada unidad de trabajo.
¿Qué puertos son importantes para localnet?
El RPC predeterminado es comúnmente 8899, con puertos relacionados de gossip/WebSocket y faucet configurables. Apunta cada herramienta a la misma URL RPC que realmente iniciaste.
¿Por qué mis pruebas pasan localmente y fallan en devnet?
Las causas comunes son suposiciones obsoletas sobre airdrops, IDs de programas, despliegues de terceros, latencia de RPC y compromiso de confirmación. Local también oculta la presión del mercado de tarifas.
¿Debería CI usar clones de mainnet en cada PR?
Prefiere fixtures confirmados y --reset para determinismo. Si clonas, cachea cuidadosamente y mantén el conjunto pequeño para que CI siga siendo fiable bajo límites de RPC.
¿Cómo funcionan los logs de programas localmente?
Los programas emiten logs en los metadatos de la transacción; solana logs los transmite. Inicia el suscriptor antes de enviar transacciones para no perder la ventana de fallo.
¿Pueden las wallets hablar con localhost?
Muchas pueden a través de RPC personalizado a http://127.0.0.1:8899, pero el soporte varía. Devnet suele ser más fácil para demos de wallets externas.
¿Qué me da `--bpf-program` en comparación con `anchor deploy`?
La precarga en la génesis hace que los reinicios y CI sean deterministas. El despliegue es mejor cuando estás iterando flujos de actualización o igualando una sesión de ledger local de larga duración.
¿Es el tiempo de slot local el mismo que en mainnet?
No. Los test validators optimizan el rendimiento del desarrollador. No trates la cadencia de slots local como un punto de referencia de latencia de producción.
¿Cómo se relacionan los fixtures con la clonación?
La clonación es una obtención automatizada en estado de inicio. Los fixtures son archivos duraderos que versionas. Ambos siembran cuentas; los fixtures suelen ser mejores para la verdad compartida de CI.
¿Dónde encaja el validador incrustado de Anchor?
anchor test puede iniciar un validador por ti. Úsalo para suites de un solo comando. Gestiona el validador tú mismo para flags personalizados, sesiones largas o clientes paralelos.
¿Surfpool gasta SOL de mainnet?
La simulación y la ejecución de bifurcaciones locales no son aterrizajes en mainnet. Todavía necesitas un RPC upstream fiable para hidratar el estado. Los envíos reales a mainnet son un paso separado.
¿Cómo debería un PR documentar la elección del entorno?
Registra la URL del clúster, los IDs de programas, las fuentes de fixtures o clones, y los pines de la cadena de herramientas (Agave 4.1.1, Anchor 0.32.1, Surfpool 0.12.0 cuando se use).
Relacionado
- Fundamentos del Desarrollo Local - bucle práctico y ejemplos de inicio
- solana-test-validator - flags, ciclo de vida y puertos
- Surfpool - simulación local de bifurcación de mainnet
- Clonación de Cuentas de Mainnet - instantáneas de cuentas de producción en localnet
- Carga de Programas y Fixtures - semillas reproducibles y precarga de programas
- Flujo de Trabajo Localnet vs Devnet - árbol de decisión para la elección del entorno
- Logs Locales y Depuración - logs, CU e inspección de fallos
- Mejores Prácticas de Desarrollo Local - lista de verificación de prácticas condensada
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, @solana/kit 7.0.0, Surfpool 0.12.0, y LiteSVM 0.6.x.