2. Implementation

1. Understanding the Protocol

Before integrating, ensure you have a thorough understanding of the protocol’s structure and behavior. Key areas to focus on include:

1. Contracts and their roles: Identify the contracts involved in the protocol and the specific roles they play. Understand how they impact the behavior of the component you're integrating.

2. Conditions for State Changes: Determine which conditions, such as oracle updates or particular method calls, trigger state changes (e.g. price updates) in the protocol.

3. Component Addition and Removal: Check how components are added or removed within the protocol. Many protocols either use a factory contract to deploy new components or provision new components directly through specific method calls.

Once you have a clear understanding of the protocol's mechanics, you can proceed with the implementation.

2. Choosing a template

We provide two templates that outline all necessary implementation steps to get you started:

• ethereum-template-factory: Use when the protocol deploys one contract per pool (e.g., UniswapV2, UniswapV3)

• ethereum-template-singleton: Use when the protocol uses a fixed set of contracts (e.g., UniswapV4)

If you are unsure which one to choose please ask in the tycho.build group for support.

Once you have chosen a template:

1. Create a new directory for your integration by copying the template, rename all the references to ethereum-template-[factory|singleton] to [CHAIN]-[PROTOCOL_SYSTEM](please use lowercase letters):

   cp -r ./substreams/ethereum-template-factory ./substreams/[CHAIN]-[PROTOCOL_SYSTEM]

2. Now, generate the required protobuf code by running:

   substreams protogen substreams.yaml --exclude-paths="google"

3. Next, register the new package within the workspace by adding it to the members list in substreams/Cargo.toml.

4. Add any ABIs specific to your protocol under [CHAIN]-[PROTOCOL-SYSTEM]/abi/

5. Your project should now compile and be runnable with substreams:

   cd [CHAIN]-[PROTOCOL-SYSTEM]
   cargo build --release --target wasm32-unknown-unknown
   substreams gui substreams.yaml map_protocol_changes

3. Implementation

If you're using a template, at minimum you'll need to implement three key sections to ensure proper functionality:

The templates include TODO comments at lines that likely require your attention. Additionally, each function is documented with explanations and hints on when modifications may be necessary.

1. Identify newly created ProtocolComponents and Metadata

   Extract relevant protocol components and attach all necessary metadata needed for encoding swaps (or other actions) or filtering components. Examples of such attributes could be: pool identifier, pool keys, swap fees, pool_type and any other relevant static properties. Note that some attribute names are reserved. They may not always be needed but must be respected for compatibility.

2. Emit balances for ProtocolComponents Tycho tracks TVL per component, so you must emit a BalanceChange whenever an event impacts the balances associated with a component. Absolute balances are expected here. Often protocols are only able to identify balance deltas - to handle these effectively please refer to our page detailing handling relative balances.

3. Track relevant storage slot changes [VM implementations only] For factory-like protocols: the template covers this automatically as long as the ProtocolComponent.id is equivalent with the contract address. For singleton contracts: you'll have to collect the contract changes for the contracts you need tracked. To handle these effectively please refer to our page detailing tracking of contract storage.

Some protocols may require additional customisation based on their specific architecture. See Common Problems & Patterns for how to handle these cases.