2. Implementation
1. Understanding the protocol
Before integrating, ensure you understand the protocol’s structure and behavior. Here are the key areas:
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.
Conditions for state changes: Determine which conditions trigger state changes – like price updates – in the protocol. For example, oracle updates or particular method calls.
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
when the protocol deploys one contract per pool (e.g., UniswapV2, UniswapV3).Use
ethereum-template-singleton
when 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:
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]
Generate the required protobuf code by running:
substreams protogen substreams.yaml --exclude-paths="google"
Register the new package within the workspace by adding it to the members list in
substreams/Cargo.toml
.Add any protocol-specific ABIs under
[CHAIN]-[PROTOCOL-SYSTEM]/abi/
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:
Identify new
ProtocolComponents
and metadataExtract relevant protocol components and attach all metadata 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.
Emit balances for
ProtocolComponents
Tycho tracks TVL per component. So you must emit a BalanceChange whenever an event impacts a component's associated balances. Expect absolute balances here. Protocols often only identify balance deltas. Please see 'handling relative balances'.Track relevant storage slot changes (VM implementations only) For factory-like protocols, the template provides automatic cover if the
ProtocolComponent.id
matches the contract address. For singleton contracts, you must collect changes for contracts that you need tracked. To do this effectively, please see 'tracking of contract storage'.
Some protocol-specific architecture necessitates additional customisation. For these cases, see Common Problems & Patterns.
Last updated