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](../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.
The GraphQL endpoint piggybacks on the HTTP transport used by JSON-RPC. Hence you'll have to enable and configure the relevant `--http` flags, and the `--graphql` flag itself:
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:
```bash
```bash
geth --http --graphql
geth --http --graphql
```
```
Now you can start querying against `http://localhost:8545/graphql`. To change the port, you'll need to provide`--http.port`, e.g.:
Now queries can be raised against `http://localhost:8545/graphql`. To change the port, provide a custom port number to`--http.port`, e.g.:
An easy way to get started right away and try out queries is the GraphiQL interface shipped with Geth. To open it visit `http://localhost:8545/graphql/ui`. To see how this works let's read the sender, recipient and value of all transactions in block number 6000000. Try this out in GraphiQL:
An easy way to try out queries is the GraphiQL interface shipped with Geth. To open it visit `http://localhost:8545/graphql/ui`. To see how this works let's read the sender, recipient and value of all transactions in block number 6000000. In GraphiQL:
```graphql
```graphql
query txInfo {
query txInfo {
@ -31,9 +31,9 @@ GraphiQL also provides a way to explore the schema Geth provides to help you for
### Query
### Query
Reading out data from Geth is the biggest use-case for GraphQL. However after trying out queries in the UI you may want to do it programmatically. You can consult the official [docs](graphql-code) to find bindings for your language. Or use your favorite tool for sending HTTP requests. For sake of completeness we briefly touch on two approaches here. First via cURL, and second via a JS script.
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.
Here's how you'd get the latest block's number via cURL. Note the use of a JSON object for the data section:
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:
```bash
```bash
❯ curl -X POST http://localhost:8545/graphql -H "Content-Type: application/json" --data '{ "query": "query { block { number } }" }'
❯ curl -X POST http://localhost:8545/graphql -H "Content-Type: application/json" --data '{ "query": "query { block { number } }" }'
@ -46,7 +46,7 @@ Alternatively store the JSON-ified query in a file (let's call it `block-num.que
❯ curl -X POST http://localhost:8545/graphql -H "Content-Type: application/json" --data '@block-num.query'
❯ curl -X POST http://localhost:8545/graphql -H "Content-Type: application/json" --data '@block-num.query'
```
```
Executing a simple query in JS looks like the following. Here we're using the lightweight library `graphql-request` to perform the request. Note the use of variables instead of hardcoding the block number in the query:
Executing a simple query in JS looks as follows. Here the lightweight library `graphql-request` is used to perform the request. Note the use of variables instead of hardcoding the block number in the query:
The `admin` API gives you access to several non-standard RPC methods, which will allow you to have
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.
a fine grained control over your Geth instance, including but not limited to network peer and RPC
endpoint management.
* TOC
{:toc}
### admin_addPeer
### admin_addPeer
@ -16,7 +12,7 @@ The `addPeer` administrative method requests adding a new remote node to the lis
nodes. The node will try to maintain connectivity to these nodes at all times, reconnecting every
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.
once in a while if the remote connection goes down.
The method accepts a single argument, the [`enode`](https://github.com/ethereum/wiki/wiki/enode-url-format)
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
URL of the remote peer to start tracking and returns a `BOOL` indicating whether the peer was accepted
for tracking or some error occurred.
for tracking or some error occurred.
@ -91,7 +87,7 @@ It returns a boolean indicating whether the operation succeeded.
The `nodeInfo` administrative property can be queried for all the information known about the running
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
Geth node at the networking granularity. These include general information about the node itself as a
participant of the [ÐΞVp2p](https://github.com/ethereum/wiki/wiki/%C3%90%CE%9EVp2p-Wire-Protocol) P2P
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
overlay protocol, as well as specialized information added by each of the running application protocols
(e.g. `eth`, `les`, `shh`, `bzz`).
(e.g. `eth`, `les`, `shh`, `bzz`).
@ -141,7 +137,7 @@ The type of events emitted by the server are as follows:
The `peers` administrative property can be queried for all the information known about the connected
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
remote nodes at the networking granularity. These include general information about the nodes themselves
as participants of the [ÐΞVp2p](https://github.com/ethereum/wiki/wiki/%C3%90%CE%9EVp2p-Wire-Protocol)
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
P2P overlay protocol, as well as specialized information added by each of the running application
The `debug` API gives you access to several non-standard RPC methods, which will allow you
The `debug` API gives access to several non-standard RPC methods, which allow inspection, debugging and setting certain debugging flags during runtime.
to inspect, debug and set certain debugging flags during runtime.
* TOC
{:toc}
### debug_accountRange
### debug_accountRange
@ -228,7 +225,7 @@ Retrieves and returns the RLP encoded block by number.
The `debug_traceCall` method lets you run an `eth_call` within the context of the given block execution using the final state of parent block as the base. The first argument (just as in `eth_call`) is a [transaction object](/docs/rpc/objects#transaction-call-object). The block can be specified either by hash or by number as the second argument. A tracer can be specified as a third argument, similar to `debug_traceTransaction`. It returns the same output as `debug_traceTransaction`.
The `debug_traceCall` method enables running an `eth_call` within the context of the given block execution using the final state of parent block as the base. The first argument (just as in `eth_call`) is a [transaction object](/docs/rpc/objects#transaction-call-object). The block can be specified either by hash or by number as the second argument. A tracer can be specified as a third argument, similar to `debug_traceTransaction`. It returns the same output as `debug_traceTransaction`.
| Client | Method invocation |
| Client | Method invocation |
|:-------:|-----------------------------------|
|:-------:|-----------------------------------|
@ -689,7 +686,7 @@ as it was executed on the network. It will replay any transaction that may have
to this one before it will finally attempt to execute the transaction that corresponds to the given
to this one before it will finally attempt to execute the transaction that corresponds to the given
hash.
hash.
In addition to the hash of the transaction you may give it a secondary *optional* argument, which
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:
specifies the options for this specific call. The possible options are:
* `disableStorage`: `BOOL`. Setting this to true will disable storage capture (default = false).
* `disableStorage`: `BOOL`. Setting this to true will disable storage capture (default = false).
@ -744,7 +741,7 @@ specifies the options for this specific call. The possible options are:
#### JavaScript-based tracing
#### JavaScript-based tracing
Specifying the `tracer` option in the second argument enables JavaScript-based tracing. In this mode, `tracer` is interpreted as a JavaScript expression that is expected to evaluate to an object which must expose the `result` and `fault` methods. There exist 3 additional methods, namely: `step`, `enter` and `exit`. You must provide either `step`, or `enter` AND `exit`(i.e. these two must be exposed together). You may expose all three if you choose to do so.
Specifying the `tracer` option in the second argument enables JavaScript-based tracing. In this mode, `tracer` is interpreted as a JavaScript expression that is expected to evaluate to an object which must expose the `result` and `fault` methods. There exist 3 additional methods, namely: `step`, `enter` and `exit`. One of either `step`, or `enter` AND `exit`must be provided(i.e. `enter` and `exit` must be exposed together). All three can be provided together.
##### Step
##### Step
@ -768,7 +765,7 @@ and the following methods:
If error is non-empty, all other fields should be ignored.
If error is non-empty, all other fields should be ignored.
For efficiency, the same `log` object is reused on each execution step, updated with current values; make sure to copy values you want to preserve beyond the current call. For instance, this step function will not work:
For efficiency, the same `log` object is reused on each execution step, updated with current values; make sure to copy values that are needed beyond the current call. For instance, this step function will not work:
function(log) {
function(log) {
this.logs.append(log);
this.logs.append(log);
@ -887,30 +884,27 @@ Sets the logging verbosity pattern.
#### Examples
#### Examples
If you want to see messages from a particular Go package (directory)
To see messages from a particular Go package (directory)
and all subdirectories, use:
and all subdirectories, use:
``` javascript
``` javascript
> debug.vmodule("eth/*=6")
> debug.vmodule("eth/*=6")
```
```
If you want to restrict messages to a particular package (e.g. p2p)
To restrict messages to a particular package (e.g. p2p)
but exclude subdirectories, use:
but exclude subdirectories, use:
``` javascript
``` javascript
> debug.vmodule("p2p=6")
> debug.vmodule("p2p=6")
```
```
If you want to see log messages from a particular source file, use
To see log messages from a particular source file, use
``` javascript
``` javascript
> debug.vmodule("server.go=6")
> debug.vmodule("server.go=6")
```
```
You can compose these basic patterns. If you want to see all
To see all output from peer.go in a package below eth (eth/peer.go, eth/downloader/peer.go) as well as output from package p2p at level <= 5, use:
output from peer.go in a package below eth (eth/peer.go,
eth/downloader/peer.go) as well as output from package p2p
Joe
2 years ago