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. If your protocol deploys one contract per pool deployment (e.g. UniswapV2 or UniswapV3) please choose the ethereum-template-factory. If your protocol does use a fixed set of contracts (e.g. UniswapV4) please use the ethereum-template-singleton . If you are unsure which one to choose please ask in tycho.build group for support.

• 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 latters):

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

• Now, generate the required protobuf code by running:

  substreams protogen substreams.yaml --exclude-paths="sf/substreams,google"

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

• Add any abis specific to your protocol under [CHAIN]-[PROTOCOL-SYSTEM]/abi/

• 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, you'll need to implement three steps to ensure proper functionality:

The template includes 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

   You will have to extract relevant protocol components and attach all necessary metadata that may serve to encode swaps (or other actions) or to filter 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 BalanceDelta for ProtocolComponents Tycho tracks TVL per component, so you must emit relative BalanceChanges whenever an event impacts the balances associated with a component. If your protocol emits events with absolute balances, you might be able to skip this step.

3. Track relevant storage slot changes 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 list the contracts you'd like to be tracked.

Depending on the specifics of your protocol additional changes may be necessary. E.g. some protocols might require storage slot tracking of a specific helper contract.