diff --git a/src/debug/getters.yaml b/src/debug/getters.yaml index c6f62ab61..c4356192d 100644 --- a/src/debug/getters.yaml +++ b/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' diff --git a/src/schemas/receipt.yaml b/src/schemas/receipt.yaml index ab67b3a13..1a76e0d8b 100644 --- a/src/schemas/receipt.yaml +++ b/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' diff --git a/tests/debug_getBlockReceipts/get-block-receipts-create-halt.io b/tests/debug_getBlockReceipts/get-block-receipts-create-halt.io new file mode 100644 index 000000000..8d8545e63 --- /dev/null +++ b/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"}]} diff --git a/tests/debug_getBlockReceipts/get-block-receipts-eip7702-unset.io b/tests/debug_getBlockReceipts/get-block-receipts-eip7702-unset.io new file mode 100644 index 000000000..7228fb6c6 --- /dev/null +++ b/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"}]} diff --git a/tests/debug_getBlockReceipts/get-block-receipts-not-found.io b/tests/debug_getBlockReceipts/get-block-receipts-not-found.io new file mode 100644 index 000000000..39551a10d --- /dev/null +++ b/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} diff --git a/tests/debug_getBlockReceipts/get-block-receipts-pre-amsterdam.io b/tests/debug_getBlockReceipts/get-block-receipts-pre-amsterdam.io new file mode 100644 index 000000000..2972db47e --- /dev/null +++ b/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"}]}