# Advanced Features

This document explains how to populate and interpret the `extra` field in `SwapChunk` (as referenced in [omniston-swap.md](https://docs.ston.fi/developer-section/omniston/swap/overview)), 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

```protobuf
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:

```typescript
// 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:

1. It examines the `protocol` field of each `SwapChunk` to determine which DEX to use
2. Based on the `extra_version`, it knows how to decode the `extra` field
3. 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](https://docs.ston.fi/developer-section/omniston/swap/overview).

## 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

## See Also

* [omniston-swap.md](https://docs.ston.fi/developer-section/omniston/swap/overview) - Main swap protocol documentation
* [omniston-nodejs.md](https://docs.ston.fi/developer-section/omniston/sdk/nodejs) - Node.js SDK usage
* [omniston-react.md](https://docs.ston.fi/developer-section/omniston/sdk/react) - React components and hooks