Update API documentation (#958)

* Update API documentation Signed-off-by: Roland Tyler <roland.tyler@consensys.net> * Space Signed-off-by: Roland Tyler <roland.tyler@consensys.net> * Review feedback Signed-off-by: Roland Tyler <roland.tyler@consensys.net> * Additional feedback Signed-off-by: Roland Tyler <roland.tyler@consensys.net> * Add additional example, clarify address parameter Signed-off-by: Roland Tyler <roland.tyler@consensys.net> * description feedback Signed-off-by: Roland Tyler <roland.tyler@consensys.net> * team feedback Signed-off-by: Roland Tyler <roland.tyler@consensys.net>
3 years ago · 9f5718149e
parent 27c600fb53
commit 9f5718149e
2 changed files with 287 additions and 3 deletions
--- a/docs/Reference/API-Methods.md
+++ b/docs/Reference/API-Methods.md
@ -787,6 +787,90 @@ We recommend using the [`TRACE` API](#trace-methods) for production use over the
    methods, use the [`--rpc-http-api`](CLI/CLI-Syntax.md#rpc-http-api) or
    [`--rpc-ws-api`](CLI/CLI-Syntax.md#rpc-ws-api) options.

+### `debug_accountAt`
+
+Returns account information at the specified index of the specified block.
+
+#### Parameters
+
+* `blockHashOrNumber`: *string* - block hash or number at which to retrieve account information
+
+* `txIndex`: *number* - transaction index at which to retrieve account information
+
+* `address`: *string* - contract or account address for which to retrieve information
+
+#### Returns
+
+`result`: *object* - account details object with the following fields:
+
+* `code`: *data* - code for the account. Displays `0x0` if the address is an externally owned account.
+
+* `nonce`: *quantity* - number of transactions made by the account before this one
+
+* `balance`: *quantity* - balance of the account in Wei
+
+* `codehash`: *data* - code hash for the account
+
+!!! example
+
+    This example uses an externally owned account address for the `address` parameter.
+
+    === "curl HTTP request"
+
+        ```bash
+        curl -X POST --data '{"jsonrpc":"2.0","method":"debug_accountAt","params":["0xc8df1f061abb4d0c107b2b1a794ade8780b3120e681f723fe55a7be586d95ba6", 0, "0xbcde5374fce5edbc8e2a8697c15331677e6ebf0b"],"id":1}' http://127.0.0.1:8545
+        ```
+
+    === "wscat WS request"
+
+        ```bash
+        {"jsonrpc":"2.0","method":"debug_accountAt","params":["0xc8df1f061abb4d0c107b2b1a794ade8780b3120e681f723fe55a7be586d95ba6", 0, "0xbcde5374fce5edbc8e2a8697c15331677e6ebf0b"],"id":1}
+        ```
+
+    === "JSON result"
+
+        ```json
+        {
+          "jsonrpc": "2.0",
+          "id": 1,
+          "result": {
+            "code": "0x0",
+            "nonce": "0x5",
+            "balance": "0xad78ebc5ac6200000",
+            "codehash" : "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470"
+          }
+        }
+        ```
+
+    This example uses a contract address for the `address` parameter.
+
+    === "curl HTTP request"
+
+        ```bash
+        curl -X POST --data '{"jsonrpc":"2.0","method":"debug_accountAt","params":["0x2b76b3a2fc44c0e21ea183d06c846353279a7acf12abcc6fb9d5e8fb14ae2f8c", 0, "0x0e0d2c8f7794e82164f11798276a188147fbd415"],"id":1}' http://127.0.0.1:8545
+        ```
+
+    === "wscat WS request"
+
+        ```bash
+        {"jsonrpc":"2.0","method":"debug_accountAt","params":["0x2b76b3a2fc44c0e21ea183d06c846353279a7acf12abcc6fb9d5e8fb14ae2f8c", 0, "0x0e0d2c8f7794e82164f11798276a188147fbd415"],"id":1}
+        ```
+
+    === "JSON result"
+
+        ```json
+        {
+          "jsonrpc": "2.0",
+          "id": 1,
+          "result": {
+            "code": "0x608060405234801561001057600080fd5b506004361061002b5760003560e01c8063b27b880414610030575b600080fd5b61004a60048036038101906100459190610108565b61004c565b005b60606000806000604051935036600085376000803686885af490503d9150816000853e806000811461007d57610093565b60008311156100925761012085019350836040525b5b5060008114156100ec578473ffffffffffffffffffffffffffffffffffffffff167f410d96db3f80b0f89b36888c4d8a94004268f8d42309ac39b7bcba706293e099856040516100e3919061016e565b60405180910390a25b5050505050565b60008135905061010281610227565b92915050565b60006020828403121561011e5761011d610211565b5b600061012c848285016100f3565b91505092915050565b600061014082610190565b61014a818561019b565b935061015a8185602086016101de565b61016381610216565b840191505092915050565b600060208201905081810360008301526101888184610135565b905092915050565b600081519050919050565b600082825260208201905092915050565b60006101b7826101be565b9050919050565b600073ffffffffffffffffffffffffffffffffffffffff82169050919050565b60005b838110156101fc5780820151818401526020810190506101e1565b8381111561020b576000848401525b50505050565b600080fd5b6000601f19601f8301169050919050565b610230816101ac565b811461023b57600080fd5b5056fea2646970667358221220fdfb5c371055342507b8fb9ca7b0c234f79819bd5cb05c0d467fb605de979eb564736f6c63430008060033",
+            "nonce": "0x1",
+            "balance": "0x0",
+            "codehash" : "0xf5f334d41776ed2828fc910d488a05c57fe7c2352aab2d16e30539d7726e1562"
+          }
+        }
+        ```
+
 ### `debug_accountRange`

 [Retesteth](https://github.com/ethereum/retesteth/wiki/Retesteth-Overview) uses
@ -796,9 +880,9 @@ Returns the accounts for a specified block.

 #### Parameters

-* `blockHashOrNumber`: *string* - block hash or number
+* `blockHashOrNumber`: *string* - block hash or number at which to retrieve account information

-* `txIndex`: *number* - transaction index from which to start
+* `txIndex`: *number* - transaction index at which to retrieve account information

 * `address`: *string* - address hash from which to start

@ -5105,10 +5189,51 @@ command line option.
        }
        ```

+### `miner_setCoinbase`
+
+Sets the coinbase, the address for the mining rewards.
+
+!!! note
+
+    You can also use `miner_setEtherbase` as an alternative method. They both work the same way.
+    Etherbase is a historic name for coinbase.
+
+#### Parameters
+
+`coinbase`: *string* - Account address you pay mining rewards to
+
+#### Returns
+
+`result`: *boolean* - `true` when address is set
+
+!!! example
+
+    === "curl HTTP request"
+
+        ```bash
+        curl -X POST --data '{"jsonrpc":"2.0","method":"miner_setCoinbase","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73"],"id":1}' http://127.0.0.1:8545
+        ```
+
+    === "wscat WS request"
+
+        ```bash
+        {"jsonrpc":"2.0","method":"miner_setCoinbase","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73"],"id":1}
+        ```
+
+    === "JSON result"
+
+        ```json
+        {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "result": true
+        }
+        ```
+
 ### `miner_start`

 Starts the mining process. To start mining, you must first specify a miner coinbase using the
-[`--miner-coinbase`](CLI/CLI-Syntax.md#miner-coinbase) command line option.
+[`--miner-coinbase`](CLI/CLI-Syntax.md#miner-coinbase) command line option or using [`miner_setCoinbase`](#miner_setcoinbase).

 #### Parameters

@ -7052,6 +7177,152 @@ the returned list items include the [revert reason](../HowTo/Send-Transactions/R
          }
        ```

+### `trace_call`
+
+Executes the given call and returns a number of possible traces for it.
+
+#### Parameters
+
+* `call`: *object* - [transaction call object](API-Objects.md#transaction-call-object)
+
+* `blockNumber`: *string* - integer representing a block number or one of the string tags `latest`,
+`earliest`, or `pending`, as described in
+[Block Parameter](../HowTo/Interact/APIs/Using-JSON-RPC-API.md#block-parameter)
+
+* `options`: *array* of *strings* - list of tracing options; tracing options are
+[`trace`, `vmTrace`, and `stateDiff`](Trace-Types.md). Specify any
+combination of the three options including none of them.
+
+#### Returns
+
+`result`: *array* of *objects* - list of [calls to other contracts](Trace-Types.md#trace) containing
+one object per call, in transaction execution order
+
+!!! example
+
+    === "curl HTTP request"
+
+        ```bash
+        curl -X POST --data '{"jsonrpc":"2.0","method":"trace_call","params":[{"from":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73","to":0x0010000000000000000000000000000000000000","gas":"0xfffff2","gasPrice":"0xef","value":"0x0","data":"0x0000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000002","nonce":"0x0"}["trace"],"latest"],"id":1}' http://127.0.0.1:8545
+        ```
+
+    === "wscat WS request"
+
+        ```bash
+        {"jsonrpc":"2.0","method":"trace_call","params":[{"from":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73","to":0x0010000000000000000000000000000000000000","gas":"0xfffff2","gasPrice":"0xef","value":"0x0","data":"0x0000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000002","nonce":"0x0"}["trace"],"latest"],"id":1}
+        ```
+
+    === "JSON result"
+
+        ```json
+        {
+            "jsonrpc": "2.0",
+            "result": {
+              "output" : "0x",
+              "stateDiff" : null,
+              "trace" : [ {
+                "action" : {
+                  "callType" : "call",
+                  "from" : "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73",
+                  "gas" : "0xffabba",
+                  "input" : "0x0000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000002",
+                  "to" : "0x0010000000000000000000000000000000000000",
+                  "value" : "0x0"
+              },
+              "result" : {
+                "gasUsed" : "0x9c58",
+                "output" : "0x"
+              },
+              "subtraces" : 0,
+              "traceAddress" : [ ],
+              "type" : "call"
+            } ],
+            "vmTrace" : null
+            },
+        "id" : 2
+        },
+        ```
+
+### `trace_filter`
+
+Returns traces matching the specified filter.
+
+#### Parameters
+
+`traceFilterOptions`: *object* - [trace filter options object](API-Objects.md#trace-filter-options-object)
+
+#### Returns
+
+`result`: *array* of *objects* - list of [calls to other contracts](Trace-Types.md#trace) containing
+one object per call, in transaction execution order
+
+!!! example
+
+    === "curl HTTP request"
+
+        ```bash
+        curl -X POST --data '{"jsonrpc":"2.0","method":"trace_filter","params":[{"fromBlock":"0x1","toBlock":"0x21","after":2,"count":2,"fromAddress":["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73"]}],"id":415}' http://127.0.0.1:8545
+        ```
+
+    === "wscat WS request"
+
+        ```bash
+        {"jsonrpc":"2.0","method":"trace_filter","params":[{"fromBlock":"0x1","toBlock":"0x21","after":2,"count":2,"fromAddress":["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73"]}],"id":415}
+        ```
+
+    === "JSON result"
+
+        ```json
+        {
+            "jsonrpc": "2.0",
+            "result": [
+              {
+                "action": {
+                  "callType": "call",
+                  "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73",
+                  "gas": "0xffad82",
+                  "input": "0x0000000000000000000000000000000000000999",
+                  "to": "0x0020000000000000000000000000000000000000",
+                  "value": "0x0"
+                },
+                "blockHash": "0xcd5d9c7acdcbd3fb4b24a39e05a38e32235751bb0c9e4f1aa16dc598a2c2a9e4",
+                "blockNumber": 6,
+                "result": {
+                  "gasUsed": "0x7536",
+                  "output": "0x"
+                },
+                "subtraces": 1,
+                "traceAddress": [],
+                "transactionHash": "0x91eeabc671e2dd2b1c8ddebb46ba59e8cb3e7d189f80bcc868a9787728c6e59e",
+                "transactionPosition": 0,
+                "type": "call"
+              },
+              {
+                "action": {
+                  "callType": "call",
+                  "from": "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73",
+                  "gas": "0xffad52",
+                  "input": "0xf000000000000000000000000000000000000000000000000000000000000001",
+                  "to": "0x0030000000000000000000000000000000000000",
+                  "value": "0x0"
+                },
+                "blockHash": "0xeed85fe57db751442c826cfe4fdf43b10a5c2bc8b6fd3a8ccced48eb3fb35885",
+                "blockNumber": 7,
+                "result": {
+                  "gasUsed": "0x1b",
+                  "output": "0xf000000000000000000000000000000000000000000000000000000000000002"
+                },
+                "subtraces": 0,
+                "traceAddress": [],
+                "transactionHash": "0x47f4d445ea1812cb1ddd3464ab23d2bfc6ed408a8a9db1c497f94e8e06e85286",
+                "transactionPosition": 0,
+                "type": "call"
+              }
+            ],
+            "id": 415
+        }
+        ```
+
 ### `trace_replayBlockTransactions`

 Provides transaction processing tracing per block.
--- a/docs/Reference/API-Objects.md
+++ b/docs/Reference/API-Objects.md
@ -181,6 +181,19 @@ Returned by [`debug_traceBlock`](API-Methods.md#debug_traceblock),
 | **returnValue** | String  | Bytes returned from transaction execution (without a `0x` prefix). |
 | **structLogs**  | Array   | Array of structured log objects.                                   |

+## Trace filter options object
+
+Parameter for [`trace_filter`](API-Methods.md#trace_filter). All parameters are optional.
+
+| Key | Type | Value |
+|-----|:----:|-------|
+| **fromBLock**   | String &#124; Tag | Trace starts at this block.                        |
+| **toBlock**     | String &#124; Tag | Trace stops at this block.                         |
+| **fromAddress** | String            | Include only traces sent from this address.        |
+| **toAddress**   | String            | Include only traces with this destination address. |
+| **after**       | Quantity          | The offset trace number.                           |
+| **count**       | Integer           | Number of traces to display in a batch.            |
+
 ## Transaction object

 Returned by [`eth_getTransactionByHash`](API-Methods.md#eth_gettransactionbyhash),