Swap extra

This document explains how to populate and interpret the extra field in SwapChunk (as referenced in omniston-swap.md), specifically when using protocols like StonFiV1, StonFiV2, DeDust, or TonCo.

Overview

In the Omniston Swap protocol, each SwapChunk contains two fields for protocol-specific data:

extra_version (integer) - Indicates the version of the data structure being used
extra (bytes) - Contains the protocol-specific data as a base64-encoded byte array

These fields allow different DEX protocols to include their own parameters and configuration for executing swaps. This document describes the format of that data and how to encode it properly.

Protocol Definitions

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;

  // Filled by Omniston service
  string recommended_min_ask_amount = 50;
}

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

  // Filled by Omniston service
  string recommended_min_ask_amount = 50;
}

message DeDustExtra {
  string pool_address = 1;
  string min_ask_amount = 2;
  string referrer_address = 3;  // Specified in `referralAddress` swap parameter in DeDust SDK

  // Filled by Omniston service
  string recommended_min_ask_amount = 50;
}

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

  // Filled by Omniston service
  string recommended_min_ask_amount = 50;
}

Field Descriptions

Common Fields

All protocol extras share these common fields:

pool_address (string)
- The address of the DEX pool contract that will execute the swap
- This is specific to the token pair being swapped and the protocol being used
min_ask_amount (string)
- The minimum amount of ask tokens that must be received for this chunk
- If the protocol cannot provide at least this amount, the swap will be aborted
- Used to protect against slippage and ensure minimum received amount
recommended_min_ask_amount (string)
- The recommended minimum amount of ask tokens (filled by Omniston service)
- This field provides an optimized slippage protection value calculated by the platform
- Available for all protocols starting with extra version 1

Protocol-Specific Fields

DeDust Protocol

The DeDust protocol includes an additional field:

referrer_address (string)
- Optional address that may receive referral rewards/fees according to DeDust's rules
- This is specified in the referralAddress parameter when using the DeDust SDK

TonCo Protocol

The TonCo protocol includes an additional field:

limit_sqrt_price (string)
- Square root price limit for the swap operation
- Used to control price impact and provide additional slippage protection
- This parameter is specific to TonCo's concentrated liquidity model

Usage Example

Here's an example of how to construct and encode the extra data for a StonFiV2 swap:

// 1. Create the protocol-specific extra data
const stonFiV2Extra = {
  pool_address: "EQA...", // Address of the StonFi pool
  min_ask_amount: "1000000", // Minimum tokens to receive
};

// 2. Wrap in ExtraData message
const extraData = {
  extra: {
    oneofKind: "ston_fi_v2",
    ston_fi_v2: stonFiV2Extra,
  },
};

// 3. Serialize to protobuf bytes
const extraBytes = ExtraData.encode(extraData).finish();

// 4. Base64 encode for JSON transport
const extraBase64 = Buffer.from(extraBytes).toString("base64");

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

Integration with Swap Flow

When the Omniston server processes a swap request:

It examines the protocol field of each SwapChunk to determine which DEX to use
Based on the extra_version, it knows how to decode the extra field
The decoded data provides the necessary parameters (pool address, minimum amounts, etc.) to execute the swap through the chosen DEX

For more details on the overall swap flow and how chunks fit into routes and steps, see omniston-swap.md.

Version History

Version 1: Initial version supporting StonFiV1, StonFiV2, DeDust, and TonCo protocols. Note: Currently, only extra_version = 1 is supported for all protocols.
- Added recommended_min_ask_amount field filled by Omniston service for optimized slippage protection
- Added support for TonCo protocol with limit_sqrt_price parameter