# 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](https://docs.propellerheads.xyz/tycho/for-dexs/protocol-integration/indexing/reserved-attributes)**.** 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](https://docs.propellerheads.xyz/tycho/for-dexs/protocol-integration/indexing/common-problems-and-patterns/normalizing-relative-erc20-balances)'.
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](https://docs.propellerheads.xyz/tycho/for-dexs/protocol-integration/indexing/common-problems-and-patterns/tracking-contract-storage)'.

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

## 4. Testing

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