From 071f02f85686acf8015eca59de5b6d00364565ed Mon Sep 17 00:00:00 2001 From: pistomat Date: Thu, 21 Dec 2023 16:37:57 +0100 Subject: [PATCH] Update readmes and add upstream changes --- .../indexing/substreams-integration/README.md | 27 ++++++ .../tutorial-ambient.md | 2 - proto/tycho/evm/v1/common.proto | 11 ++- proto/tycho/evm/v1/vm.proto | 3 +- substreams/ethereum-ambient/buf.gen.yaml | 12 +++ substreams/ethereum-ambient/src/lib.rs | 39 ++++++--- .../ethereum-ambient/src/pb/tycho.evm.v1.rs | 85 +++++++++++-------- substreams/ethereum-template/buf.gen.yaml | 12 +++ .../ethereum-template/src/pb/tycho.evm.v1.rs | 85 +++++++++++-------- 9 files changed, 191 insertions(+), 85 deletions(-) delete mode 100644 docs/indexing/substreams-integration/tutorial-ambient.md create mode 100644 substreams/ethereum-ambient/buf.gen.yaml create mode 100644 substreams/ethereum-template/buf.gen.yaml diff --git a/docs/indexing/substreams-integration/README.md b/docs/indexing/substreams-integration/README.md index 273bf21..e5c6fbe 100644 --- a/docs/indexing/substreams-integration/README.md +++ b/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 {} + ``` + 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. diff --git a/docs/indexing/substreams-integration/tutorial-ambient.md b/docs/indexing/substreams-integration/tutorial-ambient.md deleted file mode 100644 index 5364956..0000000 --- a/docs/indexing/substreams-integration/tutorial-ambient.md +++ /dev/null @@ -1,2 +0,0 @@ -# Tutorial: Ambient - diff --git a/proto/tycho/evm/v1/common.proto b/proto/tycho/evm/v1/common.proto index f9f53aa..2acbd0a 100644 --- a/proto/tycho/evm/v1/common.proto +++ b/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; } diff --git a/proto/tycho/evm/v1/vm.proto b/proto/tycho/evm/v1/vm.proto index 467bc77..95f9c1e 100644 --- a/proto/tycho/evm/v1/vm.proto +++ b/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; diff --git a/substreams/ethereum-ambient/buf.gen.yaml b/substreams/ethereum-ambient/buf.gen.yaml new file mode 100644 index 0000000..d2e6544 --- /dev/null +++ b/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 diff --git a/substreams/ethereum-ambient/src/lib.rs b/substreams/ethereum-ambient/src/lib.rs index ae169db..b9a241b 100644 --- a/substreams/ethereum-ambient/src/lib.rs +++ b/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, balance: Vec, @@ -52,16 +51,25 @@ impl From 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 { - 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, 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::>(); 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::>(); + // 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,10 +203,12 @@ 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 - // that ended up not actually changing anything. + // original value before the transactions ends we remember the initial + // value before the first change and in the end filter found deltas + // that ended up not actually changing anything. for storage_change in storage_changes.iter() { match changed_contracts.entry(storage_change.address.clone()) { // We have already an entry recording a change about this contract @@ -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(), diff --git a/substreams/ethereum-ambient/src/pb/tycho.evm.v1.rs b/substreams/ethereum-ambient/src/pb/tycho.evm.v1.rs index f59fcf2..b59b5f7 100644 --- a/substreams/ethereum-ambient/src/pb/tycho.evm.v1.rs +++ b/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, + /// The parent blocks hash. #[prost(bytes="vec", tag="2")] pub parent_hash: ::prost::alloc::vec::Vec, + /// 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, + /// The sender of the transaction. #[prost(bytes="vec", tag="2")] pub from: ::prost::alloc::vec::Vec, + /// The receiver of the transaction. #[prost(bytes="vec", tag="3")] pub to: ::prost::alloc::vec::Vec, + /// 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, + /// 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>, - #[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>, + /// 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, + /// 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, + /// The new balance of the token. #[prost(bytes="vec", tag="2")] pub balance: ::prost::alloc::vec::Vec, + /// The id of the component whose TVL is tracked. #[prost(bytes="vec", tag="3")] pub component_id: ::prost::alloc::vec::Vec, } +/// 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, -} -#[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, - #[prost(message, repeated, tag="2")] - pub entity_changes: ::prost::alloc::vec::Vec, - #[prost(message, repeated, tag="3")] - pub component_changes: ::prost::alloc::vec::Vec, - #[prost(message, repeated, tag="4")] - pub balance_changes: ::prost::alloc::vec::Vec, -} -#[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, - #[prost(message, repeated, tag="2")] - pub changes: ::prost::alloc::vec::Vec, -} +// 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, + /// The new value for this storage slot. #[prost(bytes="vec", tag="3")] pub value: ::prost::alloc::vec::Vec, } +/// 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, - /// 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, - /// 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, - /// 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, - /// 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, + /// 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, + /// An array of newly added components. #[prost(message, repeated, tag="3")] pub component_changes: ::prost::alloc::vec::Vec, + /// An array of balance changes to components. #[prost(message, repeated, tag="4")] pub balance_changes: ::prost::alloc::vec::Vec, } +/// 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, + /// The set of transaction changes observed in the specified block. #[prost(message, repeated, tag="2")] pub changes: ::prost::alloc::vec::Vec, } diff --git a/substreams/ethereum-template/buf.gen.yaml b/substreams/ethereum-template/buf.gen.yaml new file mode 100644 index 0000000..d2e6544 --- /dev/null +++ b/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 diff --git a/substreams/ethereum-template/src/pb/tycho.evm.v1.rs b/substreams/ethereum-template/src/pb/tycho.evm.v1.rs index f59fcf2..b59b5f7 100644 --- a/substreams/ethereum-template/src/pb/tycho.evm.v1.rs +++ b/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, + /// The parent blocks hash. #[prost(bytes="vec", tag="2")] pub parent_hash: ::prost::alloc::vec::Vec, + /// 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, + /// The sender of the transaction. #[prost(bytes="vec", tag="2")] pub from: ::prost::alloc::vec::Vec, + /// The receiver of the transaction. #[prost(bytes="vec", tag="3")] pub to: ::prost::alloc::vec::Vec, + /// 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, + /// 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>, - #[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>, + /// 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, + /// 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, + /// The new balance of the token. #[prost(bytes="vec", tag="2")] pub balance: ::prost::alloc::vec::Vec, + /// The id of the component whose TVL is tracked. #[prost(bytes="vec", tag="3")] pub component_id: ::prost::alloc::vec::Vec, } +/// 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, -} -#[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, - #[prost(message, repeated, tag="2")] - pub entity_changes: ::prost::alloc::vec::Vec, - #[prost(message, repeated, tag="3")] - pub component_changes: ::prost::alloc::vec::Vec, - #[prost(message, repeated, tag="4")] - pub balance_changes: ::prost::alloc::vec::Vec, -} -#[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, - #[prost(message, repeated, tag="2")] - pub changes: ::prost::alloc::vec::Vec, -} +// 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, + /// The new value for this storage slot. #[prost(bytes="vec", tag="3")] pub value: ::prost::alloc::vec::Vec, } +/// 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, - /// 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, - /// 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, - /// 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, - /// 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, + /// 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, + /// An array of newly added components. #[prost(message, repeated, tag="3")] pub component_changes: ::prost::alloc::vec::Vec, + /// An array of balance changes to components. #[prost(message, repeated, tag="4")] pub balance_changes: ::prost::alloc::vec::Vec, } +/// 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, + /// The set of transaction changes observed in the specified block. #[prost(message, repeated, tag="2")] pub changes: ::prost::alloc::vec::Vec, }