API gRPC de Sui: Guía práctica de la interfaz tipada de Sui

El papel de gRPC en la estrategia de acceso a datos de Sui

Sui está desplazando progresivamente su SDK principal y su ruta de acceso a datos desde el JSON-RPC heredado hacia una API gRPC con un cliente tipado generado. Este movimiento refleja una tendencia más amplia de la industria hacia interfaces basadas en esquemas que reducen los errores de integración y mejoran el rendimiento. Para las nuevas integraciones, comprender la superficie de gRPC se está volviendo esencial, incluso mientras JSON-RPC y GraphQL siguen disponibles para casos de uso específicos.

Las referencias de la API de Sui documentan tres superficies distintas de acceso a datos: JSON-RPC, gRPC y GraphQL. Cada una sirve a necesidades diferentes. JSON-RPC ofrece amplia compatibilidad y un modelo simple de solicitud-respuesta. GraphQL proporciona un lenguaje de consulta sobre un indexador, lo que permite a los clientes especificar la forma exacta de la respuesta. gRPC ofrece un protocolo binario fuertemente tipado y de alto rendimiento con capacidades de streaming. La documentación para desarrolladores de Sui proporciona orientación sobre SDK y acceso a datos que ayuda a los desarrolladores a elegir la superficie adecuada para su aplicación.

Este artículo se centra en la API gRPC: qué es, cómo funciona a nivel de protocolo y cómo llamarla usando el SDK de TypeScript de Sui. También contrasta gRPC con JSON-RPC y GraphQL para que puedas tomar una decisión informada sobre qué interfaz usar. Para una visión más amplia del acceso a la red Sui, consulta la página de redes Sui y el centro de aprendizaje de OnFinality.

• gRPC es un framework RPC moderno basado en HTTP/2 que utiliza Protobuf para la serialización de mensajes.
• La API gRPC de Sui proporciona un cliente tipado generado a partir de una definición de servicio .proto.
• Admite llamadas unarias y de streaming, lo que permite una recuperación eficiente de datos y actualizaciones en tiempo real.
• La API está en evolución; fija siempre la versión de tu SDK y verifica el soporte del proveedor.

Fundamentos del protocolo gRPC: HTTP/2, Protobuf y streaming

gRPC es un framework RPC de código abierto que utiliza HTTP/2 como transporte y Protocol Buffers (Protobuf) como lenguaje de definición de interfaz y formato de mensaje. Como se describe en la introducción a gRPC, gRPC permite que las aplicaciones cliente y servidor se comuniquen de forma transparente y simplifica la construcción de sistemas conectados. Admite cuatro tipos de métodos de servicio: unario, streaming de servidor, streaming de cliente y streaming bidireccional.

En una llamada gRPC, el cliente invoca un método en un stub de servicio, pasando un mensaje de solicitud tipado. El stub serializa el mensaje en formato binario Protobuf y lo envía a través de un stream HTTP/2. El servidor deserializa la solicitud, la procesa y devuelve un mensaje de respuesta tipado. Debido a que el contrato de servicio se define en un archivo .proto, tanto el cliente como el servidor comparten el mismo esquema, lo que permite la generación de código y la verificación de tipos en tiempo de compilación.

Esto contrasta con JSON-RPC, donde el cliente envía un objeto JSON con un nombre de método y parámetros, y el servidor devuelve un objeto JSON. No hay un esquema formal, por lo que los errores de tipo solo se detectan en tiempo de ejecución. La codificación binaria de gRPC también es más compacta que el texto JSON, lo que puede reducir el ancho de banda y mejorar el rendimiento, especialmente para cargas útiles grandes o llamadas de alta frecuencia.

• La multiplexación de HTTP/2 permite múltiples llamadas concurrentes sobre una sola conexión.
• Protobuf proporciona serialización binaria eficiente y tipado fuerte.
• El streaming permite flujos de datos en tiempo real, como suscripciones a transacciones.
• Los stubs de cliente generados reducen el código repetitivo y hacen cumplir el contrato de servicio.

Comparación de gRPC de Sui con JSON-RPC y GraphQL

La API JSON-RPC de Sui es una interfaz tradicional de llamada a procedimiento remoto donde cada solicitud especifica un nombre de método y una carga útil JSON. Es ampliamente compatible y fácil de usar desde cualquier cliente HTTP, pero carece de un esquema formal, por lo que los desarrolladores deben consultar la documentación para conocer los parámetros esperados y la forma de la respuesta. La guía de RPC de Sui (RPC Assistant) cubre el uso de JSON-RPC en detalle. Los métodos JSON-RPC también están sujetos a obsolescencia, como se señala en el artículo sobre la obsolescencia de métodos JSON-RPC de Sui.

GraphQL de Sui, por el contrario, es un lenguaje de consulta sobre un indexador. Los clientes especifican los campos exactos que necesitan y el servidor devuelve solo esos datos. Esta flexibilidad es potente para consultas complejas y agregación histórica, pero requiere un indexador y puede no ser adecuada para el envío de transacciones en tiempo real. El artículo sobre la superficie de consulta de la API GraphQL de Sui explora esta superficie en profundidad.

gRPC se sitúa entre estos dos extremos. Ofrece una interfaz tipada y basada en esquemas como GraphQL, pero con el rendimiento y las capacidades de streaming de un protocolo binario. A diferencia de GraphQL, gRPC no es un lenguaje de consulta; se llaman métodos predefinidos con solicitudes tipadas. A diferencia de JSON-RPC, gRPC requiere generación de código y un entorno compatible con HTTP/2. Para las nuevas integraciones que necesitan seguridad de tipos y eficiencia, gRPC es cada vez más la opción preferida.

• JSON-RPC: método + texto JSON, sin esquema, amplia compatibilidad.
• GraphQL: lenguaje de consulta sobre un indexador, forma de respuesta especificada por el cliente.
• gRPC: cliente tipado, codificación binaria Protobuf, streaming, requiere HTTP/2.
• Cada superficie tiene ventajas y desventajas; elige según las necesidades de tu aplicación.

Anatomía de una llamada gRPC de Sui a nivel de protocolo

A nivel de protocolo, una llamada gRPC de Sui comienza con un stub de cliente que invoca un método de servicio, como GetTransaction o GetObject. El cliente construye un mensaje de solicitud tipado, por ejemplo un GetTransactionRequest que contiene un digest de transacción. El stub serializa este mensaje en binario Protobuf y lo envía a través de un stream HTTP/2 al servidor. El servidor procesa la solicitud y devuelve un mensaje de respuesta tipado, como un GetTransactionResponse, que el cliente deserializa en un objeto nativo.

Esto es fundamentalmente diferente de una llamada JSON-RPC, donde el cliente envía un HTTP POST con un cuerpo JSON como {"jsonrpc":"2.0","method":"sui_getTransactionBlock","params":["0x..."],"id":1}. El servidor JSON-RPC analiza el JSON, ejecuta el método y devuelve una respuesta JSON. No hay un contrato en tiempo de compilación; el cliente debe conocer el nombre del método y el orden de los parámetros a partir de la documentación.

La definición del servicio gRPC está contenida en un archivo .proto, que el SDK de Sui envuelve y expone como un cliente tipado. Esto significa que puedes usar autocompletado y verificación de tipos en tu IDE, lo que reduce el riesgo de errores en tiempo de ejecución. El SDK también gestiona la conexión, la serialización y la deserialización, para que puedas centrarte en la lógica de la aplicación.

// Example .proto snippet (simplified)
service SuiGrpcService {
  rpc GetTransaction(GetTransactionRequest) returns (GetTransactionResponse);
  rpc GetObject(GetObjectRequest) returns (GetObjectResponse);
}

message GetTransactionRequest {
  string digest = 1;
}

message GetTransactionResponse {
  Transaction transaction = 1;
}

Configuración del SDK de TypeScript de Sui para gRPC

Para llamar a la API gRPC de Sui desde Node.js o TypeScript, necesitas el SDK de TypeScript de Sui, que incluye un cliente gRPC. El SDK está disponible en npm y se puede instalar con un gestor de paquetes. Antes de comenzar, asegúrate de que tu entorno sea compatible con HTTP/2, ya que gRPC lo requiere. Node.js tiene soporte integrado de HTTP/2, por lo que funciona de inmediato.

También necesitarás un endpoint gRPC de Sui. Proveedores como OnFinality ofrecen endpoints RPC de Sui; consulta la página de servicio de API para conocer las interfaces disponibles. Verifica siempre que tu proveedor sea compatible con gRPC, ya que no todos los endpoints RPC lo exponen. La página de precios de RPC puede ayudarte a elegir un plan que incluya acceso a gRPC.

Una vez instalado, puedes importar el cliente gRPC y crear una conexión. El SDK normalmente proporciona una clase SuiGrpcClient o similar, que instancias con la URL del endpoint. También es posible que necesites configurar la autenticación si tu proveedor requiere una clave de API. Consulta la documentación del SDK para conocer los nombres exactos de las clases y las opciones de configuración, ya que pueden cambiar entre versiones.

// Install the Sui TypeScript SDK
npm install @mysten/sui

// Import the gRPC client (class name may vary by SDK version)
import { SuiGrpcClient } from '@mysten/sui/grpc';

// Create a client instance
const client = new SuiGrpcClient({
  url: 'https://sui-grpc.example.com', // replace with your provider's gRPC endpoint
  // apiKey: 'your-api-key', // if required
});

Ejemplo ejecutable: consultar una transacción con el cliente gRPC tipado

El siguiente ejemplo de Node.js/TypeScript muestra cómo conectarse a un endpoint gRPC de Sui y recuperar una transacción por su digest usando el cliente tipado. Luego muestra la operación equivalente usando JSON-RPC para comparar. Este ejemplo asume que has instalado el SDK de TypeScript de Sui y tienes una URL de endpoint gRPC.

Reemplaza el endpoint de marcador de posición y el digest de transacción con tus propios valores. El ejemplo usa async/await por legibilidad. Ten en cuenta que los nombres exactos de los métodos y las estructuras de respuesta pueden diferir ligeramente según la versión del SDK; consulta siempre la documentación o las definiciones de tipos del SDK.

Después de ejecutar el ejemplo, deberías ver los detalles de la transacción impresos en la consola. La respuesta gRPC es un objeto tipado, mientras que la respuesta JSON-RPC es un objeto JSON plano. Esto ilustra la diferencia en la experiencia del desarrollador: con gRPC, tu IDE puede proporcionar autocompletado y verificación de tipos para los campos de respuesta.

import { SuiGrpcClient } from '@mysten/sui/grpc';
import fetch from 'node-fetch'; // for JSON-RPC comparison

const GRPC_URL = 'https://sui-grpc.example.com';
const JSON_RPC_URL = 'https://sui-json-rpc.example.com';
const TX_DIGEST = '0x...'; // replace with a real transaction digest

async function queryWithGrpc() {
  const client = new SuiGrpcClient({ url: GRPC_URL });
  const response = await client.getTransaction({ digest: TX_DIGEST });
  console.log('gRPC response:', response);
  // response is a typed object, e.g., response.transaction
}

async function queryWithJsonRpc() {
  const body = {
    jsonrpc: '2.0',
    method: 'sui_getTransactionBlock',
    params: [TX_DIGEST, { showInput: true, showEffects: true }],
    id: 1,
  };
  const res = await fetch(JSON_RPC_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  const json = await res.json();
  console.log('JSON-RPC response:', json);
}

(async () => {
  await queryWithGrpc();
  await queryWithJsonRpc();
})();

Medición reproducible: comparación de llamadas gRPC y JSON-RPC

Para evaluar las diferencias prácticas entre gRPC y JSON-RPC en tu caso de uso, puedes realizar una medición reproducible usando tu propio endpoint. La siguiente tabla proporciona una plantilla para registrar métricas clave. Complétala ejecutando la misma operación lógica (por ejemplo, obtener una transacción) a través de ambas interfaces y midiendo los tamaños de solicitud y respuesta, así como el tipo de respuesta.

Usa una herramienta como curl con --trace-ascii o un inspector de red para capturar los bytes sin procesar de JSON-RPC. Para gRPC, puedes usar el registro de una biblioteca cliente de gRPC o un proxy como grpcurl para inspeccionar la carga útil binaria. Ten en cuenta que las cargas útiles de gRPC son binarias y pueden no ser legibles por humanos, pero puedes medir su tamaño. El objetivo es comprender las ventajas y desventajas en tu entorno específico.

Recuerda que las condiciones de red, la ubicación del endpoint y la configuración del proveedor pueden afectar los resultados. Realiza múltiples pruebas y promedia los números. Este método no es un benchmark; es una forma de tomar una decisión informada basada en tus propias mediciones.

• Operación: por ejemplo, GetTransaction
• Llamada gRPC: por ejemplo, client.getTransaction({ digest })
• Método JSON-RPC: por ejemplo, sui_getTransactionBlock
• Bytes de solicitud: medir el tamaño de la carga útil sin procesar
• Bytes de respuesta: medir el tamaño de la carga útil sin procesar
• Respuesta tipada vs no tipada: gRPC devuelve un objeto tipado; JSON-RPC devuelve JSON plano

Limitaciones y compensaciones de la API gRPC de Sui

La API gRPC de Sui es potente, pero tiene limitaciones. Primero, los endpoints gRPC y los servicios admitidos varían según el proveedor y la versión de la red. No todos los proveedores de RPC exponen gRPC, y los que lo hacen pueden admitir solo un subconjunto de métodos. Verifica siempre la lista de interfaces admitidas de tu proveedor antes de integrar. La página de servicio de API de OnFinality documenta las interfaces disponibles en sus endpoints de Sui.

Segundo, la API está en evolución. La interfaz gRPC de Sui está en desarrollo activo y pueden producirse cambios importantes entre versiones del SDK. Fija la versión de tu SDK en tu proyecto para evitar roturas inesperadas y revisa las notas de la versión antes de actualizar. El artículo sobre la obsolescencia de métodos JSON-RPC de Sui destaca que los métodos JSON-RPC también están sujetos a cambios, por lo que ninguna interfaz es completamente estática.

Tercero, no se puede llamar a gRPC directamente desde un navegador sin un proxy. Los navegadores no exponen el framing HTTP/2 necesario ni el manejo binario para gRPC. El SDK de Sui proporciona una ruta segura para la web, a menudo usando gRPC-Web o un proxy, pero esto añade complejidad. Si estás creando una dApp basada en navegador, considera si JSON-RPC o GraphQL podrían ser más simples para tus operaciones de lectura.

Por último, gRPC es una interfaz de lectura/escritura para la cadena, pero no reemplaza a un indexador para la agregación histórica. Si necesitas consultar datos históricos de muchas transacciones o calcular agregados, GraphQL o un indexador dedicado son más apropiados. gRPC está optimizado para el acceso directo a la cadena, no para consultas analíticas.

• El soporte de gRPC por parte del proveedor varía; verifícalo antes de comprometerte.
• La API está en evolución; fija la versión del SDK y monitorea los cambios.
• El uso en navegador requiere un proxy o gRPC-Web; no es directo.
• No reemplaza a los indexadores cuando se necesita agregación histórica.

Solución de problemas comunes de integración con gRPC

Al integrarte con la API gRPC de Sui, puedes encontrar problemas relacionados con la conectividad, la serialización o desajustes de versión. Esta sección cubre problemas comunes y cómo diagnosticarlos. Comienza verificando que la URL de tu endpoint sea correcta y que tu proveedor admita gRPC. Una prueba rápida con grpcurl puede confirmar la conectividad y listar los servicios disponibles.

Si recibes un error UNIMPLEMENTED, el método que estás llamando puede no ser compatible con tu proveedor o puede no existir en la versión del servicio que estás utilizando. Consulta la documentación del proveedor y las definiciones .proto del SDK. Si obtienes un error DEADLINE_EXCEEDED, la solicitud agotó el tiempo de espera; considera aumentar el plazo o verificar la latencia de la red.

Los errores de serialización a menudo provienen de definiciones de Protobuf que no coinciden. Asegúrate de que tus stubs de cliente se generen a partir de la misma versión de .proto que el servidor. Si usas el SDK de Sui, esto se gestiona por ti, pero si generas tus propios stubs, mantenlos sincronizados. Para la comparación con JSON-RPC, recuerda que los errores de JSON-RPC se devuelven como objetos JSON con un campo error, mientras que gRPC usa códigos de estado.

Para obtener más consejos de solución de problemas específicos de RPC de Sui, consulta la guía de RPC de Sui (RPC Assistant). Si estás migrando desde JSON-RPC, el artículo sobre efectos de transacción y cambios de objetos en RPC de Sui explica cómo analizar los resultados de transacciones, lo cual es útil al comparar respuestas.

• Verifica la URL del endpoint y el soporte de gRPC del proveedor.
• Usa grpcurl para probar la conectividad y listar servicios.
• Comprueba si hay códigos de estado UNIMPLEMENTED o DEADLINE_EXCEEDED.
• Asegúrate de que las definiciones de Protobuf coincidan entre cliente y servidor.

Próximos pasos: integrar gRPC en tu aplicación Sui

Ahora que comprendes la API gRPC de Sui y cómo llamarla, puedes comenzar a integrarla en tu aplicación. Empieza eligiendo un proveedor que admita gRPC, como OnFinality, y obtén una URL de endpoint. Revisa la página de precios de RPC para seleccionar un plan que se ajuste a tus necesidades. Luego, instala el SDK de TypeScript de Sui y experimenta con el cliente tipado en un entorno de desarrollo.

A medida que construyas, considera las ventajas y desventajas entre gRPC, JSON-RPC y GraphQL. Para aplicaciones con muchas lecturas que necesitan seguridad de tipos y streaming, gRPC es una opción sólida. Para consultas históricas complejas, GraphQL puede ser mejor. Para integraciones simples y ampliamente compatibles, JSON-RPC sigue siendo viable. También puedes combinar interfaces: usar gRPC para el envío de transacciones y JSON-RPC para compatibilidad heredada.

Para profundizar tu comprensión, explora artículos relacionados del centro de aprendizaje de OnFinality, como la superficie de consulta de la API GraphQL de Sui y la guía sobre paginación por cursor de queryTransactionBlocks en Sui. Estos recursos te ayudarán a construir aplicaciones Sui robustas y eficientes. Para obtener una lista completa de redes y servicios, visita la página de redes Sui y el centro de aprendizaje de OnFinality.

• Elige un proveedor compatible con gRPC y obtén un endpoint.
• Instala el SDK de TypeScript de Sui y prueba el cliente tipado.
• Evalúa gRPC vs JSON-RPC vs GraphQL para tu caso de uso.
• Explora artículos relacionados del centro de aprendizaje para profundizar.