GraphQL is a query language for APIs, which allows you to query large data sets by specifying the format of the expected result. Our large data set will be the Ethereum blockchain and we’ll query it for things like events, client sync status, and transaction data.
Ethereum Grid makes it easy to configure and use Geth, the go-ethereum client, including its GraphQL server via an accessible UI. This quick tutorial will get you started.
Step 1: Download Grid
Grid‘s mission is to empower users with the latest and greatest of the Ethereum ecosystem toolset.
Grid is a desktop app that makes it easy to download and configure Ethereum tools. Mac, Windows, and Linux builds are available at grid.ethereum.org. Once downloaded and started, Grid will live in your OS menu bar as an Ethereum logo.
Step 2: Configure and Start Geth
Navigate to the Geth plugin in Grid, then, under the “Version” tab, download the latest version of Geth (GraphQL support was introduced in v1.9.0). Note: if you already have Geth installed on your system, this step is still necessary if you want to configure it via Grid. Grid manages binaries locally.
In the “Settings” tab, select the dropdown for
Enable GraphQL Server. We’re just exploring, so
Görli (testnet) is a good option for the network. Once configured, toggle the switch on to start Geth.
Step 3: Navigate to the GraphiQL Interface
GraphiQL is a fantastic in-browser IDE for exploring and querying GraphQL APIs. Geth makes this interface available at
http://localhost:8547, but you can also access it within Grid via the Geth GraphQL Explorer App, which can be found under the “About” tab.
Step 4: Run Some Queries
Let’s jump into it with some examples.
Querying for Syncing State
This query returns data on the state of your node’s syncing status.
Querying for Events
This query (from the launch post) finds the ENS
HashRegistered events on the Görli network and returns the address of the user doing the registration along with the block number and timestamp it was included in.
Use the schema documentation to explore what’s possible (hint: “Docs” button in the upper right corner of GraphiQL). As you begin typing a query, GraphiQL will autocomplete all possible options based on the schema. The example use cases provided by EthQL should prove useful as well.
Bonus: Consuming GraphQL Data
You can build a webapp now that connects to the GraphQL instance running on
localhost:8547 and send queries to the
/graphql endpoint using a client like Apollo.
If you would like to customize some of the Geth GraphQL flags further, you may click
Use custom flags and tweak the following attributes:
--graphqlEnable the GraphQL server
--graphql.addr valueGraphQL server listening interface (default: “localhost”)
--graphql.port valueGraphQL server listening port (default: 8547)
--graphql.corsdomain valueComma separated list of domains from which to accept cross origin requests (browser enforced)
Calling a Contract Function
Executing a contract function can be done by using the
call function with the contract’s method signature. A contract’s method signature is the hash of the method you are looking to call, like
balanceOf, along with the encoded parameters, like
address. You can learn more about Contract ABI and see useful utils to derive the signature from web3.js.
In the below code snippet, I’ll show how to query an ERC20 token balance using the Apollo GraphQL client:
In many cases, GraphQL is a stellar alternative to REST APIs. In querying block data, GraphQL’s simple interface is a significant improvement over the JSON-RPC API, giving you exactly the data you need in the format and structure you want it.
Geth’s GraphQL implementation is based on EIP 1767: GraphQL interface to Ethereum node data with efforts led by Consensys’ EthQL team. Keep an eye on them for more exciting developments in additional query fields and types like ERC20 transfers and balances, ENS names, and more.
If you run into any issues or have any suggestions for Grid or our Geth integration, please share your feedback with us. Is there another project you’d like to see integrated within Grid to provide an accessible UI? Let us know!