Execution

To integrate a new protocol into Tycho, you need to implement two key components:

1. SwapEncoder (Rust struct) – Handles swap encoding.

2. Executor (Solidity contract) – Executes the swap on-chain.

See more about our code architecture here.

Main Encoder Interface

Each new protocol requires a dedicated SwapEncoder that implements the SwapEncoder trait. This trait defines how swaps for the protocol are encoded into calldata.

fn encode_swap(
    &self,
    swap: Swap,
    encoding_context: EncodingContext,
) -> Result<Vec<u8>, EncodingError>;

This function encodes a swap and its relevant context information into calldata that is compatible with the Executor contract. The output of the SwapEncoder is the input of the Executor (see next section). See current implementations here.

Protocols Supporting Consecutive Swap Optimizations

As described in the Swap Group section, our encoding supports protocols which save token transfers between consecutive swaps using systems such as flash accounting. In such cases, as shown in the diagram below using Uniswap V4 as an example, the SwapEncoder is still only in charge of encoding a single swap. These swaps will then be concatenated at the StrategyEncoder level as a single executor call.

Depending on the index of the swap in the swap group, the encoder may be responsible for adding additional information which is not necessary in other swaps of the sequence (see the first swap in the diagram below).

Diagram representing swap groups

Output of a SwapEncoder for a group swap

Main Swap Interface

Every integrated protocol requires its own swap executor contract. This contract must conform to the IExecutor interface, allowing it to interact with the protocol and perform swaps. See currently implemented executors here.

It has the main method:

function swap(uint256 givenAmount, bytes calldata data)
    external
    payable
    returns (uint256 calculatedAmount)
{

This function:

• Accepts the input amount (givenAmount).

• Processes the swap using the provided calldata (data) which is the output of the SwapEncoder.

• Returns the final output amount (calculatedAmount).

Ensure that the implementation supports transferring received tokens to a designated receiver address, either within the swap function or through an additional transfer step.

If the protocol requires token approvals (allowances) before swaps can occur, manage these approvals within the implementation to ensure smooth execution of the swap.

Make sure to have an integration test that uses the calldata from the SwapEncoder as input. To do this, use the helper functions write_calldata_to_file() in encoding and loadCallDataFromFile() in execution. The first function writes the generated calldata into a calldata.txt file and the latter function reads from it.

Callbacks

Some protocols require a callback during swap execution. In these cases, the executor contract must inherit from ICallback and implement the necessary callback functions.

Required Methods

function handleCallback(
    bytes calldata data
) external returns (bytes memory result);

function verifyCallback(bytes calldata data) external view;

• handleCallback: The main entry point for handling callbacks.

• verifyCallback: Should be called within handleCallback to ensure that the msg.sender is a valid pool from the expected protocol.

Token Transfers

The Executor contracts manage token transfers between the user, protocols, and the Tycho Router. The only exception is when unwrapping WETH to ETH after a swap—in this case, the router performs the final transfer to the receiver.

The TychoRouter architecture optimizes token transfers and reduces gas costs during both single and sequential swaps. Whenever possible:

• The executor transfers input tokens directly from the user to the target protocol.

• The executor instructs the protocol to send output tokens directly to the next protocol in the swap sequence.

• For the final swap in a sequence, the protocol sends output tokens directly to the user.

Each executor inherits from the RestrictTransferFrom contract, which enables flexible and safe transfer logic. During encoding, the executor receives instructions specifying one of the following transfer types:

Transfer Type	Description
TRANSFER_FROM	Transfers tokens from the user's wallet into the TychoRouter or into the pool. It can use permit2 or normal token transfers.
TRANSFER	Assumes funds are already in the TychoRouter and transfers tokens into the pool
NONE	Assumes tokens are already in place for the swap; no transfer action is taken.

Two key constants are used in encoding to configure protocol-specific behavior:

Constant	Description
IN_TRANSFER_REQUIRED_PROTOCOLS	A list of protocols that require tokens to be transferred into the pool prior to swapping. These protocols do not perform a transferFrom during the swap themselves, and therefore require tokens to be transferred beforehand or during a callback.
CALLBACK_CONSTRAINED_PROTOCOLS	Protocols that require owed tokens to be transferred during a callback. In these cases, tokens cannot be transferred directly from the previous pool before the current swap begins.

Deploying and Whitelisting

Once your implementation is approved:

1. Deploy the executor contract on the appropriate network.

2. Contact us to whitelist the new executor address on our main router contract.

3. Update the configuration by adding the new executor address to executor_addresses.json and register the SwapEncoder within the SwapEncoderBuilder .

By following these steps, your protocol will be fully integrated with Tycho, enabling it to execute swaps seamlessly.