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.

Key Challenges in Liquidity Indexing

Before Tycho, you might face the following issues if you want to settle on onchain protocols:

Technical Complexity

• Rewrite protocol-specific mathematics in your application programming language to simulate fast locally.

• Develop protocol-specific indexing to supply data for local simulations.

• Watch and filter out user-created token pairs with unusual or malicious behavior.

Blockchain-Specific Issues

• Chain reorganizations ("reorgs") that alter transaction history must be handled with care.

• Block propagation delays caused by peer-to-peer network topology and geographic distribution.

• Continuous maintenance of node infrastructure, such as updating client versions (especially during hard forks), updating storage space, etc.

Push-Based Architecture

Problems with Traditional RPC Polling

Traditional indexers rely on node client RPC interfaces, which have significant limitations:

• Data must be requested from nodes, introducing latency and potential for error.

• Multiple requests are often needed to assemble a complete view of the data.

• Complex query contracts may be required for comprehensive data extraction (e.g., to get all Uniswap V3 ticks) whose execution adds additional latency to data retrieval.

The Streaming Solution

Tycho adopts a fundamentally different approach:

• Data is pushed/streamed as a block is processed by the node client.

• Current implementation leverages Substreams as the primary data source.

• Alternative data sources can be integrated if they provide comparable richness.

User Experience Philosophy

Abstraction by Default

• Non-blockchain-native users shouldn't need to understand chain-specific concepts.

• Reorgs and optimistic state changes remain invisible to users by default.

• Users perceive only that state has changed, regardless of underlying mechanism.

Optional Transparency

• Advanced users can access detailed information about state changes when needed.

• Granular visibility allows inspection of upcoming state changes.

• Applications can track specific liquidity pair changes for specialized use cases.

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

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.

• Build an app: Build an app using Tycho. Use the as an inspiration.

How to get started

Whichever way you choose to contribute – Tycho maintainers and the community are here to help you. Before you get started:

1. Join – our telegram group for Tycho builders.

2. Reach out to - so that he can support you and ensure someone else isn't already working on the same project.

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

• Early Access to DEXs: Be first to access new DEXs on our development endpoint before they goes live in production.

• Shape the future of Tycho: Give input and prioritize new features.

Requirements

As a Tycho Fellow, you need to:

• Integrate new DEXs: Test and integrate new DEXs as soon as they are live.

• Settle Volume on Tycho: Settle more than > 1mio / week on Tycho Router.

If you want to become a Tycho Fellow please contact @tanay_j on Telegram.

For DEXs, Auctions and Chains

Tycho Fellows can connect your DEX to most orderflow in defi.

For DEXs: Tycho Fellows integrate with all orderflow auctions and can quickly connect your DEX to most defi orderflow.

For Auctions: Tycho Fellows can serve as a competitive and diverse set of solvers in your auction. Get top quotes, competitive solutions, and optimize revenue from day 0.

For Chains: Help bring orderflow auctions and their users to your chain with the help of the solvers that power them.

Write us (@tanay_j on tg) before you launch and we'll help you start ahead.

Wrapping and unwrapping use a dedicated WETH executor, the same mechanism as any other protocol swap. The encoding library automatically inserts WETH wrap/unwrap swaps wherever an ETH/WETH bridge is needed:

• At the start: if token_in is ETH but the first swap expects WETH, a wrapping swap is prepended.

• Between swaps: if one swap outputs ETH and the next expects WETH (or vice versa), a bridging swap is inserted.

• At the end: if the last swap outputs ETH but token_out is WETH (or vice versa), an unwrapping swap is appended.

Set token_in and token_out to the actual tokens the user holds and expects to receive (native ETH or WETH), and the encoder handles the rest.

This approach supports wrapping/unwrapping at any position in the swap path (not just first and last) and works with protocols like Uniswap V4 that support native ETH swaps directly.

Address Convention

Tycho reserves the zero address (0x0000000000000000000000000000000000000000) to represent the native token across all chains.

Some protocols use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE or other sentinel addresses for native tokens. If your protocol follows this pattern, you must normalize these addresses to the zero address in your Substreams package.

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

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)

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

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

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

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

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.

Solutions can represent single-hop swaps, sequential multi-hop trades, or split routes where a token amount is distributed across multiple pools. See more about Solutions .

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 .

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 Tycho Client. 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 Tycho RPC's Tycho RPCendpoint. This service allows filtering by both quality and activity.

Quality Token Quality Ratings

The quality rating system helps you quickly assess token's specific properties:

• 100: Normal ERC-20 Token behavior

• 75: Rebasing token

• 50: Fee-on-transfer token

API Documentation

This section documents Tycho's RPC API. Full swagger docs are available at:

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.

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:

Install Rust

Install . You can do so with the following command:

Install Substreams

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:

Once you have calldata from , you can execute your trade via the Tycho Router.

Tycho Router

Send the encoded calldata to the TychoRouter (see contract addresses ). Setup depends on the user_transfer_type in your Solution:

The following diagram summarizes the code architecture:

Encoding

The TychoRouterEncoder validates solutions and produces a list of transactions to execute against the TychoRouter

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 manifest documentation or review the official Substreams UniswapV2 example integration.

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.

• Simulate or execute the best trade using Tycho Execution.

Run the Quickstart

Clone the ; here's code.

Run the quickstart with execution using the following commands:

If you don't have an RPC URL, here are some public ones for , , and .

The PRIVATE_KEY environment variable is unnecessary if you want to run the quickstart without simulation or execution.

What it does

The quickstart fetches all protocol states. Then it returns the best amount out (best price) for a given token pair (by default, 10 USDC to WETH).

Additionally, it returns calldata to execute the swap on this pool with the Tycho Router.

You should see an output like this:

If you want to see results for a different token, amount, or chain, or minimum TVL, you can set additional flags:

This example would seek the best swap for 10 USDC -> WETH on Base.

The TVL filter means we will only look for snapshot data for pools with TVL greater than the specified threshold (in ETH). Its default is 1000 ETH to limit the data you pull.

Logs

If you want to see all the Tycho Indexer and Simulation logs, run with RUST_LOG=info:

How the quickstart works

The quickstart shows you how to:

1. Set up and load necessary data, like available tokens.

2. Connect to the Tycho Indexer to fetch on-chain protocol data (e.g., Uniswap V2, Balancer V2) and build a Protocol Stream that streams updates, like new pools and states, in real-time.

3. Simulate swaps on all available pools for a specified pair (e.g., USDC, WETH), and print out the most WETH available for 10 USDC.

1. Set up

Run Tycho Indexer by setting up the following environment variables:

• TYCHO_URL (by default "tycho-beta.propellerheads.xyz")

• TYCHO_API_KEY key

• PRIVATE_KEY if you wish to execute the swap against the Tycho Router

The Indexer stream or the Simulation does not manage tokens; you manage them yourself.

To simplify this, gets all current token information from Tycho Indexer RPC for you.

2. Connect to Tycho Indexer

The protocol stream connects to Tycho Indexer to fetch the real-time state of protocols.

Here, you only subscribe to Uniswap V2 and Balancer V2. To include additional protocols like Uniswap V3, simply add:

For a full list of supported protocols and which simulation state (like UniswapV3State) they use, see .

Note: The protocol stream supplies all protocol states in the first BlockUpdate object. All subsequent BlockUpdates contain only new and changed protocol states (i.e., deltas).

3. Simulate swap

get_best_swap uses Tycho Simulation to simulate swaps and calculate buy amounts. We inspect all protocols updated in the current block (i.e., protocols with balance changes).

a. Simulating token swaps

result is a GetAmountOutResult containing information on amount out, gas cost, and the protocol's new state. So you could follow your current swap with another.

By inspecting each of the amount outs, you can then choose the protocol component with the highest amount out.

4. Encode a swap

After choosing the best swap, you can use Tycho Execution to encode it.

a. Create a solution object

Now you know the best protocol component (i.e., pool), you can compute a minimum amount out. And you can put the swap into the expected input format for your encoder.

The minimum amount out is a very important parameter to set in Tycho Execution. The value acts as a guardrail and protects your funds during execution against MEV. This quickstart accepts a slippage of 0.25% over the simulated amount out.

After this, you can create the Swap and Solution objects. For more info about the Swap and Solution models, see .

b. Encode solution

5. Encode full method calldata

You need to build the full calldata for the router. Tycho handles the swap encoding, but you control the full input to the router method. This quickstart provides helper functions (encode_tycho_router_call and sign_permit)

Use it as follows:

6. Simulate or execute the best swap

This step allows you to test or perform real transactions based on the best available swap options. For this step, you need to pass your wallet's private key in the run command. Handle it securely and never expose it publicly.

When you provide your private key, the quickstart will check your token balances and display them before showing you options:

If you don't have enough tokens for the swap, you'll see a warning:

You'll then encounter the following prompt:

You have three options:

1. Simulate the swap: Tests the swap without executing it on-chain. It simulates an approval (for permit2) and a swap transaction on the node. You'll see something like this:

If status is false, the simulation has failed. You can print the full simulation output for detailed failure information.

1. Execute the swap: Performs the swap on-chain using your real funds. The process performs an approval (for permit2) and a swap transaction. You'll receive transaction hashes and statuses like this:

After a successful execution, the program will exit. If the transaction fails, the program continues to stream new blocks.

1. Skip this swap: Ignores this swap. Then the program resumes listening for blocks.

Recap

In this quickstart, you explored how to use Tycho to:

1. Connect to the Tycho Indexer: Retrieve real-time protocol data filtered by TVL.

2. Fetch Token and Pool Data: Load all token details and process protocol updates.

3. Simulate Token Swaps: Compute the output amount, gas cost, and updated protocol state for a swap.

What's next?

• Integrate with your Solver: Add Tycho pool liquidity to your solver, using this .

• Learn more about and the datatypes necessary to encode an execution against a Tycho router or executor.

• Learn more about : Explore custom filters, protocol-specific simulations, and state transitions.

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

• Factory contracts

• Tracking contract storage [VM implementations]

Factory contracts

A common protocol design is to use factories to deploy components. In this case it is recommended to detect the creation of these components and store their contract addresses (an potentially other metadata) to track them for use later in the module. See

Tracking contract storage

For VM implementations it is essential that the contract code and storage of all involved contracts are tracked. If these contracts are known, static, and their creation event is observable by the substreams package (occurs after the start block of the package), they can be indexed by the substream package with some helpful utils: see .

If these contracts need to be dynamically determined or their creation event is not observable, instead see below:

Using the Dynamic Contract Indexer (DCI)

For contracts that cannot be statically determined at time of integration or their creation events are not observable by the substreams package, Dynamic Contract Indexer (DCI) support is provided. Keep in mind using this feature adds indexing latency and should be avoided if possible.

The DCI allows you to specify external contract call information, which it will use to trace and identify all contract dependencies. It then automates the indexing of those identified contracts and their relevant storage slots. See.

Using relative component balances

For some protocols, absolute component balances are not easily obtainable. Instead, balance deltas/changes are observed. Since absolute balances are expected by Tycho, it is recommended to use a balance store to track current balances and apply deltas as the occur. See .

Vaults/Singleton contracts

For protocols that store balances in an a-typical way (not on dedicated pool contracts), a special approach to balance tracking must be used. See.

When a contract change is indexed, consumers of the indexed data typically trigger recalculating prices on all pools marked as associated with that contract (the contract is listed in the ProtocolComponent's contracts field). In the case where multiple components are linked to a single contract, such as a vault, this may cause excessive and unnecessary simulations on components that are unaffected by a specific change on the linked contract. In this case it is recommended to use 'manual update' triggers. See for more details.

Persisting data between modules

It is often the case where data needs to be persisted between modules in your substream package. This may be because components and their metadata (such as their tokens, or pool type) are needed when handling state changes downstream, or could be because the protocol reports relative changes instead of absolute values and the relative changes must be compounded to reach an absolute value. For this, substream and are recommended.

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.

Tycho Execution provides tools for encoding and executing swaps against Tycho Router 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 .

Token transfers

You can transfer tokens in one of three ways with Tycho Execution:

• Permit2

• Standard ERC20 Approvals

• Using Vault funds

See how to change between these options when encoding .

Permit2

Tycho Execution supports Permit2 for token approvals. Before executing a swap via our router, you must approve the Permit2 contract for the specified token and amount. This ensures the router has the necessary permissions to execute trades on your behalf.

Permit2 handling is not part of the encoding step. You are responsible for creating and signing the permit yourself. The Permit2 utility struct is publicly exported from the encoding crate, so you can use it to build the PermitSingle and obtain the data needed for signing.

For more details on Permit2 and how to use it, see the .

Standard ERC20 Approvals

Tycho also supports traditional ERC20 approvals. In this model, you explicitly call approve on the token contract to grant the router permission to transfer tokens on your behalf. This is widely supported and may be preferred in environments where Permit2 is not yet available.

Using the Vault

The TychoRouter includes a built-in vault () that lets you deposit, hold, and withdraw tokens directly in the router contract. The vault tracks per-user balances, so your tokens are only accessible by you.

The router draws from your deposited balance instead of performing a transferFrom on your wallet. This saves gas (no approval or external transfer needed) and lets you use fees, proceeds from previous trades, or pre-positioned liquidity directly.

Fees earned through the fee-taking system are automatically credited to the fee receiver's vault balance, making them immediately available for future swaps or withdrawals.

More on the Vault .

Security and Audits

The Tycho Router V2 has been audited by . Past audits are .

If you discover potential security issues or have suggestions for improvements, please reach out through our official channels.

The TychoRouter V3 includes an integrated vault built on the ERC6909 multi-token standard. This replaces the "direct transfer" pattern from V2, where tokens sent to the router risked being lost.

How It Works

The vault uses dual storage:

• Transient storage tracks balance changes ("deltas") during a swap. Credits are recorded when tokens arrive at the router; debits when they leave. This is cheap (~100 gas per operation) and automatically clears at the end of each transaction.

• Persistent storage (ERC6909 balances) holds final user balances across transactions. These are updated only after a swap is fully validated.

At the end of every swap, _finalizeBalances validates the transient state before committing:

• For wallet-funded swaps: all deltas must net to zero.

• For vault-funded swaps: at most one negative delta is allowed (the input token), which is burned from the user's vault balance.

This catches encoding errors and balance mismatches before any persistent state changes.

Depositing and Withdrawing

Tokens in the vault can be used for swaps by setting user_transfer_type: UseVaultsFunds in the . They can be withdrawn at any time.

Crediting Output to the Vault

By default, output tokens are sent to the receiver address after a swap. If you set the receiver to the TychoRouter address, the output tokens are credited to the caller's vault balance instead of being transferred out.

This works with all swap types — single, sequential, and split — and with both wallet-funded and vault-funded swaps.

This enables vault rebalancing: converting one token to another without tokens leaving the contract. For example, a solver holding WETH in the vault can convert it to USDC in a single transaction, with both the debit and credit happening within the vault.

It also supports cyclical arbitrage, where you route through multiple pools and end up with more of the starting token, all settled within the vault.

Why a Vault?

The vault serves three purposes:

1. Gas savings for repeat users. Solvers and market makers can keep tokens in the contract, avoiding repeated approval and transfer costs.

2. In-contract rebalancing. Convert between tokens in the vault without additional ERC-20 transfers or approvals, since both input and output stay in the router.

3. Fee accounting. Client fees and router fees are credited directly to the receiver's vault balance. No ERC-20 transfers needed at fee-taking time, just a persistent storage write.

Security Guarantees

• Vault balances are scoped per user. Only the owner can use their funds (via msg.sender or signature checks). This is enforced at the contract level and cannot be overridden through encoding.

• Output tokens credited to the vault always go to msg.sender, not to the receiver parameter. This prevents a malicious encoder from redirecting output into another user's vault.

• Tokens sent to the router without calling

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

  • Explains why you made certain decisions, not just what they do

• Module Organisation: For complex implementations it is recommended to:

  • Break large module.rs files into smaller, focused files

  • Place these files in a modules directory
• Substream Initial Block: Your package will work just fine setting the initial block in your manifest file to 1, however it means anyone indexing your protocol has to wait for it to process an excessive number of unnecessary blocks before it reaches the first relevant block. This increases substream costs and causes long wait times for the protocol to reach the current block.

  A good rule of thumb is to identify the earliest deployed contract that you index and set this config to that block.

• Performance Considerations:

  • Minimize use of .clone(), especially in loops or on complex/nested data structures. Instead use references (&) when possible.

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:

1. Implement logic/a helper function to extract the absolute balances of the contract. This is protocol specific and might be obtained from an event, or extracted from a storage slot if an appropriate one is identified.

2. Create an InterimContractChange for the contract and add the contract balances using upsert_token_balance.

3. Add these contract changes to the appropriate TransactionChangesBuilder using add_contract_changes.

An example for a protocol that uses a single vault contract is as follows:

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.

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

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

Setup Guide

Prerequisites

Cow Protocol

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

First, initialize the encoder:

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

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.

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:

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.

Using predefined tracing information (known as entry points), Tycho's DCI assumes responsibility for these edge cases, with Substreams supplying only the core subset of the data for simulation.

Understanding Entry Points

DCI relies on the substreams package to supply tracing information for it to analyse and detect dependency contracts. It is important to understand the protocol being integrated and know where it might make external calls during simulations (swaps, price etc). These external calls need to be able to be defined fully by the combination of 'Entry Points' and 'Tracing Parameters'. See below for more information on what is not covered by the current DCI implementation.

When an entry point is traced, all subsequent calls to other external contracts are automatically traced. Only the initial entry point needs to be supplied.

Entry Point

An entry point defines an external call in very simple terms:

• address of the contract called

• signature of the function called on that contract

Tracing Parameters

This defines how the entry point should be analysed and provides extra data needed for that analysis. Currently only one approach is supported:

• RPC Trace

  This uses an RPC to simulate the defined external call (entry point) using sample call data. The sample data/parameters that can be defined for this trace include: caller and call data. Any new contracts detected by these traces are fetched at the current block—both code and relevant storage—using an RPC as well. Once the contract is known, further updates are extracted by the DCI from the substream message's block storage_changes (see implementation step 2 below). Note: This approach may cause a temporary indexing delay whenever a new trace is conducted: ie. when new entry points or new tracing parameters are added. The delay depends on the complexity/depth of the trace.

Retracing

A retrace of an entry point occurs in one of two situations:

1. New trace parameters are added to the entry point.

2. A retrigger is triggered. Retriggers are storage slots automatically flagged by the DCI for their potential to influence a trace result. Every time one those identified storage slots are updated, the trace is redone.

Implementation Steps

To use the DCI system, you will need to extend your substream package to emit the following:

1. Data to perform a trace

For successful tracing we need to define: - An 'Entry Point' for each call made to an external contract during a simulation action (swap, price calculation, etc.). - Tracing parameters for the entry point. For every entry point defined, at least 1 set of tracing parameters must be supplied. It is vital that every component that uses an entry point is explicitly linked to that entry point. Some useful helper functions are provided to facilitate building the entry point messages:

• To create a new entry point, use: tycho_substreams::entrypoint::create_entrypoint. Add the returned entry point and entry point parameter messages to the TransactionChangesBuilder using add_entrypoint and add_entrypoint_params respectively. They should be added to the transaction builder for the transaction the linked component was created.

2. All contract changes that occurred on the current block

The tycho_substreams::block_storage::get_block_storage_changes helper function simplifies this process by collecting all relevant changes for you. These changes need to be added to the storage_changes field of the final BlockChanges message emitted by the substream package.

This will be used by the DCI to extract and index contract storage updates for all contracts it identifies.

Limitations

DCI is currently limited to only support cases that can be covered by explicitly defined example trace parameters (i,e callers and call data). This means it cannot cover:

• Arbitrary call data: the automatic generation of call data, or fuzzing, is not supported. For example, external calls that take swap amounts as input - example amounts will not be auto generated and must be explicitly supplied as a Tracing Parameter.

• External signatures: calls that require externally created signatures (like Permit2 signatures). DCI cannot automatically generate valid cryptographic signatures and therefore can only support cases where a valid signature can be defined as a Tracing Parameter.

• Call data from external sources: input parameters that need to be fetched or derived from a separate trace are not supported. Only call data available within the Substreams package context can be processed.

Frequently Asked Questions

Q: Is it okay to redefine the same entry point multiple times? A: Yes. Tycho will deduplicate entry points, allowing you to add the same entry point for every new component without needing to track which ones already exist. Using storage on a substreams module affects the performance of the module so should be avoided where possible.

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:

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

Executors

For security purposes, new Executors must have:

• No ERC20 token transfers

• No delegatecalls

• Only perform native ETH transfers if this behaviour is safely reflected in getTransferData or getCallbackTransferData

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.

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.

Swap/Exchange Protocol Guide

Implementing the Protocol

To integrate an EVM exchange protocol:

Tycho Indexer

1. Understanding the protocol

Before integrating, ensure you understand the protocol’s structure and behavior. Here are the key areas:

1. Contracts and their roles: Identify the protocol's contracts and their specific roles. Understand how the contracts impact the behavior of the component you want to integrate.

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: