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.

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.

Protocols Supporting Consecutive Swap Optimizations

As described in the Swap Group section in our solver encoding docs, our swap strategies support 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 SwapStrategy level as a single executor call.

Depending on the index of the swap in the swap group, the executor 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).

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.

Deployment 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.