Integración gRPC

Integra swaps de Omniston usando la API gRPC: protocolo de alto rendimiento para trading programático de tokens en TON

Esta guía describe cómo usar la Omniston funcionalidad de swap sobre la API gRPC desde la perspectiva de un trader. Es paralela a Resumen del swap (WebSocket) pero muestra los detalles específicos de gRPC.

Diferencias clave respecto a la API WebSocket

1. Campo del protocolo Para la API gRPC, el protocol campo en cada fragmento de swap debe ser una cadena:

   • "StonFiV1", "StonFiV2", "DeDust", o "TonCo". En cambio, la API WebSocket usa códigos numéricos 1, 2, 3, o 4.

2. Versión adicional Actualmente, solo extraVersion = 1 es compatible.

3. Pasos vs. fragmentos

   • Cada SwapStep mueve de un activo a otro (por ejemplo, TON → USDC).

   • Cada paso puede tener múltiples SwapChunk objetos, pero en TON normalmente verás exactamente un fragmento por paso.

4. Nombres de métodos En la API gRPC, los traders usan llamadas similares a requestForQuote, buildTransfer, trackTrade, etc., pero estas se exponen mediante mensajes protobuf, no JSON-RPC. Los campos subyacentes son los mismos.

Puntos finales gRPC (TLS)

Producción: omni-grpc.ston.fi:443 Sandbox: omni-grpc-sandbox.ston.fi:443

⚠️ Los endpoints gRPC son host:puerto destinos sobre TLS y no son URL REST HTTP. No uses https://... como si fuera una API REST.

Flujo típico (traders)

Un flujo típico de swap basado en gRPC desde el punto de vista de un trader es:

1. Enviar una solicitud de cotización Usando Omniston.requestForQuote (o la llamada gRPC correspondiente), proporcionando:

   • bidAssetAddress, askAssetAddress

   • El amount deseado (ya sea bidUnits o askUnits)

   • Opcional referrerAddress y referrerFeeBps

   • settlementMethods = [SETTLEMENT_METHOD_SWAP] si quieres un swap

   • settlementParams como maxPriceSlippageBps, maxOutgoingMessages (para TON), o flexibleReferrerFee bandera

   Recibes un Observable (estilo RxJS en el SDK) o un flujo de QuoteResponseEvent mensajes a través de gRPC:

   • Primero, recibirás un QuoteRequestAck mensaje que contiene el rfq_id (una cadena hexadecimal SHA-256) que identifica de forma única tu solicitud de cotización

   • Luego, el servidor puede actualizar tu cotización repetidamente si llega un precio más favorable

2. Construir la transferencia Cuando tengas una Quoteválida, llama a Omniston.buildTransfer con:

   • El quote aceptaste

   • Tu sourceAddress (en bidBlockchain)

   • Tu destinationAddress (en askBlockchain)

   • Opcional: refundAddress - dónde deben devolverse los fondos si la transacción falla (por defecto, a la wallet del remitente) La API devuelve un objeto con datos de transacción específicos de la cadena de bloques (para TON, una lista de mensajes).

3. Firmar/Enviar la transacción

   • En TON, normalmente pasas estos mensajes a tu wallet (por ejemplo, TonConnect, Tonkeeper, etc.).

   • Espera a que la transacción se incluya en un bloque.

4. Seguimiento de la operación Luego puedes llamar a Omniston.trackTrade para recibir actualizaciones en streaming sobre el estado de la operación. Esto incluye si la operación se completó, se completó parcialmente o se abortó.

Tipos de datos importantes

• Blockchain Un código numérico que sigue SLIP-044. Para TON, este es 607.

• Address Un objeto:

  {
    "blockchain": 607,
    "address": "EQDA3..."
  }

• Protocolo Debe ser uno de:

  • "StonFiV1"

  • "StonFiV2"

  • "DeDust"

  • "TonCo"

• SettlementMethod Por ahora, normalmente [0] para swap en forma numérica, o (en tu SDK) SettlementMethod.SETTLEMENT_METHOD_SWAP.

• QuoteRequestAck Mensaje de confirmación enviado inmediatamente después de recibir una solicitud de cotización:

  message QuoteRequestAck {
    string rfq_id = 1;  // cadena hexadecimal SHA-256 que identifica de forma única el RFQ
  }

• SwapStep y SwapChunk

  • Cada paso es una transición de bidAssetAddress to askAssetAddress.

  • Para TON: normalmente exactamente un fragmento por paso.

  • Un fragmento incluye:

    string protocol = 1;       // por ejemplo, "StonFiV2"
    string offer_amount = 2;
    string ask_amount = 3;
    uint64 extra_version = 4;  // debe ser 1
    bytes extra = 5;           // datos codificados en base64 para tu DEX

• Quote El servidor proporciona un quoteId, bidUnits, askUnits, quoteTimestamp, tradeStartDeadline, etc. Incluye params con información de liquidación para el método elegido (SwapSettlementParams).

Cotizaciones rechazadas

Si pasas extraVersion != 1 (por ejemplo, 3), la cotización o la ruta se rechaza con un mensaje como:

Versión extra no válida para el paso 0: 3

Asegúrate de usar extraVersion = 1.

Próximos pasos

Para una definición completa y de bajo nivel del servicio gRPC (lado del resolvedor, además de los mensajes subyacentes), consulta Guía de integración del resolvedor. Para uso en Node.js o TypeScript, consulta omniston-nodejs.md o la omniston-react.md para aplicaciones React. Ambas dependen del mismo backend subyacente gRPC/WS.

Si tienes alguna pregunta o problema, por favor escríbenos en nuestro Discord de STON.fi.