Cómo verificar el estado de sincronización de un nodo Base OP-Stack mediante op-node y op-reth Engine/Admin RPC

Respuesta directa: Cómo verificar que tu nodo Base está sincronizado

Para verificar que tu nodo Base está completamente sincronizado, necesitas comprobar tanto el op-node (cliente de consenso/rollup) como el motor de ejecución (op-reth, op-geth u op-erigon). El op-node expone un admin RPC que informa de la cabeza unsafe actual (el último bloque del secuenciador), la cabeza safe (derivada de L1) y la cabeza finalized. El motor de ejecución expone su propio estado de sincronización y la altura de su cabeza. Un nodo saludable muestra la cabeza unsafe avanzando con el secuenciador, la cabeza safe poniéndose al día desde L1, y la cabeza del motor coincidiendo con el objetivo unsafe. Si alguna cabeza se detiene o el motor informa que está sincronizando, el nodo no está activo.

Esta guía está dirigida a operadores de nodos que ejecutan su propio nodo Base y necesitan diagnosticar problemas de sincronización. Complementa el artículo sobre finalidad de Base y etiquetas de bloques safe/finalized, que está escrito para consumidores de RPC que leen esas etiquetas, no para operadores de nodos que inspeccionan el estado de sincronización de su propio nodo.

Arquitectura: op-node y el motor de ejecución

Base es un rollup OP-Stack. El nodo consta de dos componentes principales: op-node (el cliente de consenso del rollup) y un motor de ejecución (op-reth, op-geth u op-erigon). Se comunican a través de la Engine API, un espacio de nombres JSON-RPC de Ethereum (engine_*) que permite al cliente de consenso dirigir la elección de bifurcación y la producción de bloques del motor de ejecución.

El op-node rastrea tres estados de cabeza:

• Cabeza unsafe: El último bloque del secuenciador, conocido a través de las actualizaciones de elección de bifurcación de la Engine API. Esta es la punta de la cadena tal como la produce el secuenciador.

• Cabeza safe: El último bloque que se ha derivado de datos finalizados de L1. Avanza a medida que el op-node procesa los lotes de L1.

• Cabeza finalized: El último bloque que es final en L1 y, por tanto, final en Base.

El motor de ejecución mantiene su propia cadena canónica y expone su cabeza mediante los métodos eth_blockNumber o eth_getBlockByNumber. La cabeza unsafe del op-node debe coincidir con la cabeza del motor cuando el nodo está completamente sincronizado.

Para obtener detalles autorizados, consulta la documentación de Base sobre cómo ejecutar un nodo y la documentación de op-node de Optimism.

Acceso al admin RPC de op-node y a la Engine API

El op-node expone un admin RPC en un puerto separado (por defecto 9545) que proporciona métodos específicos del nodo. Para habilitarlo, debes iniciar op-node con la bandera --admin.rpc.enabled y opcionalmente establecer --admin.rpc.port. El admin RPC incluye métodos como admin_health, admin_logs y admin_sync (dependiendo de la versión).

El motor de ejecución expone la Engine API en su puerto JSON-RPC (por defecto 8545 para op-reth). Para consultar los métodos del motor, necesitas autenticarte usando un secreto JWT, que se pasa mediante la bandera --authrpc.jwtsecret tanto en op-node como en el motor de ejecución.

Importante: Estos espacios de nombres de administración y motor son solo para operadores y no deben exponerse públicamente. Pueden revelar información sensible y permitir el control del nodo. Siempre vincúlalos a localhost o a una red privada.

Para conocer los nombres y argumentos exactos de los métodos, consulta la documentación de tu versión específica de OP-Stack, ya que pueden variar.

Paso a paso: Consultar el estado de sincronización

Los siguientes comandos asumen que tienes curl y jq instalados, y que tu admin RPC de op-node está disponible en http://localhost:9545 y la Engine API de tu motor de ejecución en http://localhost:8551 (con JWT). Reemplaza los puertos y rutas según sea necesario.

Primero, verifica el endpoint de salud de op-node:

Esto devuelve un objeto JSON con un booleano healthy y detalles sobre la cabeza unsafe, safe y finalized. Un nodo saludable debe mostrar "healthy": true y las cabezas deben estar avanzando.

A continuación, consulta el admin RPC de op-node para obtener el estado de sincronización. El nombre del método puede ser admin_sync u optimism_syncStatus dependiendo de la versión. Por ejemplo:

Esto devuelve un objeto con bloques unsafe_l2, safe_l2 y finalized_l2, cada uno con un número de bloque y un hash.

Ahora verifica la cabeza del motor de ejecución. Usa el método de la Engine API engine_getPayloadV2 o simplemente eth_blockNumber (si está habilitado). Por ejemplo:

Compara el número de bloque de la cabeza del motor con la cabeza unsafe de op-node. Deben ser iguales o muy cercanos (dentro de unos pocos bloques).

curl -s http://localhost:9545/health | jq .

curl -s -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"admin_sync","params":[],"id":1}' http://localhost:9545 | jq .

curl -s -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' http://localhost:8545 | jq -r '.result' | xargs printf "%d\n"

Interpretación de la salida: Saludable vs degradado

Un nodo saludable muestra lo siguiente:

• El endpoint de salud de op-node devuelve "healthy": true.

• La cabeza unsafe avanza a la velocidad esperada (típicamente cada 2 segundos en Base).

• La cabeza safe también avanza, aunque puede ir por detrás de la cabeza unsafe unos minutos mientras espera confirmaciones de L1.

• La cabeza del motor de ejecución coincide con la cabeza unsafe.

Un nodo degradado podría mostrar:

• El endpoint de salud devuelve "healthy": false con una razón como "unsafe head is behind" o "engine sync not progressing".

• La cabeza unsafe no avanza, lo que indica que la fuente del secuenciador está caída o que el nodo está en modo de respaldo.

• La cabeza safe está atascada, lo que significa que la derivación de L1 no está progresando.

• La cabeza del motor de ejecución está muy por detrás de la cabeza unsafe, lo que indica que el motor todavía está sincronizando o está atascado.

Si el nodo está en modo seguro (fuente del secuenciador no disponible), solo derivará bloques de L1, lo cual es más lento. La cabeza unsafe puede no avanzar, pero la cabeza safe debería seguir progresando. Esto no es necesariamente un error, pero significa que el nodo no está en la punta.

Detección de sincronización atascada y problemas de poda

Una falla común es un nodo que parece estar ejecutándose pero está atascado en la sincronización inicial o detrás de una instantánea obsoleta. Por ejemplo, un nodo de archivo iniciado desde una instantánea puede no alcanzar la punta porque la instantánea está desactualizada. Del mismo modo, op-node puede colgarse mientras op-reth está podando, como se informa en problemas de GitHub.

Para detectar estos problemas:

• Revisa los registros de op-node en busca de errores como "engine sync not progressing" o "unsafe head is behind".

• Verifica el estado de sincronización del motor de ejecución. Para op-reth, puedes usar el método reth_sync (si está habilitado) o inspeccionar los registros para ver el progreso de la sincronización.

• Si el motor todavía está sincronizando, informará un estado syncing en la Engine API. Puedes consultar engine_getPayloadV2 y verificar latestValidHash y finalizedBlockHash.

• Si el nodo está atascado detrás de una instantánea obsoleta, es posible que necesites resincronizar desde una instantánea más reciente o usar una sincronización de punto de control.

Por ejemplo, para verificar el estado de sincronización de op-reth:

Esto devuelve un objeto con los campos current_block, highest_block y stage. Si current_block no aumenta, la sincronización está atascada.

curl -s -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"reth_sync","params":[],"id":1}' http://localhost:8545 | jq .

Lista de verificación para operadores

Usa esta lista de verificación para diagnosticar y solucionar problemas de sincronización en tu nodo Base:

1. Verifica la salud de op-node: Ejecuta curl -s http://localhost:9545/health | jq . y verifica que healthy sea true.

2. Verifica el estado de sincronización de op-node: Consulta admin_sync y anota los números de bloque unsafe, safe y finalized.

3. Verifica la cabeza del motor de ejecución: Consulta eth_blockNumber y compáralo con la cabeza unsafe.

4. Verifica el estado de sincronización del motor: Para op-reth, consulta reth_sync y asegúrate de que current_block esté avanzando.

5. Inspecciona los registros: Busca errores en los registros de op-node y op-reth. Los errores comunes incluyen "engine sync not progressing", "unsafe head is behind" y mensajes de "pruning".

6. Verifica la fuente del secuenciador: Si la cabeza unsafe no avanza, verifica si la fuente del secuenciador es accesible. Es posible que debas reiniciar op-node con los endpoints --l1.beacon y --l1.rpc correctos.

7. Verifica la conexión L1: Asegúrate de que op-node pueda alcanzar el nodo L1 y que L1 esté sincronizado.

8. Reinicia los servicios: Si todo lo demás falla, reinicia op-node y el motor de ejecución. A veces un simple reinicio resuelve problemas transitorios.

9. Resincroniza si es necesario: Si el nodo está atascado detrás de una instantánea obsoleta, considera resincronizar desde una instantánea más reciente o usar una sincronización de punto de control.

Script de medición reproducible

El siguiente script consulta tanto op-node como el motor de ejecución e imprime una tabla de alturas de cabezas. Ejecútalo dos veces con un retraso para ver si las cabezas están avanzando.

Completa los resultados en la tabla a continuación después de ejecutar el script dos veces con un intervalo de 30 segundos:

Si los deltas son cero para unsafe y engine, el nodo no está sincronizando. Si la cabeza safe también es cero, la derivación de L1 está atascada.

#!/bin/bash
# Guarda como check_sync.sh y ejecuta con: bash check_sync.sh

OP_NODE_ADMIN="http://localhost:9545"
ENGINE_RPC="http://localhost:8551"

# Obtener estado de sincronización de op-node
sync_status=$(curl -s -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"admin_sync","params":[],"id":1}' $OP_NODE_ADMIN)
unsafe=$(echo $sync_status | jq -r '.result.unsafe_l2.number')
safe=$(echo $sync_status | jq -r '.result.safe_l2.number')
finalized=$(echo $sync_status | jq -r '.result.finalized_l2.number')

# Obtener cabeza del motor (asumiendo que eth_blockNumber está habilitado)
engine_hex=$(curl -s -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' $ENGINE_RPC | jq -r '.result')
engine=$((16#${engine_hex#0x}))

# Imprimir tabla
echo "Tipo de cabeza | Número de bloque"
echo "----------|--------------"
echo "Unsafe    | $unsafe"
echo "Safe      | $safe"
echo "Finalized | $finalized"
echo "Engine    | $engine"

Limitaciones y compensaciones

Los métodos descritos requieren acceso a nivel de operador al admin RPC y a la Engine API del nodo. Estos endpoints no están disponibles en proveedores de RPC públicos como el nodo RPC de Base de OnFinality. Si estás usando un nodo gestionado, no puedes consultar estos espacios de nombres directamente; en su lugar, puedes monitorear el estado de sincronización a través de endpoints públicos como eth_blockNumber y compararlo con el último bloque de un explorador de bloques.

Los nombres y argumentos exactos de los métodos pueden variar entre versiones de OP-Stack y clientes de ejecución. Siempre consulta la documentación de tu versión específica. Por ejemplo, el método admin RPC de op-node podría ser admin_sync u optimism_syncStatus, y el método de sincronización de op-reth podría ser reth_sync o admin_peerInfo.

Exponer endpoints de administración o motor RPC públicamente es un riesgo de seguridad. Pueden permitir que atacantes controlen tu nodo o extraigan información sensible. Siempre vincúlalos a localhost o usa un firewall.

Para más información sobre monitoreo de salud de nodos, consulta Monitoreo de endpoints RPC y salud de nodos.

Próximos pasos y lecturas adicionales

Ahora que puedes verificar el estado de sincronización de tu nodo Base, es posible que desees explorar temas relacionados:

• Latencia de RPC de Base – comprende las expectativas de latencia para tu nodo.

• Ejecución y consulta de nodos de archivo de Base – si necesitas datos históricos.

• Finalidad de Base y etiquetas de bloques safe/finalized – para consumidores que leen estas etiquetas.

• Centro de aprendizaje de OnFinality – más guías para operadores de nodos y desarrolladores.

• Servicio API – si prefieres un servicio RPC gestionado.

• Precios de RPC – comprende los costos si escalas.

Si estás usando el nodo Base gestionado de OnFinality, no necesitas realizar estas comprobaciones tú mismo; nuestra infraestructura se encarga de la sincronización y el monitoreo de salud. Para más información, consulta Nodo RPC de Base (Asistente RPC).