Funciones avanzadas

Funciones avanzadas de swap con protocolo de datos extra: personaliza parámetros de swap y enrutamiento para escenarios de trading complejos

Este documento explica cómo completar e interpretar el extra campo en SwapChunk (como se referencia en omniston-swap.md), específicamente al usar protocolos como StonFiV1, StonFiV2, DeDust, o TonCo.

Resumen

En el protocolo Omniston Swap, cada SwapChunk contiene dos campos para datos específicos del protocolo:

• extra_version (entero) - Indica la versión de la estructura de datos que se está utilizando

• extra (bytes) - Contiene los datos específicos del protocolo como un arreglo de bytes codificado en base64

Estos campos permiten que diferentes protocolos DEX incluyan sus propios parámetros y configuración para ejecutar swaps. Este documento describe el formato de esos datos y cómo codificarlos correctamente.

Definiciones del protocolo

message ExtraData {
  oneof extra {
    StonFiV1Extra ston_fi_v1 = 1;
    StonFiV2Extra ston_fi_v2 = 2;
    DeDustExtra de_dust = 3;
    TonCoExtra ton_co = 4;
  }
}

message StonFiV1Extra {
  string pool_address = 1;
  string min_ask_amount = 2;

  // Rellenado por el servicio Omniston
  string recommended_min_ask_amount = 50;
}

message StonFiV2Extra {
  string pool_address = 1;
  string min_ask_amount = 2;

  // Rellenado por el servicio Omniston
  string recommended_min_ask_amount = 50;
}

message DeDustExtra {
  string pool_address = 1;
  string min_ask_amount = 2;
  string referrer_address = 3;  // Especificado en el parámetro de swap `referralAddress` en el SDK de DeDust

  // Rellenado por el servicio Omniston
  string recommended_min_ask_amount = 50;
}

message TonCoExtra {
  string pool_address = 1;
  string min_ask_amount = 2;
  string limit_sqrt_price = 3;

  // Rellenado por el servicio Omniston
  string recommended_min_ask_amount = 50;
}

Descripción de los campos

Campos comunes

Todos los extras del protocolo comparten estos campos comunes:

• pool_address (cadena)

  • La dirección del contrato del pool DEX que ejecutará el swap

  • Esto es específico del par de tokens que se intercambia y del protocolo utilizado

• min_ask_amount (cadena)

  • La cantidad mínima de tokens ask que debe recibirse para este fragmento

  • Si el protocolo no puede proporcionar al menos esta cantidad, el swap se abortará

  • Se usa para proteger contra el deslizamiento y garantizar la cantidad mínima recibida

• recommended_min_ask_amount (cadena)

  • La cantidad mínima recomendada de tokens ask (rellenada por el servicio Omniston)

  • Este campo proporciona un valor optimizado de protección contra deslizamiento calculado por la plataforma

  • Disponible para todos los protocolos a partir de la versión extra 1

Campos específicos del protocolo

Protocolo DeDust

El protocolo DeDust incluye un campo adicional:

• referrer_address (cadena)

  • Dirección opcional que puede recibir recompensas/comisiones por referencia según las reglas de DeDust

  • Esto se especifica en el referralAddress parámetro al usar el SDK de DeDust

Protocolo TonCo

El protocolo TonCo incluye un campo adicional:

• limit_sqrt_price (cadena)

  • Límite de precio de la raíz cuadrada para la operación de swap

  • Se usa para controlar el impacto en el precio y proporcionar protección adicional contra deslizamiento

  • Este parámetro es específico del modelo de liquidez concentrada de TonCo

Ejemplo de uso

Aquí tienes un ejemplo de cómo construir y codificar los datos extra para un swap de StonFiV2:

// 1. Crear los datos extra específicos del protocolo
const stonFiV2Extra = {
  pool_address: "EQA...", // Dirección del pool de StonFi
  min_ask_amount: "1000000", // Mínimo de tokens a recibir
};

// 2. Envolver en el mensaje ExtraData
const extraData = {
  extra: {
    oneofKind: "ston_fi_v2",
    ston_fi_v2: stonFiV2Extra,
  },
};

// 3. Serializar a bytes protobuf
const extraBytes = ExtraData.encode(extraData).finish();

// 4. Codificar en base64 para transporte JSON
const extraBase64 = Buffer.from(extraBytes).toString("base64");

// 5. Usar en SwapChunk
const chunk = {
  protocol: "StonFiV2",
  offer_amount: "2000000",
  ask_amount: "1950000",
  extra_version: 1,
  extra: extraBase64,
};

Integración con el flujo de swap

Cuando el servidor Omniston procesa una solicitud de swap:

1. Examina el protocol campo de cada SwapChunk para determinar qué DEX usar

2. Basado en el extra_version, sabe cómo decodificar el extra campo

3. Los datos decodificados proporcionan los parámetros necesarios (dirección del pool, cantidades mínimas, etc.) para ejecutar el swap a través del DEX elegido

Para más detalles sobre el flujo general del swap y cómo encajan los fragmentos en rutas y pasos, consulta omniston-swap.md.

Historial de versiones

• Versión 1: Versión inicial con soporte para los protocolos StonFiV1, StonFiV2, DeDust y TonCo. Nota: Actualmente, solo extra_version = 1 es compatible para todos los protocolos.

  • Agregado recommended_min_ask_amount campo rellenado por el servicio Omniston para una protección optimizada contra deslizamiento

  • Agregado soporte para el protocolo TonCo con el limit_sqrt_price parámetro

Ver también

• omniston-swap.md - Documentación principal del protocolo de swap

• omniston-nodejs.md - Uso del SDK de Node.js

• omniston-react.md - Componentes y hooks de React