React

Primeros pasos con el SDK de Omniston en React: crea interfaces DeFi responsivas con swaps entre DEX

Primeros pasos

Este paquete proporciona enlace para omniston-sdk al ecosistema de React. Usando este paquete, puedes acceder a todos los métodos de Omniston como hooks impulsados por TanStack react query (estados de carga listos para usar, reintentos, manejo de errores y mucho más)

📦 Paquete NPM: @ston-fi/omniston-sdk-react

Echa un vistazo a nuestra app de demostración que usa NextJs y omniston-sdk-react paquete

Instalación

vía NPM

npm install @ston-fi/omniston-sdk-react

vía YARN

yarn add @ston-fi/omniston-sdk-react

vía PNPM

pnpm install @ston-fi/omniston-sdk-react

Envuelve tu aplicación en el proveedor de Omniston

import { Omniston, OmnistonProvider } from "@ston-fi/omniston-sdk-react";

const omniston = new Omniston({ apiUrl: "wss://omni-ws.ston.fi" });

const App = () => (
  <OmnistonProvider omniston={omniston}>{children}</OmnistonProvider>
);

El proveedor acepta los siguientes parámetros:

Nombre	Tipo	Descripción
omniston	Omniston	Una instancia de Omniston preinstanciada configurada con tu URL de API

Ejemplo en sandbox (pruebas)

Si está desarrollando o probando su integración, use el entorno público de sandbox en lugar de producción.

import { Omniston, OmnistonProvider } from "@ston-fi/omniston-sdk-react";

const omniston = new Omniston({ apiUrl: "wss://omni-ws-sandbox.ston.fi" });

const App = () => (
  <OmnistonProvider omniston={omniston}>{children}</OmnistonProvider>
);

Sandbox está destinado solo para desarrollo y pruebas de integración. No use sandbox en aplicaciones de producción.

Configuración personalizada de transporte

Ahora puedes configurar un Transporte personalizado para tener un control más preciso sobre la conexión a la API de WebSocket:

import { Omniston, OmnistonProvider, WebSocketTransport } from "@ston-fi/omniston-sdk-react";

const omnistonApiUrl = "wss://omni-ws.ston.fi";
const omnistonTransport = new WebSocketTransport(omnistonApiUrl);

const omniston = new Omniston({
  apiUrl: omnistonApiUrl,
  transport: omnistonTransport,
});

const App = () => (
  <OmnistonProvider omniston={omniston}>{children}</OmnistonProvider>
);

// Puedes controlar la conexión del transporte:
// omnistonTransport.close();
// omnistonTransport.connect();
// omnistonTransport.connectionStatusEvents.subscribe(({ status }) => { /* ... */ })

Enviar una solicitud de cotización

Envía una solicitud de cotización para intercambiar un activo por otro activo.

import { useRfq, GaslessSettlement } from "@ston-fi/omniston-sdk-react";

const {
  isLoading,
  error,
  data: quoteResponse,
  ...restQuery
} = useRfq({
  settlementMethods: [SettlementMethod.SETTLEMENT_METHOD_SWAP],
  askAssetAddress: {
    blockchain: Blockchain.TON,
    address: "EQA2kCVNwVsil2EM2mB0SkXytxCqQjS4mttjDpnXmwG9T6bO", // STON
  },
  bidAssetAddress: {
    blockchain: Blockchain.TON,
    address: "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs", // USDT
  },
  amount: {
    bidUnits: "1000000", // 1 USDT
  },
  settlementParams: {
    maxPriceSlippageBps: 0,
    gaslessSettlement: GaslessSettlement.GASLESS_SETTLEMENT_POSSIBLE,
    maxOutgoingMessages: 4, // predeterminado para TON
    flexibleReferrerFee: true, // permite una comisión de referidor menor si el resolver mejora la cotización
  },
});

// Manejar diferentes tipos de respuesta
if (quoteResponse) {
  switch (quoteResponse.type) {
    case 'ack':
      console.log(`La solicitud de cotización fue reconocida con el ID: ${quoteResponse.rfqId}`);
      break;
    case 'quoteUpdated':
      console.log(`La cotización se actualizó para la solicitud ${quoteResponse.rfqId}`);
      // Usa quoteResponse.quote para los datos reales de la cotización
      break;
  }
}

Un QuoteRequest tiene las siguientes propiedades:

Nombre	Tipo	Descripción
settlementMethods	SettlementMethod[]	Métodos admitidos de liquidación del swap
askAssetAddress	Address	Dirección específica de la blockchain del activo ask
bidAssetAddress	Address	Dirección específica de la blockchain del activo bid
amount	{ bidUnits: string } | { askUnits: string }	Ya sea la cantidad del activo bid o del activo ask
amount.bidUnits	string	La cantidad del activo bid que el trader desea pagar, incluidas todas las comisiones, en unidades del activo base
amount.askUnits	string	La cantidad del activo ask que el trader desea obtener después de todas las comisiones, en unidades del activo base
referrerAddress	Address | undefined	La dirección del referidor que recibirá las comisiones
referrerFeeBps	number | undefined	La cantidad de comisiones requerida por el referente en puntos básicos (1/10000 = 0.01%)
settlementParams	RequestSettlementParams | undefined	Parámetros adicionales del RFQ relacionados con la liquidación. Consulte la tabla de abajo.

RequestSettlementParams

Nombre	Tipo	Descripción
max_price_slippage_bps	number | undefined	Deslizamiento máximo del precio, en puntos básicos (0,01%). Por ejemplo, 100 = 1% de deslizamiento. Establézcalo en 0 para usar el deslizamiento recomendado.
gasless_settlement	GaslessSettlement | undefined	Preferencia de liquidación sin gas. Opciones: GASLESS_SETTLEMENT_PROHIBITED (sin gasless), GASLESS_SETTLEMENT_POSSIBLE (permitir gasless), GASLESS_SETTLEMENT_REQUIRED (requiere gasless).
max_outgoing_messages	number | undefined	Número máximo de mensajes salientes admitidos por la cartera. Para la blockchain TON, el valor predeterminado es 4 si se omite.
flexible_referrer_fee	boolean | undefined	Establezca en true para permitir que los resolvers reduzcan la comisión efectiva del referidor por debajo de referrerFeeBps al ofrecer una mejor tasa. El valor predeterminado es false. En los SDK, páselo como flexibleReferrerFee. Consulte Comisión flexible del referidor para más detalles.

Nota: Algunos parámetros en RequestSettlementParams solo pueden ser relevantes para ciertas blockchains o ciertos métodos de liquidación. Si su método de liquidación o cartera no los requiere, puede omitarlos o establecerlos en valores predeterminados.

Opciones de liquidación sin gas:

• GASLESS_SETTLEMENT_PROHIBITED: Deshabilita completamente la liquidación sin gas

• GASLESS_SETTLEMENT_POSSIBLE: Permite la liquidación sin gas si está disponible (recomendado)

• GASLESS_SETTLEMENT_REQUIRED: Fuerza la liquidación sin gas (fallará si no está disponible)

El servidor devuelve Observable<QuoteResponseEvent>, que es un flujo de actualizaciones de cotización.

Un QuoteResponseEvent puede ser uno de los siguientes:

• { type: "ack"; rfqId: string; } - Confirmación de que se recibió la solicitud de cotización

• { type: "quoteUpdated"; quote: Quote; rfqId: string; } - Una actualización de la cotización (incluye rfqId después de la confirmación)

• { type: "noQuote"; }

• { type: "unsubscribed"; rfqId: string; } - Dado de baja del flujo de cotizaciones (incluye rfqId después de la confirmación)

Un Quote tiene las siguientes propiedades:

Nombre	Tipo	Descripción
quoteId	string	ID de la cotización generada por la plataforma (32 caracteres)
resolverId	string	ID del resolver
resolverName	string	Nombre del resolver
bidAssetAddress	Address	Dirección específica de la blockchain del activo bid
askAssetAddress	Address	Dirección específica de la blockchain del activo ask
bidUnits	string	La cantidad del activo bid que el trader debe pagar, incluidas todas las comisiones
askUnits	string	La cantidad del activo ask que el trader obtendrá después de todas las comisiones
referrerAddress	Address | undefined	La dirección del referidor que recibirá las comisiones
referrerFeeAsset	Address	El activo de las comisiones que recibirá el referidor
referrerFeeUnits	string	La cantidad de comisiones que recibirá el referidor (en unidades de referrerFeeAsset)
protocolFeeAsset	Address	El activo de las comisiones cobradas por el protocolo
protocolFeeUnits	string	La cantidad de comisiones cobradas por el protocolo (en unidades de protocolFeeAsset).
quoteTimestamp	number	La marca de tiempo (segundos UTC) de la cotización enviada por el resolver
tradeStartDeadline	number	Marca de tiempo máxima (segundos UTC) del inicio de la operación
gasBudget	string	La cantidad de presupuesto de gas para la operación
estimatedGasConsumption	string	Cantidad estimada de unidades de gas que se gastarán para realizar la operación
params	object | undefined	Varios parámetros específicos del método de liquidación. Consulte el código fuente para más detalles.

Construir una transacción

Ahora que tenemos una cotización, debemos solicitar al servidor que construya una transacción para iniciar la operación que el usuario pueda verificar y firmar.

import { useOmniston } from "@ston-fi/omniston-sdk-react";

const omniston = useOmniston();

const tx = await omniston.buildTransfer({
  quote,
  sourceAddress: {
    blockchain: Blockchain.TON,
    address: "", // dirección de la cartera remitente en `offerBlockchain`
  },
  destinationAddress: {
    blockchain: Blockchain.TON,
    address: "", // dirección de la cartera receptora en `askBlockchain`
  },
  gasExcessAddress: {
    blockchain: Blockchain.TON,
    address: "", // la dirección que recibirá el gas no gastado por la operación
  },
  useRecommendedSlippage: true, // usar el deslizamiento recomendado de la cotización
});

const messages = tx.ton?.messages ?? [];

El buildTransfer el método toma un TransactionRequest objeto como parámetro, que tiene las siguientes propiedades:

Nombre	Tipo	Descripción
quote	Quote	La cotización válida recibida de Omniston.requestForQuote
sourceAddress	Address	La dirección en offerBlockchain que enviará la transacción inicial para iniciar la operación
destinationAddress	Address	La dirección en askBlockchain que recibirá el resultado de la operación
gasExcessAddress	Address | undefined	La dirección que recibirá el gas no gastado por la operación
refundAddress	Address | undefined	La dirección a la que se devolverán los fondos en caso de un fallo
useRecommendedSlippage	boolean | undefined	Si se debe usar el deslizamiento recomendado de la cotización. El valor predeterminado es false.

Firmar la transacción

Puedes encontrar las instrucciones sobre cómo enviar una transacción usando el @tonconnect/ui-react paquete aquí.

import { useTonConnectUI } from "@tonconnect/ui-react";

const [tonConnect] = useTonConnectUI();

await tonConnect.sendTransaction({
  validUntil: Date.now() + 1000000,
  messages: messages.map((message) => ({
    address: message.targetAddress,
    amount: message.sendAmount,
    payload: message.payload,
  })),
});

Obtén el hash de la transacción saliente

Consulta TON Cookbook para obtener instrucciones detalladas.

Para fines del tutorial, usaremos el @ton/core paquete para obtener el hash externo de la transacción y encontrar el hash interno con TonAPI v2.

import { Cell } from "@ton/core";

const externalTxHash = Cell.fromBase64(boc).hash().toString("hex");
const response = await fetch(`https://tonapi.io/v2/traces/${externalTxHash}`);
const outgoingTxHash = (await response.json()).transaction.hash;

Escuchar actualizaciones del estado de la operación

Después de que el usuario haya firmado e iniciado la transacción, podemos rastrear el estado de la operación.

import { useTrackTrade } from "@ston-fi/omniston-sdk-react";
import { useTonAddress } from "@tonconnect/ui-react";

const walletAddress = useTonAddress();

const {
  isLoading,
  error,
  data: status,
  ...restQuery
} = useTrackTrade({
  quoteId: quote.quoteId,
  traderWalletAddress: {
    blockchain: Blockchain.TON,
    address: walletAddress,
  },
  outgoingTxHash: "", // Reemplace con el outgoingTxHash real
});

El trackTrade el método tiene los siguientes parámetros:

Nombre	Tipo	Descripción
quoteId	string	ID de la cotización recibida de Omniston.requestFromQuote
traderWalletAddress	Address	La dirección de la cartera del trader que inició la transacción
outgoingTxHash	string	Hash de la transacción que inició la operación

Devuelve Observable<TradeStatus>. Para los distintos valores del estado de la operación, consulte el código fuente. Nos interesa el enum del resultado de la operación, que puede leerse del campo status.tradeSettled?.result? . El enum tiene los siguientes valores:

Nombre	Descripción
TRADE_RESULT_FULLY_FILLED	La operación se ha completado y ejecutado por completo.
TRADE_RESULT_PARTIALLY_FILLED	La operación se ha ejecutado parcialmente. Algo salió mal.
TRADE_RESULT_ABORTED	La operación ha sido abortada.
TRADE_RESULT_UNKNOWN
UNRECOGNIZED