Tycho
  • Quickstart
  • Overview
  • Motivation
  • Concepts
  • How to Contribute
    • Bounties
  • For Solvers
    • Indexer
      • Tycho RPC
      • Tycho Client
        • Binary / CLI
        • Rust Client
        • Python Client
    • Simulation
    • Execution
      • Encoding
      • Executing
      • Contract Addresses
      • Execution Venues
    • Hosted Endpoints
    • Supported Protocols
  • For DEXs
    • Protocol Integration
      • Indexing
        • 1. Setup
        • 2. Implementation
        • 3. Testing
          • How to Run
        • Common Problems & Patterns
          • Tracking Components
          • Tracking Contract Storage
          • Normalizing relative ERC20 Balances
          • Tracking Contract Balances
          • Custom protobuf models
        • Best Practices
        • Reserved Attributes
      • Simulation
        • Ethereum: Solidity
      • Execution
        • Code Architecture
      • Contributing guidelines
Powered by GitBook
On this page
  • What is Substreams?
  • Integration Modes
  • VM Integration
  • Native Integration
  • Understanding the Data Model
  • Data Encoding
  • Reserved Attributes
  • Changes of interest
Export as PDF
  1. For DEXs
  2. Protocol Integration

Indexing

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:

  • Quick explanation

  • SPKGs

  • Full documentation

Integration Modes

VM Integration

VM integrations primarily track contract storage associated with the protocol’s behavior. A key limitation in Substreams is that to access a contract's full storage, you must witness its creation. Most integrations probably use the VM method due to its 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.

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 here. 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. See list of reserved attributes.

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:

PreviousProtocol IntegrationNext1. Setup

Last updated 18 days ago

1. Setup
2. Implementation
3. Testing