Merge branch 'main' into unify-requests-flat

Author: fjl

graphql.json

@@ -473,22 +473,6 @@
             "isDeprecated": false,
             "deprecationReason": null
           },
-          {
-            "name": "totalDifficulty",
-            "description": "TotalDifficulty is the sum of all difficulty values up to and including\nthis block.",
-            "args": [],
-            "type": {
-              "kind": "NON_NULL",
-              "name": null,
-              "ofType": {
-                "kind": "SCALAR",
-                "name": "BigInt",
-                "ofType": null
-              }
-            },
-            "isDeprecated": false,
-            "deprecationReason": null
-          },
           {
             "name": "ommerCount",
             "description": "OmmerCount is the number of ommers (AKA uncles) associated with this\nblock. If ommers are unavailable, this field will be null.",

schema.graphqls

@@ -122,12 +122,6 @@ type Block {
   """Difficulty is a measure of the difficulty of mining this block."""
   difficulty: BigInt!
 
-  """
-  TotalDifficulty is the sum of all difficulty values up to and including
-  this block.
-  """
-  totalDifficulty: BigInt!
-
   """
   OmmerCount is the number of ommers (AKA uncles) associated with this
   block. If ommers are unavailable, this field will be null.

src/debug/getters.yaml

@@ -108,7 +108,6 @@
               receiptsRoot: '0xccd2d33763dc0ac3fe02d4ecbbcd7d2bdc6f57db635ba31007184679303721d7'
               miner: '0x0000000000000000000000000000000000000000'
               difficulty: '0x1'
-              totalDifficulty: '0x1'
               extraData: '0x00000000000000000000000000000000000000000000000000000000000000008c6a091f07e4ba3930f2f5fabbfc5b1c70986319096760ba200a6abc0d30e33c2d501702d1b58d7f75807bdbf981044557628611319121170b96466ec06bb3fd01'
               size: '0x3a0'
               gasLimit: '0xffffffffffff'
@@ -145,7 +144,6 @@
               receiptsRoot: '0x2b5c77f6e7764d2468178fab7253346b9b8bb6a34b63946f6bdc2f5ad398bfc3'
               miner: '0x0000000000000000000000000000000000000000'
               difficulty: '0x2'
-              totalDifficulty: '0x2'
               extraData: '0x00000000000000000000000000000000000000000000000000000000000000004d04551bdd9ae08af1fd661e49d4ab662c98c532c7ec0e4656a27e4de7d330af578ab1e4f5e49e085ff1d78673c7388ed9ccf017fbe89e53066bfa4018142c0701'
               size: '0x3a0'
               gasLimit: '0xffffffffffff'

src/engine/common.md

@@ -161,7 +161,7 @@ Execution layer clients **MUST** support `engine_exchangeCapabilities` method, w
 
 #### Specification
 
-1. Consensus and execution layer client software **MAY** exchange with a list of currently supported Engine API methods. Execution layer client software **MUST NOT** log any error messages if this method has either never been called or haven't been called for a significant amount of time.
+1. Consensus and execution layer client software **MAY** exchange with a list of currently supported Engine API methods. Execution layer client software **MUST NOT** log any error messages if this method has either never been called or hasn't been called for a significant amount of time.
 
 2. Request and response lists **MUST** contain Engine API methods that are currently supported by consensus and execution client software respectively. Name of each method in both lists **MUST** include suffixed version. Consider the following examples:
     * Client software of both layers currently supports `V1` and `V2` versions of `engine_newPayload` method:

src/engine/paris.md

@@ -222,7 +222,7 @@ The payload build process is specified as follows:
 
     1. Verify that `payloadAttributes.timestamp` is greater than `timestamp` of a block referenced by `forkchoiceState.headBlockHash` and return `-38003: Invalid payload attributes` on failure.
 
-    2. If `payloadAttributes` passes all valdiation steps, begin a payload build process building on top of `forkchoiceState.headBlockHash` and identified via `buildProcessId` value. The build process is specified in the [Payload building](#payload-building) section.
+    2. If `payloadAttributes` passes all validation steps, begin a payload build process building on top of `forkchoiceState.headBlockHash` and identified via `buildProcessId` value. The build process is specified in the [Payload building](#payload-building) section.
 
     3. If `payloadAttributes` validation fails, the `forkchoiceState` update **MUST NOT** be rolled back.
 
@@ -235,7 +235,7 @@ The payload build process is specified as follows:
   * `{error: {code: -38002, message: "Invalid forkchoice state"}}` if `forkchoiceState` is either invalid or inconsistent
   * `{error: {code: -38003, message: "Invalid payload attributes"}}` if the payload is deemed `VALID` and `forkchoiceState` has been applied successfully, but no build process has been started due to invalid `payloadAttributes`.
 
-10. If any of the above fails due to errors unrelated to the normal processing flow of the method, client software **MUST** respond with an error object.
+9. If any of the above fails due to errors unrelated to the normal processing flow of the method, client software **MUST** respond with an error object.
 
 ### engine_getPayloadV1
 

src/engine/prague.md

@@ -148,7 +148,7 @@ The response of this method is updated with [`ExecutionPayloadBodyV2`](#executio
 * method: `engine_getPayloadBodiesByRangeV2`
 * params:
   1. `start`: `QUANTITY`, 64 bits - Starting block number
-  1. `count`: `QUANITTY`, 64 bits - Number of blocks to return
+  1. `count`: `QUANTITY`, 64 bits - Number of blocks to return
 * timeout: 10s
 
 #### Response

src/engine/shanghai.md

@@ -202,7 +202,7 @@ This method follows the same specification as [`engine_getPayloadV1`](./paris.md
 * method: `engine_getPayloadBodiesByRangeV1`
 * params:
   1. `start`: `QUANTITY`, 64 bits - Starting block number
-  1. `count`: `QUANITTY`, 64 bits - Number of blocks to return
+  1. `count`: `QUANTITY`, 64 bits - Number of blocks to return
 * timeout: 10s
 
 #### Response

src/eth/block.yaml

@@ -16,6 +16,48 @@
       oneOf:
         - $ref: '#/components/schemas/notFound'
         - $ref: '#/components/schemas/Block'
+  examples:
+    - name: eth_getBlockByHash example
+      params:
+        - name: Block hash
+          value: '0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c'
+        - name: Hydrated transactions
+          value: false
+      result:
+        name: Block information
+        value:
+          number: '0x68b3'
+          hash: '0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c'
+          mixHash: '0x24900fb3da77674a861c428429dce0762707ecb6052325bbd9b3c64e74b5af9d'
+          parentHash: '0x1f68ac259155e2f38211ddad0f0a15394d55417b185a93923e2abe71bb7a4d6d'
+          nonce: '0x378da40ff335b070'
+          sha3Uncles: '0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347'
+          logsBloom: '0x00000000000000100000004080000000000500000000000000020000100000000800001000000004000001000000000000000800040010000020100000000400000010000000000000000040000000000000040000000000000000000000000000000400002400000000000000000000000000000004000004000000000000840000000800000080010004000000001000000800000000000000000000000000000000000800000000000040000000020000000000000000000800000400000000000000000000000600000400000000002000000000000000000000004000000000000000100000000000000000000000000000000000040000900010000000'
+          transactionsRoot: '0x4d0c8e91e16bdff538c03211c5c73632ed054d00a7e210c0eb25146c20048126'
+          stateRoot: '0x91309efa7e42c1f137f31fe9edbe88ae087e6620d0d59031324da3e2f4f93233'
+          receiptsRoot: '0x68461ab700003503a305083630a8fb8d14927238f0bc8b6b3d246c0c64f21f4a'
+          miner: '0xb42b6c4a95406c78ff892d270ad20b22642e102d'
+          difficulty: '0x66e619a'
+          totalDifficulty: '0x1e875d746ae'
+          extraData: '0xd583010502846765746885676f312e37856c696e7578'
+          size: '0x334'
+          gasLimit: '0x47e7c4'
+          gasUsed: '0x37993'
+          timestamp: '0x5835c54d'
+          uncles: []
+          transactions:
+            - '0xa0807e117a8dd124ab949f460f08c36c72b710188f01609595223b325e58e0fc'
+            - '0xeae6d797af50cb62a596ec3939114d63967c374fa57de9bc0f4e2b576ed6639d'
+          baseFeePerGas: '0x7'
+          withdrawalsRoot: '0x7a4ecf19774d15cf9c15adf0dd8e8a250c128b26c9e2ab2a08d6c9c8ffbd104f'
+          withdrawals:
+            - index: '0x0'
+              validatorIndex: '0x9d8c0'
+              address: '0xb9d7934878b5fb9610b3fe8a5e441e8fad7e293f'
+              amount: '0x11a33e3760'
+          blobGasUsed: '0x0'
+          excessBlobGas: '0x0'
+          parentBeaconBlockRoot: '0x95c4dbd5b19f6fe3cbc3183be85ff4e85ebe75c5b4fc911f1c91e5b7a554a685'
 - name: eth_getBlockByNumber
   summary: Returns information about a block by number.
   params:
@@ -34,6 +76,48 @@
       oneOf:
         - $ref: '#/components/schemas/notFound'
         - $ref: '#/components/schemas/Block'
+  examples:
+    - name: eth_getBlockByNumber example
+      params:
+        - name: block
+          value: '0x68B3'
+        - name: Hydrated transactions
+          value: false
+      result:
+        name: Block information
+        value:
+          number: '0x68b3'
+          hash: '0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c'
+          mixHash: '0x24900fb3da77674a861c428429dce0762707ecb6052325bbd9b3c64e74b5af9d'
+          parentHash: '0x1f68ac259155e2f38211ddad0f0a15394d55417b185a93923e2abe71bb7a4d6d'
+          nonce: '0x378da40ff335b070'
+          sha3Uncles: '0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347'
+          logsBloom: '0x00000000000000100000004080000000000500000000000000020000100000000800001000000004000001000000000000000800040010000020100000000400000010000000000000000040000000000000040000000000000000000000000000000400002400000000000000000000000000000004000004000000000000840000000800000080010004000000001000000800000000000000000000000000000000000800000000000040000000020000000000000000000800000400000000000000000000000600000400000000002000000000000000000000004000000000000000100000000000000000000000000000000000040000900010000000'
+          transactionsRoot: '0x4d0c8e91e16bdff538c03211c5c73632ed054d00a7e210c0eb25146c20048126'
+          stateRoot: '0x91309efa7e42c1f137f31fe9edbe88ae087e6620d0d59031324da3e2f4f93233'
+          receiptsRoot: '0x68461ab700003503a305083630a8fb8d14927238f0bc8b6b3d246c0c64f21f4a'
+          miner: '0xb42b6c4a95406c78ff892d270ad20b22642e102d'
+          difficulty: '0x66e619a'
+          totalDifficulty: '0x1e875d746ae'
+          extraData: '0xd583010502846765746885676f312e37856c696e7578'
+          size: '0x334'
+          gasLimit: '0x47e7c4'
+          gasUsed: '0x37993'
+          timestamp: '0x5835c54d'
+          uncles: [ ]
+          transactions:
+            - '0xa0807e117a8dd124ab949f460f08c36c72b710188f01609595223b325e58e0fc'
+            - '0xeae6d797af50cb62a596ec3939114d63967c374fa57de9bc0f4e2b576ed6639d'
+          baseFeePerGas: '0x7'
+          withdrawalsRoot: '0x7a4ecf19774d15cf9c15adf0dd8e8a250c128b26c9e2ab2a08d6c9c8ffbd104f'
+          withdrawals:
+            - index: '0x0'
+              validatorIndex: '0x9d8c0'
+              address: '0xb9d7934878b5fb9610b3fe8a5e441e8fad7e293f'
+              amount: '0x11a33e3760'
+          blobGasUsed: '0x0'
+          excessBlobGas: '0x0'
+          parentBeaconBlockRoot: '0x95c4dbd5b19f6fe3cbc3183be85ff4e85ebe75c5b4fc911f1c91e5b7a554a685'
 - name: eth_getBlockTransactionCountByHash
   summary: Returns the number of transactions in a block from a block matching the given block hash.
   params:
@@ -47,6 +131,14 @@
         - $ref: '#/components/schemas/notFound'
         - title: Transaction count
           $ref: '#/components/schemas/uint'
+  examples:
+    - name: eth_getBlockTransactionCountByHash example
+      params:
+        - name: Block hash
+          value: '0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238'
+      result:
+        name: Transaction count
+        value: '0x8'
 - name: eth_getBlockTransactionCountByNumber
   summary: Returns the number of transactions in a block matching the given block number.
   params:
@@ -60,6 +152,14 @@
         - $ref: '#/components/schemas/notFound'
         - title: Transaction count
           $ref: '#/components/schemas/uint'
+  examples:
+    - name: eth_getBlockTransactionCountByNumber example
+      params:
+        - name: Block
+          value: '0xe8'
+      result:
+        name: Transaction count
+        value: '0x8'
 - name: eth_getUncleCountByBlockHash
   summary: Returns the number of uncles in a block from a block matching the given block hash.
   params:
@@ -73,6 +173,14 @@
         - $ref: '#/components/schemas/notFound'
         - title: Uncle count
           $ref: '#/components/schemas/uint'
+  examples:
+    - name: eth_getUncleCountByBlockHash example
+      params:
+        - name: Block hash
+          value: '0xb3b20624f8f0f86eb50dd04688409e5cea4bd02d700bf6e79e9384d47d6a5a35'
+      result:
+        name: Uncle count
+        value: '0x1'
 - name: eth_getUncleCountByBlockNumber
   summary: Returns the number of transactions in a block matching the given block number.
   params:
@@ -86,6 +194,14 @@
         - $ref: '#/components/schemas/notFound'
         - title: Uncle count
           $ref: '#/components/schemas/uint'
+  examples:
+    - name: eth_getUncleCountByBlockNumber example
+      params:
+        - name: Block
+          value: '0xe8'
+      result:
+        name: Uncle count
+        value: '0x1'
 - name: eth_getBlockReceipts
   summary: Returns the receipts of a block by number or hash.
   params:
@@ -102,3 +218,56 @@
           type: array
           items:
             $ref: '#/components/schemas/ReceiptInfo'
+  examples:
+    - name: eth_getBlockReceipts example
+      params:
+        - name: Block
+          value: 'latest'
+      result:
+        name: Receipts information
+        value:
+          - blockHash: '0x19514ce955c65e4dd2cd41f435a75a46a08535b8fc16bc660f8092b32590b182'
+            blockNumber: '0x6f55'
+            contractAddress: null
+            cumulativeGasUsed: '0x18c36'
+            from: '0x22896bfc68814bfd855b1a167255ee497006e730'
+            gasUsed: '0x18c36'
+            blobGasUsed: '0x20000'
+            effectiveGasPrice: '0x9502f907'
+            blobGasPrice: '0x32'
+            logs:
+              - address: '0xfd584430cafa2f451b4e2ebcf3986a21fff04350'
+                topics:
+                  - '0x2f8788117e7eff1d82e926ec794901d17c78024a50270940304540a733656f0d'
+                  - '0x4be29e0e4eb91f98f709d98803cba271592782e293b84a625e025cbb40197ba8'
+                  - '0x000000000000000000000000835281a2563db4ebf1b626172e085dc406bfc7d2'
+                  - '0x00000000000000000000000022896bfc68814bfd855b1a167255ee497006e730'
+                data: '0x'
+                blockNumber: '0x6f55'
+                transactionHash: '0x4a481e4649da999d92db0585c36cba94c18a33747e95dc235330e6c737c6f975'
+                transactionIndex: '0x0'
+                blockHash: '0x19514ce955c65e4dd2cd41f435a75a46a08535b8fc16bc660f8092b32590b182'
+                logIndex: '0x0'
+                removed: false
+            logsBloom: '0x00000004000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000200000000000000000000080020000000000000200010000000000000000000001000000800000000000000000000000000000000000000000000000000000100100000000000000000000008000000000000000000000000000000002000000000000000000000'
+            status: '0x1'
+            to: '0xfd584430cafa2f451b4e2ebcf3986a21fff04350'
+            transactionHash: '0x4a481e4649da999d92db0585c36cba94c18a33747e95dc235330e6c737c6f975'
+            transactionIndex: '0x0'
+            type: '0x0'
+          - blockHash: '0x19514ce955c65e4dd2cd41f435a75a46a08535b8fc16bc660f8092b32590b182'
+            blockNumber: '0x6f55'
+            contractAddress: null
+            cumulativeGasUsed: '0x1de3e'
+            from: '0x712e3a792c974b3e3dbe41229ad4290791c75a82'
+            gasUsed: '0x5208'
+            blobGasUsed: '0x20000'
+            effectiveGasPrice: '0x9502f907'
+            blobGasPrice: '0x32'
+            logs: []
+            logsBloom: '0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000'
+            status: '0x1'
+            to: '0xd42e2b1c14d02f1df5369a9827cb8e6f3f75f338'
+            transactionHash: '0xefb83b4e3f1c317e8da0f8e2fbb2fe964f34ee184466032aeecac79f20eacaf6'
+            transactionIndex: '0x1'
+            type: '0x2'

src/eth/client.yaml

@@ -5,20 +5,41 @@
     name: Chain ID
     schema:
       $ref: '#/components/schemas/uint'
+  examples:
+    - name: eth_chainId example
+      params: []
+      result:
+        name: Chain ID
+        value: '0x1'
 - name: eth_syncing
   summary: Returns an object with data about the sync status or false.
   params: []
   result:
     name: Syncing status
     schema:
       $ref: '#/components/schemas/SyncingStatus'
+  examples:
+    - name: eth_syncing example
+      params: []
+      result:
+        name: Syncing status
+        value:
+          startingBlock: '0x0'
+          currentBlock: '0x1518'
+          highestBlock: '0x9567a3'
 - name: eth_coinbase
   summary: Returns the client coinbase address.
   params: []
   result:
     name: Coinbase address
     schema:
       $ref: '#/components/schemas/address'
+  examples:
+    - name: eth_coinbase example
+      params: []
+      result:
+        name: Coinbase address
+        value: '0xfe3b557e8fb62b89f4916b721be55ceb828dbd73'
 - name: eth_accounts
   summary: Returns a list of addresses owned by client.
   params: []
@@ -29,10 +50,23 @@
       type: array
       items:
         $ref: '#/components/schemas/address'
+  examples:
+    - name: eth_accounts example
+      params: []
+      result:
+        name: Accounts
+        value:
+          - '0xd1f5279be4b4dd94133a23dee1b23f5bfc0db1d0'
 - name: eth_blockNumber
   summary: Returns the number of most recent block.
   params: []
   result:
     name: Block number
     schema:
       $ref: '#/components/schemas/uint'
+  examples:
+    - name: eth_blockNumber example
+      params: []
+      result:
+        name: Block number
+        value: '0x2377'