Lectura del estado del sistema de Sui vía RPC: época, validadores, checkpoints

Estado de usuario frente a estado del sistema en RPC de Sui

La superficie JSON-RPC de Sui se divide en dos grandes categorías: estado de usuario y estado del sistema. El estado de usuario abarca objetos, monedas, transacciones y eventos: los datos con los que interactúan directamente las aplicaciones y los usuarios finales. El estado del sistema abarca parámetros a nivel de protocolo: la época actual, el comité de validadores, los pools de staking, el precio de gas de referencia y la versión del protocolo. Estos no son objetos propiedad del usuario; describen el contexto operativo de la red.

La distinción importa porque ambas categorías tienen patrones de lectura y costes diferentes. Las lecturas de estado de usuario suelen ser búsquedas puntuales o consultas paginadas limitadas a una dirección o ID de objeto. Las lecturas de estado del sistema, en cambio, devuelven un único objeto grande que incluye el conjunto completo de validadores. Ese payload es más pesado y cambia con menos frecuencia, por lo que el almacenamiento en caché y los campos de resumen cobran importancia.

Para operadores e indexadores, el estado del sistema es la fuente autoritativa para comprobaciones de estado y reconciliación. Si tu indexador registra transacciones sin registrar la época en la que ocurrieron, no podrás reconciliar después tus datos con las rotaciones del comité o los cambios en el precio del gas. La guía de RPC de Sui cubre la superficie de métodos más amplia, mientras que este artículo se centra específicamente en la ruta de lectura del estado del sistema.

• Estado de usuario: objetos, monedas, transacciones, eventos, limitados a direcciones o IDs.
• Estado del sistema: época, comité, stake, precio del gas, versión del protocolo, a nivel de red.
• Las lecturas de estado del sistema son más pesadas y deben cachearse o resumirse cuando sea posible.

El modelo de épocas de Sui y por qué importa para trabajos de larga duración

Sui avanza en épocas, que son periodos acotados definidos por una marca de tiempo de inicio y una duración. En cada límite de época, el comité de validadores puede rotar, se distribuyen las recompensas de staking y el precio de gas de referencia puede cambiar. La documentación de conceptos de épocas de Sui describe cómo se establece la duración de la época y cómo funciona la rotación del comité.

Para cualquier trabajo de larga duración (un indexador, un agente de monitorización o un script de reconciliación), la época es un metadato crítico. Si registras los efectos de una transacción sin registrar la época, pierdes la capacidad de correlacionar esos datos con el comité que los procesó o con el precio del gas vigente. Esto es especialmente importante para aplicaciones financieras que necesitan auditar cambios de stake o costes de gas a lo largo del tiempo.

La marca de tiempo de inicio de época y la duración se devuelven como epochStartTimestampMs y epochDurationMs en el objeto de estado del sistema. Estos campos te permiten calcular el tiempo restante en la época actual, lo que resulta útil para programar mantenimiento o anticipar cambios de comité. Sin embargo, estas marcas de tiempo las genera el nodo y pueden estar sujetas a desfase de reloj respecto a tu cliente.

• Las épocas acotan la rotación del comité, las recompensas de staking y los cambios en el precio del gas.
• Registra la época junto con cualquier dato indexado para su posterior reconciliación.
• epochStartTimestampMs y epochDurationMs permiten calcular el tiempo restante de la época.

Lectura del estado del sistema con suix_getLatestSuiSystemState

El método suix_getLatestSuiSystemState devuelve el último objeto de estado del sistema SUI. Según la referencia de la API JSON-RPC de Sui, este objeto incluye la época actual, epochStartTimestampMs, epochDurationMs, safeMode, protocolVersion, referenceGasPrice y el conjunto de validadores activos. Cada entrada de validador incluye campos como name, stakingPoolId, votingPower, stake y gasPrice.

Este es el método principal para leer el estado a nivel de protocolo. Es una única llamada que devuelve un payload grande, por lo que no debe sondearse con alta frecuencia. Para monitorización, una cadencia de una vez por época o una vez cada pocos minutos suele ser suficiente. Los conceptos de validadores y staking de Sui explican cómo se relacionan el poder de voto y los pools de staking con el comité.

Dado que la lista de validadores es grande, algunos proveedores ofrecen campos de resumen o métodos alternativos que devuelven una vista reducida. La disponibilidad de estas optimizaciones se documenta por proveedor y varía. Cuando sea compatible, prefiere una lectura de resumen para monitorización ligera y reserva el estado completo del sistema para reconciliación o análisis detallado.

• Devuelve época, marcas de tiempo, versión del protocolo, precio del gas y conjunto de validadores.
• Las entradas de validador incluyen name, stakingPoolId, votingPower, stake y gasPrice.
• El payload es pesado; evita el sondeo de alta frecuencia y prefiere campos de resumen cuando estén disponibles.

Comprobación de actividad ligera con sui_getLatestCheckpointSequenceNumber

El método sui_getLatestCheckpointSequenceNumber devuelve solo el último número de secuencia de checkpoint certificado. Es una llamada barata en comparación con obtener el estado completo del sistema. Resulta útil como sonda de actividad: si el número de secuencia avanza, el nodo está produciendo o recibiendo checkpoints. Si se estanca, el nodo puede estar retrasado o desconectado.

Combinar este método con el estado del sistema te proporciona una señal de retraso. El estado del sistema te indica la época y el comité actuales de la red; el número de secuencia de checkpoint te indica cuánto ha avanzado la punta de checkpoints del nodo. Si comparas la punta de tu nodo con una punta de referencia de otro endpoint, puedes detectar un nodo que está por detrás de la red.

Para un tratamiento más profundo del consumo de checkpoints, consulta el artículo sobre stream de checkpoints y servicio de ledger. Ese artículo cubre el streaming de checkpoints, mientras que este se centra en el número de secuencia como sonda ligera.

• Devuelve solo el último número de secuencia de checkpoint certificado: barato y rápido.
• Úsalo como sonda de actividad y para detección de retraso frente a una punta de referencia.
• Combínalo con el estado del sistema para correlacionar el progreso de checkpoints con los límites de época.

El sobre de la petición JSON-RPC y consideraciones de coste

Todas las llamadas JSON-RPC de Sui usan el sobre estándar JSON-RPC 2.0: un campo jsonrpc establecido en "2.0", un id para correlación de peticiones, una cadena method y un array u objeto params. La especificación JSON-RPC 2.0 define esta estructura. Los métodos de Sui siguen esta convención, con nombres de método como suix_getLatestSuiSystemState y sui_getLatestCheckpointSequenceNumber.

La advertencia sobre el coste es que las lecturas de estado del sistema son más pesadas que las lecturas puntuales. Una llamada a suix_getLatestSuiSystemState devuelve el conjunto completo de validadores, que puede tener cientos de entradas. Esto consume más ancho de banda y tiempo de procesamiento que una simple búsqueda de objeto. Para monitorización de alta frecuencia, usa sui_getLatestCheckpointSequenceNumber en su lugar, o comprueba si tu proveedor ofrece un método de resumen.

Al construir un bucle de monitorización, separa las cadencias: sondea con frecuencia el número de secuencia de checkpoint para actividad y obtén el estado completo del sistema con menos frecuencia para datos de época y comité. Esto reduce la carga tanto en tu cliente como en el nodo.

• Sobre: jsonrpc, id, method, params, según JSON-RPC 2.0.
• Las lecturas de estado del sistema son más pesadas que las lecturas puntuales; ajusta la cadencia de sondeo en consecuencia.
• Usa la secuencia de checkpoint para actividad frecuente; el estado del sistema para reconciliación periódica.

Ejemplo ejecutable en Node.js: obtención y resumen del estado del sistema

El siguiente ejemplo usa el cliente @mysten/sui para obtener el último estado del sistema y el número de secuencia de checkpoint, calcular el tiempo restante en la época actual e imprimir un resumen compacto de estado. Asume que tienes una URL de endpoint RPC de Sui. Sustituye el marcador de posición por el endpoint de tu proveedor.

El script imprime epoch, epochStartTimestampMs, epochDurationMs, protocolVersion, referenceGasPrice y el número de validadores activos. Luego obtiene el último número de secuencia de checkpoint y calcula el tiempo restante de la época en milisegundos. Finalmente, imprime un resumen de estado en una línea.

Este ejemplo es intencionadamente mínimo. En producción, añadirías manejo de errores, reintentos y posiblemente una comparación con un endpoint de referencia para detección de retraso.

import { SuiClient } from '@mysten/sui/client';

const client = new SuiClient({ url: 'https://your-sui-rpc-endpoint.example' });

async function main() {
  const systemState = await client.getLatestSuiSystemState();
  const epoch = systemState.epoch;
  const epochStart = Number(systemState.epochStartTimestampMs);
  const epochDuration = Number(systemState.epochDurationMs);
  const protocolVersion = systemState.protocolVersion;
  const referenceGasPrice = systemState.referenceGasPrice;
  const activeValidators = systemState.activeValidators.length;

  const checkpointSeq = await client.getLatestCheckpointSequenceNumber();

  const now = Date.now();
  const elapsed = now - epochStart;
  const remaining = Math.max(0, epochDuration - elapsed);

  console.log('Epoch:', epoch);
  console.log('Epoch start (ms):', epochStart);
  console.log('Epoch duration (ms):', epochDuration);
  console.log('Protocol version:', protocolVersion);
  console.log('Reference gas price:', referenceGasPrice);
  console.log('Active validators:', activeValidators);
  console.log('Latest checkpoint seq:', checkpointSeq);
  console.log('Remaining epoch time (ms):', remaining);
  console.log('Health: epoch', epoch, '| validators', activeValidators, '| checkpoint', checkpointSeq, '| remaining', remaining, 'ms');
}

main().catch(console.error);

Ejemplo de JSON-RPC en bruto con curl

Si prefieres no usar el SDK, puedes llamar a los métodos directamente con curl. El siguiente ejemplo envía una petición JSON-RPC para el último estado del sistema y extrae la época y el número de validadores usando jq. Sustituye la URL del endpoint por la de tu proveedor.

Este enfoque es útil para comprobaciones rápidas o para integrarlo en scripts de shell. Ten en cuenta que la respuesta es grande; canalizarla a través de jq para extraer solo los campos que necesitas reduce el ruido.

Para el número de secuencia de checkpoint, se muestra una llamada separada. Puedes combinar ambas llamadas en un script para calcular el retraso o el tiempo restante de la época.

curl -s -X POST https://your-sui-rpc-endpoint.example \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"suix_getLatestSuiSystemState","params":[]}' \
  | jq '{epoch: .result.epoch, protocolVersion: .result.protocolVersion, referenceGasPrice: .result.referenceGasPrice, validatorCount: (.result.activeValidators | length)}'

curl -s -X POST https://your-sui-rpc-endpoint.example \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"sui_getLatestCheckpointSequenceNumber","params":[]}' \
  | jq '{latestCheckpointSeq: .result}'

Tabla de resultados reproducible para tu endpoint

Para medir el comportamiento de tu propio endpoint, completa la siguiente tabla. Ejecuta el ejemplo de Node.js o curl contra tu endpoint y registra los valores. Repite en distintos momentos para observar los cambios de época y la progresión de checkpoints.

Las columnas de la tabla capturan los campos clave: endpoint, epoch, protocolVersion, referenceGasPrice, número de validadores activos, último número de secuencia de checkpoint, número de secuencia de la punta del nodo (si tienes una referencia) y una señal de retraso. La señal de retraso puede calcularse como la diferencia entre la secuencia de checkpoint de tu nodo y una punta de referencia de otro endpoint.

Esta tabla es una plantilla. Los valores que registres son tus propias mediciones; no se proporcionan aquí. Úsala para construir una línea base y detectar anomalías a lo largo del tiempo.

• Endpoint: la URL RPC que estás probando.
• Epoch: el número de época actual del estado del sistema.
• ProtocolVersion: la versión del protocolo reportada por el nodo.
• ReferenceGasPrice: el precio de gas de referencia actual.
• ActiveValidatorCount: número de validadores activos en el comité.
• LatestCheckpointSeq: el último número de secuencia de checkpoint certificado del nodo.
• NodeTipSeq: una punta de referencia de otro endpoint (si está disponible).
• LagSignal: NodeTipSeq menos LatestCheckpointSeq (positivo significa que tu nodo está por detrás).

Limitaciones y compensaciones en las lecturas de estado del sistema

La lista de validadores es grande y puede recortarse. Algunos proveedores ofrecen campos de resumen o métodos alternativos que devuelven una vista reducida. La disponibilidad de estas optimizaciones se documenta por proveedor y varía. Si tu proveedor no las admite, debes obtener el payload completo y extraer lo que necesites.

Los campos de temporización de época son informativos pero están sujetos al desfase de reloj entre el nodo y tu cliente. epochStartTimestampMs lo genera el nodo; si el reloj de tu cliente difiere, el tiempo restante calculado puede ser incorrecto. Trátalo como una estimación, no como una cuenta atrás precisa.

safeMode y protocolVersion pueden cambiar en una actualización. Un nodo en modo seguro puede detener ciertas operaciones, y la versión del protocolo se incrementa con las actualizaciones de red. Tu monitorización debe tratar estos campos como dinámicos y alertar ante cambios inesperados. La disponibilidad de métodos también se documenta por proveedor y varía; no todos los endpoints exponen todos los métodos.

• La lista de validadores es pesada; los campos de resumen dependen del proveedor.
• Las marcas de tiempo de época están sujetas a desfase de reloj; trata el tiempo restante como una estimación.
• safeMode y protocolVersion pueden cambiar en actualizaciones; monitoriza valores inesperados.
• La disponibilidad de métodos varía según el proveedor; verifícala antes de depender de un método.

Resolución de problemas comunes de RPC de estado del sistema

Método no encontrado: si suix_getLatestSuiSystemState o sui_getLatestCheckpointSequenceNumber devuelven un error de método no encontrado, es posible que el endpoint no admita ese método. Consulta la documentación de tu proveedor. Algunos proveedores solo exponen un subconjunto de la superficie JSON-RPC de Sui.

Payload pesado: si la respuesta es lenta o se agota el tiempo de espera, la lista completa de validadores puede ser demasiado grande para tu cliente o red. Prueba un método de resumen si está disponible, o aumenta el tiempo de espera y reduce la frecuencia de sondeo. Para actividad, usa sui_getLatestCheckpointSequenceNumber en su lugar.

Confusión con la época: si el número de época parece inconsistente con tus expectativas, verifica que estás consultando la red correcta (mainnet vs testnet). Comprueba también si el nodo está en modo seguro o retrasado. La época avanza en los límites; si sondeas con frecuencia, puede que la veas cambiar a mitad del bucle. Registra la época con cada punto de datos para evitar mezclar datos de épocas diferentes.

• Método no encontrado: verifica la compatibilidad del proveedor con el método.
• Payload pesado: usa campos de resumen o cambia a la secuencia de checkpoint para actividad.
• Confusión con la época: confirma la red, comprueba el modo seguro y registra la época con los datos.

Próximos pasos para monitorización y reconciliación

Para construir una configuración de monitorización robusta, combina las lecturas de estado del sistema con sondas de secuencia de checkpoint. Usa la página de redes de Sui para encontrar endpoints, y considera el servicio de API para acceso gestionado. Para precios y límites de tasa, consulta precios de RPC.

Para profundizar en temas relacionados, explora el centro de aprendizaje de OnFinality. El artículo sobre paginación por cursor de queryTransactionBlocks cubre la paginación de transacciones, mientras que lectura de saldos y metadatos de monedas de Sui cubre las lecturas de estado de usuario. Para versionado de objetos, consulta versiones de objetos de Sui y ordenación Lamport.

Por último, integra el seguimiento de épocas en tu indexador o agente de monitorización. Registra la época junto con cada punto de datos y alerta ante cambios de época, modo seguro o cambios en la versión del protocolo. Esto garantiza que tus datos sigan siendo reconciliables a través de las rotaciones de comité y las actualizaciones del precio del gas.

• Combina las lecturas de estado del sistema con sondas de secuencia de checkpoint para detección de retraso.
• Registra la época con cada punto de datos para la reconciliación.
• Alerta ante cambios de época, modo seguro y cambios en la versión del protocolo.