Merge pull request #572 from chainstack/feature/ethereum-api-new-methods

Feature/ethereum api new methods
chainstack · Dec 2, 2022 · 58dd4f1 · 58dd4f1
2 parents de3a4a5 + f687216
commit 58dd4f1
Show file tree

Hide file tree

Showing 76 changed files with 2,112 additions and 823 deletions.
diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-3.8.5+{BUILD_NUM}
+3.8.6+{BUILD_NUM}
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -492,6 +492,11 @@ module.exports = {
             collapsable: true,
             children: [
               "api/ethereum/ethereum-api-reference",
+              "api/ethereum/deploy-your-ethereum-node-to-enable-debug-and-trace-api-methods",
+              "api/ethereum/debug_traceBlockByHash",
+              "api/ethereum/debug_traceBlockByNumber",
+              "api/ethereum/debug_traceCall",
+              "api/ethereum/debug_traceTransaction",
               "api/ethereum/eth_blocknumber",
               "api/ethereum/eth_call",
               "api/ethereum/eth_chainid",
@@ -500,6 +505,7 @@ module.exports = {
               "api/ethereum/eth_getbalance",
               "api/ethereum/eth_getblockbyhash",
               "api/ethereum/eth_getblockbynumber",
+              "api/ethereum/eth_getBlockReceipts",
               "api/ethereum/eth_getblocktransactioncountbyhash",
               "api/ethereum/eth_getblocktransactioncountbynumber",
               "api/ethereum/eth_getcode",
@@ -549,6 +555,16 @@ module.exports = {
               "api/ethereum/eth_v1_node_version",
               "api/ethereum/eth_v1_node_syncing",
               "api/ethereum/eth_v1_node_health",
+              "api/ethereum/trace_block",
+              "api/ethereum/trace_call",
+              "api/ethereum/trace_callMany",
+              "api/ethereum/trace_filter",
+              "api/ethereum/trace_replayBlockTransactions",
+              "api/ethereum/trace_replayTransaction",
+              "api/ethereum/trace_transaction",
+              "api/ethereum/txpool_content",
+              "api/ethereum/txpool_inspect",
+              "api/ethereum/txpool_status",
             ],
           },
           {

diff --git a/docs/api/ethereum/debug_traceBlockByHash.md b/docs/api/ethereum/debug_traceBlockByHash.md
@@ -0,0 +1,62 @@
+---
+meta:
+  - name: description
+    content: debug_traceBlockByHash JSON-RPC method details and code examples.
+  - name: keywords
+    content: json rpc methods curl api web3.py web3.js eth.rb javascript python ruby ethereum debug trace
+---
+
+# Ethereum debug_traceBlockByHash RPC method
+
+Ethereum API method that replays the block that is already present in the database.
+
+::: tip Information
+
+Learn [how to deploy](/api/ethereum/deploy-your-ethereum-node-to-enable-debug-and-trace-api-methods) a node with the debug and trace API methods enabled.
+
+:::
+
+**Parameters:**
+
+* `hash` — the hash of the block to be traced.
+
+**Returns:**
+
+* `array` — the block traces that have the following object shape (all return types are hexadecimal representations of their data type unless otherwise stated):
+* `results` — the trace object with:
+  * `calls` — the array of transactions in the block with:
+  * `from` — the address of the sender.
+  * `gas` — the quantity of the gas provided for the call, encoded as hexadecimal.
+  * `gas used` — the quantity of the gas used for the call, encoded as hexadecimal.
+  * `input` — the call data.
+  * `output` — the return data.
+  * `to` — the address of the receiver. `null` if it is a contract creation transaction.
+  * `type` — the type of the transaction, can be `CALL` or `CREATE`.
+  * `value` — the amount of value for the transfer, encoded as hexadecimal.
+
+**Example:**
+
+<CodeSwitcher :languages="{py:'web3.py', cr:'cURL'}">
+
+<template v-slot:py>
+
+``` py
+from web3 import Web3
+node_url = "CHAINSTACK_NODE_URL"
+web3 = Web3.HTTPProvider(node_url)
+
+debug = web3.make_request('debug_traceBlockByHash', ['0x02409f8fcc7944a10903840ce1afb1df4559aba8c82ec6849f99b3a8cd3d7490', {'tracer': 'callTracer'}])
+print(debug)
+```
+
+</template>
+<template v-slot:cr>
+
+``` sh
+curl -X POST "CHAINSTACK_NODE_URL" \
+  -H 'Content-Type: application/json' \
+  --data '{"method":"debug_traceBlockByHash","params":["0x02409f8fcc7944a10903840ce1afb1df4559aba8c82ec6849f99b3a8cd3d7490", {"tracer": "callTracer"}],"id":1,"jsonrpc":"2.0"}'
+```
+
+</template>
+</CodeSwitcher>
diff --git a/docs/api/ethereum/debug_traceBlockByNumber.md b/docs/api/ethereum/debug_traceBlockByNumber.md
@@ -0,0 +1,65 @@
+---
+meta:
+  - name: description
+    content: debug_traceBlockByNumber JSON-RPC method details and code examples.
+  - name: keywords
+    content: json rpc methods curl api web3.py web3.js eth.rb javascript python ruby ethereum debug trace
+---
+
+# Ethereum debug_traceBlockByNumber RPC method
+
+Ethereum API method that replays the block that is already present in the database.
+
+::: tip Information
+
+Learn [how to deploy](/api/ethereum/deploy-your-ethereum-node-to-enable-debug-and-trace-api-methods) a node with the debug and trace API methods enabled.
+
+:::
+
+**Parameters:**
+
+* `quantity or tag` — the integer block number, or the string with:
+  * `latest` — the latest block that is to be validated. The Beacon Chain may reorg and the latest block can become orphaned.
+  * `earliest` — the genesis block.
+  * `pending` — the pending state and transactions block.
+
+**Returns:**
+
+* `array` — the block traces that have the following object shape (all return types are hexadecimal representations of their data type unless otherwise stated):
+* `results` — the trace object with:
+  * `calls` — the array of transactions in the block with:
+    * `from` — the address of the sender.
+    * `gas` — the quantity of the gas provided for the call, encoded as hexadecimal.
+    * `gas used` — the quantity of the gas used for the call, encoded as hexadecimal.
+    * `input` — the call data.
+    * `output` — the return data.
+    * `to` — the address of the receiver. `null` if it is a contract creation transaction.
+    * `type` — the type of the transaction, can be `CALL` or `CREATE`.
+    * `value` — the amount of value for the transfer, encoded as hexadecimal.
+
+**Example:**
+
+<CodeSwitcher :languages="{py:'web3.py', cr:'cURL'}">
+
+<template v-slot:py>
+
+``` py
+from web3 import Web3
+node_url = "CHAINSTACK_NODE_URL"
+web3 = Web3.HTTPProvider(node_url)
+
+debug = web3.make_request('debug_traceBlockByNumber', ['0xF4031C', {'tracer': 'callTracer'}])
+print(debug)
+```
+
+</template>
+<template v-slot:cr>
+
+``` sh
+curl -X POST "CHAINSTACK_NODE_URL" \
+  -H 'Content-Type: application/json' \
+  --data '{"method":"debug_traceBlockByNumber","params":["0xF4031C", {"tracer": "callTracer"}],"id":1,"jsonrpc":"2.0"}'
+```
+
+</template>
+</CodeSwitcher>
diff --git a/docs/api/ethereum/debug_traceCall.md b/docs/api/ethereum/debug_traceCall.md
@@ -0,0 +1,71 @@
+---
+meta:
+  - name: description
+    content: debug_traceCall JSON-RPC method details and code examples.
+  - name: keywords
+    content: json rpc methods curl api web3.py web3.js eth.rb javascript python ruby ethereum debug trace
+---
+
+# Ethereum debug_traceCall RPC method
+
+Ethereum API method that lets you run `eth_call` on top of a block.
+
+::: tip Information
+
+Learn [how to deploy](/api/ethereum/deploy-your-ethereum-node-to-enable-debug-and-trace-api-methods) a node with the debug and trace API methods enabled.
+
+:::
+
+**Parameters:**
+
+* `object` — the transaction call object with:
+  * `from` — (optional) the string of the address the transaction is sent from.
+  * `to` — the string of the address to which the transaction is directed.
+  * `gas` — (optional) the integer of the gas provided for the transaction execution.
+  * `gasprice` — (optional) the integer of the gasPrice used for each paid gas, encoded as hexadecimal.
+  * `value` — (optional) the integer of the value sent with this transaction, encoded as hexadecimal.
+  * `data` — (optional) the string of the hash of the method signature and encoded parameters; see the [Ethereum Contract ABI](https://solidity.readthedocs.io/en/latest/abi-spec.html).
+  * `quantity or tag` — the integer block number, or the string with:
+    * `latest` — the latest block that is to be validated. The Beacon Chain may reorg and the latest block can become orphaned.
+    * `earliest` — the genesis block.
+    * `pending` — the pending state and transactions block.
+
+**Returns:**
+
+* `array` — the block traces, which have the following object shape (all return types are hexadecimal representations of their data type unless otherwise stated):
+* `results` — the trace object with:
+  * `failed` — the boolean transaction result: `true` if it failed, `false` if it was successful.
+  * `gas` — the quantity of the gas provided for the call, encoded as hexadecimal.
+  * `returnvalue` — data.
+  * `structlogs` — array with:
+    * `entries` — array.
+    * `storagesbydepth` — array.
+
+**Example:**
+
+<CodeSwitcher :languages="{py:'web3.py', cr:'cURL'}">
+
+<template v-slot:py>
+
+``` py
+from web3 import Web3
+node_url = "CHAINSTACK_NODE_URL"
+web3 = Web3.HTTPProvider(node_url)
+
+debug = web3.make_request('debug_traceCall', [{
+    "to": "0x690B9A9E9aa1C9dB991C7721a92d351Db4FaC990"
+    }, "latest"])
+print(debug)
+```
+
+</template>
+<template v-slot:cr>
+
+``` sh
+curl -X POST "CHAINSTACK_NODE_URL" \
+  -H 'Content-Type: application/json' \
+  --data '{"method":"debug_traceCall","params":[{"from":null,"to":"0x6b175474e89094c44da98b954eedeac495271d0f"}, "latest"],"id":1,"jsonrpc":"2.0"}'
+```
+
+</template>
+</CodeSwitcher>
diff --git a/docs/api/ethereum/debug_traceTransaction.md b/docs/api/ethereum/debug_traceTransaction.md
@@ -0,0 +1,59 @@
+---
+meta:
+  - name: description
+    content: debug_traceTransaction JSON-RPC method details and code examples.
+  - name: keywords
+    content: json rpc methods curl api web3.py web3.js eth.rb javascript python ruby ethereum debug trace
+---
+
+# Ethereum debug_traceTransaction RPC method
+
+Ethereum API method that returns all traces of the given transaction.
+
+::: tip Information
+
+Learn [how to deploy](/api/ethereum/deploy-your-ethereum-node-to-enable-debug-and-trace-api-methods) a node with the debug and trace API methods enabled.
+
+:::
+
+**Parameters:**
+
+* `hash` — the hash of a transaction.
+
+**Returns:**
+
+* `array` — the block traces, which have the following object shape (all return types are hexadecimal representations of their data type unless otherwise stated):
+* `results` — the trace object with:
+  * `failed` — the boolean transaction result: `true` if it failed, `false` if it was successful.
+  * `gas` — the quantity of the gas provided for the call, encoded as hexadecimal.
+  * `returnvalue` — data.
+  * `structlogs` — array with:
+    * `entries` — array.
+    * `storagesbydepth` — array.
+
+**Example:**
+
+<CodeSwitcher :languages="{py:'web3.py', cr:'cURL'}">
+
+<template v-slot:py>
+
+``` py
+from web3 import Web3
+node_url = "CHAINSTACK_NODE_URL"
+web3 = Web3.HTTPProvider(node_url)
+
+debug = web3.make_request('debug_traceTransaction', ['0x2b2156ca419a971b22385d27046c343a68fd289f3461f17afc0a4df21c2647f0'])
+print(debug)
+```
+
+</template>
+<template v-slot:cr>
+
+``` sh
+curl -X POST "CHAINSTACK_NODE_URL" \
+  -H 'Content-Type: application/json' \
+  --data '{"method":"debug_traceTransaction","params":["0x2b2156ca419a971b22385d27046c343a68fd289f3461f17afc0a4df21c2647f0"],"id":1,"jsonrpc":"2.0"}'
+```
+
+</template>
+</CodeSwitcher>
diff --git a/...api/ethereum/deploy-your-ethereum-node-to-enable-debug-and-trace-api-methods.md b/...api/ethereum/deploy-your-ethereum-node-to-enable-debug-and-trace-api-methods.md
@@ -0,0 +1,67 @@
+---
+meta:
+  - name: description
+    content: Learn how to deploy an Ethereum node that supports debug and trace API methods.
+  - name: keywords
+    content: ethereum debug trace namespaces json rpc methods node deploy
+---
+
+# Deploy your Ethereum node to enable debug and trace API methods
+
+## Introduction
+
+The debug and trace API methods are special RPC methods that allow you to replay transactions in the Ethereum Virtual Machine to get the execution details in the exact same way as they happened on the chain.
+
+To get the debug and trace API methods enabled on your Chainstack node, you must deploy a node of a certain configuration which will also depend on your [subscription plan](/platform/manage-your-organization-subscription-plan-and-support-level). Node configurations distribute between the subscription plans as follows:
+
+| API methods | Subscription plan | Node type | Node mode | Client |
+| ----------- | ----------------- | --------- | --------- | ------ |
+| `debug_*`   | Growth and higher | Dedicated | Full | Geth |
+| `debug_*`   | Growth and higher | Dedicated | Archive | Geth |
+| `debug_*` and `trace_*` | Growth and higher | Dedicated | Archive | Erigon |
+| `debug_*` and `trace_*` | Business and higher | Elastic | Archive | Erigon |
+
+## Deploy a dedicated Ethereum node for the debug and trace API methods
+
+Once you have [joined a public network](/platform/join-a-public-network#join-an-ethereum-network), deploy your dedicated Ethereum node with the `debug_*` or both `debug_*` and `trace_*` API methods enabled:
+
+1. Select the project with the network.
+1. Select the network.
+1. Click **Add node**.
+1. Provide a node name.
+1. Under **Type**, select **Dedicated**.
+1. Under **Mode**, select one of the following [modes](/operations/ethereum/modes):
+   * **Full** — will enable the `debug_*` API method on your node by default. With a full node, you will be able to query historical states for the immediately previous 128 blocks.
+   * **Archive** — with an archive node, you will be able to query historical states for the entire chain.
+1. Under **Hosting**, select **Chainstack**. See [Support hosting options](/platform/supported-hosting-options).
+1. For **Chainstack** hosting, select a cloud provider and a region.
+1. If you are deploying a dedicated archive node, under **Client**, select one of the following:
+   * **Geth** — to enable the `debug_*` API method on your node.
+   * **Erigon** — to enable both `debug_*` and `trace_*` API methods on your node.
+1. Review your changes and click **Send request**.
+
+Chainstack Sales team will reach out to your shortly.
+
+## Deploy an elastic Ethereum node for the debug and trace APIs methods
+
+Once you have [joined a public network](/platform/join-a-public-network#join-an-ethereum-network), deploy your elastic Ethereum node with both `debug_*` and `trace_*` API methods enabled:
+
+1. Select the project with the network.
+1. Select the network.
+1. Click **Add node**.
+1. Provide a node name.
+1. Under **Type**, select **Elastic**.
+1. Under **Mode**, select **Archive**. With an archive node, you will be able to query historical states for the entire chain.
+1. Under **Debug and trace APIs**, select **On**.
+1. Under **Hosting**, select **Chainstack**.
+1. For Chainstack hosting, select a cloud provider and a region.
+1. Review your changes and click **Add node**.
+
+The node status will change from **Pending** to **Running** once deployed. You will also see the **Debug and trace** tag next to the node name.
+
+::: tip See also
+
+* [Ethereum API reference](/api/ethereum/ethereum-api-reference)
+* [Operations: Ethereum](/operations/ethereum)
+
+:::