debug: add debug_getBlockReceipts with EIP-8037 dimensional gas fields

src/debug/getters.yaml

@@ -179,3 +179,59 @@
                   s: '0x50e205faed23c219ba15610de2451d458cbd4221207b2168344cfc972a7973c0'
             hash: '0x601a3ae9b6eceb2476d249e1cffe058ba3ff2c9c1b28b1ec7a0259fdd1d90121'
             rlp: '0xf9039df9025ca098ae440cd7b904d842daa6c263608969a3c8ce6a9acd6bd1f99b394f5f28a207a01dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347940000000000000000000000000000000000000000a0140a9783291704223eb759e3a0db5471a520d349fc17ac2f77ff8582472e3baca08ee998cc699a1f9310a1079458780b3ebee8756f96a0905f5224b89d0eb17486a02b5c77f6e7764d2468178fab7253346b9b8bb6a34b63946f6bdc2f5ad398bfc3b9010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020886ffffffffffff8301a4c9845f5b6b80b86100000000000000000000000000000000000000000000000000000000000000004d04551bdd9ae08af1fd661e49d4ab662c98c532c7ec0e4656a27e4de7d330af578ab1e4f5e49e085ff1d78673c7388ed9ccf017fbe89e53066bfa4018142c0701a00000000000000000000000000000000000000000000000000000000000000000880000000000000000f9013af90137808203e88301a4c98080b8e6608060405234801561001057600080fd5b5060c78061001f6000396000f3fe6080604052348015600f57600080fd5b506004361060325760003560e01c80636057361d146037578063b05784b8146062575b600080fd5b606060048036036020811015604b57600080fd5b8101908080359060200190929190505050607e565b005b60686088565b6040518082815260200191505060405180910390f35b8060008190555050565b6000805490509056fea26469706673582212208dea039245bf78c381278382d7056eef5083f7d243d8958817ef447e0a403bd064736f6c63430006060033820f9da002e30624c0305e64812e1d9e325ba6e50410314634b008edcb50f45be71fa0d4a050e205faed23c219ba15610de2451d458cbd4221207b2168344cfc972a7973c0c0'
+- name: debug_getBlockReceipts
+  summary: Returns receipts of a block with EIP-8037 dimensional gas accounting.
+  description: |
+    Mirrors `eth_getBlockReceipts`. When EIP-8037 is active, each receipt
+    additionally carries `stateGasCharged` (pre-refund state-dimension gas)
+    and `stateGasRefunded` (state-dimension refunds applied). Pre-activation
+    blocks omit both fields.
+
+    Header reconstruction (MUST):
+      `header.stateGasUsed   = Σ stateGasCharged − Σ stateGasRefunded`
+      `header.regularGasUsed = Σ gasUsed − header.stateGasUsed`
+
+    All wire values are unsigned hex. Per-tx `stateGasRefunded` MAY exceed
+    `stateGasCharged` (EIP-7702 unset); at the block boundary
+    `Σ stateGasCharged ≥ Σ stateGasRefunded` is guaranteed by the builder.
+  params:
+    - name: Block
+      required: true
+      schema:
+        $ref: '#/components/schemas/BlockNumberOrTagOrHash'
+  result:
+    name: Receipts information
+    schema:
+      oneOf:
+        - $ref: '#/components/schemas/notFound'
+        - title: Receipts information
+          type: array
+          items:
+            $ref: '#/components/schemas/ReceiptInfo'
+  errors:
+    - code: 4444
+      message: Pruned history unavailable
+  examples:
+    - name: debug_getBlockReceipts example
+      params:
+        - name: Block
+          value: '0x3b3a'
+      result:
+        name: Receipts information
+        value:
+          - blockHash: '0x71ae9b3da6f96b8b3c6f5e1c0a4d5e3f2b9a8c7d6e5f4a3b2c1d0e9f8a7b6c5d'
+            blockNumber: '0x3b3a'
+            contractAddress: '0x1234567890123456789012345678901234567890'
+            cumulativeGasUsed: '0x38cf0'
+            effectiveGasPrice: '0xb2d05e00'
+            from: '0xabcdef0123456789abcdef0123456789abcdef01'
+            gasUsed: '0x38cf0'
+            logs: []
+            logsBloom: '0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000'
+            status: '0x1'
+            to: null
+            transactionHash: '0x9f2c0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f'
+            transactionIndex: '0x0'
+            type: '0x2'
+            stateGasCharged: '0x32760'
+            stateGasRefunded: '0x0'

src/schemas/receipt.yaml

@@ -122,3 +122,52 @@ ReceiptInfo:
       title: blob gas price
       description: The actual value per gas deducted from the sender's account for blob gas. Only specified for blob transactions as defined by EIP-4844.
       $ref: '#/components/schemas/uint'
+    stateGasCharged:
+      title: state gas charged
+      description: |
+        Total state-dimension gas charged to this transaction before refunds, in gas units.
+
+        Equals the sum of:
+        1. Intrinsic state-gas at transaction entry — `AccountCreationCost` for tx-level
+           CREATE; `STATE_BYTES_PER_AUTH_BASE × CPSB` per EIP-7702 authorization in the
+           auth list.
+        2. End-of-frame state-gas charges from successful CALL, CREATE, CREATE2, and
+           SSTORE operations. Reverted or exceptionally-halted frames contribute nothing.
+
+        Always ≥ 0. Does NOT include refunds (see `stateGasRefunded`). The net state gas
+        attributable to this transaction is `stateGasCharged − stateGasRefunded` and
+        MAY be negative under EIP-7702 unset.
+
+        Present only for transactions in blocks under a fork that activates EIP-8037
+        (Amsterdam onward). Omitted otherwise.
+
+        Source: EIP-8037 attribute `tx_state_gas_charged` (per ethereum/EIPs#11573).
+      $ref: '#/components/schemas/uint'
+    stateGasRefunded:
+      title: state gas refunded
+      description: |
+        Total state-dimension gas refunded to this transaction, in gas units.
+
+        Refund kinds:
+        1. SELFDESTRUCT same-transaction-create-and-destroy refund per EIP-6780
+           (bypasses the EIP-3529 20% refund cap).
+        2. EIP-7702 unset-delegation refund — `STATE_BYTES_PER_AUTH_BASE × CPSB` per
+           cleared authorization. The underlying charge may have been paid in an
+           earlier transaction; the refund is credited to this transaction.
+        3. Tx-level CREATE-halt refund of `intrinsic_state_gas` when a contract-
+           creation transaction exceptionally halts or reverts
+           (per ethereum/EIPs#11611).
+
+        Always ≥ 0. MAY exceed `stateGasCharged` for the same transaction (e.g.,
+        EIP-7702 unset of a delegation paid for earlier). At the block boundary,
+        `Σ stateGasCharged ≥ Σ stateGasRefunded` is guaranteed by the block builder.
+
+        Header reconstruction:
+          `header.stateGasUsed = Σ(receipts.stateGasCharged) − Σ(receipts.stateGasRefunded)`
+          `header.regularGasUsed = Σ(receipts.gasUsed) − header.stateGasUsed`
+
+        Present only for transactions in blocks under a fork that activates EIP-8037
+        (Amsterdam onward). Omitted otherwise.
+
+        Source: EIP-8037 attribute `tx_state_gas_refunded` (per ethereum/EIPs#11573).
+      $ref: '#/components/schemas/uint'

tests/debug_getBlockReceipts/get-block-receipts-create-halt.io

@@ -0,0 +1,4 @@
+// Amsterdam: top-level CREATE exceptional halt — intrinsic_state_gas refunded per EIPs#11611.
+// The bal-devnet-6 divergence case: buggy clients omit the refund, drift by AccountCreationCost (131488).
+>> {"jsonrpc":"2.0","id":1,"method":"debug_getBlockReceipts","params":["0x3b3b"]}
+<< {"jsonrpc":"2.0","id":1,"result":[{"blockHash":"0x71ae9b3db1c2c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2","blockNumber":"0x3b3b","contractAddress":null,"cumulativeGasUsed":"0xf4240","effectiveGasPrice":"0xb2d05e00","from":"0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef","gasUsed":"0xf4240","logs":[],"logsBloom":"0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000","status":"0x0","to":null,"transactionHash":"0x4e8b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b","transactionIndex":"0x0","type":"0x2","stateGasCharged":"0x20120","stateGasRefunded":"0x20120"}]}

tests/debug_getBlockReceipts/get-block-receipts-eip7702-unset.io

@@ -0,0 +1,4 @@
+// Amsterdam, two-tx block: tx 1 (EIP-7702 unset) has stateGasRefunded > stateGasCharged.
+// Demonstrates per-tx refund-exceeds-charge is conformant; block-boundary sum_charged >= sum_refunded.
+>> {"jsonrpc":"2.0","id":1,"method":"debug_getBlockReceipts","params":["0x3b3d"]}
+<< {"jsonrpc":"2.0","id":1,"result":[{"blockHash":"0x71ae9b3dd3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0","blockNumber":"0x3b3d","contractAddress":"0xbeefbeefbeefbeefbeefbeefbeefbeefbeefbeef","cumulativeGasUsed":"0x6590","effectiveGasPrice":"0xb2d05e00","from":"0x1111111111111111111111111111111111111111","gasUsed":"0x6590","logs":[],"logsBloom":"0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000","status":"0x1","to":null,"transactionHash":"0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","transactionIndex":"0x0","type":"0x2","stateGasCharged":"0x32760","stateGasRefunded":"0x0"},{"blockHash":"0x71ae9b3dd3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0","blockNumber":"0x3b3d","contractAddress":null,"cumulativeGasUsed":"0xdac0","effectiveGasPrice":"0xb2d05e00","from":"0x6666666666666666666666666666666666666666","gasUsed":"0x7530","logs":[],"logsBloom":"0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000","status":"0x1","to":"0x8888888888888888888888888888888888888888","transactionHash":"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","transactionIndex":"0x1","type":"0x4","stateGasCharged":"0x1388","stateGasRefunded":"0x6986"}]}

tests/debug_getBlockReceipts/get-block-receipts-not-found.io

@@ -0,0 +1,3 @@
+// unknown block returns null
+>> {"jsonrpc":"2.0","id":1,"method":"debug_getBlockReceipts","params":["0x00000000000000000000000000000000000000000000000000000000deadbeef"]}
+<< {"jsonrpc":"2.0","id":1,"result":null}

tests/debug_getBlockReceipts/get-block-receipts-pre-amsterdam.io

@@ -0,0 +1,3 @@
+// pre-Amsterdam: dimensional fields omitted (not zero)
+>> {"jsonrpc":"2.0","id":1,"method":"debug_getBlockReceipts","params":["0x1"]}
+<< {"jsonrpc":"2.0","id":1,"result":[{"blockHash":"0x79ba0368c2c6563a7d263695b583dcc6d1c25d4988daa0105804d38bdd987f2f","blockNumber":"0x1","contractAddress":"0x9344b07175800259691961298ca11c824e65032d","cumulativeGasUsed":"0x102d3","effectiveGasPrice":"0x1","from":"0x7435ed30a8b4aeb0877cef0c6e8cffe834eb865f","gasUsed":"0x102d3","logs":[],"logsBloom":"0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000","root":"0x19fb42ec665b1940ad4b603066bb6efef7d0b97172806da958d1ada7094db01f","to":null,"transactionHash":"0xc1d605c6612a5fe84dc95810030bfe5b1d327652b381bc695e28f50d13b2b09e","transactionIndex":"0x0","type":"0x0"}]}