Encoding

The first step to execute a trade on chain is encoding.

Our Rust crate offers functionality to convert your trades into calldata, which the Tycho contracts can execute.

See this Quickstart section for an example of how to encode your trade.

Encoders

Builder

To create an EVMTychoEncoder, you need to use an EVMEncoderBuilder. A valid encoder needs to have a chain and a strategy encoder set. More info about the strategies can be found here.

To simplify the setup, we provide shortcut methods for common use cases:

• tycho_router: Uses the TychoRouter contract, assuming that you transfer the input token to the contract in the same transaction.

• tycho_router_permit2: Uses Permit2 for token approvals and transfers. This method requires a signer private key.

• direct_execution: Generates calldata for direct execution via the Executor contracts, bypassing the Tycho router. This is useful if you're integrating Tycho Executors with your own routing logic. See more details here.

Example Usage

let encoder = EVMEncoderBuilder::new()
    .chain(Chain::Ethereum)
    .tycho_router(None)
    .expect("Failed to create encoder builder")
    .build()
    .expect("Failed to build encoder");

Strategy

When initializing the EVMEncoderBuilder, you must define a strategy. The strategy determines how the trade is encoded.

Currently, we support two encoding strategies:

• Split Swap Strategy: Enables multi-hop trade execution via the Tycho Router. Supports split swap solutions.

• Executor Strategy: Generates calldata for direct execution via the Executor contracts (no router interaction). Supports multi-swap trades only if all swaps can be compressed into a single Swap Group, otherwise, only single-hop trades are supported.

Models

Solution Struct

The Solution struct specifies the details of your order and how it should be filled. This is the input of the encoding module.

The Solution struct consists of the following attributes:

Attribute	Type	Description
given_token	Bytes	The token being sold (exact in) or bought (exact out)
given_amount	BigUint	Amount of the given token
checked_token	Bytes	The token being bought (exact in) or sold (exact out). This token's final balance will be checked by the router if you provide a checked_amount.
sender	Bytes	Address of the sender of the given token
receiver	Bytes	Address of the receiver of the checked token
exact_out	bool	False if the solution is an exact input solution (i.e. solves a sell order). Currently only exact input solutions are supported.
router_address	Bytes	Address of the router contract to be used.
swaps	Vec<Swap>	List of swaps to fulfill the solution.
slippage	Option<f64>	If set, this value will be applied to expected_amount and will become the checked_amount if greater than the user-inputted checked_amount (exact in) or less than the user-inputted checked_amount (exact out).
expected_amount	Option<BigUint>	Amount expected to receive (exact in) or pay (exact out) for this solution. Slippage is applied onto this amount.
checked_amount	Option<BigUint>	Minimum amount out (exact in) or maximum amount in (exact out) to be checked for the solution to be valid. If not set, no checks will be performed.
native_action	Option<NativeAction>	If set, the native token will be wrapped before the swap or unwrapped after the swap (more here).

Wrapping and Unwrapping

Our router accepts wrapping native tokens to wrapped token before performing the first swap, and unwrapping wrapped tokens to native tokens after the final swap, before sending the funds to the receiver.

In order to perform this, the native_action parameter of the solution must be set to either Some(NativeAction.WRAP) or Some(NativeAction.UNWRAP).

When wrapping:

• The given_token of the solution should be ETH

• The token_in of the first swap should be WETH

When unwrapping:

• The checked_token of the solution should be ETH

• The token_out of the final swap should be WETH

Swap Struct

A solution consists of one or more swaps. A swap represents a swap operation to be performed on a pool.

The Swap struct has the following attributes:

Attribute	Type	Description
component	ProtocolComponent	Protocol component from Tycho core
token_in	Bytes	Token you provide to the pool
token_out	Bytes	Token you expect from the pool
split	f64	Percentage of the amount in to be swapped in this operation (for example, 0.5 means 50%)

To create a Swap, use the new function where you can pass any struct that implements Into<ProtocolComponent> .

Split Swaps

Solutions can have splits where one or more token hops are split between two or more pools. We perform internal validation on split swaps. A split swap is considered valid if:

1. The checked token is reachable from the given token through the swap path

2. There are no tokens that are unconnected

3. Each split amount is small than 1 (100%) and larger or equal to 0 (0%)

4. For each set of splits, set the split for the last swap to 0. This tells the router to send all tokens not assigned to the previous splits in the set (i.e., the remainder) to this pool.

5. The sum of all non-remainder splits for each token is smaller than 1 (100%)

Swap Group

Certain protocols, such as Uniswap V4, allow you to save token transfers between consecutive swaps thanks to their flash accounting. In case your solution contains sequential (non-split) swaps of such protocols, our encoders compress these consecutive swaps into a single swap group, meaning that a single call to our executor is sufficient for performing these multiple swaps.

In the example above, the encoder will compress three consecutive swaps into the following swap group to call the UniswapV4 executor:

SwapGroup {
    input_token: weth_address,
    output_token: dai_address,
    protocol_system: "uniswap_v4",
    swaps: vec![weth_wbtc_swap, wbtc_usdc_swap, usdc_dai_swap],
    split: 0,
}

One solution will contain multiple swap groups if different protocols are used.

Example Solution

The following diagram shows a swap from ETH to DAI through USDC. ETH arrives in the router and is wrapped to WETH. The solution then splits between three (WETH, USDC) pools and finally swaps from USDC to DAI on one pool.

The Solution object for the given scenario would look as follows:

swap_a = Swap::new(
    pool_a,
    weth_address,
    usdc_address,
    0.3, // 30% of WETH amount
);
swap_b = Swap::new(
    pool_b,
    weth_address,
    usdc_address,
    0.3, // 30% of WETH amount
);
swap_c = Swap::new(
    pool_c,
    weth_address,
    usdc_address,
    0f64, // Rest of remaining WETH amount
);
swap_d = Swap::new(
    pool_d,
    usdc,
    dai,
    0f64, // All of USDC amount
);

let solution = Solution {
    sender: user_address,
    receiver: user_address,
    given_token: eth_address,
    given_amount: sell_amount,
    checked_token: dai_address,
    exact_out: false, // Sell order
    router_address,
    slippage: None, // Do not perform slippage check
    expected_amount: None, // Do not perform slippage check
    check_amount: None, // Do not perform final checking
    swaps: vec![swap_a, swap_b, swap_c, swap_d],
    native_action: Some(NativeAction.WRAP) // Wrap ETH to WETH before first swap
    direct_executionL False, // Swap through Tycho router, not straight to executor
};

Transaction struct

Encoding returns you a Transaction struct. It has the following attributes:

Attribute	Type	Description
to	Bytes	The contract address to which you send the transaction.
value	BigUint	Amount of ETH to send (for native transactions)
data	Vec<u8>	The encoded calldata containing the swap details.

Run as a Binary

Installation

First, build and install the binary:

# Build the project
cargo build --release

# Install the binary to your system
cargo install --path .

After installation, you can use the tycho-encode command from any directory in your terminal.

Commands

The command lets you choose the encoding strategy to be used. These correspond to the shortcut methods of the builder. The available strategies are:

• tycho-router: Encodes a transaction using the Tycho Router encoding strategy. Requires a private key for signing Permit2.

• tycho-router-permit2: Encodes a transaction using the Tycho Router encoding strategy. Requires a private key for signing Permit2.

• direct-execution: Encodes a transaction using the direct execution encoding strategy. Does not require a private key.

Encoding Transactions

The commands accept the following options:

• --config_path: Path to the executor addresses configuration file (defaults to src/encoding/config/executor_addresses.json)

• --swapper-pk: Private key for signing approvals (required when direct_execution is false)

Example

Here's a complete example that encodes a swap from WETH to DAI using Uniswap V2 and the Tycho Router strategy with Permit2:

echo '{"sender":"0x1234567890123456789012345678901234567890","receiver":"0x1234567890123456789012345678901234567890","given_token":"0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2","given_amount":"1000000000000000000","checked_token":"0x6B175474E89094C44Da98b954EedeAC495271d0F","exact_out":false,"slippage":0.01,"expected_amount":"1000000000000000000","checked_amount":"990000000000000000","router_address":"0xaa820C29648D5EA543d712cC928377Bd7206a0E7","swaps":[{"component":{"id":"0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640","protocol_system":"uniswap_v2","protocol_type_name":"UniswapV2Pool","chain":"ethereum","tokens":["0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"],"contract_ids":["0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D"],"static_attributes":{"factory":"0x5c69bee701ef814a2b6a3edd4b1652cb9cc5aa6f"},"change":"Update","creation_tx":"0x0000000000000000000000000000000000000000000000000000000000000000","created_at":"2024-02-28T12:00:00"},"token_in":"0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2","token_out":"0x6B175474E89094C44Da98b954EedeAC495271d0F","split":0.0}],"direct_execution":true}' | tycho-encode tycho-router-permit2 --swapper-pk 0x123456789abcdef123456789abcdef123456789abcdef123456789abcdef1234