diff --git a/content/docs/interacting_with_geth/JavaScript-Console.md b/content/docs/interacting_with_geth/JavaScript-Console.md index db4e49d0f8..fdd5746c84 100644 --- a/content/docs/interacting_with_geth/JavaScript-Console.md +++ b/content/docs/interacting_with_geth/JavaScript-Console.md @@ -1,6 +1,6 @@ --- title: JavaScript Console -sort_key: D +description: How to interact with Geth using Javascript --- Geth responds to instructions encoded as JSON objects as defined in the [JSON-RPC-API](/docs/rpc/server). A Geth user can send these instructions directly, for example over HTTP using tools like [Curl](https://github.com/curl/curl). The code snippet below shows a request for an account balance sent to a local Geth node with the HTTP port `8545` exposed. diff --git a/content/docs/interacting_with_geth/RPC/batch.md b/content/docs/interacting_with_geth/RPC/batch.md index 4b60c6622d..f978a5b9b3 100644 --- a/content/docs/interacting_with_geth/RPC/batch.md +++ b/content/docs/interacting_with_geth/RPC/batch.md @@ -1,6 +1,6 @@ --- title: Batch requests -sort_key: C +description: How to make batch requests using JSON-RPC API --- The JSON-RPC [specification](https://www.jsonrpc.org/specification#batch) outlines how clients can send multiple requests at the same time by filling the request objects in an array. This feature is implemented by Geth's API and can be used to cut network delays. Batching offers visible speed-ups specially when used for fetching larger amounts of mostly independent data objects. Below is an example for fetching a list of blocks in JS: diff --git a/content/docs/interacting_with_geth/RPC/graphql.md b/content/docs/interacting_with_geth/RPC/graphql.md index 1abf0a9853..d5a8d22982 100644 --- a/content/docs/interacting_with_geth/RPC/graphql.md +++ b/content/docs/interacting_with_geth/RPC/graphql.md @@ -1,9 +1,9 @@ --- title: GraphQL Server -sort_key: C +description: Documentation for Geth's GraphQL API --- -In addition to the [JSON-RPC APIs](../rpc/server), Geth supports the GraphQL API as specified by [EIP-1767](eip-1767). GraphQL lets you specify which fields of an objects you need as part of the query, eliminating the extra load on the client for filling in fields which are not needed. It also allows for combining several traditional JSON-RPC requests into one query which translates into less overhead and more performance. +In addition to the [JSON-RPC APIs](/content/docs/interacting_with_geth/RPC/server.md), Geth supports the GraphQL API as specified by [EIP-1767](https://eips.ethereum.org/EIPS/eip-1767). GraphQL lets you specify which fields of an objects you need as part of the query, eliminating the extra load on the client for filling in fields which are not needed. It also allows for combining several traditional JSON-RPC requests into one query which translates into less overhead and more performance. The GraphQL endpoint piggybacks on the HTTP transport used by JSON-RPC. Hence the relevant `--http` flags and the `--graphql` flag should be passed to Geth: @@ -31,7 +31,7 @@ GraphiQL also provides a way to explore the schema Geth provides to help you for ### Query -Reading out data from Geth is the biggest use-case for GraphQL. In addition to using the UI queries can also be sent programmatically. The official GraphQL[docs](graphql-code) explain how to find bindings for many languages, or send http requests from the terminal using tools such as Curl. +Reading out data from Geth is the biggest use-case for GraphQL. In addition to using the UI queries can also be sent programmatically. The official GraphQL[docs](https://graphql.org/code/) explain how to find bindings for many languages, or send http requests from the terminal using tools such as Curl. For example, the code snippet below shows how to obtain the latest block number using Curl. Note the use of a JSON object for the data section: @@ -61,5 +61,3 @@ request('http://localhost:8545/graphql', query, { number: '6004067' }) .catch((err) => { console.log(err) }) ``` -[eip-1767]: https://eips.ethereum.org/EIPS/eip-1767 -[graphql-code]: https://graphql.org/code/ diff --git a/content/docs/interacting_with_geth/RPC/ns-admin.md b/content/docs/interacting_with_geth/RPC/ns-admin.md index a545a226d9..d54584f5ef 100644 --- a/content/docs/interacting_with_geth/RPC/ns-admin.md +++ b/content/docs/interacting_with_geth/RPC/ns-admin.md @@ -1,6 +1,6 @@ --- title: admin Namespace -sort_key: C +description: Documentation for the JSON-RPC API "admin" namespace --- The `admin` API gives access to several non-standard RPC methods, which allows fine grained control over a Geth instance, including but not limited to network peer and RPC endpoint management. @@ -8,13 +8,9 @@ The `admin` API gives access to several non-standard RPC methods, which allows f ### admin_addPeer -The `addPeer` administrative method requests adding a new remote node to the list of tracked static -nodes. The node will try to maintain connectivity to these nodes at all times, reconnecting every -once in a while if the remote connection goes down. +The `addPeer` administrative method requests adding a new remote node to the list of tracked static nodes. The node will try to maintain connectivity to these nodes at all times, reconnecting every once in a while if the remote connection goes down. -The method accepts a single argument, the [`enode`](https://ethereum.org/en/developers/docs/networking-layer/network-addresses/#enode) -URL of the remote peer to start tracking and returns a `BOOL` indicating whether the peer was accepted -for tracking or some error occurred. +The method accepts a single argument, the [`enode`](https://ethereum.org/en/developers/docs/networking-layer/network-addresses/#enode) URL of the remote peer to start tracking and returns a `BOOL` indicating whether the peer was accepted for tracking or some error occurred. | Client | Method invocation | |:--------|------------------------------------------------| @@ -31,10 +27,7 @@ true ### admin_addTrustedPeer -Adds the given node to a reserved trusted list which allows the -node to always connect, even if the slots are full. - -It returns a `BOOL` to indicate whether the peer was successfully added to the list. +Adds the given node to a reserved trusted list which allows the node to always connect, even if the slots are full. It returns a `BOOL` to indicate whether the peer was successfully added to the list. | Client | Method invocation | |:--------|------------------------------------------------| @@ -43,8 +36,7 @@ It returns a `BOOL` to indicate whether the peer was successfully added to the l ### admin_datadir -The `datadir` administrative property can be queried for the absolute path the running Geth node -currently uses to store all its databases. +The `datadir` administrative property can be queried for the absolute path the running Geth node currently uses to store all its databases. | Client | Method invocation | |:--------|-----------------------------------| @@ -61,10 +53,7 @@ currently uses to store all its databases. ### admin_exportChain -Exports the current blockchain into a local file. -It optionally takes a first and last block number, in which case it exports only that range of blocks. - -It returns a boolean indicating whether the operation succeeded. +Exports the current blockchain into a local file. It optionally takes a first and last block number, in which case it exports only that range of blocks. It returns a boolean indicating whether the operation succeeded. | Client | Method invocation | |:--------|---------------------------------------------------------------------- | @@ -73,10 +62,7 @@ It returns a boolean indicating whether the operation succeeded. ### admin_importChain -Imports an exported list of blocks from a local file. Importing involves processing the blocks and inserting them -into the canonical chain. The state from the parent block of this range is required. - -It returns a boolean indicating whether the operation succeeded. +Imports an exported list of blocks from a local file. Importing involves processing the blocks and inserting them into the canonical chain. The state from the parent block of this range is required. It returns a boolean indicating whether the operation succeeded. | Client | Method invocation | |:--------|-------------------------------------------------------| @@ -85,11 +71,7 @@ It returns a boolean indicating whether the operation succeeded. ### admin_nodeInfo -The `nodeInfo` administrative property can be queried for all the information known about the running -Geth node at the networking granularity. These include general information about the node itself as a -participant of the [ÐΞVp2p](https://github.com/ethereum/devp2p/blob/master/caps/eth.md) P2P -overlay protocol, as well as specialized information added by each of the running application protocols -(e.g. `eth`, `les`, `shh`, `bzz`). +The `nodeInfo` administrative property can be queried for all the information known about the running Geth node at the networking granularity. These include general information about the node itself as a participant of the [ÐΞVp2p](https://github.com/ethereum/devp2p/blob/master/caps/eth.md) P2P overlay protocol, as well as specialized information added by each of the running application protocols (e.g. `eth`, `les`, `shh`, `bzz`). | Client | Method invocation | |:--------|-------------------------------------------| @@ -124,9 +106,7 @@ overlay protocol, as well as specialized information added by each of the runnin ### admin_peerEvents -PeerEvents creates an [RPC subscription](/docs/rpc/pubsub) which receives peer events from the node's p2p server. - -The type of events emitted by the server are as follows: +PeerEvents creates an [RPC subscription](/docs/rpc/pubsub) which receives peer events from the node's p2p server. The type of events emitted by the server are as follows: - `add`: emitted when a peer is added - `drop`: emitted when a peer is dropped @@ -135,11 +115,7 @@ The type of events emitted by the server are as follows: ### admin_peers -The `peers` administrative property can be queried for all the information known about the connected -remote nodes at the networking granularity. These include general information about the nodes themselves -as participants of the [ÐΞVp2p](https://github.com/ethereum/devp2p/blob/master/caps/eth.md) -P2P overlay protocol, as well as specialized information added by each of the running application -protocols (e.g. `eth`, `les`, `shh`, `bzz`). +The `peers` administrative property can be queried for all the information known about the connected remote nodes at the networking granularity. These include general information about the nodes themselves as participants of the [ÐΞVp2p](https://github.com/ethereum/devp2p/blob/master/caps/eth.md) P2P overlay protocol, as well as specialized information added by each of the running application protocols (e.g. `eth`, `les`, `shh`, `bzz`). | Client | Method invocation | |:--------|------------------------------------------| @@ -186,10 +162,7 @@ protocols (e.g. `eth`, `les`, `shh`, `bzz`). ### admin_removePeer -Disconnects from a remote node if the connection exists. - -It returns a boolean indicating validations succeeded. Note a `true` value doesn't necessarily mean -that there was a connection which was disconnected. +Disconnects from a remote node if the connection exists. It returns a boolean indicating validations succeeded. Note a `true` value doesn't necessarily mean that there was a connection which was disconnected. | Client | Method invocation | |:--------|----------------------------------------------------- | @@ -198,9 +171,7 @@ that there was a connection which was disconnected. ### admin_removeTrustedPeer -Removes a remote node from the trusted peer set, but it does not disconnect it automatically. - -It returns a boolean indicating validations succeeded. +Removes a remote node from the trusted peer set, but it does not disconnect it automatically. It returns a boolean indicating validations succeeded. | Client | Method invocation | |:--------|----------------------------------------------------- | @@ -209,8 +180,7 @@ It returns a boolean indicating validations succeeded. ### admin_startHTTP -The `startHTTP` administrative method starts an HTTP based JSON-RPC [API](/docs/rpc/server) -webserver to handle client requests. All the parameters are optional: +The `startHTTP` administrative method starts an HTTP based JSON-RPC [API](/docs/rpc/server) webserver to handle client requests. All the parameters are optional: * `host`: network interface to open the listener socket on (defaults to `"localhost"`) * `port`: network port to open the listener socket on (defaults to `8545`) @@ -234,8 +204,7 @@ true ### admin_startWS -The `startWS` administrative method starts an WebSocket based [JSON RPC](https://www.jsonrpc.org/specification) -API webserver to handle client requests. All the parameters are optional: +The `startWS` administrative method starts an WebSocket based [JSON RPC](https://www.jsonrpc.org/specification) API webserver to handle client requests. All the parameters are optional: * `host`: network interface to open the listener socket on (defaults to `"localhost"`) * `port`: network port to open the listener socket on (defaults to `8546`) diff --git a/content/docs/interacting_with_geth/RPC/ns-clique.md b/content/docs/interacting_with_geth/RPC/ns-clique.md index 98c68c5317..cd1d2344bc 100644 --- a/content/docs/interacting_with_geth/RPC/ns-clique.md +++ b/content/docs/interacting_with_geth/RPC/ns-clique.md @@ -1,6 +1,6 @@ --- title: clique Namespace -sort_key: C +description: Documentation for the JSON-RPC API "clique" namespace --- The `clique` API provides access to the state of the clique consensus engine. This API cna be used to manage signer votes and to check the health of a private network. @@ -52,8 +52,7 @@ Retrieves the state snapshot at a given block. ### clique_getSigner -Returns the signer for a specific clique block. Can be called with either a blocknumber, blockhash or an rlp encoded blob. -The RLP encoded blob can either be a block or a header. +Returns the signer for a specific clique block. Can be called with either a blocknumber, blockhash or an rlp encoded blob. The RLP encoded blob can either be a block or a header. | Client | Method invocation | |:--------|------------------------------------------------------| @@ -89,10 +88,7 @@ Returns the current proposals the node is voting on. ### clique_propose -Adds a new authorization proposal that the signer will attempt to push through. If the -`auth` parameter is true, the local signer votes for the given address to be included in -the set of authorized signers. With `auth` set to `false`, the vote is against the -address. +Adds a new authorization proposal that the signer will attempt to push through. If the `auth` parameter is true, the local signer votes for the given address to be included in the set of authorized signers. With `auth` set to `false`, the vote is against the address. | Client | Method invocation | |:--------|-----------------------------------------------------------| @@ -101,8 +97,7 @@ address. ### clique_discard -This method drops a currently running proposal. The signer will not cast -further votes (either for or against) the address. +This method drops a currently running proposal. The signer will not cast further votes (either for or against) the address. | Client | Method invocation | |:--------|-----------------------------------------------------| @@ -111,8 +106,7 @@ further votes (either for or against) the address. ### clique_status -This is a debugging method which returns statistics about signer activity -for the last 64 blocks. The returned object contains the following fields: +This is a debugging method which returns statistics about signer activity for the last 64 blocks. The returned object contains the following fields: - `inturnPercent`: percentage of blocks signed in-turn - `sealerActivity`: object containing signer addresses and the number diff --git a/content/docs/interacting_with_geth/RPC/ns-debug.md b/content/docs/interacting_with_geth/RPC/ns-debug.md index f9cbfe0d7b..db5c66feaf 100644 --- a/content/docs/interacting_with_geth/RPC/ns-debug.md +++ b/content/docs/interacting_with_geth/RPC/ns-debug.md @@ -1,6 +1,6 @@ --- title: debug Namespace -sort_key: C +description: Documentation for the JSON-RPC API "clique" namespace --- The `debug` API gives access to several non-standard RPC methods, which allow inspection, debugging and setting certain debugging flags during runtime. @@ -19,9 +19,7 @@ If `incompletes` is false, then accounts for which the key preimage (i.e: the `a ### debug_backtraceAt -Sets the logging backtrace location. When a backtrace location -is set and a log message is emitted at that location, the stack -of the goroutine executing the log statement will be printed to stderr. +Sets the logging backtrace location. When a backtrace location is set and a log message is emitted at that location, the stack of the goroutine executing the log statement will be printed to stderr. The location is specified as `:`. @@ -38,11 +36,7 @@ Example: ### debug_blockProfile -Turns on block profiling for the given duration and writes -profile data to disk. It uses a profile rate of 1 for most -accurate information. If a different rate is desired, set -the rate and write the profile manually using -`debug_writeBlockProfile`. +Turns on block profiling for the given duration and writes profile data to disk. It uses a profile rate of 1 for most accurate information. If a different rate is desired, set the rate and write the profile manually using `debug_writeBlockProfile`. | Client | Method invocation | |:--------|----------------------------------------------------------------| @@ -72,8 +66,7 @@ Returns leveldb properties of the key-value database. ### debug_cpuProfile -Turns on CPU profiling for the given duration and writes -profile data to disk. +Turns on CPU profiling for the given duration and writes profile data to disk. | Client | Method invocation | |:--------|--------------------------------------------------------------| @@ -83,8 +76,7 @@ profile data to disk. ### debug_dbAncient -Retrieves an ancient binary blob from the freezer. The freezer is a collection of append-only immutable files. -The first argument `kind` specifies which table to look up data from. The list of all table kinds are as follows: +Retrieves an ancient binary blob from the freezer. The freezer is a collection of append-only immutable files. The first argument `kind` specifies which table to look up data from. The list of all table kinds are as follows: - `headers`: block headers - `hashes`: canonical hash table (block number -> block hash) @@ -119,8 +111,7 @@ Returns the raw value of a key stored in the database. ### debug_dumpBlock -Retrieves the state that corresponds to the block number and returns a list of accounts (including -storage and code). +Retrieves the state that corresponds to the block number and returns a list of accounts (including storage and code). | Client | Method invocation | |:--------|-------------------------------------------------------| @@ -168,8 +159,7 @@ Forces garbage collection ### debug_freezeClient -Forces a temporary client freeze, normally when the server is overloaded. -Available as part of LES light server. +Forces a temporary client freeze, normally when the server is overloaded. Available as part of LES light server. | Client | Method invocation | |:--------|------------------------------------------------------| @@ -182,8 +172,7 @@ Available as part of LES light server. Returns garbage collection statistics. -See https://golang.org/pkg/runtime/debug/#GCStats for information about -the fields of the returned object. +See https://golang.org/pkg/runtime/debug/#GCStats for information about the fields of the returned object. | Client | Method invocation | |:--------|---------------------------------------------------| @@ -193,10 +182,7 @@ the fields of the returned object. ### debug_getAccessibleState -Returns the first number where the node has accessible state on disk. -This is the post-state of that block and the pre-state of the next -block. The (from, to) parameters are the sequence of blocks -to search, which can go either forwards or backwards. +Returns the first number where the node has accessible state on disk. This is the post-state of that block and the pre-state of the next block. The (from, to) parameters are the sequence of blocks to search, which can go either forwards or backwards. | Client | Method invocation | |:--------|-----------------------------------------------------------------------| @@ -206,8 +192,7 @@ to search, which can go either forwards or backwards. ### debug_getBadBlocks -Returns a list of the last 'bad blocks' that the client has seen on -the network and returns them as a JSON list of block-hashes. +Returns a list of the last 'bad blocks' that the client has seen on the network and returns them as a JSON list of block-hashes. | Client | Method invocation | |:--------|---------------------------------------------------| @@ -247,9 +232,7 @@ Returns all accounts that have changed between the two blocks specified. A chang ### debug_getModifiedAccountsByNumber -Returns all accounts that have changed between the two blocks specified. -A change is defined as a difference in nonce, balance, code hash or -storage hash. +Returns all accounts that have changed between the two blocks specified. A change is defined as a difference in nonce, balance, code hash or storage hash. | Client | Method invocation | |:--------|---------------------------------------------------------------------------------| @@ -267,8 +250,7 @@ Returns the consensus-encoding of all receipts in a single block. ### debug_goTrace -Turns on Go runtime tracing for the given duration and writes -trace data to disk. +Turns on Go runtime tracing for the given duration and writes trace data to disk. | Client | Method invocation | |:--------|-----------------------------------------------------------| @@ -288,8 +270,7 @@ Executes a block (bad- or canon- or side-), and returns a list of intermediate r Returns detailed runtime memory statistics. -See https://golang.org/pkg/runtime/#MemStats for information about -the fields of the returned object. +See https://golang.org/pkg/runtime/#MemStats for information about the fields of the returned object. | Client | Method invocation | |:--------|---------------------------------------------------| @@ -337,10 +318,7 @@ Fetches and retrieves the seed hash of the block by number ### debug_setBlockProfileRate -Sets the rate (in samples/sec) of goroutine block profile -data collection. A non-zero rate enables block profiling, -setting it to zero stops the profile. Collected profile data -can be written using `debug_writeBlockProfile`. +Sets the rate (in samples/sec) of goroutine block profile data collection. A non-zero rate enables block profiling, setting it to zero stops the profile. Collected profile data can be written using `debug_writeBlockProfile`. | Client | Method invocation | |:--------|---------------------------------------------------------------| @@ -349,8 +327,7 @@ can be written using `debug_writeBlockProfile`. ### debug_setGCPercent -Sets the garbage collection target percentage. A negative value disables garbage -collection. +Sets the garbage collection target percentage. A negative value disables garbage collection. | Client | Method invocation | |:--------|---------------------------------------------------| @@ -361,8 +338,7 @@ collection. ### debug_setHead -Sets the current head of the local chain by block number. **Note**, this is a -destructive action and may severely damage the chain. Use with *extreme* caution. +Sets the current head of the local chain by block number. **Note**, this is a destructive action and may severely damage the chain. Use with *extreme* caution. | Client | Method invocation | |:--------|---------------------------------------------------| @@ -384,9 +360,7 @@ Sets the rate of mutex profiling. ### debug_stacks -Returns a printed representation of the stacks of all goroutines. -Note that the web3 wrapper for this method takes care of the printing -and does not return the string. +Returns a printed representation of the stacks of all goroutines. Note that the web3 wrapper for this method takes care of the printing and does not return the string. | Client | Method invocation | |:--------|---------------------------------------------------| @@ -396,8 +370,7 @@ and does not return the string. ### debug_standardTraceBlockToFile -When JS-based tracing (see below) was first implemented, the intended usecase was to enable long-running tracers that could stream results back via a subscription channel. -This method works a bit differently. (For full details, see [PR](https://github.com/ethereum/go-ethereum/pull/17914)) +When JS-based tracing (see below) was first implemented, the intended usecase was to enable long-running tracers that could stream results back via a subscription channel. This method works a bit differently. (For full details, see [PR](https://github.com/ethereum/go-ethereum/pull/17914)) - It streams output to disk during the execution, to not blow up the memory usage on the node - It uses `jsonl` as output format (to allow streaming) @@ -409,12 +382,13 @@ This method works a bit differently. (For full details, see [PR](https://github. This means that this method is only 'useful' for callers who control the node -- at least sufficiently to be able to read the artefacts from the filesystem after the fact. The method can be used to dump a certain transaction out of a given block: -``` + +```sh > debug.standardTraceBlockToFile("0x0bbe9f1484668a2bf159c63f0cf556ed8c8282f99e3ffdb03ad2175a863bca63", {txHash:"0x4049f61ffbb0747bb88dc1c85dd6686ebf225a3c10c282c45a8e0c644739f7e9", disableMemory:true}) ["/tmp/block_0x0bbe9f14-14-0x4049f61f-099048234"] ``` Or all txs from a block: -``` +```sh > debug.standardTraceBlockToFile("0x0bbe9f1484668a2bf159c63f0cf556ed8c8282f99e3ffdb03ad2175a863bca63", {disableMemory:true}) ["/tmp/block_0x0bbe9f14-0-0xb4502ea7-409046657", "/tmp/block_0x0bbe9f14-1-0xe839be8f-954614764", "/tmp/block_0x0bbe9f14-2-0xc6e2052f-542255195", "/tmp/block_0x0bbe9f14-3-0x01b7f3fe-209673214", "/tmp/block_0x0bbe9f14-4-0x0f290422-320999749", "/tmp/block_0x0bbe9f14-5-0x2dc0fb80-844117472", "/tmp/block_0x0bbe9f14-6-0x35542da1-256306111", "/tmp/block_0x0bbe9f14-7-0x3e199a08-086370834", "/tmp/block_0x0bbe9f14-8-0x87778b88-194603593", "/tmp/block_0x0bbe9f14-9-0xbcb081ba-629580052", "/tmp/block_0x0bbe9f14-10-0xc254381a-578605923", "/tmp/block_0x0bbe9f14-11-0xcc434d58-405931366", "/tmp/block_0x0bbe9f14-12-0xce61967d-874423181", "/tmp/block_0x0bbe9f14-13-0x05a20b35-267153288", "/tmp/block_0x0bbe9f14-14-0x4049f61f-606653767", "/tmp/block_0x0bbe9f14-15-0x46d473d2-614457338", "/tmp/block_0x0bbe9f14-16-0x35cf5500-411906321", "/tmp/block_0x0bbe9f14-17-0x79222961-278569788", "/tmp/block_0x0bbe9f14-18-0xad84e7b1-095032683", "/tmp/block_0x0bbe9f14-19-0x4bd48260-019097038", "/tmp/block_0x0bbe9f14-20-0x1517411d-292624085", "/tmp/block_0x0bbe9f14-21-0x6857e350-971385904", "/tmp/block_0x0bbe9f14-22-0xbe3ae2ca-236639695"] @@ -433,7 +407,8 @@ INFO [10-15|13:48:34.421] Wrote trace file=/tmp/block_0x14490c57-2-0x3f4263fe-05 ``` The `options` is as follows: -``` + +```sh type StdTraceConfig struct { *vm.LogConfig Reexec *uint64 @@ -502,9 +477,7 @@ Returns the structured logs created during the execution of EVM against a block ### debug_traceBlock -The `traceBlock` method will return a full stack trace of all invoked opcodes of all transaction -that were included in this block. **Note**, the parent of this block must be present or it will -fail. +The `traceBlock` method will return a full stack trace of all invoked opcodes of all transaction that were included in this block. **Note**, the parent of this block must be present or it will fail. | Client | Method invocation | |:--------|--------------------------------------------------------------------------| @@ -553,8 +526,7 @@ References: ### debug_traceBlockByNumber -Similar to [debug_traceBlock](#debug_traceblock), `traceBlockByNumber` accepts a block number and will replay the -block that is already present in the database. +Similar to [debug_traceBlock](#debug_traceblock), `traceBlockByNumber` accepts a block number and will replay the block that is already present in the database. | Client | Method invocation | |:--------|--------------------------------------------------------------------------------| @@ -567,8 +539,7 @@ References: ### debug_traceBlockByHash -Similar to [debug_traceBlock](#debug_traceblock), `traceBlockByHash` accepts a block hash and will replay the -block that is already present in the database. +Similar to [debug_traceBlock](#debug_traceblock), `traceBlockByHash` accepts a block hash and will replay the block that is already present in the database. | Client | Method invocation | |:--------|---------------------------------------------------------------------------------| @@ -606,7 +577,8 @@ The `debug_traceCall` method enables running an `eth_call` within the context of #### Example No specific call options: -``` + +```sh > debug.traceCall(null, "0x0") { failed: false, @@ -616,7 +588,8 @@ No specific call options: } ``` Tracing a call with a destination and specific sender, disabling the storage and memory output (less data returned over RPC) -``` + +```sh debug.traceCall({ "from": "0xdeadbeef29292929192939494959594933929292", "to": "0xde929f939d939d393f939393f93939f393929023", @@ -626,9 +599,9 @@ debug.traceCall({ "latest", {"disableStorage": true, "disableMemory": true}) ``` -It is possible to supply 'overrides' for both state-data (accounts/storage) and block data (number, timestamp etc). In the example below, -a call which executes `NUMBER` is performed, and the overridden number is placed on the stack: -``` +It is possible to supply 'overrides' for both state-data (accounts/storage) and block data (number, timestamp etc). In the example below, a call which executes `NUMBER` is performed, and the overridden number is placed on the stack: + +```sh > debug.traceCall({ from: eth.accounts[0], value:"0x1", @@ -662,15 +635,14 @@ a call which executes `NUMBER` is performed, and the overridden number is placed ``` Curl example: -``` +```sh > curl -H "Content-Type: application/json" -X POST localhost:8545 --data '{"jsonrpc":"2.0","method":"debug_traceCall","params":[null, "pending"],"id":1}' {"jsonrpc":"2.0","id":1,"result":{"gas":53000,"failed":false,"returnValue":"","structLogs":[]}} ``` ### debug_traceChain -Returns the structured logs created during the execution of EVM between two blocks (excluding start) as a JSON object. -This endpoint must be invoked via `debug_subscribe` as follows: +Returns the structured logs created during the execution of EVM between two blocks (excluding start) as a JSON object. This endpoint must be invoked via `debug_subscribe` as follows: `const res = provider.send('debug_subscribe', ['traceChain', '0x3f3a2a', '0x3f3a2b'])` @@ -681,13 +653,10 @@ please refer to the [subscription page](https://geth.ethereum.org/docs/rpc/pubsu **OBS** In most scenarios, `debug.standardTraceBlockToFile` is better suited for tracing! -The `traceTransaction` debugging method will attempt to run the transaction in the exact same manner -as it was executed on the network. It will replay any transaction that may have been executed prior -to this one before it will finally attempt to execute the transaction that corresponds to the given +The `traceTransaction` debugging method will attempt to run the transaction in the exact same manner as it was executed on the network. It will replay any transaction that may have been executed prior to this one before it will finally attempt to execute the transaction that corresponds to the given hash. -In addition to the hash of the transaction it can take a secondary *optional* argument, which -specifies the options for this specific call. The possible options are: +In addition to the hash of the transaction it can take a secondary *optional* argument, which specifies the options for this specific call. The possible options are: * `disableStorage`: `BOOL`. Setting this to true will disable storage capture (default = false). * `disableStack`: `BOOL`. Setting this to true will disable stack capture (default = false). @@ -856,16 +825,15 @@ Note that several values are Golang big.Int objects, not JavaScript numbers or J Usage example, returns the top element of the stack at each CALL opcode only: - debug.traceTransaction(txhash, {tracer: '{data: [], fault: function(log) {}, step: function(log) { if(log.op.toString() == "CALL") this.data.push(log.stack.peek(0)); }, result: function() { return this.data; }}'}); - +```sh +debug.traceTransaction(txhash, {tracer: '{data: [], fault: function(log) {}, step: function(log) { if(log.op.toString() == "CALL") this.data.push(log.stack.peek(0)); }, result: function() { return this.data; }}'}); +``` ### debug_verbosity -Sets the logging verbosity ceiling. Log messages with level -up to and including the given level will be printed. +Sets the logging verbosity ceiling. Log messages with level up to and including the given level will be printed. -The verbosity of individual packages and source files -can be raised using `debug_vmodule`. +The verbosity of individual packages and source files can be raised using `debug_vmodule`. | Client | Method invocation | |:--------|---------------------------------------------------| @@ -884,8 +852,7 @@ Sets the logging verbosity pattern. #### Examples -To see messages from a particular Go package (directory) -and all subdirectories, use: +To see messages from a particular Go package (directory) and all subdirectories, use: ``` javascript > debug.vmodule("eth/*=6") @@ -921,10 +888,7 @@ Writes a goroutine blocking profile to the given file. ### debug_writeMemProfile -Writes an allocation profile to the given file. -Note that the profiling rate cannot be set through the API, -it must be set on the command line using the `--pprof.memprofilerate` -flag. +Writes an allocation profile to the given file. Note that the profiling rate cannot be set through the API, it must be set on the command line using the `--pprof.memprofilerate` flag. | Client | Method invocation | |:--------|-------------------------------------------------------------| diff --git a/content/docs/interacting_with_geth/RPC/ns-eth.md b/content/docs/interacting_with_geth/RPC/ns-eth.md index fe126eb99d..4756a1c4a1 100644 --- a/content/docs/interacting_with_geth/RPC/ns-eth.md +++ b/content/docs/interacting_with_geth/RPC/ns-eth.md @@ -1,43 +1,33 @@ --- title: eth Namespace -sort_key: C +sort_key: Documentation for the JSON-RPC API "eth" namespace --- Geth provides several extensions to the standard "eth" JSON-RPC namespace. ### eth_subscribe, eth_unsubscribe -These methods are used for real-time events through subscriptions. See the [subscription -documentation](./pubsub) for more information. +These methods are used for real-time events through subscriptions. See the [subscription documentation](/content/docs/interacting_with_geth/RPC/pubsub.md) for more information. ### eth_call -Executes a new message call immediately, without creating a transaction on the block -chain. The `eth_call` method can be used to query internal contract state, to execute -validations coded into a contract or even to test what the effect of a transaction would -be without running it live. +Executes a new message call immediately, without creating a transaction on the block chain. The `eth_call` method can be used to query internal contract state, to execute validations coded into a contract or even to test what the effect of a transaction would be without running it live. #### Parameters -The method takes 3 parameters: an unsigned transaction object to execute in read-only -mode; the block number to execute the call against; and an optional state override-set to -allow executing the call against a modified chain state. +The method takes 3 parameters: an unsigned transaction object to execute in read-only mode; the block number to execute the call against; and an optional state override-set to allow executing the call against a modified chain state. ##### 1. `Object` - Transaction call object -The *transaction call object* is mandatory. Please see [here](/docs/rpc/objects#transaction-call-object) for details. +The *transaction call object* is mandatory. Please see [here](/content/docs/interacting_with_geth/RPC/objects.md) for details. ##### 2. `Quantity | Tag` - Block number or the string `latest` or `pending` -The *block number* is mandatory and defines the context (state) against which the -specified transaction should be executed. It is not possible to execute calls against -reorged blocks; or blocks older than 128 (unless the node is an archive node). +The *block number* is mandatory and defines the context (state) against which the specified transaction should be executed. It is not possible to execute calls against reorged blocks; or blocks older than 128 (unless the node is an archive node). ##### 3. `Object` - State override set -The *state override set* is an optional address-to-state mapping, where each entry -specifies some state to be ephemerally overridden prior to executing the call. Each -address maps to an object containing: +The *state override set* is an optional address-to-state mapping, where each entry specifies some state to be ephemerally overridden prior to executing the call. Each address maps to an object containing: | Field | Type | Bytes | Optional | Description | |:------------|:-----------|:------|:---------|:------------| @@ -49,15 +39,9 @@ address maps to an object containing: The goal of the *state override set* is manyfold: - * It can be used by DApps to reduce the amount of contract code needed to be deployed on - chain. Code that simply returns internal state or does pre-defined validations can be - kept off chain and fed to the node on-demand. - * It can be used for smart contract analysis by extending the code deployed on chain with - custom methods and invoking them. This avoids having to download and reconstruct the - entire state in a sandbox to run custom code against. - * It can be used to debug smart contracts in an already deployed large suite of contracts - by selectively overriding some code or state and seeing how execution changes. - Specialized tooling will probably be necessary. + * It can be used by DApps to reduce the amount of contract code needed to be deployed on chain. Code that simply returns internal state or does pre-defined validations can be kept off chain and fed to the node on-demand. + * It can be used for smart contract analysis by extending the code deployed on chain with custom methods and invoking them. This avoids having to download and reconstruct the entire state in a sandbox to run custom code against. + * It can be used to debug smart contracts in an already deployed large suite of contracts by selectively overriding some code or state and seeing how execution changes. Specialized tooling will probably be necessary. Example: @@ -77,15 +61,11 @@ Example: #### Return Values -The method returns a single `Binary` consisting the return value of the executed contract -call. +The method returns a single `Binary` consisting the return value of the executed contract call. #### Simple example -With a synced Rinkeby node with RPC exposed on localhost (`geth --rinkeby --http`) we can -make a call against the [Checkpoint -Oracle](https://rinkeby.etherscan.io/address/0xebe8efa441b9302a0d7eaecc277c09d20d684540) -to retrieve the list of administrators: +With a synced Rinkeby node with RPC exposed on localhost (`geth --rinkeby --http`) we can make a call against the [CheckpointOracle](https://rinkeby.etherscan.io/address/0xebe8efa441b9302a0d7eaecc277c09d20d684540) to retrieve the list of administrators: ``` $ curl --data '{"method":"eth_call","params":[{"to":"0xebe8efa441b9302a0d7eaecc277c09d20d684540","data":"0x45848dfc"},"latest"],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545 @@ -112,13 +92,9 @@ Just for the sake of completeness, decoded the response is: #### Override example -The above *simple example* showed how to call a method already exposed by an on-chain -smart contract. What if we want to access some data not exposed by it? +The above *simple example* showed how to call a method already exposed by an on-chain smart contract. What if we want to access some data not exposed by it? -We can gut out the -[original](https://github.com/ethereum/go-ethereum/blob/master/contracts/checkpointoracle/contract/oracle.sol) -checkpoint oracle contract with one that retains the same fields (to retain the same -storage layout), but one that includes a different method set: +We can gut out the [original](https://github.com/ethereum/go-ethereum/blob/master/contracts/checkpointoracle/contract/oracle.sol) checkpoint oracle contract with one that retains the same fields (to retain the same storage layout), but one that includes a different method set: ``` pragma solidity ^0.5.10; @@ -139,10 +115,7 @@ contract CheckpointOracle { } ``` -With a synced Rinkeby node with RPC exposed on localhost (`geth --rinkeby --http`) we can -make a call against the live [Checkpoint -Oracle](https://rinkeby.etherscan.io/address/0xebe8efa441b9302a0d7eaecc277c09d20d684540), -but override its byte code with our own version that has an accessor for the voting +With a synced Rinkeby node with RPC exposed on localhost (`geth --rinkeby --http`) we can make a call against the live [Checkpoint Oracle](https://rinkeby.etherscan.io/address/0xebe8efa441b9302a0d7eaecc277c09d20d684540), but override its byte code with our own version that has an accessor for the voting threshold field: ``` @@ -163,10 +136,7 @@ Just for the sake of completeness, decoded the response is: `2`. ### eth_createAccessList -This method creates an [EIP2930](https://eips.ethereum.org/EIPS/eip-2930) type `accessList` based on a given `Transaction`. -The `accessList` contains all storage slots and addresses read and written by the transaction, except for the sender account and the precompiles. -This method uses the same `transaction` call [object](/docs/rpc/objects#transaction-call-object) and `blockNumberOrTag` object as `eth_call`. -An `accessList` can be used to unstuck contracts that became inaccessible due to gas cost increases. +This method creates an [EIP2930](https://eips.ethereum.org/EIPS/eip-2930) type `accessList` based on a given `Transaction`. The `accessList` contains all storage slots and addresses read and written by the transaction, except for the sender account and the precompiles. This method uses the same `transaction` call [object](/docs/rpc/objects#transaction-call-object) and `blockNumberOrTag` object as `eth_call`. An `accessList` can be used to unstuck contracts that became inaccessible due to gas cost increases. #### Parameters @@ -185,8 +155,7 @@ curl --data '{"method":"eth_createAccessList","params":[{"from": "0x8cd02c6cbd83 The method `eth_createAccessList` returns list of addresses and storage keys used by the transaction, plus the gas consumed when the access list is added. -That is, it gives the list of addresses and storage keys that will be used by that transaction, plus the gas consumed if the access list is included. Like `eth_estimateGas`, this is an estimation; the list could change when the transaction is actually mined. -Adding an `accessList` to a transaction does not necessary result in lower gas usage compared to a transaction without an access list. +That is, it gives the list of addresses and storage keys that will be used by that transaction, plus the gas consumed if the access list is included. Like `eth_estimateGas`, this is an estimation; the list could change when the transaction is actually mined. Adding an `accessList` to a transaction does not necessary result in lower gas usage compared to a transaction without an access list. Example: ```json diff --git a/content/docs/interacting_with_geth/RPC/ns-les.md b/content/docs/interacting_with_geth/RPC/ns-les.md index cbc965b832..fa12d51372 100644 --- a/content/docs/interacting_with_geth/RPC/ns-les.md +++ b/content/docs/interacting_with_geth/RPC/ns-les.md @@ -1,12 +1,10 @@ --- title: les Namespace -sort_key: C +description: Documentation for the JSON-RPC API "les" namespace --- The `les` API is for managing LES server settings, including client parameters and payment settings for prioritized clients. It also provides functions to query checkpoint information in both server and client mode. -* TOC -{:toc} ### les_serverInfo diff --git a/content/docs/interacting_with_geth/RPC/ns-miner.md b/content/docs/interacting_with_geth/RPC/ns-miner.md index 8eea5e8c87..720b9fc351 100644 --- a/content/docs/interacting_with_geth/RPC/ns-miner.md +++ b/content/docs/interacting_with_geth/RPC/ns-miner.md @@ -1,6 +1,6 @@ --- title: miner Namespace -sort_key: C +description: Documentation for the JSON-RPC API "miner" namespace --- The `miner` API is **now deprecated** because mining was switched off at the transition to proof-of-stake. It existed to provide remote control the node's mining operation and set various mining specific settings. It is provided here for historical interest! @@ -16,8 +16,7 @@ Get hashrate in H/s (Hash operations per second). ### miner_setExtra -Sets the extra data a miner can include when miner blocks. This is capped at -32 bytes. +Sets the extra data a miner can include when miner blocks. This is capped at 32 bytes. | Client | Method invocation | |:--------|----------------------------------------------------| @@ -27,8 +26,7 @@ Sets the extra data a miner can include when miner blocks. This is capped at ### miner_setGasPrice -Sets the minimal accepted gas price when mining transactions. Any transactions that are -below this limit are excluded from the mining process. +Sets the minimal accepted gas price when mining transactions. Any transactions that are below this limit are excluded from the mining process. | Client | Method invocation | |:--------|-------------------------------------------------------| @@ -47,8 +45,7 @@ Updates the interval for recomitting the miner sealing work. ### miner_start -Start the CPU mining process with the given number of threads and generate a new DAG -if need be. +Start the CPU mining process with the given number of threads and generate a new DAG if need be. | Client | Method invocation | |:--------|-----------------------------------------------------| diff --git a/content/docs/interacting_with_geth/RPC/ns-net.md b/content/docs/interacting_with_geth/RPC/ns-net.md index ad4ee571a3..bacd9a8a04 100644 --- a/content/docs/interacting_with_geth/RPC/ns-net.md +++ b/content/docs/interacting_with_geth/RPC/ns-net.md @@ -1,6 +1,6 @@ --- title: net Namespace -sort_key: C +description: Documentation for the JSON-RPC API "net" namespace --- The `net` API provides insight about the networking aspect of the client. diff --git a/content/docs/interacting_with_geth/RPC/ns-personal.md b/content/docs/interacting_with_geth/RPC/ns-personal.md index 6a2d7903fc..da00e87e62 100644 --- a/content/docs/interacting_with_geth/RPC/ns-personal.md +++ b/content/docs/interacting_with_geth/RPC/ns-personal.md @@ -1,6 +1,6 @@ --- title: personal Namespace -sort_key: C +description: Documentation for the JSON-RPC API "personal" namespace --- The personal API manages private keys in the key store. @@ -16,8 +16,7 @@ Requests a HD wallet to derive a new account, optionally pinning it for later re ### personal_importRawKey -Imports the given unencrypted private key (hex string) into the key store, -encrypting it with the passphrase. +Imports the given unencrypted private key (hex string) into the key store, encrypting it with the passphrase. Returns the address of the new account. @@ -37,8 +36,7 @@ Initializes a new wallet at the provided URL by generating and returning a new p ### personal_listAccounts -Returns all the Ethereum account addresses of all keys -in the key store. +Returns all the Ethereum account addresses of all keys in the key store. | Client | Method invocation | | :--------| --------------------------------------------------- | @@ -77,8 +75,7 @@ Returns a list of wallets this node manages. ### personal_lockAccount -Removes the private key with given address from memory. -The account can no longer be used to send transactions. +Removes the private key with given address from memory. The account can no longer be used to send transactions. | Client | Method invocation | | :--------| -------------------------------------------------------- | @@ -87,12 +84,8 @@ The account can no longer be used to send transactions. ### personal_newAccount -Generates a new private key and stores it in the key store directory. -The key file is encrypted with the given passphrase. -Returns the address of the new account. - -At the geth console, `newAccount` will prompt for a passphrase when -it is not supplied as the argument. +Generates a new private key and stores it in the key store directory. The key file is encrypted with the given passphrase. +Returns the address of the new account. At the geth console, `newAccount` will prompt for a passphrase when it is not supplied as the argument. | Client | Method invocation | | :--------| --------------------------------------------------- | @@ -117,10 +110,8 @@ The passphrase can also be supplied as a string. ### personal_openWallet -Initiates a hardware wallet opening procedure by establishing a USB -connection and then attempting to authenticate via the provided passphrase. Note, -the method may return an extra challenge requiring a second open (e.g. the -Trezor PIN matrix challenge). +Initiates a hardware wallet opening procedure by establishing a USB connection and then attempting to authenticate via the provided passphrase. Note, +the method may return an extra challenge requiring a second open (e.g. the Trezor PIN matrix challenge). | Client | Method invocation | | :--------| ----------------------------------------------------------- | @@ -131,13 +122,8 @@ Trezor PIN matrix challenge). Decrypts the key with the given address from the key store. -Both passphrase and unlock duration are optional when using the JavaScript console. -If the passphrase is not supplied as an argument, the console will prompt for -the passphrase interactively. - -The unencrypted key will be held in memory until the unlock duration expires. -If the unlock duration defaults to 300 seconds. An explicit duration -of zero seconds unlocks the key until geth exits. +Both passphrase and unlock duration are optional when using the JavaScript console. If the passphrase is not supplied as an argument, the console will prompt for +the passphrase interactively. The unencrypted key will be held in memory until the unlock duration expires. If the unlock duration defaults to 300 seconds. An explicit duration of zero seconds unlocks the key until geth exits. The account can be used with `eth_sign` and `eth_sendTransaction` while it is unlocked. @@ -162,8 +148,7 @@ Supplying the passphrase and unlock duration as arguments: true ``` -To type in the passphrase and still override the default unlock duration, -pass `null` as the passphrase. +To type in the passphrase and still override the default unlock duration, pass `null` as the passphrase. ``` > personal.unlockAccount("0x5e97870f263700f46aa00d967821199b9bc5a120", null, 30) @@ -225,7 +210,7 @@ See ecRecover to verify the signature. ### personal_signTransaction -SignTransaction will create a transaction from the given arguments and tries to sign it with the key associated with `tx.from`. If the given passwd isn't able to decrypt the key it fails. The transaction is returned in RLP-form, not broadcast to other nodes. The first argument is a [transaction object](/docs/rpc/objects#transaction-call-object) and the second argument is the password, similar to `personal_sendTransaction`. +SignTransaction will create a transaction from the given arguments and tries to sign it with the key associated with `tx.from`. If the given passwd isn't able to decrypt the key it fails. The transaction is returned in RLP-form, not broadcast to other nodes. The first argument is a [transaction object](/content/docs/interacting_with_geth/RPC/objects.md) and the second argument is the password, similar to `personal_sendTransaction`. | Client | Method invocation | | :--------| -----------------------------------------------------------------| @@ -250,4 +235,3 @@ SignTransaction will create a transaction from the given arguments and tries to > personal.ecRecover("0xdeadbeaf", "0xa3f20717a250c2b0b729b7e5becbff67fdaef7e0699da4de7ca5895b02a170a12d887fd3b17bfdce3481f10bea41f45ba9f709d39ce8325427b57afcfc994cee1b") "0x9b2055d370f73ec7d8a03e965129118dc8f5bf83" ``` - diff --git a/content/docs/interacting_with_geth/RPC/ns-txpool.md b/content/docs/interacting_with_geth/RPC/ns-txpool.md index 1790ec9dcc..caeb230af8 100644 --- a/content/docs/interacting_with_geth/RPC/ns-txpool.md +++ b/content/docs/interacting_with_geth/RPC/ns-txpool.md @@ -1,25 +1,17 @@ --- title: txpool Namespace -sort_key: C +description: Documentation for the JSON-RPC API "txpool" namespace --- -The `txpool` API gives access to several non-standard RPC methods to inspect the contents of the -transaction pool containing all the currently pending transactions as well as the ones queued for -future processing. +The `txpool` API gives access to several non-standard RPC methods to inspect the contents of the transaction pool containing all the currently pending transactions as well as the ones queued for future processing. ### txpool_content -The `content` inspection property can be queried to list the exact details of all the transactions -currently pending for inclusion in the next block(s), as well as the ones that are being scheduled -for future execution only. +The `content` inspection property can be queried to list the exact details of all the transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only. -The result is an object with two fields `pending` and `queued`. Each of these fields are associative -arrays, in which each entry maps an origin-address to a batch of scheduled transactions. These batches -themselves are maps associating nonces with actual transactions. +The result is an object with two fields `pending` and `queued`. Each of these fields are associative arrays, in which each entry maps an origin-address to a batch of scheduled transactions. These batches themselves are maps associating nonces with actual transactions. -Please note, there may be multiple transactions associated with the same account and nonce. This can -happen if the user broadcast mutliple ones with varying gas allowances (or even completely different -transactions). +Please note, there may be multiple transactions associated with the same account and nonce. This can happen if the user broadcast mutliple ones with varying gas allowances (or even completely different transactions). | Client | Method invocation | |:-------:|-----------------------------------------------------------------------| @@ -114,8 +106,7 @@ transactions). ### txpool_contentFrom -Retrieves the transactions contained within the txpool, -returning pending as well as queued transactions of this address, grouped by nonce. +Retrieves the transactions contained within the txpool, returning pending as well as queued transactions of this address, grouped by nonce. | Client | Method invocation | |:-------:|--------------------------------------------------------| @@ -124,18 +115,11 @@ returning pending as well as queued transactions of this address, grouped by non ### txpool_inspect -The `inspect` inspection property can be queried to list a textual summary of all the transactions -currently pending for inclusion in the next block(s), as well as the ones that are being scheduled -for future execution only. This is a method specifically tailored to developers to quickly see the -transactions in the pool and find any potential issues. +The `inspect` inspection property can be queried to list a textual summary of all the transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only. This is a method specifically tailored to developers to quickly see the transactions in the pool and find any potential issues. -The result is an object with two fields `pending` and `queued`. Each of these fields are associative -arrays, in which each entry maps an origin-address to a batch of scheduled transactions. These batches -themselves are maps associating nonces with transactions summary strings. +The result is an object with two fields `pending` and `queued`. Each of these fields are associative arrays, in which each entry maps an origin-address to a batch of scheduled transactions. These batches themselves are maps associating nonces with transactions summary strings. -Please note, there may be multiple transactions associated with the same account and nonce. This can -happen if the user broadcast mutliple ones with varying gas allowances (or even completely different -transactions). +Please note, there may be multiple transactions associated with the same account and nonce. This can happen if the user broadcast mutliple ones with varying gas allowances (or even completely different transactions). | Client | Method invocation | |:-------:|--------------------------------------------------------------| @@ -200,11 +184,9 @@ transactions). ### txpool_status -The `status` inspection property can be queried for the number of transactions currently pending for -inclusion in the next block(s), as well as the ones that are being scheduled for future execution only. +The `status` inspection property can be queried for the number of transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only. -The result is an object with two fields `pending` and `queued`, each of which is a counter representing -the number of transactions in that particular state. +The result is an object with two fields `pending` and `queued`, each of which is a counter representing the number of transactions in that particular state. | Client | Method invocation | |:--------|-----------------------------------------------| diff --git a/content/docs/interacting_with_geth/RPC/objects.md b/content/docs/interacting_with_geth/RPC/objects.md index 703270687e..504cfa624c 100644 --- a/content/docs/interacting_with_geth/RPC/objects.md +++ b/content/docs/interacting_with_geth/RPC/objects.md @@ -1,6 +1,6 @@ --- title: Objects -sort_key: D +description: Data structures used for RPC methods --- The following are data structures which are used for various RPC methods. diff --git a/content/docs/interacting_with_geth/RPC/pubsub.md b/content/docs/interacting_with_geth/RPC/pubsub.md index 007ecfb06d..59e822d01c 100644 --- a/content/docs/interacting_with_geth/RPC/pubsub.md +++ b/content/docs/interacting_with_geth/RPC/pubsub.md @@ -1,6 +1,6 @@ --- title: Real-time Events -sort_key: B +description: How to subscribe to events using JSON-RPC notifications. --- Geth v1.4 and later support publish / subscribe using JSON-RPC notifications. This allows clients to wait for events instead of polling for them. @@ -54,9 +54,7 @@ Subscriptions are created with a regular RPC call with `eth_subscribe` as method ## Cancel subscription -Subscriptions are cancelled with a regular RPC call with `eth_unsubscribe` as method and -the subscription id as first parameter. It returns a bool indicating if the subscription -was cancelled successful. +Subscriptions are cancelled with a regular RPC call with `eth_unsubscribe` as method and the subscription id as first parameter. It returns a bool indicating if the subscription was cancelled successful. ### Parameters 1. subscription id @@ -74,8 +72,7 @@ was cancelled successful. Fires a notification each time a new header is appended to the chain, including chain reorganizations. Users can use the bloom filter to determine if the block contains logs that are interested to them. Note that if geth receives multiple blocks simultaneously, e.g. catching up after being out of sync, only the last block is emitted. -In case of a chain reorganization the subscription will emit the last header in the new -chain. Therefore the subscription can emit multiple headers on the same height. +In case of a chain reorganization the subscription will emit the last header in the new chain. Therefore the subscription can emit multiple headers on the same height. #### Example @@ -169,9 +166,7 @@ returns ### syncing -Indicates when the node starts or stops synchronizing. The result can either be a boolean -indicating that the synchronization has started (true), finished (false) or an object with -various progress indicators. +Indicates when the node starts or stops synchronizing. The result can either be a boolean indicating that the synchronization has started (true), finished (false) or an object with various progress indicators. #### Parameters diff --git a/content/docs/interacting_with_geth/RPC/server.md b/content/docs/interacting_with_geth/RPC/server.md index 5021a7b8d7..a45f6311c1 100644 --- a/content/docs/interacting_with_geth/RPC/server.md +++ b/content/docs/interacting_with_geth/RPC/server.md @@ -1,31 +1,21 @@ --- title: JSON-RPC Server -sort_key: A +sort_key: Introduction to the JSON-RPC server --- -Interacting with Geth requires sending requests to specific JSON-RPC API -methods. Geth supports all standard [JSON-RPC API][web3-rpc] endpoints. -The RPC requests must be sent to the node and the response returned to the client -using some transport protocol. This page outlines the available transport protocols -in Geth, providing the information users require to choose a transport protocol for -a specific user scenario. +Interacting with Geth requires sending requests to specific JSON-RPC API methods. Geth supports all standard [JSON-RPC API](https://github.com/ethereum/execution-apis) endpoints. +The RPC requests must be sent to the node and the response returned to the client using some transport protocol. This page outlines the available transport protocols in Geth, providing the information users require to choose a transport protocol for a specific user scenario. -{:toc} -- this will be removed by the toc ## Introduction -JSON-RPC is provided on multiple transports. Geth supports JSON-RPC over HTTP, -WebSocket and Unix Domain Sockets. Transports must be enabled through -command-line flags. +JSON-RPC is provided on multiple transports. Geth supports JSON-RPC over HTTP, WebSocket and Unix Domain Sockets. Transports must be enabled through +command-line flags. -Ethereum JSON-RPC APIs use a name-space system. RPC methods are grouped into -several categories depending on their purpose. All method names are composed of -the namespace, an underscore, and the actual method name within the namespace. -For example, the `eth_call` method resides in the `eth` namespace. +Ethereum JSON-RPC APIs use a name-space system. RPC methods are grouped into several categories depending on their purpose. All method names are composed of +the namespace, an underscore, and the actual method name within the namespace. For example, the `eth_call` method resides in the `eth` namespace. -Access to RPC methods can be enabled on a per-namespace basis. Find -documentation for individual namespaces in the sidebar. +Access to RPC methods can be enabled on a per-namespace basis. Find documentation for individual namespaces in the sidebar. ## Transports @@ -33,50 +23,35 @@ There are three transport protocols available in Geth: IPC, HTTP and Websockets. ### HTTP Server -[HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP) is a unidirectional transport protocol -that connects a client and server. The client sends a request to the server, and the server -returns a response back to the client. An HTTP connection is closed after the response for a given -request is sent. +[HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP) is a unidirectional transport protocol that connects a client and server. The client sends a request to the server, and the server returns a response back to the client. An HTTP connection is closed after the response for a given request is sent. -HTTP is supported in every browser as well as almost all programming toolchains. Due to its ubiquity -it has become the most widely used transport for interacting with Geth. To start a HTTP server in Geth, include the `--http` flag: +HTTP is supported in every browser as well as almost all programming toolchains. Due to its ubiquity it has become the most widely used transport for interacting with Geth. To start a HTTP server in Geth, include the `--http` flag: ```sh geth --http ``` -If no other commands are provided, Geth falls back to its default behaviour of accepting connections -from the local loopback interface (127.0.0.1). The default listening port is 8545. The ip address and -listening port can be customized using the `--http.addr` and `--http.port` flags: +If no other commands are provided, Geth falls back to its default behaviour of accepting connections from the local loopback interface (127.0.0.1). The default listening port is 8545. The ip address and listening port can be customized using the `--http.addr` and `--http.port` flags: ```sh geth --http --http.port 3334 ``` -Not all of the JSON-RPC method namespaces are enabled for HTTP requests by default. -Instead, they have to be whitelisted explicitly when Geth is started. Calling non-whitelisted -RPC namespaces returns an RPC error with code `-32602`. +Not all of the JSON-RPC method namespaces are enabled for HTTP requests by default. Instead, they have to be whitelisted explicitly when Geth is started. Calling non-whitelisted RPC namespaces returns an RPC error with code `-32602`. -The default whitelist allows access to the `eth`, `net` and `web3` namespaces. To enable access -to other APIs like account management (`personal`) and debugging (`debug`), they must be configured -using the `--http.api` flag. Enabling these APIs over HTTP is **not recommended** because access -to these methods increases the attack surface. +The default whitelist allows access to the `eth`, `net` and `web3` namespaces. To enable access to other APIs like account management (`personal`) and debugging (`debug`), they must be configured using the `--http.api` flag. Enabling these APIs over HTTP is **not recommended** because access to these methods increases the attack surface. ```sh geth --http --http.api personal,eth,net,web3 ``` -Since the HTTP server is reachable from any local application, additional protection is built into -the server to prevent misuse of the API from web pages. To enable access to the API from a web page -(for example to use the online IDE, [Remix](https://remix.ethereum.org)), the server needs to be -configured to accept Cross-Origin requests. This is achieved using the `--http.corsdomain` flag. +Since the HTTP server is reachable from any local application, additional protection is built into the server to prevent misuse of the API from web pages. To enable access to the API from a web page (for example to use the online IDE, [Remix](https://remix.ethereum.org)), the server needs to be configured to accept Cross-Origin requests. This is achieved using the `--http.corsdomain` flag. ```sh geth --http --http.corsdomain https://remix.ethereum.org ``` -The `--http.corsdomain` command also acceptsd wildcards that enable access to the RPC from any -origin: +The `--http.corsdomain` command also acceptsd wildcards that enable access to the RPC from any origin: ```sh --http.corsdomain '*' @@ -84,28 +59,19 @@ origin: ### WebSocket Server -Websocket is a bidirectional transport protocol. A Websocket connection is maintained by client and server -until it is explicitly terminated by one. Most modern browsers support Websocket which means -it has good tooling. +Websocket is a bidirectional transport protocol. A Websocket connection is maintained by client and server until it is explicitly terminated by one. Most modern browsers support Websocket which means it has good tooling. -Because Websocket is bidirectional, servers can push events to clients. That makes Websocket a good -choice for use-cases involving [event subscription](https://geth.ethereum.org/docs/rpc/pubsub). Another -benefit of Websocket is that after the handshake procedure, the overhead of individual messages is low, +Because Websocket is bidirectional, servers can push events to clients. That makes Websocket a good choice for use-cases involving [event subscription](https://geth.ethereum.org/docs/rpc/pubsub). Another benefit of Websocket is that after the handshake procedure, the overhead of individual messages is low, making it good for sending high number of requests. -Configuration of the WebSocket endpoint in Geth follows the same pattern as the HTTP transport. -WebSocket access can be enabled using the `--ws` flag. If no additional information is provided, -Geth falls back to its default behaviour which is to establish the Websocket on port 8546. -The `--ws.addr`, `--ws.port` and `--ws.api` flags can be used to customize settings -for the WebSocket server. For example, to start Geth with a Websocket connection for RPC using +Configuration of the WebSocket endpoint in Geth follows the same pattern as the HTTP transport. WebSocket access can be enabled using the `--ws` flag. If no additional information is provided, Geth falls back to its default behaviour which is to establish the Websocket on port 8546. The `--ws.addr`, `--ws.port` and `--ws.api` flags can be used to customize settings for the WebSocket server. For example, to start Geth with a Websocket connection for RPC using the custom port 3334 and whitelisting the `eth`, `net` and `web3` namespaces: ```sh geth --ws --ws.port 3334 --ws.api eth,net,web3 ``` -Cross-Origin request protection also applies to the WebSocket server. The -`--ws.origins` flag can be used to allow access to the server from web pages: +Cross-Origin request protection also applies to the WebSocket server. The `--ws.origins` flag can be used to allow access to the server from web pages: ```sh geth --ws --ws.origins http://myapp.example.com @@ -113,29 +79,16 @@ geth --ws --ws.origins http://myapp.example.com As with `--http.corsdomain`, using the wildcard `--ws.origins '*'` allows access from any origin. -{% include note.html content=" By default, **account unlocking is forbidden when HTTP or -Websocket access is enabled** (i.e. by passing `--http` or `ws` flag). This is because an -attacker that manages to access the node via the externally-exposed HTTP/WS port can then -control the unlocked account. It is possible to force account unlock by including the -`--allow-insecure-unlock` flag but this is unsafe and **not recommended** except for expert -users that completely understand how it can be used safely. -This is not a hypothetical risk: **there are bots that continually scan for http-enabled -Ethereum nodes to attack**" %} +{% include note.html content=" By default, **account unlocking is forbidden when HTTP or Websocket access is enabled** (i.e. by passing `--http` or `ws` flag). This is because an attacker that manages to access the node via the externally-exposed HTTP/WS port can then control the unlocked account. It is possible to force account unlock by including the `--allow-insecure-unlock` flag but this is unsafe and **not recommended** except for expert users that completely understand how it can be used safely. This is not a hypothetical risk: **there are bots that continually scan for http-enabled Ethereum nodes to attack**" %} ### IPC Server -IPC is normally available for use in local environments where the node and the console -exist on the same machine. Geth creates a pipe in the computers local file system -(at `ipcpath`) that configures a connection between node and console. The `geth.ipc` file can -also be used by other processes on the same machine to interact with Geth. +IPC is normally available for use in local environments where the node and the console exist on the same machine. Geth creates a pipe in the computers local file system (at `ipcpath`) that configures a connection between node and console. The `geth.ipc` file can also be used by other processes on the same machine to interact with Geth. -On UNIX-based systems (Linux, OSX) the IPC is a UNIX domain socket. On Windows IPC is -provided using named pipes. The IPC server is enabled by default and has access to all -JSON-RPC namespaces. +On UNIX-based systems (Linux, OSX) the IPC is a UNIX domain socket. On Windows IPC is provided using named pipes. The IPC server is enabled by default and has access to all JSON-RPC namespaces. -The listening socket is placed into the data directory by default. On Linux and macOS, -the default location of the geth socket is +The listening socket is placed into the data directory by default. On Linux and macOS, the default location of the geth socket is ```sh ~/.ethereum/geth.ipc @@ -152,8 +105,7 @@ using the `--ipcdisable` flag. ## Choosing a transport protocol -The following table summarizes the relative strengths and weaknesses of each transport -protocol so that users can make informed decisions about which to use. +The following table summarizes the relative strengths and weaknesses of each transport protocol so that users can make informed decisions about which to use. | | HTTP | WS | IPC | | :----------------------------------:|:-----------:|:--------:|:-------:| @@ -161,22 +113,10 @@ protocol so that users can make informed decisions about which to use. | Remote connection | **Y** | **Y** | N | | Per-message metadata overhead | high | low | low | -As a general rule IPC is most secure because it is limited to interactions on the -local machine and cannot be exposed to external traffic. It can also be used -to subscribe to events. HTTP is a familiar and idempotent transport that closes -connections between requests and can therefore have lower overall overheads if the number -of requests is fairly low. Websockets provides a continuous open channel that can enable -event subscriptions and streaming and handle large volumes of requests with smaller per-message -overheads. +As a general rule IPC is most secure because it is limited to interactions on the local machine and cannot be exposed to external traffic. It can also be used +to subscribe to events. HTTP is a familiar and idempotent transport that closes connections between requests and can therefore have lower overall overheads if the number of requests is fairly low. Websockets provides a continuous open channel that can enable event subscriptions and streaming and handle large volumes of requests with smaller per-message overheads. ## Summary -RPC requests to a Geth node can be made using three different transport protocols. The -protocols are enabled at startup using their respective flags. The right choice of transport -protocol depends on the specific use case. - - -[web3-rpc]: https://github.com/ethereum/execution-apis -[remix]: https://remix.ethereum.org -[rpc]: https://www.ibm.com/docs/en/aix/7.1?topic=concepts-remote-procedure-call +RPC requests to a Geth node can be made using three different transport protocols. The protocols are enabled at startup using their respective flags. The right choice of transport protocol depends on the specific use case.