Update HIP-1056: Contract Service output and trace specification (#1229)

Signed-off-by: Michael Tinker <michael.tinker@swirldslabs.com>
Co-authored-by: Michael Garber <michael.garber@hashgraph.com>

Author: tinker-michaelj

HIP/hip-1056.md

@@ -3,7 +3,7 @@ hip: 1056
 title: Block Streams
 author: >-
   Jasper Potts <@jasperpotts>, Richard Bair <@rbair23>, Nana Essilfie-Conduah <@Nana-EC>,
-  Mark Blackman <mark@swirldslabs.com>, Edward Wertz<@edward-swirldslabs>
+  Mark Blackman <mark@swirldslabs.com>, Edward Wertz<@edward-swirldslabs>, Michael Tinker <@tinker-michaelj> 
 working-group: >-
   Jasper Potts <@jasperpotts>, Richard Bair <@rbair23>, Nana Essilfie-Conduah <@Nana-EC>,
   Mark Blackman <mark@swirldslabs.com>, Leemon Baird, Joseph Sinclair <@jsync-swirlds>, Nick Poorman <@nickpoorman>,
@@ -17,7 +17,7 @@ status: Approved
 last-call-date-time: 2025-06-03T07:00:00Z
 created: 2023-06-04
 discussions-to: https://github.com/hiero-ledger/hiero-improvement-proposals/discussions/1055
-updated: 2025-07-15
+updated: 2025-07-28
 requires: 1183, 1127, cutover
 ---
 
@@ -503,16 +503,34 @@ in. Block items removed from a filtered stream are represented by one or more
 `FilteredItemHash`’s which provide the missing hashes required to validate the
 filtered stream with the same block proof as the full stream.
 
-> The parent-child relationship of some transactions is preserved in the Block
-> Streams and will see the appropriate `BlockItem`s for each level. For example,
-> a `CryptoTransfer` transaction to a non existing EVM address results in the
-> auto creation of a new Account with the said EVM address. In the Block Streams
-> the `CryptoTransfer` transaction will be described by its `EventTransaction`,
-> `TransactionResult`, `TransactionOutput` and `StateChange` `BlockItem`s. The
-> `CryptoCreate` transaction will also be described by its own
-> `EventTransaction`, `TransactionResult`, `TransactionOutput and `StateChange`
-> `BlockItem`s. In this way a transactions input, output and impacts on the
-> network are clearly described.
+The parent-child relationship of some transactions is preserved in the Block
+Streams and will see the appropriate `BlockItem`s for each level. For example,
+a `CryptoTransfer` transaction to a non existing EVM address results in the
+auto creation of a new Account with the said EVM address. In the Block Streams
+the `CryptoTransfer` transaction will be described by its `SignedTransaction`,
+`TransactionResult`, and `TransactionOutput` and `BlockItem`s. The `CryptoCreate`
+transaction will also be described by its own `SignedTransaction`,
+`TransactionResult`, and `TransactionOutput and `BlockItem`s. However, because
+both logical transactions are in the same Hiero transactional unit, only
+the parent `CryptoTransfer` will have a `StateChanges` item; and that item will
+include all changes for the entire transactional unit. In this way a transactions
+input, output and impacts on the network are clearly described.
+
+The distinction between a **logical transaction** in the block stream and its
+**Hiero transactional unit** is especially significant for
+[batch transactions](https://hips.hedera.com/hip/hip-551). The `AtomicBatch`
+transaction lets a Hiero user group arbitrary HAPI transactions into an
+all-or-nothing unit. None of the HAPI transactions in the group have their own
+`StateChanges` block item---only the `AtomicBatch` has a `StateChanges` item.
+This item includes _either_ the effects of executing every transaction in
+the group with final status `SUCCESS`; _or_ just the effects of paying fees for
+whatever transactions in the group were attempted before getting a status other
+than `SUCCESS`. The logical transactions inside the batch are legible in the
+block stream because their "input" appears as a `SignedTransaction` item in the
+batch and their "output" appears as a `TransactionResult` item along with any
+`TransactionOutput` or `TraceData` needed for extra detail. But a `StateChanges`
+item always represents the boundary of a Hiero transactional unit, and never the
+boundary of a logical transaction.
 
 ##### Forward Compatibility
 
@@ -547,7 +565,6 @@ and a new "BridgeTransform" which is in Trace Data.
  * The "ConsensusTransform" is field 20 (20 modulo 10 is 0, so it is a Consensus Header).
  * The "BridgeTransform" field is 24 (24 modulo 10 is 4, so it is Trace Data).
 
-
 #### BlockHeader
 
 A `BlockHeader` is one type of `output` BlockItem and will always be the first element in a Block. It contains Block
@@ -867,20 +884,22 @@ message TransactionOutput {
 ```
 
 ```protobuf
-message ContractCallOutput {
+message CallContractOutput {
     /**
-     * Result details for an EVM transaction execution
+     * An EVM transaction result. Contains just the information not already
+     * externalized in the matching transaction body.
      */
-    EVMTransactionResult evm_transaction_result = 1;
+    proto.EvmTransactionResult evm_transaction_result = 1;
 }
 ```
 
 ```protobuf
-message ContractCreateOutput {
+message CreateContractOutput {
     /**
-     * Result details for an EVM transaction execution
+     * An EVM transaction result. Contains just the information not already
+     * externalized in the matching transaction body.
      */
-    EVMTransactionResult evm_transaction_result = 1;
+    proto.EvmTransactionResult evm_transaction_result = 1;
 }
 ```
 
@@ -895,10 +914,21 @@ message CreateAccountOutput {
 
 ```protobuf
 message EthereumOutput {
-    /**
-     * Result details for an EVM transaction execution
-     */
-    EVMTransactionResult evm_transaction_result = 1;
+    oneof transaction_result {
+        /**
+         * An EVM transaction result for an Ethereum transaction executed as a
+         * call. Contains just the information not already externalized in the
+         * matching transaction body.
+         */
+        proto.EvmTransactionResult evm_call_transaction_result = 1;
+
+        /**
+         * An EVM transaction result for an Ethereum transaction executed as a
+         * create. Contains just the information not already externalized in the
+         * matching transaction body.
+         */
+        proto.EvmTransactionResult evm_create_transaction_result = 2;
+    }
 }
 ```
 
@@ -1783,118 +1813,194 @@ A `TraceData` block item is added to contain all information that could be cosni
 The consensus node will export all necessary and important data for a transactions execution in the block streams,
 however every byte of information is stored fore er and needed in the proof of the network data. As such it's important
 to ensure that data is required but also laid out in a way that makes it easier for filtering by downstream clients.
-To this point the `TraceData` would initially contain smart contracts `EVMTraceData` that support traceability information (e.g.
+To this point the `TraceData` would initially contain smart contracts `EvmTraceData` that support traceability information (e.g.
 contract actions, read values etc). Future trace like data can be added to `TraceData` and Block Nodes, Mirror Nodes and
-other block stream parsign clients can decided to store or filter it out based on their needs.
+other block stream clients can decided to store or filter it out based on their needs.
 
 ```protobuf
-message ContractSlotReads {
-     
-     message SlotRead {
-          oneof identifier {
-               /**
-               * The contract storage slot counter in this block 
-               * This is populated in place of the 256 bit word when the given slot is written to in state changes
-               */
-               int32 index = 1;
-
-               /**
-               * The key of this contratc storage slot, may be left-padded with zeros to form a 256-bit word.
-               * This is populated when the slot was not written and only read
-               */
-               bytes key = 2;
-          }
-
-          /**
-          * The storage value in this slot, may be left-padded with zeros to form a 256-bit word.
-          */
-          bytes read_value = 3;
-     }
-     
-     /**
-      * The contract associated with the storage slots this slot belongs to.
-      */
-     ContractID contract_id = 1;
-
-     /**
-      * The storage slots that were read in this EVM exectuion. They may or may not have assocaited slot writes
-      */
-     repeated SlotRead slot_reads = 2;    
-}
-
 /**
- * EVM transaction execution log storage details
- * Details maps to the log object in eth_getTransactionReceipt response without repeating info already available in the input transaction
- * Log bloom logic is removed as it may be calculated by block parser for both transactions and block level
+ * EVM trace data, including:
+ * 1. Contract actions executed during the transaction (i.e., the call trace)
+ * 2. Contract slot usages, including reads and writes.
+ * 3. Full error message, if any, produced by the contract call.
+ * 4. Initcode used for any internal contract creations.
+ * 5. Events logged during the transaction.
  */
-message EVMTransactionLog {
-     /**
-      * The contract emitting the log. ContractID vs 20 bye address is used to preserve space
-      */
-     ContractID contract_id = 1;
+message EvmTraceData {
+    /**
+     * All contract actions executed during the transaction.
+     */
+    repeated proto.ContractAction contract_actions = 1;
 
-     /**
-      * The Log data
-      */
-     bytes data = 2;
+    /**
+     * Contract slot usages in the transaction, by contract id.
+     */
+    repeated ContractSlotUsage contract_slot_usages = 2;
 
-     /**
-      * The logc topics left padding of 0's by EVM is stripped to save space. 
-      * Indexers should left-pad with zeros to form a 256-bit word.
-      */
-     repeated bytes topics = 3;
+    /**
+     * Additional details of any error message in the EVM transaction result.
+     * <p>
+     * This SHALL be unset if the contract call succeeded.
+     */
+    string error_details = 3;
+
+    /**
+     * The initcode executed for an internal contract creation.
+     */
+    ExecutedInitcode executed_initcode = 4;
+
+    /**
+     * Log events produced during the transaction, by contract id.
+     */
+    repeated EvmTransactionLog logs = 5;
 }
 
 /**
- * The init bytecode components for child contracts created as part of the contract execution.
- * init_bytecode = deploy_bytecode + runtime_byteode + metadata_bytecode
+ * Usage of a contract's storage slots in an EVM transaction.<br/>
+ * In the common case that a contract operation is the only EVM
+ * transaction in its Hiero transactional unit, this message simply
+ * sets `written_keys_are_non_identical_state_changes` to true;
+ * meaning a stream consumer should extract the written keys from
+ * the Hiero unit's SlotKey state changes that match this message's
+ * `contract_id` (but ignoring any* MapUpdateChange with
+ * `identical` set to true).
+ * <p>
+ * In the less common case that an EVM transaction is one of
+ * several in its Hiero transactional unit (e.g., because it is
+ * one of several ContractCalls in an AtomicBatch); this message
+ * explicitly traces the storage slots that were written during
+ * its transaction's execution.
  */
-message ContractInitByteCode {
+message ContractSlotUsage {
+    /**
+     * The contract using the storage slots.
+     */
+    proto.ContractID contract_id = 1;
+
     /**
-     * The bytecode that predeces and deploys the runtime bytecode in a contracts deployment
+     * When this EVM transaction was one of several within its Hiero
+     * transactional unit, the storage slots that it wrote.
+     * <p>
+     * The written value can be unambiguously derived from the block items
+     * in this EVM transaction's Hiero transactional unit. In particular,
+     * 1. If a following EVM trace modifies the same slot, the value written
+     * in this EVM transaction was whatever value the following trace read.
+     * 2. If the slot was not modified in a following EVM trace, the value
+     * is whatever value was committed to the Merkle state for the slot.
      */
-    google.protobuf.BytesValue deploy_bytecode = 1;
+    WrittenSlotKeys written_slot_keys = 3;
 
     /**
-     * The bytecode that follows the runtime bytecode (found in contract state) in a contracts deployment.
+     * The storage slots that were read in this EVM execution. They may or
+     * may not have associated slot writes.
      */
-    google.protobuf.BytesValue metadata_bytecode = 2;
+    repeated SlotRead slot_reads = 4;
+}
+
+message WrittenSlotKeys {
+    repeated bytes keys = 1;
+}
+
+/**
+ * A slot read in a contract's storage, as used in an EVM transaction.<br/>
+ */
+message SlotRead {
+    oneof identifier {
+        /**
+        * If this slot was also written, the index of the written key in a
+        * an explicit or implicit list of written keys in the stream.
+        * <p>
+        * The case of the explicit list is when this SlotRead appears in a
+        * ContractSlotUsage with `written_slot_keys` set to a non-empty list
+        * of keys. In this case, the index is into that list.
+        * <p>
+        * The case of the implicit list is when this SlotRead appears in a
+        * ContractSlotUsage with `written_slot_keys` unset. In this case,
+        * the list is implicit---it is the list of all SlotKey state changes
+        * in the Hiero transactional unit that match this ContractSlotUsage's
+        * `contract_id` and have `identical` set to false.
+        */
+        int32 index = 1;
+
+        /**
+        * If this slot was only read, its key represented with minimal bytes
+        * (no leading zeros); a stream consumer can left-pad this field with
+        * zeros to form a 32-byte EVM slot key.
+        */
+        bytes key = 2;
+    }
 
     /**
-     * The bytecode that defines a deployed contracts logic. Only present if not in state.
+    * The storage value in this slot, represented with minimal bytes (no
+    * leading zeros); a stream consumer can left-pad this field with zeros.
+    * to form a 32-byte EVM slot value.
+    */
+    bytes read_value = 3;
+}
+
+/**
+  * Information about the initcode executed to create a contract.
+ */
+message ExecutedInitcode {
+    /**
+     * The id of the contract created by the initcode.
      */
-    google.protobuf.BytesValue runtime_bytecode = 3;
+    proto.ContractID contract_id = 1;
+
+    oneof initcode {
+        /**
+         * If the runtime bytecode follows the common convention of appearing as a subsequence
+         * of the initcode, the initcode pieces that surround the runtime bytecode (which is
+         * necessarily in the Hiero transactional unit's state changes).
+         */
+        InitcodeBookends initcode_bookends = 2;
+
+        /**
+         * If the runtime bytecode is not a subsequence of the initcode, the explicit initcode.
+         */
+        bytes explicit_initcode = 3;
+    }
 }
 
 /**
- * EVM tranaction execution trace details
- * Details maps to the variable needed for debugging executions
+  * The initcode bookends of a contract, which are the deploy bytecode and metadata
+  * bytecode that surround the runtime bytecode in a contract's deployment.
+  * <p>
+  * The runtime bytecode is not included here, as it is externalized via a state change
+  * with the matching contract id in the Hiero transactional unit.
  */
-message EVMTraceData { 
+message InitcodeBookends {
     /**
-     * The init bytecode component for this child contract created as part of the contract execution.
+     * The bytecode that precedes the runtime bytecode of a contract in initcode.
      */
-    ContractInitByteCode init_bytecode = 1;
+    bytes deploy_bytecode = 1;
 
     /**
-     * The inter contract interaction details. This represents the internal EVM message frames.
+     * The bytecode that follows the runtime bytecode of a contract in initcode.
      */
-    repeated ContractAction contract_actions = 2;    
- 
+    bytes metadata_bytecode = 2;
+}
+
+/**
+ * A EVM transaction log; c.f. eth_getTransactionReceipt.<br/>
+ * Stream consumers may compute bloom values from topics and data if desired.
+ */
+message EvmTransactionLog {
     /**
-     * Contract slot values that were read during the execution of the EVM transaction. Associated written values will be in state changes
+     * The contract emitting the log.
      */
-    repeated ContractSlotReads contract_slot_reads = 3;
+    proto.ContractID contract_id = 1;
 
     /**
-     * Any error message produced by the contract call.
+     * The logged data.
      */
-    string full_error_message = 4;
+    bytes data = 2;
 
     /**
-     * Any Log events produced by this contract call.
+     * The log's topics represented with minimal bytes (no leading zeros);
+     * a stream consumer can left-pad with zeros to form a 256-bit words.
      */
-    repeated EVMTransactionLog logs = 5;
+    repeated bytes topics = 3;
 }
 ```