Update readmes and add upstream changes

docs/indexing/substreams-integration/README.md

@@ -65,6 +65,33 @@ The module is a Rust library that is compiled into a SPKG (`.spkg`) file using t
 
 Read our [Substreams README.md](../../../substreams/README.md) for more information on how to write the Rust module.
 
+### How to implement the integration
+
+1. Create a new directory for your integration by cloning the template, rename all the references to `ethereum-template` to `[CHAIN]-[PROTOCOL_SYSTEM]`:
+
+    ```bash
+    cp -r ./substreams/ethereum-template ./substreams/[CHAIN]-[PROTOCOL_SYSTEM]
+    ```
+1. Implement the logic in the Rust module `lib.rs`. The main function to implement is the `map_changes` function, which is called for every block. 
+    
+    ```rust
+    #[substreams::handlers::map]
+    fn map_changes(
+        block: eth::v2::Block,
+    ) -> Result<tycho::BlockContractChanges, substreams::errors::Error> {}
+    ```
+    The `map_changes` function takes a raw block as input and returns a `BlockContractChanges` struct, which is derived from the `BlockContractChanges` protobuf message in [vm.proto](../../../proto/tycho/evm/v1/vm.proto). 
+
+
+1. The `BlockContractChanges` is a list of `TransactionContractChanges`, which includes these main fields:
+    - list of `ContractChange` - All storage slots that have changed in the transaction for every contract tracked by any ProtocolComponent
+    - list of `ProtocolComponent` - All the protocol component changes in the transaction
+    - list of `BalanceChange` - All the contract component changes in the transaction
+
+    See the [Ambient reference example](../../../substreams/ethereum-ambient/src/lib.rs) for more information.
+
+
+
 ### Testing
 
 Read the [Substreams testing docs](../../../substreams/README.md#testing-your-implementation) for more information on how to test your integration.

docs/indexing/substreams-integration/tutorial-ambient.md

@@ -1,2 +0,0 @@
-# Tutorial: Ambient
-

proto/tycho/evm/v1/common.proto

@@ -37,6 +37,7 @@ enum ChangeType {
 }
 
 // A custom struct representing an arbitrary attribute of a protocol component.
+// This is mainly used by the native integration to track the necessary information about the protocol.
 message Attribute {
   // The name of the attribute.
   string name = 1;
@@ -47,6 +48,11 @@ message Attribute {
 }
 
 // A struct describing a part of the protocol.
+// Note: For example this can be a UniswapV2 pair, that would track the two ERC20 tokens used by the pair, 
+// the contract would be only the single sontract. The attributes would be empty for the VM integration, 
+// because we track all the relevant info via storage slots and balance changes.
+// It can also be a wrapping contract, like WETH, that has a constant price, but it allows swapping tokens. 
+// This is why the name ProtocolComponent is used instead of "Pool" or "Pair".
 message ProtocolComponent {
   // A unique identifier for the component within the protocol.
   // Can be a stringified address or a string describing the trading pair.
@@ -54,8 +60,9 @@ message ProtocolComponent {
   // Addresses of the ERC20 tokens used by the component.
   repeated bytes tokens = 2;
   // Addresses of the contracts used by the component.
+  // Usually it is a single contract, but some protocols use multiple contracts.
   repeated bytes contracts = 3;
-  // Attributes of the component.
+  // Attributes of the component. Used mainly be the native integration.
   // The inner ChangeType of the attribute has to match the ChangeType of the ProtocolComponent.
   repeated Attribute static_att = 4;
   // Type of change the component underwent.
@@ -64,11 +71,13 @@ message ProtocolComponent {
 
 // A struct for following the changes of Total Value Locked (TVL) of a protocol component.
 // Note that if the ProtocolComponent contains multiple contracts, the TVL is tracked for the component as a whole.
+// E.g. for UniswapV2 pair WETH/USDC, this tracks the USDC and WETH balance of the pair contract.
 message BalanceChange {
   // The address of the ERC20 token whose balance changed.
   bytes token = 1;
   // The new balance of the token.
   bytes balance = 2;
   // 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.
   bytes component_id = 3;
 }

proto/tycho/evm/v1/vm.proto

@@ -33,8 +33,9 @@ message TransactionContractChanges {
   // The transaction instance that results in the changes.
   Transaction tx = 1;
   // Contains the changes induced by the above transaction, aggregated on a per-contract basis.
+  // Must include changes to every contract that is tracked by all ProtocolComponents.
   repeated ContractChange contract_changes = 2;
-  // An array of newly added components.
+  // An array of any component changes.
   repeated ProtocolComponent component_changes = 3;
   // An array of balance changes to components.
   repeated BalanceChange balance_changes = 4;

substreams/ethereum-ambient/buf.gen.yaml

@@ -0,0 +1,12 @@
+
+version: v1
+plugins:
+- plugin: buf.build/community/neoeinstein-prost:v0.2.2
+  out: src/pb
+  opt:
+    - file_descriptor_set=false
+
+- plugin: buf.build/community/neoeinstein-prost-crate:v0.3.1
+  out: src/pb
+  opt:
+    - no_features

substreams/ethereum-ambient/src/lib.rs

@@ -3,7 +3,7 @@ use std::collections::{hash_map::Entry, HashMap};
 use anyhow::{anyhow, bail};
 use ethabi::{decode, ParamType};
 use hex_literal::hex;
-use substreams_ethereum::pb::eth;
+use substreams_ethereum::pb::eth::{self};
 
 use pb::tycho::evm::v1::{self as tycho};
 
@@ -24,8 +24,7 @@ impl SlotValue {
     }
 }
 
-// uses a map for slots, protobuf does not
-// allow bytes in hashmap keys
+// Uses a map for slots, protobuf does not allow bytes in hashmap keys
 struct InterimContractChange {
     address: Vec<u8>,
     balance: Vec<u8>,
@@ -52,16 +51,25 @@ impl From<InterimContractChange> for tycho::ContractChange {
 }
 
 /// Extracts all contract changes relevant to vm simulations
+///
+/// This is the main logic of the substreams integration. It takes a raw ethereum block on input and extracts the BlockContractChanges stream. It includes tracking:
+/// - new pool initializations
+/// - all storage slot changes for the Ambient contract
+/// - all ERC20 balance changes for the Ambient pools
+/// - all code changes and balance updates of the Ambient contract
+/// 
+/// Generally we detect all changes in transactions sequentially and detect if it is a CREATE or UPDATE change based on already present data.
 #[substreams::handlers::map]
 fn map_changes(
     block: eth::v2::Block,
 ) -> Result<tycho::BlockContractChanges, substreams::errors::Error> {
-    let mut block_changes = tycho::BlockContractChanges { block: None, changes: Vec::new() };
+    let mut block_changes = tycho::BlockContractChanges::default();
 
     let mut tx_change = tycho::TransactionContractChanges::default();
 
     let mut changed_contracts: HashMap<Vec<u8>, InterimContractChange> = HashMap::new();
 
+    // Collect all accounts created in this block
     let created_accounts: HashMap<_, _> = block
         .transactions()
         .flat_map(|tx| {
@@ -74,7 +82,7 @@ fn map_changes(
         .collect();
 
     for block_tx in block.transactions() {
-        // extract storage changes
+        // Extract storage changes for all contracts relevant to this ProtocolComponent (i.e. Ambient)
         let mut storage_changes = block_tx
             .calls
             .iter()
@@ -87,6 +95,7 @@ fn map_changes(
             .collect::<Vec<_>>();
         storage_changes.sort_unstable_by_key(|change| change.ordinal);
 
+        // Detect all call to the Ambient contracts, even inner calls
         let ambient_calls = block_tx
             .calls
             .iter()
@@ -94,6 +103,8 @@ fn map_changes(
             .filter(|call| call.address == AMBIENT_CONTRACT)
             .collect::<Vec<_>>();
 
+        // Detect all pool initializations
+        // Official documentation: https://docs.ambient.finance/developers/dex-contract-interface/pool-initialization 
         for call in ambient_calls {
             if call.input.len() < 4 {
                 continue;
@@ -175,7 +186,7 @@ fn map_changes(
                                     pool_index
                                 ),
                                 tokens,
-                                contracts: vec![hex::encode(AMBIENT_CONTRACT)],
+                                contracts: vec![AMBIENT_CONTRACT.to_vec()],
                                 static_att: vec![static_attribute],
                                 change: tycho::ChangeType::Creation.into(),
                             };
@@ -192,6 +203,8 @@ fn map_changes(
             }
         }
 
+        // Extract all contract changes.
+        // We cache the data in a general interim contract > slot > value data structure.
         // Note: some contracts change slot values and change them back to their
         // original value before the transactions ends we remember the initial
         // value before the first change and in the end filter found deltas
@@ -223,7 +236,7 @@ fn map_changes(
                         }
                     }
                 }
-                // Intialise a new contract change after obsering a storage change
+                // Intialise a new contract change after observing a storage change
                 Entry::Vacant(e) => {
                     let mut slots = HashMap::new();
                     slots.insert(
@@ -248,7 +261,7 @@ fn map_changes(
             }
         }
 
-        // extract balance changes
+        // Extract balance changes
         let mut balance_changes = block_tx
             .calls
             .iter()
@@ -290,7 +303,7 @@ fn map_changes(
             }
         }
 
-        // extract code changes
+        // Extract code changes
         let mut code_changes = block_tx
             .calls
             .iter()
@@ -328,7 +341,7 @@ fn map_changes(
             }
         }
 
-        // if there were any changes, add transaction and push the changes
+        // If there were any changes, add transaction and push the changes
         if !storage_changes.is_empty() || !balance_changes.is_empty() || !code_changes.is_empty() {
             tx_change.tx = Some(tycho::Transaction {
                 hash: block_tx.hash.clone(),

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

@@ -1,62 +1,92 @@
 // @generated
+// This file contains the proto definitions for Substreams common to all integrations.
+
+/// A struct describing a block.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct Block {
+    /// The blocks hash.
     #[prost(bytes="vec", tag="1")]
     pub hash: ::prost::alloc::vec::Vec<u8>,
+    /// The parent blocks hash.
     #[prost(bytes="vec", tag="2")]
     pub parent_hash: ::prost::alloc::vec::Vec<u8>,
+    /// The block number.
     #[prost(uint64, tag="3")]
     pub number: u64,
+    /// The block timestamp.
     #[prost(uint64, tag="4")]
     pub ts: u64,
 }
+/// A struct describing a transaction.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct Transaction {
+    /// The transaction hash.
     #[prost(bytes="vec", tag="1")]
     pub hash: ::prost::alloc::vec::Vec<u8>,
+    /// The sender of the transaction.
     #[prost(bytes="vec", tag="2")]
     pub from: ::prost::alloc::vec::Vec<u8>,
+    /// The receiver of the transaction.
     #[prost(bytes="vec", tag="3")]
     pub to: ::prost::alloc::vec::Vec<u8>,
+    /// The transactions index within the block.
     #[prost(uint64, tag="4")]
     pub index: u64,
 }
+/// A custom struct representing an arbitrary attribute of a protocol component.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct Attribute {
+    /// The name of the attribute.
     #[prost(string, tag="1")]
     pub name: ::prost::alloc::string::String,
+    /// The value of the attribute.
     #[prost(bytes="vec", tag="2")]
     pub value: ::prost::alloc::vec::Vec<u8>,
+    /// The type of change the attribute underwent.
     #[prost(enumeration="ChangeType", tag="3")]
     pub change: i32,
 }
+/// A struct describing a part of the protocol.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct ProtocolComponent {
+    /// A unique identifier for the component within the protocol.
+    /// Can be a stringified address or a string describing the trading pair.
     #[prost(string, tag="1")]
     pub id: ::prost::alloc::string::String,
+    /// Addresses of the ERC20 tokens used by the component.
     #[prost(bytes="vec", repeated, tag="2")]
     pub tokens: ::prost::alloc::vec::Vec<::prost::alloc::vec::Vec<u8>>,
-    #[prost(string, repeated, tag="3")]
-    pub contracts: ::prost::alloc::vec::Vec<::prost::alloc::string::String>,
+    /// Addresses of the contracts used by the component.
+    #[prost(bytes="vec", repeated, tag="3")]
+    pub contracts: ::prost::alloc::vec::Vec<::prost::alloc::vec::Vec<u8>>,
+    /// Attributes of the component.
+    /// The inner ChangeType of the attribute has to match the ChangeType of the ProtocolComponent.
     #[prost(message, repeated, tag="4")]
     pub static_att: ::prost::alloc::vec::Vec<Attribute>,
+    /// Type of change the component underwent.
     #[prost(enumeration="ChangeType", tag="5")]
     pub change: i32,
 }
+/// A struct for following the changes of Total Value Locked (TVL) of a protocol component.
+/// Note that if the ProtocolComponent contains multiple contracts, the TVL is tracked for the component as a whole.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 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.
     #[prost(bytes="vec", tag="2")]
     pub balance: ::prost::alloc::vec::Vec<u8>,
+    /// The id of the component whose TVL is tracked.
     #[prost(bytes="vec", tag="3")]
     pub component_id: ::prost::alloc::vec::Vec<u8>,
 }
+/// Enum to specify the type of a change.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, ::prost::Enumeration)]
 #[repr(i32)]
 pub enum ChangeType {
@@ -89,77 +119,64 @@ impl ChangeType {
         }
     }
 }
-#[allow(clippy::derive_partial_eq_without_eq)]
-#[derive(Clone, PartialEq, ::prost::Message)]
-pub struct EntityChanges {
-    #[prost(string, tag="1")]
-    pub component_id: ::prost::alloc::string::String,
-    #[prost(message, repeated, tag="2")]
-    pub attributes: ::prost::alloc::vec::Vec<Attribute>,
-}
-#[allow(clippy::derive_partial_eq_without_eq)]
-#[derive(Clone, PartialEq, ::prost::Message)]
-pub struct TransactionEntityChanges {
-    #[prost(message, optional, tag="1")]
-    pub tx: ::core::option::Option<Transaction>,
-    #[prost(message, repeated, tag="2")]
-    pub entity_changes: ::prost::alloc::vec::Vec<EntityChanges>,
-    #[prost(message, repeated, tag="3")]
-    pub component_changes: ::prost::alloc::vec::Vec<ProtocolComponent>,
-    #[prost(message, repeated, tag="4")]
-    pub balance_changes: ::prost::alloc::vec::Vec<BalanceChange>,
-}
-#[allow(clippy::derive_partial_eq_without_eq)]
-#[derive(Clone, PartialEq, ::prost::Message)]
-pub struct BlockEntityChanges {
-    #[prost(message, optional, tag="1")]
-    pub block: ::core::option::Option<Block>,
-    #[prost(message, repeated, tag="2")]
-    pub changes: ::prost::alloc::vec::Vec<TransactionEntityChanges>,
-}
+// This file contains proto definitions specific to the VM integration.
+
+/// A key value entry into contract storage.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct ContractSlot {
+    /// A contract's storage slot.
     #[prost(bytes="vec", tag="2")]
     pub slot: ::prost::alloc::vec::Vec<u8>,
+    /// The new value for this storage slot.
     #[prost(bytes="vec", tag="3")]
     pub value: ::prost::alloc::vec::Vec<u8>,
 }
+/// Changes made to a single contract's state.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct ContractChange {
+    /// The contract's address
     #[prost(bytes="vec", tag="1")]
     pub address: ::prost::alloc::vec::Vec<u8>,
-    /// empty bytes indicates no change
+    /// The new balance of the contract, empty bytes indicates no change.
     #[prost(bytes="vec", tag="2")]
     pub balance: ::prost::alloc::vec::Vec<u8>,
-    /// empty bytes indicates no change
+    /// The new code of the contract, empty bytes indicates no change.
     #[prost(bytes="vec", tag="3")]
     pub code: ::prost::alloc::vec::Vec<u8>,
-    /// empty sequence indicates no change
+    /// The changes to this contract's slots, empty sequence indicates no change.
     #[prost(message, repeated, tag="4")]
     pub slots: ::prost::alloc::vec::Vec<ContractSlot>,
-    /// Whether this is an update, creation or deletion
+    /// Whether this is an update, a creation or a deletion.
     #[prost(enumeration="ChangeType", tag="5")]
     pub change: i32,
 }
+/// A set of changes aggregated by transaction.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct TransactionContractChanges {
+    /// The transaction instance that results in the changes.
     #[prost(message, optional, tag="1")]
     pub tx: ::core::option::Option<Transaction>,
+    /// Contains the changes induced by the above transaction, aggregated on a per-contract basis.
     #[prost(message, repeated, tag="2")]
     pub contract_changes: ::prost::alloc::vec::Vec<ContractChange>,
+    /// An array of newly added components.
     #[prost(message, repeated, tag="3")]
     pub component_changes: ::prost::alloc::vec::Vec<ProtocolComponent>,
+    /// An array of balance changes to components.
     #[prost(message, repeated, tag="4")]
     pub balance_changes: ::prost::alloc::vec::Vec<BalanceChange>,
 }
+/// A set of transaction changes within a single block.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct BlockContractChanges {
+    /// The block for which these changes are collectively computed.
     #[prost(message, optional, tag="1")]
     pub block: ::core::option::Option<Block>,
+    /// The set of transaction changes observed in the specified block.
     #[prost(message, repeated, tag="2")]
     pub changes: ::prost::alloc::vec::Vec<TransactionContractChanges>,
 }

substreams/ethereum-template/buf.gen.yaml

@@ -0,0 +1,12 @@
+
+version: v1
+plugins:
+- plugin: buf.build/community/neoeinstein-prost:v0.2.2
+  out: src/pb
+  opt:
+    - file_descriptor_set=false
+
+- plugin: buf.build/community/neoeinstein-prost-crate:v0.3.1
+  out: src/pb
+  opt:
+    - no_features

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

@@ -1,62 +1,92 @@
 // @generated
+// This file contains the proto definitions for Substreams common to all integrations.
+
+/// A struct describing a block.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct Block {
+    /// The blocks hash.
     #[prost(bytes="vec", tag="1")]
     pub hash: ::prost::alloc::vec::Vec<u8>,
+    /// The parent blocks hash.
     #[prost(bytes="vec", tag="2")]
     pub parent_hash: ::prost::alloc::vec::Vec<u8>,
+    /// The block number.
     #[prost(uint64, tag="3")]
     pub number: u64,
+    /// The block timestamp.
     #[prost(uint64, tag="4")]
     pub ts: u64,
 }
+/// A struct describing a transaction.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct Transaction {
+    /// The transaction hash.
     #[prost(bytes="vec", tag="1")]
     pub hash: ::prost::alloc::vec::Vec<u8>,
+    /// The sender of the transaction.
     #[prost(bytes="vec", tag="2")]
     pub from: ::prost::alloc::vec::Vec<u8>,
+    /// The receiver of the transaction.
     #[prost(bytes="vec", tag="3")]
     pub to: ::prost::alloc::vec::Vec<u8>,
+    /// The transactions index within the block.
     #[prost(uint64, tag="4")]
     pub index: u64,
 }
+/// A custom struct representing an arbitrary attribute of a protocol component.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct Attribute {
+    /// The name of the attribute.
     #[prost(string, tag="1")]
     pub name: ::prost::alloc::string::String,
+    /// The value of the attribute.
     #[prost(bytes="vec", tag="2")]
     pub value: ::prost::alloc::vec::Vec<u8>,
+    /// The type of change the attribute underwent.
     #[prost(enumeration="ChangeType", tag="3")]
     pub change: i32,
 }
+/// A struct describing a part of the protocol.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct ProtocolComponent {
+    /// A unique identifier for the component within the protocol.
+    /// Can be a stringified address or a string describing the trading pair.
     #[prost(string, tag="1")]
     pub id: ::prost::alloc::string::String,
+    /// Addresses of the ERC20 tokens used by the component.
     #[prost(bytes="vec", repeated, tag="2")]
     pub tokens: ::prost::alloc::vec::Vec<::prost::alloc::vec::Vec<u8>>,
-    #[prost(string, repeated, tag="3")]
-    pub contracts: ::prost::alloc::vec::Vec<::prost::alloc::string::String>,
+    /// Addresses of the contracts used by the component.
+    #[prost(bytes="vec", repeated, tag="3")]
+    pub contracts: ::prost::alloc::vec::Vec<::prost::alloc::vec::Vec<u8>>,
+    /// Attributes of the component.
+    /// The inner ChangeType of the attribute has to match the ChangeType of the ProtocolComponent.
     #[prost(message, repeated, tag="4")]
     pub static_att: ::prost::alloc::vec::Vec<Attribute>,
+    /// Type of change the component underwent.
     #[prost(enumeration="ChangeType", tag="5")]
     pub change: i32,
 }
+/// A struct for following the changes of Total Value Locked (TVL) of a protocol component.
+/// Note that if the ProtocolComponent contains multiple contracts, the TVL is tracked for the component as a whole.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 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.
     #[prost(bytes="vec", tag="2")]
     pub balance: ::prost::alloc::vec::Vec<u8>,
+    /// The id of the component whose TVL is tracked.
     #[prost(bytes="vec", tag="3")]
     pub component_id: ::prost::alloc::vec::Vec<u8>,
 }
+/// Enum to specify the type of a change.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, ::prost::Enumeration)]
 #[repr(i32)]
 pub enum ChangeType {
@@ -89,77 +119,64 @@ impl ChangeType {
         }
     }
 }
-#[allow(clippy::derive_partial_eq_without_eq)]
-#[derive(Clone, PartialEq, ::prost::Message)]
-pub struct EntityChanges {
-    #[prost(string, tag="1")]
-    pub component_id: ::prost::alloc::string::String,
-    #[prost(message, repeated, tag="2")]
-    pub attributes: ::prost::alloc::vec::Vec<Attribute>,
-}
-#[allow(clippy::derive_partial_eq_without_eq)]
-#[derive(Clone, PartialEq, ::prost::Message)]
-pub struct TransactionEntityChanges {
-    #[prost(message, optional, tag="1")]
-    pub tx: ::core::option::Option<Transaction>,
-    #[prost(message, repeated, tag="2")]
-    pub entity_changes: ::prost::alloc::vec::Vec<EntityChanges>,
-    #[prost(message, repeated, tag="3")]
-    pub component_changes: ::prost::alloc::vec::Vec<ProtocolComponent>,
-    #[prost(message, repeated, tag="4")]
-    pub balance_changes: ::prost::alloc::vec::Vec<BalanceChange>,
-}
-#[allow(clippy::derive_partial_eq_without_eq)]
-#[derive(Clone, PartialEq, ::prost::Message)]
-pub struct BlockEntityChanges {
-    #[prost(message, optional, tag="1")]
-    pub block: ::core::option::Option<Block>,
-    #[prost(message, repeated, tag="2")]
-    pub changes: ::prost::alloc::vec::Vec<TransactionEntityChanges>,
-}
+// This file contains proto definitions specific to the VM integration.
+
+/// A key value entry into contract storage.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct ContractSlot {
+    /// A contract's storage slot.
     #[prost(bytes="vec", tag="2")]
     pub slot: ::prost::alloc::vec::Vec<u8>,
+    /// The new value for this storage slot.
     #[prost(bytes="vec", tag="3")]
     pub value: ::prost::alloc::vec::Vec<u8>,
 }
+/// Changes made to a single contract's state.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct ContractChange {
+    /// The contract's address
     #[prost(bytes="vec", tag="1")]
     pub address: ::prost::alloc::vec::Vec<u8>,
-    /// empty bytes indicates no change
+    /// The new balance of the contract, empty bytes indicates no change.
     #[prost(bytes="vec", tag="2")]
     pub balance: ::prost::alloc::vec::Vec<u8>,
-    /// empty bytes indicates no change
+    /// The new code of the contract, empty bytes indicates no change.
     #[prost(bytes="vec", tag="3")]
     pub code: ::prost::alloc::vec::Vec<u8>,
-    /// empty sequence indicates no change
+    /// The changes to this contract's slots, empty sequence indicates no change.
     #[prost(message, repeated, tag="4")]
     pub slots: ::prost::alloc::vec::Vec<ContractSlot>,
-    /// Whether this is an update, creation or deletion
+    /// Whether this is an update, a creation or a deletion.
     #[prost(enumeration="ChangeType", tag="5")]
     pub change: i32,
 }
+/// A set of changes aggregated by transaction.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct TransactionContractChanges {
+    /// The transaction instance that results in the changes.
     #[prost(message, optional, tag="1")]
     pub tx: ::core::option::Option<Transaction>,
+    /// Contains the changes induced by the above transaction, aggregated on a per-contract basis.
     #[prost(message, repeated, tag="2")]
     pub contract_changes: ::prost::alloc::vec::Vec<ContractChange>,
+    /// An array of newly added components.
     #[prost(message, repeated, tag="3")]
     pub component_changes: ::prost::alloc::vec::Vec<ProtocolComponent>,
+    /// An array of balance changes to components.
     #[prost(message, repeated, tag="4")]
     pub balance_changes: ::prost::alloc::vec::Vec<BalanceChange>,
 }
+/// A set of transaction changes within a single block.
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct BlockContractChanges {
+    /// The block for which these changes are collectively computed.
     #[prost(message, optional, tag="1")]
     pub block: ::core::option::Option<Block>,
+    /// The set of transaction changes observed in the specified block.
     #[prost(message, repeated, tag="2")]
     pub changes: ::prost::alloc::vec::Vec<TransactionContractChanges>,
 }