Resumen
Sui gRPC es la interfaz RPC basada en Protocol Buffers, con seguridad de tipos, expuesta por los nodos completos de Sui. Es la ruta de producción recomendada para leer el estado de la cadena, ejecutar transacciones y consumir streams en tiempo real. OnFinality proporciona infraestructura administrada de Sui gRPC y RPC en mainnet y testnet; los detalles actuales de los endpoints se publican en /networks/sui. En la práctica, se usa grpcurl con un marcador de posición GRPC_ENDPOINT y metadatos de autorización de su proveedor, y luego se apunta a los servicios por nombre. LedgerService cubre checkpoints y datos de consenso, StateService cubre lecturas de objetos y saldos, TransactionExecutionService proporciona los flujos de trabajo ExecuteTransaction y SimulateTransaction, y SubscriptionService ofrece SubscribeCheckpoints, SubscribeTransactions y SubscribeEvents para streaming. Dado que JSON-RPC se está retirando, los equipos deben planificar una migración mapeando los flujos de trabajo heredados de lectura, escritura y suscripción a estos servicios gRPC. Trabaje a partir de clientes generados o definiciones proto, no de llamadas JSON construidas a mano. Pruebe en testnet con el faucet en https://faucet.sui.io, mantenga mainnet separado y verifique la reconexión de streams y las máscaras de campo antes de producción.
Puntos clave
- Sui gRPC utiliza Protocol Buffers sobre HTTP/2 para lecturas, ejecución, simulación y streaming eficientes.
- LedgerService, StateService, TransactionExecutionService y SubscriptionService cubren datos de cadena, estado de objetos, ciclo de vida de transacciones y streams en tiempo real.
- Para una integración segura, utilice grpcurl con el marcador de posición GRPC_ENDPOINT y metadatos de autorización emitidos por el proveedor; nunca incruste hosts en vivo.
- Planifique la migración desde JSON-RPC mapeando flujos de trabajo de lectura, escritura y suscripción a los servicios gRPC; luego verifique la semántica de objetos y checkpoints.
Sui gRPC: Por qué es la ruta de integración predeterminada
Sui gRPC es la interfaz RPC basada en protocolos expuesta por los nodos completos de Sui. Utiliza Protocol Buffers (proto) sobre HTTP/2 para una comunicación segura, compacta y bidireccional. Para aplicaciones de producción, gRPC es la ruta recomendada porque reduce el tamaño de la carga útil, admite streaming del servidor y se mapea directamente al modelo de objetos y checkpoints de Sui.
OnFinality proporciona infraestructura administrada de Sui gRPC y RPC para mainnet y testnet. Los endpoints exactos y los detalles de acceso se publican en la página de red de Sui (/networks/sui). Los equipos deben tratar gRPC como infraestructura: verificar los servicios compatibles, la visibilidad de solicitudes y la conmutación por error antes de mover tráfico sostenido.
Si viene de JSON-RPC, planifique la migración en torno a flujos de trabajo en lugar de copias método por método. El mismo estado de cadena está disponible, pero gRPC agrupa operaciones en servicios como LedgerService y TransactionExecutionService.
Configuración segura de endpoints con grpcurl y marcadores de posición de autorización
Para experimentar sin un cliente generado, use grpcurl. No pegue un endpoint público de un tercero a menos que tenga permiso explícito y comprenda los límites de frecuencia. Para endpoints administrados por OnFinality, use el marcador de posición GRPC_ENDPOINT y pase metadatos de autenticación mediante -rpc-header. El host exacto y el formato del token están disponibles en el panel del proveedor o en la página /networks/sui.
Un listado mínimo con grpcurl se ve así:
- Utilice TLS (puerto 443) para servicios administrados; localhost en texto plano solo es para nodos completos autoalojados.
- Mantenga los tokens de autorización en variables de entorno o un administrador de secretos; nunca los incluya en el control de versiones.
- Valide la lista de servicios con grpcurl $GRPC_ENDPOINT list, luego describa un servicio con grpcurl $GRPC_ENDPOINT describe <service>.
Servicios centrales de Sui gRPC y sus responsabilidades
La API de Sui gRPC está agrupada en servicios definidos en archivos proto. Los cuatro servicios más relevantes para los constructores son LedgerService, StateService, TransactionExecutionService y SubscriptionService. Pueden existir otros servicios para metadatos de paquetes o verificación de firmas; consulte los stubs generados de su cliente o el listado de servicios del proveedor.
| Criterio | Qué revisar | Por qué importa |
|---|---|---|
| LedgerService | Recuperación de checkpoints, datos de consenso, orden de transacciones | Fundamental para indexadores que necesitan datos consistentes y ordenados |
| StateService | Lecturas de objetos, saldos, campos dinámicos | Núcleo para wallets, exploradores y dApps que leen estado de objetos |
| TransactionExecutionService | Flujos de trabajo de ExecuteTransaction y SimulateTransaction | Permite ejecución firmada y simulación segura de pre-vuelo |
| SubscriptionService | SubscribeCheckpoints, SubscribeTransactions, SubscribeEvents | Permite feeds en tiempo real con baja latencia sin polling |
Lectura de objetos y checkpoints
El modelo centrado en objetos de Sui significa que la lectura de estado a menudo comienza con un ID de objeto o dirección de propietario. StateService maneja lecturas de objetos y consultas relacionadas. Puede recuperar objetos individuales, listar objetos propiedad de una dirección e inspeccionar campos dinámicos utilizando los métodos de cliente generados para esos flujos de trabajo. Dado que los métodos gRPC son tipados, trabaja con referencias de objetos y máscaras de campo donde se admiten, en lugar de parámetros JSON de forma libre.
La recuperación de checkpoints es servida por LedgerService. Un checkpoint es un conjunto certificado de transacciones que delimita la finalidad de Sui. Utilice los métodos de LedgerService para obtener el número de secuencia del último checkpoint, recuperar un checkpoint por secuencia o digest, y paginar a través de listas de transacciones dentro de un checkpoint. Este es un patrón fundamental para indexadores que necesitan datos consistentes y ordenados.
- Capture siempre el número de secuencia, el digest y la marca de tiempo al procesar checkpoints para reanudabilidad.
- Para lecturas de objetos, prefiera máscaras de campo para controlar el tamaño de la respuesta.
- Trate las versiones de objetos como importantes: las consultas de estado pueden incluir una versión de objeto para razonar sobre actualizaciones.
Ejecución y simulación de transacciones con TransactionExecutionService
TransactionExecutionService es donde viven la ejecución y simulación de transacciones firmadas. Use SimulateTransaction para validar una transacción antes de enviarla. La simulación acepta una carga útil de transacción y devuelve efectos sin comprometer el estado, lo que la hace útil para estimar gas, verificar errores de Move y previsualizar cambios de saldo.
Use ExecuteTransaction para enviar una transacción completamente firmada para su inclusión. Los campos de solicitud exactos están definidos en los esquemas proto y los envoltorios de cliente generados; no los reconstruya a mano. Después de llamar a ExecuteTransaction, rastree la inclusión en el checkpoint o espere los efectos a través del cliente o del feed de suscripción para confirmar la finalidad.
Si un cliente generado usa un nombre de envoltorio ligeramente diferente, siga el método generado que expone el flujo de trabajo de ExecuteTransaction.
- Simule primero, ejecute después.
- Mantenga intactos los bytes de la transacción firmada; no modifique después de firmar.
- Use comprobaciones de idempotencia o digest de transacción para reintentos.
Streaming con SubscribeCheckpoints, SubscribeTransactions y SubscribeEvents
SubscriptionService proporciona RPCs de streaming del servidor para actividad en cadena en tiempo real. SubscribeCheckpoints envía checkpoints finalizados a medida que se certifican. SubscribeTransactions transmite transacciones ejecutadas, y SubscribeEvents transmite eventos Move emitidos. Estos métodos reducen el polling y permiten que indexadores, exploradores y sistemas de alerta reaccionen con baja latencia.
Cada stream admite filtrado del lado del servidor y máscaras de campo donde el proto las define. Al reconectar, use el último número de secuencia de checkpoint procesado o el digest de transacción para reanudar sin brechas. Para endpoints públicos o administrados, tenga en cuenta los tiempos de espera de stream y las políticas de reconexión; pruebe con clientes de larga duración.
- SubscribeCheckpoints: utilícelo para estado de cadena ordenado e indexación.
- SubscribeTransactions: utilícelo para feeds de transacciones y observación de mempool.
- SubscribeEvents: utilícelo para escuchar tipos de eventos Move emitidos.
Mapeo práctico de migración de JSON-RPC a gRPC
La migración es un mapeo de flujos de trabajo, no un intercambio de métodos uno a uno. Los métodos heredados de JSON-RPC como suix_getObject, suix_getBalance, suix_executeTransactionBlock y suix_subscribeEvent se mapean conceptualmente a StateService, LedgerService, TransactionExecutionService y SubscriptionService. Sin embargo, las formas de solicitud y respuesta difieren porque gRPC usa mensajes protobuf, no SuiJSON.
Comience por inventariar las llamadas JSON-RPC en su base de código. Agrúpelas en lecturas (objetos, saldos), checkpoints, ejecución/simulación de transacciones y suscripciones. Luego implemente cada grupo utilizando el cliente gRPC generado para su lenguaje. Mantenga la misma lógica de aplicación para analizar efectos; ajústese a los tipos protobuf nativos.
No invente campos protobuf a partir de nombres JSON-RPC. Genere stubs de las definiciones proto oficiales de Sui o de las bibliotecas cliente documentadas por el proveedor, luego use los métodos generados.
| Criterio | Qué revisar | Por qué importa |
|---|---|---|
| Lectura de objeto (suix_getObject) | Consulta de objeto StateService con solicitud tipada | Reemplaza la recuperación de objetos JSON heredada |
| Lectura de saldo (suix_getBalance) | Consulta de saldo StateService | Acceso tipado a monedas y saldos |
| Último checkpoint (suix_getLatestCheckpointSequenceNumber) | Secuencia del último checkpoint de LedgerService | Altura de checkpoint para seguimiento de finalidad |
| Ejecución de transacción (suix_executeTransactionBlock) | TransactionExecutionService.ExecuteTransaction | Envío de transacción firmada |
| Simulación (suix_dryRunTransactionBlock) | TransactionExecutionService.SimulateTransaction | Validación previa al vuelo y estimación de gas |
| Suscripción a eventos (suix_subscribeEvent) | SubscriptionService.SubscribeEvents | Feed de eventos con streaming del servidor |
Consideraciones para mainnet y testnet
Use endpoints separados para mainnet y testnet. Testnet es para desarrollo y pruebas, no para producción. El faucet oficial de testnet de Sui es https://faucet.sui.io; verifique la política y los límites actuales del faucet antes de solicitar tokens. Los datos y endpoints de testnet no son permanentes y pueden reiniciarse o cambiar.
Los endpoints de mainnet requieren una planificación de capacidad cuidadosa y monitoreo de producción. La página de red de Sui de OnFinality (/networks/sui) lista los detalles actuales de mainnet y testnet. Para configuración específica de testnet, consulte /rpc-assistant/sui-testnet-rpc.
- Nunca reutilice tokens o claves de mainnet en testnet.
- Mantenga separadas las configuraciones de testnet y mainnet en su canal de implementación.
- Trate los streams de testnet como efímeros; construya reanudabilidad a partir de checkpoints.
Elección de un plan de Sui gRPC de OnFinality y verificaciones operativas
Al pasar de infraestructura compartida a dedicada, revise estas verificaciones: ¿El plan expone los servicios gRPC requeridos? ¿Se permiten streams de suscripción y cuáles son sus límites de tiempo de espera/retención? ¿Hay visibilidad de solicitudes y errores? ¿Se necesita un nodo dedicado para aislamiento o capacidad predecible?
La guía de proveedores de Sui RPC de OnFinality (/rpc-assistant/sui-rpc-providers) y la página de nodos Sui RPC (/rpc-assistant/sui-rpc-node) explican las opciones. Use la página de red de Sui (/networks/sui) para datos de endpoints.
| Criterio | Qué revisar | Por qué importa |
|---|---|---|
| Cobertura de servicios | Los cuatro servicios centrales más cualquier servicio gRPC adicional que necesite | Los servicios faltantes bloquean flujos de trabajo críticos |
| Límites de streaming | Política de tiempo de espera, retención y reconexión para SubscribeCheckpoints y otros streams | Los streams deben permanecer conectados para indexación y alertas |
| Visibilidad | Volumen de solicitudes, tasas de error y paneles de uso | La depuración y planificación de capacidad requieren observabilidad |
| Aislamiento | Endpoint compartido vs nodo dedicado | Las aplicaciones de alto rendimiento necesitan latencia y cuota predecibles |
Preguntas frecuentes
¿Sui gRPC está listo para producción en comparación con JSON-RPC?
Sí. Sui gRPC es la interfaz recomendada para producción. Proporciona serialización binaria eficiente, seguridad de tipos y streaming. JSON-RPC se está retirando, por lo que gRPC es la ruta a futuro para aplicaciones nuevas y en migración.
¿Cómo pruebo Sui gRPC con grpcurl de forma segura?
Use un marcador de posición GRPC_ENDPOINT de su proveedor y pase metadatos de autorización con -rpc-header 'authorization: Bearer <token>'. Use siempre TLS para endpoints administrados. Comience con grpcurl $GRPC_ENDPOINT list para descubrir los servicios disponibles.
¿Cuál es la diferencia entre ExecuteTransaction y SimulateTransaction?
SimulateTransaction ejecuta una transacción sin comprometer el estado, devolviendo efectos y estimaciones de gas. ExecuteTransaction envía una transacción firmada para su inclusión. Use la simulación primero para detectar errores, luego ejecute solo después de validar.
¿Qué métodos de streaming debo usar para checkpoints, transacciones y eventos?
Use SubscribeCheckpoints para feeds de checkpoints certificados, SubscribeTransactions para streams de transacciones ejecutadas y SubscribeEvents para streams de eventos Move. Todos son RPCs de streaming del servidor de SubscriptionService.
¿Puedo usar el mismo endpoint de Sui gRPC para mainnet y testnet?
No. Mainnet y testnet son entornos separados con estado y endpoints diferentes. Use un endpoint de testnet dedicado para desarrollo y pruebas. Para ayuda con testnet, consulte /rpc-assistant/sui-testnet-rpc.
¿Cómo abordo la migración de JSON-RPC a gRPC sin reescribir todo?
Inventaríe las llamadas JSON-RPC y agrúpelas en lecturas, checkpoints, ejecución/simulación y suscripciones. Mapee cada grupo al servicio gRPC apropiado e implemente utilizando clientes generados. No intente replicar campos SuiJSON; deje que los tipos protobuf impulsen su código.
Ethereum
Solana
Polygon
Base
Arbitrum
BNB Chain
Polkadot
Optimism
