Improve the naming of utils.

proto/tycho/evm/v1/utils.proto

@@ -4,8 +4,13 @@ package tycho.evm.v1;
 
 import "tycho/evm/v1/common.proto";
 
-// A struct for following the changes of Total Value Locked (TVL).
+// A message containing relative balance changes.
+//
+// Used to track token balances of protocol components in case they are only
+// available as relative values within a block.
 message BalanceDelta {
+  // The ordinal of the balance change. Must be unique & deterministic over all balances
+  // changes within a block.
   uint64 ord = 1;
   // The tx hash of the transaction that caused the balance change.
   Transaction tx = 2;
@@ -14,19 +19,23 @@ message BalanceDelta {
   // The delta balance of the token.
   bytes delta = 4;
   // The id of the component whose TVL is tracked.
-  // If the protocol component includes multiple contracts, the balance change must be aggregated to reflect how much tokens can be traded.
+  // If the protocol component includes multiple contracts, the balance change must be
+  // aggregated to reflect how much tokens can be traded.
   bytes component_id = 5;
 }
 
-message BalanceDeltas {
+// A set of balances deltas, usually a group of changes within a single block.
+message BlockBalanceDeltas {
   repeated BalanceDelta balance_deltas = 1;
 }
 
+// A message containing protocol components that were created by a single tx.
 message TransactionProtocolComponents {
   Transaction tx = 1;
   repeated ProtocolComponent components = 2;
 }
 
-message GroupedTransactionProtocolComponents {
+// All protocol components that were created within a block with their corresponding tx.
+message BlockTransactionProtocolComponents {
   repeated TransactionProtocolComponents tx_components = 1;
 }

substreams/ethereum-balancer/src/modules.rs

@@ -20,7 +20,7 @@ use contract_changes::extract_contract_changes;
 use substreams_ethereum::Event;
 
 use crate::pb::tycho::evm::v1::{self as tycho};
-use crate::pb::tycho::evm::v1::{BalanceDelta, BalanceDeltas, GroupedTransactionProtocolComponents, TransactionProtocolComponents};
+use crate::pb::tycho::evm::v1::{BalanceDelta, BlockBalanceDeltas, BlockTransactionProtocolComponents, TransactionProtocolComponents};
 use crate::{abi, contract_changes, pool_factories};
 
 const VAULT_ADDRESS: &[u8] = &hex!("BA12222222228d8Ba445958a75a0704d566BF2C8");
@@ -37,10 +37,10 @@ impl PartialEq for TransactionWrapper {
 }
 
 #[substreams::handlers::map]
-pub fn map_pools_created(block: eth::v2::Block) -> Result<GroupedTransactionProtocolComponents> {
+pub fn map_pools_created(block: eth::v2::Block) -> Result<BlockTransactionProtocolComponents> {
     // Gather contract changes by indexing `PoolCreated` events and analysing the `Create` call
     // We store these as a hashmap by tx hash since we need to agg by tx hash later
-    Ok(GroupedTransactionProtocolComponents {
+    Ok(BlockTransactionProtocolComponents {
         tx_components: block
             .transactions()
             .filter_map(|tx| {
@@ -82,7 +82,7 @@ pub fn map_pools_created(block: eth::v2::Block) -> Result<GroupedTransactionProt
 
 /// Simply stores the `ProtocolComponent`s with the pool id as the key
 #[substreams::handlers::store]
-pub fn store_pools_created(map: GroupedTransactionProtocolComponents, store: StoreAddInt64) {
+pub fn store_pools_created(map: BlockTransactionProtocolComponents, store: StoreAddInt64) {
     store.add_many(
         0,
         &map.tx_components
@@ -100,7 +100,7 @@ pub fn store_pools_created(map: GroupedTransactionProtocolComponents, store: Sto
 pub fn map_balance_deltas(
     block: eth::v2::Block,
     store: StoreGetInt64,
-) -> Result<BalanceDeltas, anyhow::Error> {
+) -> Result<BlockBalanceDeltas, anyhow::Error> {
     let balance_deltas = block
         .logs()
         .filter(|log| log.address() == VAULT_ADDRESS)
@@ -169,13 +169,13 @@ pub fn map_balance_deltas(
         })
         .collect::<Vec<_>>();
 
-    Ok(BalanceDeltas { balance_deltas })
+    Ok(BlockBalanceDeltas { balance_deltas })
 }
 
 /// It's significant to include both the `pool_id` and the `token_id` for each balance delta as the
 ///  store key to ensure that there's a unique balance being tallied for each.
 #[substreams::handlers::store]
-pub fn store_balance_changes(deltas: BalanceDeltas, store: StoreAddBigInt) {
+pub fn store_balance_changes(deltas: BlockBalanceDeltas, store: StoreAddBigInt) {
     deltas.balance_deltas.iter().for_each(|delta| {
         store.add(
             delta.ord,
@@ -198,8 +198,8 @@ pub fn store_balance_changes(deltas: BalanceDeltas, store: StoreAddBigInt) {
 #[substreams::handlers::map]
 pub fn map_changes(
     block: eth::v2::Block,
-    grouped_components: GroupedTransactionProtocolComponents,
-    deltas: BalanceDeltas,
+    grouped_components: BlockTransactionProtocolComponents,
+    deltas: BlockBalanceDeltas,
     components_store: StoreGetInt64,
     balance_store: StoreDeltas, // Note, this map module is using the `deltas` mode for the store.
 ) -> Result<tycho::BlockContractChanges> {
@@ -229,7 +229,7 @@ pub fn map_changes(
         });
 
     // Balance changes are gathered by the `StoreDelta` based on `PoolBalanceChanged` creating
-    //  `BalanceDeltas`. We essentially just process the changes that occured to the `store` this
+    //  `BlockBalanceDeltas`. We essentially just process the changes that occured to the `store` this
     //  block. Then, these balance changes are merged onto the existing map of tx contract changes,
     //  inserting a new one if it doesn't exist.
     balance_store

substreams/ethereum-balancer/src/pb/tycho.evm.v1.rs

@@ -106,7 +106,7 @@ pub struct BalanceChange {
     /// The address of the ERC20 token whose balance changed.
     #[prost(bytes="vec", tag="1")]
     pub token: ::prost::alloc::vec::Vec<u8>,
-    /// The new balance of the token.
+    /// The new balance of the token. Note: it must be a big endian encoded int.
     #[prost(bytes="vec", tag="2")]
     pub balance: ::prost::alloc::vec::Vec<u8>,
     /// The id of the component whose TVL is tracked.  Note: This MUST be utf8 encoded.
@@ -267,10 +267,15 @@ pub struct BlockContractChanges {
     #[prost(message, repeated, tag="2")]
     pub changes: ::prost::alloc::vec::Vec<TransactionContractChanges>,
 }
-/// A struct for following the changes of Total Value Locked (TVL).
+/// A message containing relative balance changes.
+///
+/// Used to track token balances of protocol components in case they are only
+/// available as relative values within a block.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct BalanceDelta {
+    /// The ordinal of the balance change. Must be unique & deterministic over all balances
+    /// changes within a block.
     #[prost(uint64, tag="1")]
     pub ord: u64,
     /// The tx hash of the transaction that caused the balance change.
@@ -283,16 +288,19 @@ pub struct BalanceDelta {
     #[prost(bytes="vec", tag="4")]
     pub delta: ::prost::alloc::vec::Vec<u8>,
     /// The id of the component whose TVL is tracked.
-    /// If the protocol component includes multiple contracts, the balance change must be aggregated to reflect how much tokens can be traded.
+    /// If the protocol component includes multiple contracts, the balance change must be
+    /// aggregated to reflect how much tokens can be traded.
     #[prost(bytes="vec", tag="5")]
     pub component_id: ::prost::alloc::vec::Vec<u8>,
 }
+/// A set of balances deltas, usually a group of changes within a single block.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
-pub struct BalanceDeltas {
+pub struct BlockBalanceDeltas {
     #[prost(message, repeated, tag="1")]
     pub balance_deltas: ::prost::alloc::vec::Vec<BalanceDelta>,
 }
+/// A message containing protocol components that were created by a single tx.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct TransactionProtocolComponents {
@@ -301,9 +309,10 @@ pub struct TransactionProtocolComponents {
     #[prost(message, repeated, tag="2")]
     pub components: ::prost::alloc::vec::Vec<ProtocolComponent>,
 }
+/// All protocol components that were created within a block with their corresponding tx.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
-pub struct GroupedTransactionProtocolComponents {
+pub struct BlockTransactionProtocolComponents {
     #[prost(message, repeated, tag="1")]
     pub tx_components: ::prost::alloc::vec::Vec<TransactionProtocolComponents>,
 }

substreams/ethereum-balancer/substreams.yaml

@@ -7,7 +7,7 @@ protobuf:
   files:
     - tycho/evm/v1/vm.proto
     - tycho/evm/v1/common.proto
-    - tycho/evm/v1/balancer.proto
+    - tycho/evm/v1/utils.proto
   importPaths:
     - ../../proto