# 2. Implementation

## 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.
2. **Conditions for state changes**: Determine which conditions trigger state changes – like price updates – in the protocol. For example, oracle updates or particular method calls.
3. **Component addition and removal**: Check how the protocol adds and removes components. Many protocols use a factory contract to deploy new components. Or they provide new components directly through specific method calls.

Once you understand the protocol's mechanics, you can proceed with implementation.

## 2. Choosing a template

These two templates outline all necessary steps for implementation:

* Use[`ethereum-template-factory`](https://github.com/propeller-heads/tycho-indexer/tree/main/protocols/substreams/ethereum-template-factory) when the protocol deploys one contract per pool (e.g., UniswapV2, UniswapV3).
* Use[`ethereum-template-singleton`](https://github.com/propeller-heads/tycho-indexer/tree/main/protocols/substreams/ethereum-template-singleton)when the protocol uses a fixed set of contracts (e.g., UniswapV4).

Find support in the [tycho.build](https://t.me/+B4CNQwv7dgIyYTJl) group if you don't know which template to choose.

After choosing a template:

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

   ```bash
   cp -r ./protocols/substreams/ethereum-template-factory ./protocols/substreams/[CHAIN]-[PROTOCOL_SYSTEM]
   ```
2. Generate the required protobuf code by running:

   ```bash
   substreams protogen substreams.yaml --exclude-paths="google"
   ```
3. Register the new package within the workspace by adding it to the members list in `protocols/substreams/Cargo.toml`.
4. Add any protocol-specific ABIs under `[CHAIN]-[PROTOCOL-SYSTEM]/abi/`
5. Your project should compile and it should run with substreams:

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

## 3. Implementation

If you use a template, you must implement at least **three key sections** to ensure proper functionality:

{% hint style="info" %}
The templates include **TO-DO** comments at lines that probably require your attention. Each function is also documented with explanations and hints for when modifications may be necessary.
{% endhint %}

1. **Identify new `ProtocolComponents` and metadata**

   Extract relevant protocol components and attach all metadata (attributes) necessary to encode swaps (or other actions) or to filter components. For example: pool identifier, pool keys, swap fees, pool\_type, or other relevant static properties.\
   Some[ attribute names are reserved](/tycho/for-dexs/protocol-integration/indexing/reserved-attributes.md)**.** They are not always 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 a component's associated balances. *Absolute balances are expected here.* Protocols often only identify balance deltas - to handle these effectively please see '[handling relative balances](/tycho/for-dexs/protocol-integration/indexing/common-problems-and-patterns/normalizing-relative-erc20-balances.md)'.
3. **Track relevant storage slot changes (VM implementations only)**\
   For **factory-like protocols:** the template covers this automatically if the `ProtocolComponent.id` matches the contract address.\
   For **singleton contracts:** you must collect the changes for contracts that you need tracked. To do this effectively, please see '[tracking of contract storage](/tycho/for-dexs/protocol-integration/indexing/common-problems-and-patterns/tracking-contract-storage.md)'.

Some protocols may require additional customisation based on their specific architecture. See [Common Patterns & Problems](/tycho/for-dexs/protocol-integration/indexing/common-problems-and-patterns.md) for how to handle these cases.

## 4. Testing

To test indexing only, follow the instructions for the[ full test suite](/tycho/for-dexs/protocol-integration/3.-testing.md), but set [skip\_simulations](https://docs.propellerheads.xyz/tycho/for-dexs/protocol-integration/indexing/pages/4yTxdhS737ITsSOTN4RL#id-4.-skip_simulation) to true. This will limit the test run to evaluating only the substreams package's indexing behavior, without running simulations.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.propellerheads.xyz/tycho/for-dexs/protocol-integration/indexing/2.-implementation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.