Beacon API: Interfaz REST del Nodo de Consenso de Ethereum Explicada

Alcance y las dos cosas llamadas Beacon API

Esta página cubre la API Beacon de Ethereum: la interfaz HTTP RESTful expuesta por una implementación de nodo beacon de la capa de consenso, especificada en el repositorio ethereum/beacon-APIs y renderizada como un documento OpenAPI. Es la interfaz que un cliente validador utiliza para comunicarse con su nodo beacon, y la interfaz que exploradores, indexadores y herramientas de monitoreo usan para leer datos de consenso.

El nombre es ambiguo. La API web del navegador navigator.sendBeacon() no está relacionada: envía un pequeño POST asíncrono cuando una página se descarga, típicamente para analítica. Si llegó buscando eso, la documentación de Beacon de MDN y W3C es la referencia correcta. Todo lo siguiente concierne a la API REST de consenso de Ethereum, que es el significado relevante para operadores de nodos e infraestructura de validadores.

• API Beacon de Ethereum: REST/HTTP, JSON por defecto, SSZ para un subconjunto de endpoints, versionada por endpoint.
• API Beacon del navegador: un único método navigator.sendBeacon(), sin respuesta esperada, no disponible en Web Workers.
• Este artículo trata sobre la primera; las dos comparten nombre y nada más.

Suposiciones antes de comenzar

El procedimiento asume que tiene acceso a un nodo beacon en ejecución, ya sea autoalojado o a través de un proveedor de RPC gestionado, y que sabe si su API HTTP está expuesta en localhost o detrás de una puerta de enlace. La exposición pública de la API de un nodo beacon está desaconsejada por la propia especificación, porque varios endpoints desencadenan un procesamiento pesado y pueden ser abusados para denegación de servicio. Trate la API como un servicio interno a menos que haya añadido autenticación y limitación de velocidad delante de ella.

También necesita curl y, para los ejemplos SSZ, una herramienta que pueda escribir salida binaria en un archivo. No se requieren claves de validador para los diagnósticos de solo lectura; enviar bloques o atestaciones sí requiere un cliente validador y configuración de firma, lo cual está fuera del alcance de este artículo.

Modelo mental: nodo beacon, cliente validador y el límite REST

Un nodo beacon mantiene el estado de la cadena beacon comunicándose con sus pares. Conceptualmente no posee pares de claves de validador. Un cliente validador es un proceso separado que posee claves privadas, decide qué firmar y utiliza la API del nodo beacon para obtener obligaciones, producir bloques y atestaciones, y difundir mensajes firmados. Por lo tanto, la API es tanto una superficie de lectura (datos de cadena, configuración, información del nodo) como una superficie de escritura (envíos al pool, publicación de bloques y atestaciones).

Los endpoints están versionados individualmente. No hay relación entre todos los endpoints v1 y todos los endpoints v2; debe leer la versión en cada ruta. Las respuestas devuelven los datos solicitados bajo una clave data de nivel superior, con metadatos opcionales en claves hermanas. Se pueden añadir campos sin incrementar la versión, pero eliminar o cambiar el formato de un campo listado requiere una nueva versión. Esa regla es lo que hace seguro construir clientes que ignoran campos desconocidos.

Grupos de endpoints y para qué sirve cada uno

El documento OpenAPI agrupa los endpoints por propósito. Conocer los grupos le ayuda a elegir la ruta correcta y evitar exponer accidentalmente rutas de depuración.

El grupo Beacon consulta el estado y los objetos de la cadena beacon: cabeceras, bloques, estados y pools. El grupo Config devuelve la configuración de la cadena, valores de especificación y calendarios de bifurcación. El grupo Node devuelve información de identidad y salud del nodo, como versión y estado de sincronización. El grupo Validator está destinado a clientes validador e incluye el conjunto mínimo de endpoints necesarios para una implementación de validador funcional, además de un flujo de validador documentado. El grupo Events proporciona suscripciones a eventos, típicamente mediante eventos enviados por el servidor. El grupo Rewards consulta recompensas y penalizaciones. El grupo Debug está marcado explícitamente como no apto para exposición pública.

• Consultas de cadena de solo lectura: grupo Beacon.
• Calendario de bifurcaciones y constantes de especificación: grupo Config.
• Comprobaciones de salud e identidad: grupo Node.
• Obligaciones del validador, producción de bloques y envíos: grupo Validator.
• Actualizaciones en streaming: grupo Events.
• Solo diagnóstico: grupo Debug, mantener privado.

JSON, SSZ y negociación de contenido

Por defecto, las solicitudes envían y reciben JSON, así que incluya Content-Type: application/json y Accept: application/json donde haya un cuerpo involucrado. Un subconjunto de endpoints también puede aceptar o devolver SSZ, el formato de serialización de la capa de consenso. Para enviar SSZ, establezca Content-Type: application/octet-stream. Para preferir SSZ en una respuesta, establezca una cabecera Accept que lo clasifique por encima de JSON, por ejemplo application/octet-stream;q=1.0,application/json;q=0.9.

El contrato del servidor es explícito: devolver 415 si el Content-Type de la solicitud no es compatible, y 406 si no puede producir una respuesta en un formato aceptado. Si no se envía cabecera Accept, se asume JSON. El servidor debe indicar el formato de respuesta en Content-Type. Esto importa cuando escribe clientes, porque un 200 con un tipo de contenido inesperado es un error que debe mostrar en lugar de analizar a ciegas.

curl -sS -D - -o /dev/null \
  -H 'Accept: application/json' \
  "$BEACON_URL/eth/v1/node/version"

Diagnóstico ejecutable: sondear un nodo beacon en cuatro llamadas

La siguiente secuencia es segura contra cualquier nodo que esté autorizado a consultar. Comprueba la accesibilidad, la identidad, el estado de sincronización y una lectura de cadena, y registra el estado HTTP y el tipo de contenido de cada llamada para que pueda distinguir un problema de transporte de un problema de formato. Establezca BEACON_URL en la URL base de su nodo, por ejemplo http://127.0.0.1:5052 para un nodo local o la URL base HTTPS de su proveedor.

Ejecute cada llamada y anote el código de estado y el Content-Type. Un 200 con application/json en las cuatro es el resultado saludable esperado. Un 415 o 406 apunta a sus cabeceras, no al nodo. Un error de conexión apunta a la URL, el firewall o TLS. Un 503 en el endpoint de sincronización es normal mientras el nodo aún se está poniendo al día.

export BEACON_URL="http://127.0.0.1:5052"

# 1. Identity and version
curl -sS -w '\nHTTP %{http_code} %{content_type}\n' \
  -H 'Accept: application/json' \
  "$BEACON_URL/eth/v1/node/version"

# 2. Sync status
curl -sS -w '\nHTTP %{http_code} %{content_type}\n' \
  -H 'Accept: application/json' \
  "$BEACON_URL/eth/v1/node/syncing"

# 3. Chain configuration (fork schedule)
curl -sS -w '\nHTTP %{http_code} %{content_type}\n' \
  -H 'Accept: application/json' \
  "$BEACON_URL/eth/v1/config/fork_schedule"

# 4. A recent block header by id
curl -sS -w '\nHTTP %{http_code} %{content_type}\n' \
  -H 'Accept: application/json' \
  "$BEACON_URL/eth/v1/beacon/headers/head"

Verificación: cómo se ve un resultado correcto

Una ejecución correcta devuelve cuerpos JSON con una clave data de nivel superior en cada endpoint. El endpoint de versión devuelve campos de identidad del nodo. El endpoint de sincronización devuelve un booleano e información del slot de cabeza; si el nodo no está sincronizado, el slot de cabeza estará retrasado respecto a la red. El calendario de bifurcaciones devuelve las bifurcaciones y épocas configuradas. El endpoint de cabeceras devuelve la cabecera del bloque de cabeza con su raíz y slot.

Registre sus observaciones en una tabla para que la ejecución sea reproducible y comparable entre nodos o a lo largo del tiempo. No complete números que no haya observado; la tabla a continuación es una plantilla, no un conjunto de resultados.

• | Comprobación | Endpoint | Estado esperado | Tipo de contenido esperado | Observado |
• | Identidad | /eth/v1/node/version | 200 | application/json | (registrar) |
• | Sincronización | /eth/v1/node/syncing | 200 | application/json | (registrar) |
• | Bifurcaciones | /eth/v1/config/fork_schedule | 200 | application/json | (registrar) |
• | Cabecera de cabeza | /eth/v1/beacon/headers/head | 200 | application/json | (registrar) |

Medir la latencia y la consistencia usted mismo

Las afirmaciones de rendimiento de los proveedores no son portables, así que mida contra su propia carga de trabajo. Un método simple es cronometrar repetidamente un conjunto fijo de llamadas de solo lectura y registrar la distribución, no solo la media. Use time_total de curl o un pequeño script, ejecute suficientes iteraciones para ver el comportamiento de la cola y separe las conexiones en frío de las reutilizadas.

El script a continuación cronometra el endpoint de sincronización e imprime cada muestra. Ejecútelo contra dos endpoints candidatos y compare medianas y máximos. Mantenga el tamaño de muestra y la ventana de tiempo idénticos entre endpoints, y anote la hora del día, porque los nodos de consenso están más ocupados alrededor de los límites de slot.

import json, statistics, time, urllib.request

BEACON_URL = "http://127.0.0.1:5052"
PATH = "/eth/v1/node/syncing"
N = 30

samples = []
for _ in range(N):
    start = time.perf_counter()
    req = urllib.request.Request(BEACON_URL + PATH, headers={"Accept": "application/json"})
    with urllib.request.urlopen(req, timeout=10) as resp:
        body = json.loads(resp.read())
    elapsed_ms = (time.perf_counter() - start) * 1000
    samples.append(elapsed_ms)
    print(f"{elapsed_ms:8.1f} ms  synced={body['data'].get('is_synced')}")

print(f"median={statistics.median(samples):.1f} ms  max={max(samples):.1f} ms")

Solución de problemas comunes de la API Beacon

La mayoría de las fallas caen en unos pocos grupos: URL base o versión de ruta incorrecta, desajuste de cabeceras, nodo no sincronizado o un endpoint intencionalmente restringido. Revíselos en ese orden antes de asumir que un nodo está roto.

Si obtiene 404, verifique la versión del endpoint en la ruta contra el documento OpenAPI para la versión de API soportada por el nodo; las versiones son por endpoint y los nodos más antiguos pueden no implementar rutas más nuevas. Si obtiene 415 o 406, su cabecera Content-Type o Accept es la causa. Si las lecturas tienen éxito pero los datos parecen obsoletos, revise el endpoint de sincronización y el slot de cabeza. Si un cliente validador no puede iniciar, verifique que apunte a la URL correcta del nodo beacon y que los endpoints de validador requeridos sean accesibles.

• Conexión rechazada o tiempo de espera agotado: URL, puerto, firewall o terminación TLS.
• 404: ruta incorrecta o versión de endpoint no soportada en ese nodo.
• 415/406: negociación de formato de solicitud o respuesta.
• Datos obsoletos: nodo sincronizándose o retrasado respecto a la cabeza de la red.
• 403/401: capa de autenticación de puerta de enlace o proveedor delante del nodo.

Limitaciones y compensaciones

La API Beacon no está diseñada para ser un servicio público de internet. La especificación advierte que exponerla sin capas de seguridad adicionales abre el nodo a denegación de servicio a través de endpoints pesados. Si necesita acceso público de lectura, coloque una puerta de enlace de almacenamiento en caché y limitación de velocidad delante de ella y exponga solo los endpoints de lectura que necesite.

El soporte de SSZ es parcial: solo un subconjunto de endpoints lo acepta o devuelve, y cada uno se anota individualmente. JSON es el valor predeterminado seguro para herramientas y depuración. El versionado es por endpoint, por lo que fijarse a una única versión de API en todas las rutas no tiene sentido; en su lugar, lea la versión en cada ruta de la que dependa y pruebe contra las versiones de nodo que realmente ejecute.

Finalmente, la API es una interfaz local del nodo, no una garantía de consenso. Dos nodos saludables pueden devolver cabezas ligeramente diferentes en el mismo instante. Diseñe los clientes para tolerar eso en lugar de tratar cualquier divergencia como un error.

Próximos pasos para uso en producción

Una vez que sus diagnósticos pasen, pase de llamadas ad hoc a una integración monitoreada. Envuelva las cuatro comprobaciones anteriores en una sonda de salud, alerte sobre respuestas no 200 y sobre retraso de sincronización, y registre los tipos de contenido para que las regresiones de formato sean visibles. Para infraestructura de validadores, siga el flujo de validador documentado en lugar de ensamblar endpoints manualmente.

Si prefiere no operar nodos de consenso usted mismo, compare opciones gestionadas y mídalas con el mismo procedimiento. Comience con el directorio de redes de OnFinality para ver las cadenas soportadas, revise los precios de RPC para límites de rendimiento y solicitudes, y considere un nodo dedicado cuando necesite capacidad predecible o exposición privada de API. Para recomendaciones concretas de endpoints y proveedores, use el RPC Assistant en lugar de adivinar URL públicas.

• Explore las cadenas soportadas en el directorio de redes de OnFinality.
• Revise los precios de RPC y límites de solicitudes antes de dimensionar una carga de trabajo.
• Evalúe un nodo dedicado para acceso privado o de alto volumen a la API Beacon.
• Consulte la descripción general del servicio RPC y la guía de endpoints RPC.