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, or DeDust.

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;
  }
}

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

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

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

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

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

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, and DeDust protocols