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:

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

• Useethereum-template-singletonwhen the protocol uses a fixed set of contracts (e.g., UniswapV4).

Find support in the tycho.build 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):

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

2. Generate the required protobuf code by running:

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

3. Register the new package within the workspace by adding it to the members list in 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:

   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:

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.

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. They are not always needed but must be respected for compatibility.

2. Emit balances forProtocolComponents 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'.

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

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

4. Testing

To test indexing only, follow the instructions for the full test suite, but set skip_simulations to true. This will limit the test run to evaluating only the substreams package's indexing behavior, without running simulations.