Upstream changes for proto

proto/tycho/evm/v1/common.proto

@@ -2,20 +2,33 @@ syntax = "proto3";
 
 package tycho.evm.v1;
 
+// This file contains the proto definitions for Substreams common to all integrations.
+
+// A struct describing a block.
 message Block {
+  // The blocks hash.
   bytes hash = 1;
+  // The parent blocks hash.
   bytes parent_hash = 2;
+  // The block number.
   uint64 number = 3;
+  // The block timestamp.
   uint64 ts = 4;
 }
 
+// A struct describing a transaction.
 message Transaction {
+  // The transaction hash.
   bytes hash = 1;
+  // The sender of the transaction.
   bytes from = 2;
+  // The receiver of the transaction.
   bytes to = 3;
+  // The transactions index within the block.
   uint64 index = 4;
 }
 
+// Enum to specify the type of a change.
 enum ChangeType {
   CHANGE_TYPE_UNSPECIFIED = 0;
   CHANGE_TYPE_UPDATE = 1;
@@ -23,22 +36,39 @@ enum ChangeType {
   CHANGE_TYPE_DELETION = 3;
 }
 
+// A custom struct representing an arbitrary attribute of a protocol component.
 message Attribute {
+  // The name of the attribute.
   string name = 1;
+  // The value of the attribute.
   bytes value = 2;
+  // The type of change the attribute underwent.
   ChangeType change = 3;
 }
 
+// A struct describing a part of the protocol.
 message ProtocolComponent {
+  // A unique identifier for the component within the protocol.
+  // Can be a stringified address or a string describing the trading pair.
   string id = 1;
+  // Addresses of the ERC20 tokens used by the component.
   repeated bytes tokens = 2;
-  repeated string contracts = 3;
+  // Addresses of the contracts used by the component.
+  repeated bytes contracts = 3;
+  // Attributes of the component.
+  // 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.
   ChangeType change = 5;
 }
 
+// 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.
 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.
   bytes component_id = 3;
 }

proto/tycho/evm/v1/entity.proto

@@ -4,19 +4,29 @@ package tycho.evm.v1;
 
 import "tycho/evm/v1/common.proto";
 
+// This file contains the definition for the native integration of Substreams.
+
+// A component is a set of attributes that are associated with a custom entity.
 message EntityChanges {
+  // A unique identifier of the entity within the protocol.
   string component_id = 1;
+  // The set of attributes that are associated with the entity.
   repeated Attribute attributes = 2;
 }
 
 message TransactionEntityChanges {
   Transaction tx = 1;
   repeated EntityChanges entity_changes = 2;
+  // An array of newly added components.
   repeated ProtocolComponent component_changes = 3;
+  // An array of balance changes to components.
   repeated BalanceChange balance_changes = 4;
 }
 
+// A set of transaction changes within a single block.
 message BlockEntityChanges {
+  // The block for which these changes are collectively computed.
   Block block = 1;
+  // The set of transaction changes observed in the specified block.
   repeated TransactionEntityChanges changes = 2;
 }

proto/tycho/evm/v1/vm.proto

@@ -4,31 +4,46 @@ package tycho.evm.v1;
 
 import "tycho/evm/v1/common.proto";
 
+// This file contains proto definitions specific to the VM integration.
+
+// A key value entry into contract storage.
 message ContractSlot {
+  // A contract's storage slot.
   bytes slot = 2;
+  // The new value for this storage slot.
   bytes value = 3;
 }
 
+// Changes made to a single contract's state.
 message ContractChange {
+  // The contract's address
   bytes address = 1;
-  // empty bytes indicates no change
+  // The new balance of the contract, empty bytes indicates no change.
   bytes balance = 2;
-  // empty bytes indicates no change
+  // The new code of the contract, empty bytes indicates no change.
   bytes code = 3;
-  // empty sequence indicates no change
+  // The changes to this contract's slots, empty sequence indicates no change.
   repeated ContractSlot slots = 4;
-  // Whether this is an update, creation or deletion
+  // Whether this is an update, a creation or a deletion.
   ChangeType change = 5;
 }
 
+// A set of changes aggregated by transaction.
 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.
   repeated ContractChange contract_changes = 2;
+  // An array of newly added components.
   repeated ProtocolComponent component_changes = 3;
+  // An array of balance changes to components.
   repeated BalanceChange balance_changes = 4;
 }
 
+// A set of transaction changes within a single block.
 message BlockContractChanges {
+  // The block for which these changes are collectively computed.
   Block block = 1;
+  // The set of transaction changes observed in the specified block.
   repeated TransactionContractChanges changes = 2;
 }