Tycho is free and open source

Tycho is, and always will be, free software, open source, and MIT licensed.

Free hosted indexer: Today, we host a free indexer for each chain, and we aim to maintain this indefinitely. If this ever changes, you will know at least 3 months ahead of time and have enough time to host your own indexer.

Indexer Redundancy

We are working with independent third parties to host additional indexers, both free and paid – to add redundancy to our indexer.

Tycho's Financial Model

Tycho finances development and maintenance through:

• Grants: Tycho receives grants from chains, DEXs, and others that benefit from the flow that Tycho brings.

• Tools built on Tycho: Useful tooling built on Tycho with a fee model (Coming soon).

What is Tycho?

Tycho is an open-source interface to on-chain liquidity. Tycho

• Indexes DEX protocol state for you with low latency,

Tycho is a community project that helps DEXs and Solvers coordinate.

What you can contribute

A quick overview, there are three ways to contribute to Tycho:

• Pick an issue: Find issues to contribute to in the – or propose an issue for a new feature.

In some cases, the community sponsors a bounty.

Specifically for:

• DEX Integrations: Some DEXs can't integrate themselves - and instead sponsor a bounty for the community.

• Orderflow integrations: Tools that want to use Tycho in their router.

• Tycho X Projects: Teams can also sponsor bounties for Tycho X projects.

How bounties work

• Cumulative Bounties: Several parties can sponsor and cumulate a bounty for the same issue.

• Single winner: Bounties are, unless specified otherwise, awarded in full to the first team that satisfies the requirements.

• Core Maintainer Support: Tycho maintainers will support every team working on a bounty. Incl. guidance, PR reviews, and final assessment.

• Award of a Bounty

Steps

• Discover a bounty: Find current open bounties in the – .

• Reach out: Reach out to Tycho maintainers at or dm if you plan to work on a bounty.

• Submit: Submit your work in a PR and notify maintainers.

• Review & Award: After a successful review by the three assessors, maintainers will merge the PR and payout the bounty. (any merged PR automatically qualifies for the bounty.)

Open Bounties

Find the list of open bounties here:

Tycho indexes on-chain liquidity, with a current focus on token swaps. Future development can include other liquidity provisioning, lending, and derivatives.

The DeFi Fragmentation Challenge

The rapid innovation in DeFi protocols has created a fragmented ecosystem without standardized interfaces for fundamental operations like swaps, liquidity provisioning, etc.

Tycho aims to provide a standardized interface across those operations.

With a focus on fast local simulations on top of the latest known state of the chain and settlements through tycho-execution.

Tycho Fellows are Solvers, Searchers, and Market Makers who work with the Propeller Foundation to bring all DeFi liquidity (across chains, pools, and tokens) to all traders.

For Solvers & Searchers

Benefits as a Tycho Fellow

How to swap on-chain with Tycho. This quickstart will help you:

• Fetch real-time market data from Tycho Indexer.

• Simulate swaps between token pairs. This lets you calculate spot prices and output amounts using Tycho Simulation.

• Encode the best trade for given token pairs.

If protocols use factories to deploy components, a common pattern used during indexing is to detect the creation of these new components and store their contract addresses to track them downstream. Later, you might need to emit balance and state changes based on the current set of tracked components.

Implementation Steps

Tycho exposes data through two mechanisms, the RPC and the stream. The RPC provides you access to static data, like the state of a component at a given block or extended information about the tokens it has found. For streaming data, we recommend using the . This guide documents the RPC interfaces.

Token Information

Tycho stream provides only the token addresses that Protocol Components use. If you require more token information, you can request using 's endpoint. This service allows filtering by both quality and activity.

is a library to help you integrate liquidity layer protocols (DEXs, Staking, Lending, etc.) into Tycho.

Integration Process

To integrate with Tycho, you need three components:

1. Indexing: You must provide the protocol state/data needed for simulation and execution.

Tycho Indexer gives you a low-latency, reorg-aware stream of all attributes you need to simulate swaps over DEX and other onchain liquidity.

Native and VM indexing

Tycho can track protocols in two ways:

• For Native Simulation

In some cases, you may need to create custom intermediate protobuf messages, especially when facilitating communication between Substreams handler modules or storing additional data in stores.

Place these protobuf files within your Substreams package, such as ./substreams/ethereum-template/proto/custom-messages.proto. Be sure to link them in the substreams.yaml file. For more details, refer to the substreams or review the official Substreams example integration.

Tracking balances is complex if only relative values are available. If the protocol provides absolute balances (e.g., through logs), you can skip this section and simply emit the absolute balances.

To derive absolute balances from relative values, you’ll need to aggregate by component and token, ensuring that balance changes are tracked at the transaction level within each block.

Implementation Steps:

1. Index relative balance changes

To accurately process each block and report balance changes, implement a handler that returns the BlockBalanceDeltas struct. Each BalanceDelta for a component-token pair must be assigned a strictly increasing ordinal to preserve transaction-level integrity. Incorrect ordinal sequencing can lead to inaccurate balance aggregation.

Example interface for a handler that uses an integer, loaded from a store to indicate if a specific address is a component:

Use the tycho_substream::balances::extract_balance_deltas_from_tx function from our Substreams SDK to extract BalanceDelta data from ERC20 Transfer events for a given transaction, as in the .

2. Aggregate balances with an additive store

To efficiently convert BlockBalanceDeltas messages into absolute values while preserving transaction granularity, use the StoreAddBigInt type with a store module. The tycho_substream::balances::store_balance_changes helper function simplifies this task.

Typical usage of this function:

3. Combine absolute values with component and address

Finally, associate absolute balances with their corresponding transaction, component, and token. Use the tycho_substream::balances::aggregate_balances_changes helper function for the final aggregation step. This function outputs BalanceChange structs for each transaction, which can then be integrated into map_protocol_changes to retrieve absolute balance changes per transaction.

Example usage:

Each step ensures accurate tracking of balance changes, making it possible to reflect absolute values for components and tokens reliably.

To add support for a new RFQ provider in Tycho, you’ll need to implement a client, a state, and the logic to encode and execute trades.

The state, encoding, and execution logic for RFQs follow the same structure as on-chain protocol integrations. See our simulation and execution guides for details.

We recommend using the existing Bebop integration as a reference.

RFQClient

Each RFQ protocol must implement the RFQClient trait:

Responsibilities:

• stream: Connects to the RFQ provider and emits real-time indicative price updates.

• request_binding_quote: Sends an HTTP request to fetch a binding quote for a specific swap.

You’ll also need to provide a builder to configure and construct your client, similar to BebopClientBuilder.

State

Each provider must define a state object that represents a full snapshot of their indicative prices.

This state must implement:

• ProtocolSim for simulation

• TryFromWithBlock to decode incoming messages into a usable state

Details on how to implement these can be found .

Encoder + Executor

To support execution, implement:

• Encoder: Encodes the calldata to execute a swap on the RFQ via the Tycho Router. Be sure to request the binding quote here.

• Executor: Executes the swap

For more see .

This allows the RFQ to be used in hybrid routes and benefit from Tycho’s execution optimizations.

The following diagram summarizes the code architecture:

Encoding

The TychoRouterEncoder and TychoExecutorEncoder are responsible for validating the solutions of orders and providing you with a list of transactions that you must execute against the TychoRouter or Executors.

The TychoRouterEncoder uses a StrategyEncoder that it choses automatically depending on the solution (see more about strategies ).

Internally, both encoders choose the appropriate SwapEncoder(s) to encode the individual swaps, which depend on the protocols used in the solution.

Execution

The TychoRouter calls one or more Executors (corresponding with the output of the SwapEncoders) to interact with the correct protocol and perform each swap of the solution. The TychoRouter optionally verifies that the user receives a minimum amount of the output token.

If you select the ExecutorStrategyEncoder during setup, you must execute the outputted calldata directly against the Executor which corresponds to the solution’s swap’s protocol. Beware that you are responsible for performing any necessary output amount checks. This strategy is useful if you want to call Tycho executors through your own router. For more information direct execution, see .

Local Development

Changing Rust Code

Please make sure that the following commands pass if you have changed the code:

We are using the stable toolchain for building and testing, but the nightly toolchain for formatting and linting, as it allows us to use the latest features of rustfmt and clippy.

If you are working in VSCode, we recommend you install the extension, and use the following VSCode user settings:

Changing Solidity code

Setup

Install foudryup and foundry

Running tests

Code formatting

Assembly

Please minimize use of assembly for security reasons.

Contract Analysis

We use to detect any potential vulnerabilities in our contracts.

To run locally, simply install Slither in your conda env and run it inside the foundry directory.

Creating a Pull Request

We use as our convention for formatting commit messages and PR titles.

Tycho Indexer

Metrics

Install Rust

Install . You can do so with the following command:

Install Substreams

You can do so with any of the following:

Once you have the calldata from , you can execute your trade in one of two ways:

1. Via the Tycho Router – Execute trades through our audited router for seamless execution.

2. Directly to the Executor – Bypass the Tycho Router and execute the trade using your own router.

Some best practices we encourage on all integrations are:

• Clear Documentation: Write clear, thorough comments. Good documentation:

  • Helps reviewers understand your logic and provide better feedback

  • Serves as a guide for future developers who may adapt your solutions

Sometimes the balances a component uses is stored on a contract that is not a dedicated single pool contract. During Tycho VM simulations, token contracts are mocked and any balances checked or used during a swap need to be overwritten for a simulation to succeed. Default behavior is for the component balances reported to be used to overwrite the pool contract balances. This assumes 2 things: there is a one-to-one relationship between contracts and components, and the hex-encoded contract address serves as the component ID.

If a protocol deviates from this assumption, the balances for each appropriate contract needs to be tracked for that contract. All contracts that have their balances checked/accessed during a simulation need to be tracked in this way.

Implementation Steps:

Tycho Execution provides tools for encoding and executing swaps against Tycho routers and protocol executors. It is divided into two main components:

• Encoding: A Rust crate that encodes swaps and generates calldata for execution.

• Executing: Solidity contracts for executing trades on-chain.

The source code for Tycho Execution is available . For a practical example of its usage, please refer to our .

This outlines the core entities and components that form the foundation of the Tycho system. Understanding these concepts is essential for working with or on the application effectively.

Entities

ProtocolSystem

With ProtocolSystems we usually refer to a DeFi protocol. A group of smart contracts that work collectively provide financial services to users. Each protocol typically contains:

• A single Extractor (see below)

• One or more ProtocolComponents

We model major versions of protocols as distinct entities. For example, Uniswap V2 and Uniswap V3 are separate ProtocolSystems.

Attributes:

• name: The protocols' identifier

• protocol_type: The category of protocol being indexed, currently pure organisational use.

  • name: The identifier of the protocol type

  • financial_type: The specific financial service provided:

Token

Tokens represent fungible tradeable assets on a blockchain. Users interact with protocols primarily to buy, sell, or provide liquidity for tokens. While ERC20 is the most common standard, Tycho supports other token types as well.

Tycho automatically detects and ingests new tokens when a ProtocolComponent using that token is ingested in the DB. Upon detection, we run test transactions to determine the token's behavior.

Attributes:

• Address: The blockchain address that uniquely identifies the token

• Decimals: Number of decimal places used to represent token values

• Symbol: Short human-readable identifier (e.g., ETH, USDC)

• Tax: Token transfer tax in basis points, averaged across simulated transfers

ProtocolComponent

ProtocolComponents represent specific operations that can be executed on token sets within a ProtocolSystem. Examples include liquidity pools in DEXes or lending markets in lending protocols.

A new ProtocolComponent is created whenever a new operation becomes available for a set of tokens such as when a new trading pair is deployed on a DEX.

Attributes:

• id: A unique identifier for the component

• protocol_system: The parent protocol system

• protocol_type_name: Subtype classification for filtering components

• chain: Blockchain where the component operates

Each component also has dynamic attributes that change over time and contain state required to simulate operations.

Indexer

The indexer subsystem processes blockchain data, maintains an up-to-date representation of entities and provides RPC and Websocket endpoints exposing those entities to clients.

Extractor

An Extractor processes incoming blockchain data, either at the block level or at shorter intervals (e.g. mempool data or partial blocks from builders).

The Extractor:

1. Pushes finalized state changes to permanent storage

2. Stores unfinalized data in system buffers (see ReorgBuffers below)

3. Performs basic validation, such as checking for the existence of related entities and verifying the connectedness of incoming data

4. Aggregates processed changes and broadcasts them to connected clients

Versioning

Tycho's persistence layer tracks state changes at the transaction level. This granular versioning enables future use cases such as:

• Replay changes transaction by transaction for backtesting

• Historical analysis of protocol behavior

The default storage backend (PostgreSQL) maintains versioned data up to a configurable time horizon. Older changes are pruned to conserve storage space and maintain query performance.

Reorg Buffer

ReorgBuffers store unfinalized blockchain state changes that haven't yet reached sufficient confirmation depth.

This approach allows Tycho to:

1. Respond to queries with the latest state by merging buffer data with permanent storage

2. Handle chain reorganizations by rolling back unconfirmed changes

3. Send precise correction messages to clients when previously reported states are invalidated

When a reorganization occurs, the system uses these buffers to calculate exactly what data needs correction, minimizing disruption to connected applications.

Dynamic Contract Indexing (DCI)

The DCI is an extractor extension designed to dynamically identify and index dependency contracts based on supplied tracing information. The DCI relies on an integrated protocol to provide the information with which it can analyse and detect contracts that require indexing.

On a successful trace, the DCI identifies all external contracts that were called, which storage slots were accessed for those contracts, and potential retriggers for the entry point. A retrigger is any contract storage slot that is flagged for its potential to influence a trace result. If a retrigger slot is updated, the trace is repeated. For all identified contracts, the code and relevant storage is fetched at the current block. Thereafter, updates for those contracts are extracted from the block messages themselves.

Simulation

The simulation library allows clients to locally compute the outcome of potential operations without executing them on-chain, enabling efficient price discovery and impact analysis.

Virtual Machine (VM) vs Native (Custom)

Tycho offers two approaches for simulating protocol operations:

Virtual Machine (VM) Integration

• Uses the blockchain's VM to execute operations

• Requires a contract that adapts the protocol's interface to Tycho's interface

• Creates a minimal local blockchain view with only the necessary contract state

• Advantages:

Native Implementation

• Reimplements protocol operations directly in Rust code

• Compiles to optimized machine code for the target architecture

• May still access the VM if required, e.g. to simulate Uniswap V4 hooks

• Advantages:

Execution

Solution

The Solution represents a complete pathway for moving tokens through one or more protocols to fulfil a trade. It bridges the gap between finding the best trade route and actually executing it on-chain.

The flexible nature of Solutions allows them to represent simple single-hop swaps, sequential multi-hop trades, or split routes where a token amount is distributed across multiple pools simultaneously. You can see more about Solutions .

Transaction

A Transaction turns a Solution into actual blockchain instructions. It contains the specific data needed to execute your trade: which contract to call, what function to use, what parameters to pass, and how much native token to send.

This is the final product that you submit to the blockchain. It handles approvals, native token wrapping/unwrapping, and proper contract interactions so you don't have to. For more about Transactions, see .

Strategy

Strategies define how Solutions are translated into Transactions, offering different tradeoffs between complexity, gas efficiency, and security. They encapsulate the logic for how trades should be executed on-chain.

Tycho currently supports three distinct strategies for executing trades: Single, Sequential, and Split.

Before diving into these, it is useful to clarify a few terms:

• Solution / Trade: A complete plan to exchange token A for token B. This may involve routing through intermediate tokens, but it is conceptually treated as a single trade.

• Swap/Hop: An individual exchange between two tokens. A trade may consist of one or more swaps.

Single

The encoder uses the single strategy when a Solution has exactly one swap on one pool.

Sequential

The encoder uses the sequential strategy when your Solution has multiple sequential swaps, and no splits (e.g. A → B → C). Outputs from one are equal to the input to the next swap.

Split

With the Split strategy, you can encode the most advanced solutions: Trades that involve multiple swaps, where you split amounts either in parallel paths or within stages of a multi-hop route.

For more about split swaps, see .

A python package is available to ease integration into python-based projects. To install locally:

Setup Guide

Prerequisites

• Git

• Rust 1.84.0 or later

• Python 3.9 or above

Install the package

Understanding and using the Python Client

The Python client is a Python wrapper around our that enables interaction with the Tycho Indexer. It provides two main functionalities:

• Streaming Client: Python wrapper around for real-time data streaming

• RPC Client: Pure Python implementation for querying data

Streaming Implementation

The TychoStream class:

1. Locates the Rust binary (tycho-client-cli)

2. Spawns the binary as a subprocess

3. Configures it with parameters like URL, authentication, exchanges, and filters

4. Implements an async iterator pattern that:

Here's one example on how to use it:

RPC Client Implementation

The TychoRPCClient class:

• Makes HTTP requests to the Tycho RPC server

• Serializes Python objects to JSON

• Deserializes JSON responses to typed Pydantic models

• Handles blockchain-specific data types like HexBytes

Here's one example on how to use it to fetch tokens information (available at endpoint):

Cow Protocol

To solve orders on CoW Protocol, you'll need to prepare your solution following specific formatting requirements.

First, initialize the encoder:

Since you are not passing the swapper_pk, the TychoRouter will use a transferFrom to transfer the token in as opposed to using permit2.

When solving for CoW Protocol, you need to return a that contains a list of interactions to be executed in sequence.

To solve with the Tycho Router you only need one custom interaction where:

1. callData is the full encoded method calldata using the encoded solution returned from encoder.encode_solutions(...)

2. allowances is a list with one entry where the allowance for the token in and amount in is set for spender to be the Tycho Router. This is necessary for the transferFrom to work.

Uniswap X

To help you fill Uniswap X orders using Tycho, we provide an example contract. This contract is a starting point—you should adapt it to fit your use case.

The example contract:

• Inherits from IReactorCallback and implements execute and reactorCallback

• Calls the TychoRouter from reactorCallback to execute swaps

• Uses standard token approvals to allow

See how to encode the callbackData for TychoRouter .

For more on filling Uniswap X orders, see their and .

Other competition venues

For other venues, like 1inch Fusion, please contact us.

When to use the binary client

The binary client is recommended for 2 situations:

• For a quick setup, to consume data from Tycho Indexer direct on a terminal

• To consume data from Tycho Indexer on apps developed in languages where there isn't a native tycho client available (e.g: any languages apart from Rust and Python). For the supported languages, please check the or docs.

Installing Tycho-client

This guide provides two methods to install Tycho Client:

1. Install with Cargo (recommended for most users)

2. Download pre-built binaries from GitHub Releases

Method 1: Install with Cargo

Prerequisites

• Cargo

• Rust 1.84.0 or later

Method 2: Download from GitHub Releases

Step 1: Download the pre-built binary

For a simple, setup-free start, download the latest tycho-client binary release that matches your OS/architecture on .

Step 2: Extract the binary from the tar.gz

Open a terminal and navigate to the directory where the file was downloaded. Run the following command to extract the contents:

Step 3: Link the binary to a directory in your system's PATH (recommended):

Step 4: Verify Installation

You should see the Tycho Client version displayed. If you need more guidance, contact us via

Using Tycho Client

Running the client

Step 1: Setting up API Key

If you're connecting to our hosted service, please follow our to get an API Key. Once you have a key, export it using an environment variable

or use the command line flag

Step 2: Consume data from Tycho Indexer

Now, you're all set up!

Before consuming the data, you first need to choose which protocols you want to track. You can find a list of here. For example, to track the Uniswap V2 and V3 pools on Mainnet, with a minimum value locked of 100 ETH, run:

Or skip secure connections entirely with --no-tls for local setups [coming soon].

Debugging

Since all messages are sent directly to stdout in a single line, logs are saved to a file: ./logs/dev_logs.log. You can configure the directory with the --log-dir option.

Configuring the client

For more details on using the CLI and its parameters, run:

For extended explanation on how each parameter works, check our guide.

The rust crate provides a flexible library for developers to integrate Tycho’s real-time data into any Rust application.

Setup Guide

To use Tycho Client in Rust, add the following crates to your Cargo.toml:

Step 2: Use Tycho-client

From there it is easy to add a Tycho stream to your rust program like so:

You can also use the client to interact with Tycho RPC for fetching static information. For example, you can fetch tokens (available at endpoint) with the following:

In VM implementations, accurately identifying and extracting relevant contract changes is essential.

The tycho_substreams::contract::extract_contract_changes helper function simplifies this process significantly.

Factory protocols

In factory-based protocols, each contract typically corresponds to a unique component, allowing its hex-encoded address to serve as the component ID, provided there is a one-to-one relationship between contracts and components.

The example below shows how to use a component store to define a predicate. This predicate filters for contract addresses of interest:

Other protocols

For protocols where contracts aren't necessarily pools themselves, you'll need to identify specific contracts to track. These addresses can be:

1. Hard-coded (for single-chain implementations)

2. Configured via parameters in your file (for chain-agnostic implementations)

3. Read from the storage of a known contract (hardcoded or configured)

Here's how to extract changes for specific addresses using configuration parameters:

Our indexing integrations require a Substreams SPKG to transform raw blockchain data into structured data streams. These packages enable our indexing integrations to track protocol state changes with low latency.

What is Substreams?

Substreams is a new indexing technology that uses Rust modules to process blockchain data. An SPKG file contains the Rust modules, protobuf definitions, and a manifest, and runs on the Substreams server.

Learn more:

Integration Modes

VM Integration

VM integrations primarily track contract storage associated with the protocol’s behavior. Most integrations will likely use the VM method due to its relative simplicity, so this guide focuses on VM-based integrations.

It's important to know that simulations run in an empty VM, which is only loaded with the indexed contracts and storage. If your protocol calls external contracts during any simulation (swaps, price calculations, etc.), those contracts also have to be indexed. There are 2 approaches that can be used to index external contracts:

• Direct indexing on the substream package. This is where you index the external contract the same way you would index your own protocol's contract. A key limitation in Substreams to keep in mind is that you must witness a contract’s creation to access its full storage and index it.

• Using the DCI (Dynamic Contract Indexer). To be used if your protocol calls external contracts whose creation event cannot be witnessed within the Substreams package - for example: oracles deployed long before the protocol's initial block, or when which contract is called can be changed during the protocol's lifetime. Use of the DCI introduces indexing latency and should only be used if necessary.

Native Integration

Native integrations follow a similar approach, with one main difference: Instead of emitting changes in contract storage slots, they should emit values for all created and updated attributes relevant to the protocol’s behavior.

Understanding the Data Model

The Tycho Indexer ingests all data versioned by block and transaction. This approach maintains a low-latency feed. And it correctly handles chains that undergo reorgs. Here are the key requirements for the data emitted:

1. Each state change must include the transaction that caused it.

2. Each transaction must be paired with its corresponding block.

3. All changes must be absolute values (final state), not deltas.

Details of the data model that encodes these changes, transactions, and blocks in messages are available . These models facilitate communication between Substreams and the Tycho Indexer, and within Substreams modules. Tycho Indexer expects to receive a BlockChanges output from your Substreams package.

You must aggregate changes at the transaction level. Emitting BlockChanges with duplicate transactions in the changes attributes is an error.

Data Encoding

To ensure compatibility across blockchains, many data types are encoded as variable-length bytes. This flexible approach requires an informal interface so that consuming applications can interpret these bytes consistently:

• Integers: When encoding integers, particularly those representing balances, always use unsigned big-endian format. Multiple points within the system reference balances, so they must be consistently decoded along their entire journey.

• Strings: Use UTF-8 encoding for any string data stored as bytes.

• Attributes: Attribute encoding is variable and depends on specific use cases. But whenever possible, follow the encoding standards above for integers and strings.

Reserved Attributes

We reserve some attribute names for specific functions in our simulation process. Use these names only for their intended purposes. .

Changes of interest

Tycho Protocol Integrations should communicate the following changes:

1. New Protocol Components: Signify any newly added protocol components. For example, pools, pairs, or markets – anything that indicates you can execute a new operation using the protocol.

2. ERC20 Balances: For any contracts involved with the protocol, you should report balance changes in terms of absolute balances.

3. Protocol State Changes: For VM integrations, this typically involves reporting contract storage changes for all contracts whose state is accessible during a swap operation (except token contracts).

For a hands-on integration guide, see the following pages:

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

Substreams relies on witnessing contract creations to provide a contract's entire storage. Unless the system witnesses the creation and identifies at that point that the contract is relevant to the protocol, it cannot be indexed or used in simulations.

The Dynamic Contract Indexing (DCI) system is a Tycho feature that addresses this limitation by dynamically identifying and indexing dependency contracts - such as oracles and price feeds - whose creation events are not observable. This may be because:

• the contracts were created long before the protocol's first indexed block (startBlock on the substreams configuration file)

• the dependency is updatable and which contracts are called may change during the protocol's lifetime. For example: a protocol switches oracle provider.

Some protocol design choices follow a common pattern. Instructions on how to handle these cases are provided. Such cases include:

• [VM 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.

Certain attribute names are reserved exclusively for specific purposes. Please use them only for their intended applications. Attribute names are unique: if the same attribute is set twice, the value will be overwritten.

Static Attributes

The following attributes names are reserved and must be given using ProtocolComponent.static_att. These attributes MUST be immutable.

1. manual_updates

Description

Determines whether the component updates should be manually triggered using the update_marker state attribute. By default, updates occur automatically whenever there is a change indexed for any of the required contracts. For contracts with frequent changes, automatic updates may not be desirable. For instance, a change in Balancer Vault storage should only trigger updates for the specific pools affected by the change, rather than for all pools indiscriminately. The manual_updates field helps to control and prevent unnecessary updates in such cases.

If it's enable, updates on this component are only triggered by emitting an update_marker state attribute (described ).

Type

Set to [1u8]to enable manual updates.

Example Usage

2. pool_id

Description

The pool_id static attribute is used to specify the identifier of the pool when it differs from the ProtocolComponent.id. For example, Balancer pools have a component ID that corresponds to their contract address, and a separate pool ID used for registration on the Balancer Vault contract (needed for swaps and simulations).

Notice: In most of the cases, using ProtocolComponent.id is preferred over pool_id and pool_id should only be used if a special identifier is strictly necessary.

Type

This attribute value must be provided as a UTF-8 encoded string in bytes.

Example Usage

State Attributes

The following attributes names are reserved and must be given using EntityChanges. Unlike static attributes, state attributes are updatable.

1. stateless_contract_addr

Description

The stateless_contract_addr_{index} field specifies the address of a stateless contract required by the component. Stateless contracts are those where storage is not accessed for the calls made to it during swaps or simulations.

This is particularly useful in scenarios involving DELEGATECALL. If the contract's bytecode can be retrieved in Substreams, provide it using the stateless_contract_code attribute (see ).

Note: If no contract code is given, the consumer of the indexed protocol has to access a chain node to fetch the code. This is considered non-ideal and should be avoided where possible.

An index is used if multiple stateless contracts are needed. This index should start at 0 and increment by 1 for each additional stateless_contract_addr.

The value for stateless_contract_addr_{index} can be provided in two ways:

1. Direct Contract Address: A static contract address can be specified directly.

2. Dynamic Address Resolution: Alternatively, you can define a function or method that dynamically resolves and retrieves the stateless contract address at runtime. This can be particularly useful in complex contract architectures, such as those using a dynamic proxy pattern. It is important to note that the called contract must be indexed by the Substreams module.

Type

This attribute value must be provided as a UTF-8 encoded string in bytes.

Example Usage

1. Direct Contract Address

To specify a direct contract address:

2. Dynamic Address Resolution

To specify a function that dynamically resolves the address:

2. stateless_contract_code

Description

The stateless_contract_code_{index} field is used to specify the bytecode for a given stateless_contract_addr. The index used here must match with the index of the related address.

Type

This attribute value must be provided as bytes.

Example Usage

3. update_marker

Description

The update_marker field is used to indicate that a pool has changed, thereby triggering an update on the protocol component. This is particularly useful for when is enabled.

Type

Set to [1u8]to trigger an update.

Example Usage

4. balance_owner[deprecated]

Description

The balance_owner field specifies the address of the account that owns the protocol component tokens, when tokens are not owned by the protocol component itself or the multiple contracts are involved. This is particularly useful for protocols that use a vault, for example Balancer.

Type

This attribute value must be provided as bytes.

Example Usage

Ethereum

Currently, Tycho supports the following protocols:

Request for Quote (RFQ) protocols work differently from on-chain protocols. Instead of reading pool data from the chain, they fetch prices from off-chain market makers via WebSocket or API.

You ask for a quote for a specific trade size, and they return a price. Quotes can be:

• Indicative — estimated prices used for simulation.

• Binding — firm prices, valid for a short time, used at execution.

Tycho supports streaming, simulating, and executing RFQ quotes as part of multi-protocol swaps.

Tycho Simulation is a Rust crate that provides powerful tools for interacting with protocol states, calculating spot prices, and simulating token swaps.

The repository is available here.

Installation

The tycho-simulation package is available on Github.

To use the simulation tools with Ethereum Virtual Machine (EVM) chains, add the optional evm feature flag to your dependency configuration:

Add this to your project's Cargo.toml file.

Main Interface

All protocols implement the ProtocolSim trait (see definition ). It has the main methods:

Spot price

spot_price returns the pool's current marginal price.

Get amount out

get_amount_out simulates token swaps.

You receive a GetAmountOutResult , which is defined as follows:

new state allows you to, for example, simulate consecutive swaps in the same protocol.

Please refer to the of the ProtocolSim trait and its methods for more in-depth information.

Fee

fee returns the fee of the protocol as a ratio. For example if the fee is 1%, the value returned would be 0.01.

Get limits

get_limits returns a tuple containing the maximum amount in and out that can be traded between two tokens.

Swap to price

swap_to_price returns the amount of token_in required to move the pool's marginal price down to a target price, and the amount of token_out received. The target_price is denoted as token_out (numerator) per token_in (denominator) net of all fees.

Price represents a price as a rational fraction (numerator / denominator).

Trade represents a trade between two tokens at a given price on a pool.

Query supply

query_supply returns the maximum amount of token_out a pool can supply, and corresponding token_in demand, while respecting a minimum trade price. The target_price is denoted as token_out (numerator) per token_in (denominator) net of all fees.

Please refer to the of the ProtocolSim trait and its methods for more in-depth information.

Streaming Protocol States

To maintain up-to-date states of the protocols you wish to simulate over, you can use a Tycho Indexer stream. Such a stream can be set up in 2 easy steps:

Step 1: Fetch tokens

It is necessary to collect all tokens you are willing to support/swap over as this must be set on the stream builder in step 2. You can either set up custom logic to define this, or use the Tycho Indexer RPC to fetch and filter for tokens of interest. To simplify this, a util function called load_all_tokensis supplied and can be used as follows:

Step 2: Create a stream

You can use the to easily set up and manage multiple protocols within one stream. An example of creating such a stream with Uniswap V2 and Balancer V2 protocols is as follows:

Some protocols, such as Balancer V2 and Curve, require a pool filter to be defined to filter out unsupported pools. If a protocol needs a pool filter and the user does not provide one, a warning will be raised during the stream setup process.

The stream created emits Update messages which consist of:

• block number_or_timestamp- the block this update message refers to

• new_pairs- new components witnessed (either recently created or newly meeting filter criteria)

• removed_pairs- components no longer tracked (either deleted due to a reorg or no longer meeting filter criteria)

The first message received will contain states for all protocol components registered to. Thereafter, further block updates will only contain data for updated or new components.

Note: For efficiency, ProtocolSim states contain simulation-critical data only. Reference data such as protocol names and token information is provided in the ProtocolComponent objects within the new_pairs field. Consider maintaining a store of these components if you need this metadata.

For a full list of supported protocols and the simulation state implementations they use, see .

Example Use Case: Token Price Printer

You can find an example of a price printer .

Clone the repo, then run:

You will see a UI where you can select any pool, press enter, and simulate different trade amounts on the pool.

The program prints logs automatically to a file in the logs directory in the repo.

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.

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 .

If your protocol needs some specific constant addresses please add them in .

After implementing your SwapEncoder , you need to:

• Add your protocol with a placeholder address in: and

• Add your protocol in the .

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 be leveraging the RestrictTransferFrom contract. See currently implemented executors .

The IExecutor interface has the main method:

This function:

• Accepts the input amount (givenAmount). Note that the input amount is calculated at execution time and not during encoding. This is to account for possible slippage.

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

Callbacks

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

Required Methods

• 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 must inherit from the RestrictTransferFrom contract, which enables flexible and safe transfer logic. During encoding, the executor receives instructions specifying one of the following transfer types:

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

Include your protocol in these constants if necessary.

Testing

Each new integration must be thoroughly tested in both Rust and Solidity. This includes:

• Unit tests for the SwapEncoder in Rust

• Unit tests for the Executor in Solidity

• Two key integration tests to verify the full swap flow: SwapEncoder to Executor integration test and a full TychoRouter integration test