To enable simulations for a newly added protocol, it must first be integrated into the Tycho Simulation repository. Please submit a pull request to the repository to include it.

Native Integration

In order to add a new native protocol, you will need to complete the following high-level steps:

1. Create a protocol state struct that contains the state of the protocol, and implements the ProtocolSim trait (see ).

2. Create a tycho decoder for the protocol state: i.e. implement TryFromWithBlock for ComponentWithState to your new protocol state.

Each native protocol should have its own module under tycho-simulation/src/evm/protocol.

VM Integration

To create a VM integration, provide a manifest file and an implementation of the corresponding adapter interface. is a library to integrate DEXs and other onchain liquidity protocols into Tycho.

Example Implementations

The following exchanges are integrated with the VM approach:

• Balancer V2 (see code )

Install prerequisites

1. Install , start by downloading and installing the Foundry installer:

   then start a new terminal session and run

2. Clone the Tycho Protocol SDK:

3. Install dependencies:

Understanding the ISwapAdapter

Read the documentation of the interface. It describes the functions that need to be implemented and the manifest file.

Additionally, read through the docstring of the interface and the interface, which defines the data types and errors the adapter interface uses. You can also generate the documentation locally and look at the generated documentation in the ./docs folder:

Implementing the ISwapAdapter interface

Your integration should be in a separate directory in the evm/src folder. Start by cloning the template directory:

Implement the ISwapAdapter interface in the ./evm/src/<your-adapter-name>.sol file. See Balancer V2 implementation for reference.

Testing your implementation

1. Set up test files:

   • Copy evm/test/TemplateSwapAdapter.t.sol

   • Rename to <your-adapter-name>.t.sol

Add implementation to Tycho simulation

Once you have the swap adapter implemented for the new protocol, you will need to:

1. Generate the adapter runtime file by running the script in our SDK repository with the proper input parameters. For example, in order to build the Balancer V2 runtime, the following command can be run:\

2. Add the associated adapter runtime file to tycho-simulations/src/protocol/vm/assets. Make sure to name the file according to the protocol name used by Tycho Indexer in the following format: <Protocol><Version>Adapter.evm.runtime. For example: vm:balancer_v2 will be BalancerV2Adapter.evm.runtime. Following this naming format is important as we use an automated name resolution for these files.

Filtering

If your implementation does not support all pools indexed for a protocol, you can create a filter function to handle this. This filter can then be used when registering an exchange in the ProtocolStreamBuilder. See for example implementations.

Swap/Exchange Protocol Guide

Implementing the Protocol

To integrate an EVM exchange protocol:

1. Implement the interface.

2. Create a manifest file summarizing the protocol's metadata.

The Manifest File

The manifest file contains author information and additional static details about the protocol and its testing. Here's a list of all valid keys:

Key Functions

Price (optional)

Calculates marginal prices for specified amounts.

• Return marginal prices in buyToken/sellToken units.

• Include all protocol fees (use minimum fee for dynamic fees).

• If you don't implement this function, flag it accordingly in capabilities and make it revert using the NotImplemented error.

• While optional, we highly recommend implementing this function. If unavailable, we'll numerically estimate the price function from the swap function.

Swap

Simulates token swapping on a given pool.

• Execute the swap and change the VM state accordingly.

• Include a gas usage estimate for each amount (use gasleft() function).

• Return a Trade struct with a price attribute containing price(specifiedAmount).

GetLimits

Retrieves token trading limits.

• Return the maximum tradeable amount for each token.

• The limit is reached when the change in received amounts is zero or close to zero.

• Overestimate the limit if in doubt.

• Ensure the swap function doesn't error with LimitExceeded for amounts below the limit.

getCapabilities

Retrieves pool capabilities.

getTokens (optional)

Retrieves tokens for a given pool.

• We mainly use this for testing, as it's redundant with the required substreams implementation.

getPoolIds (optional)

Retrieves a range of pool IDs.

• We mainly use this for testing. It's okay not to return all available pools here.

• This function helps us test against the substreams implementation.

• If you implement it, it saves us time writing custom tests.