AION GraphQL — A Query Layer for AION Blockchain

In this post, I am going to talk about AION GraphQL. It is an opensource project which provides a GraphQL server implementation for AION Blockchain.

Let’s start with a brief description of AION, GraphQL.

AION
Aion is a public blockchain and a smart contract platform which aims to solve scalability, and interoperability issues in blockchain networks. The mainnet network of AION blockchain went live in April’2018. Currently it supports Solidity as Smart Contract language. But more language supports are coming. It’s a decentralized public network where anybody can deploy smart contracts and develop decentralized applications. Out of box, the AION kernel node supports Java RPC and web3 JS api which can be used to interact with the blockchain. More details about Aion can be found at Aion website.

GraphQL

GraphQL is a query language for APIs and a run-time for fulfilling those queries. Similar to REST, GraphQL is an another way to send / receive data over HTTP between client and server. But it has many big advantages over REST and it provides a new way to think about the API.

Unlike REST,
> A GraphQL server usually exposes a single end point or url.
> Client / Consumer application decides which fields to get in the response.

So if a mobile client needs less data from an API, no need to expose an another API endpoint specifically for mobile clients. The same API can work for both desktop and mobile client where mobile client can request for less data and desktop client can have the full set of data.

AION GraphQL

https://aion-graphql.com
The goal of AION GraphQL project is to bring all these advantages of GraphQL to AION blockchain by providing a GraphQL API layer on top of AION blockchain. These APIs can be accessed over https(s) by any GraphQL client library (Apollo or Relay etc.) or by just through normal javascript.

So the dApps developers now have an another way to access or update blockchain data.

The project internally uses Java RPC library provided by AION. The currently supported GraphQL apis can be mapped 1:1 with AION java api. It also provides some easy to understand high-level APIs. More high level apis will be gradually added to the project.

The following APIs are now supported

• blockApi
• txnApi
• accountApi
• adminApi
• chainApi
• netApi
• walletApi
• contractApi

There are three possible types of queries you can do with GraphQL

Query : All read operations. No state change in blockchain.
Mutation: Operations which change blockchain state.
Subscription: Listen to different events in blockchain.

query {
   txnApi {
       transactions(first: 3) {
           to
           from
           value
        }
   }
}

You can easily configure and run a AION GraphQL instance on your own server. Just follow the instructions on the project page.

The project also bundles an opensource GraphQL editor from graphql-playground project, which can be used to query and explore API schema/doc without writing any code.

If you want to try without installing your own instance, you can access the following url. The following instance is available for AION community to try and test GraphQL queries on AION mainnet.

Playground : (In browser editor for testing)

https://api.aion-graphql.com/playground.html

API Endpoint (Needs to be invoked from application)

https://api.aion-graphql.com/graphql

So enough of theory, now let’s try few queries.

Our First Query on AION Blockchain

Go to AION GraphQL Playground and try these queries.

1. Let’s fetch last 2 transactions from the blockchain. For that we need to use txnApi. Try the following query on playground IDE.

query {
  txnApi {
    transactions(first: 2) {
      to
      from
      value
    }
  }
}

By running the above query, you should get the last 2 transactions from AION blockchain.

Response:

{
  "data": {
    "txnApi": {
      "transactions": [
        {
          "to": "a0890be3adcf529711aa142a2e4fb3154ea59b284ce19a1515110c872c6b2a66",
          "from": "a0fde4c8c5b90d55f81970750c80ac7130c269bbbdce5b4ece3cfd10ff7e5f40",
          "value": 1018904574958000000
        },
        {
          "to": "a076a2f223d70abbba726d6f6511886b4780c7a9b70dc23b4fe3a22f169ce74d",
          "from": "a0a1e55cbbffc99d9dcaf56e5350847267471cd6d69d4dead14953e5e82d97bf",
          "value": 1503030942934000000
        }
      ]
    }
  }
}

2. So now let’s say, we also want to fetch the account balance of all involved accounts in last 2 transactions.
Getting account balance needs a call to accountApi. So in normal scenario we need to make two calls to the server to fetch the required details.
1. Get last 2 transactions
2. Get balances for to/from accounts in last 2 transactions.

But in GraphQL, the client needs to make only one call to server to fetch all the required information. GraphQL server will invoke multiple services in server side to get required data.

So our new query to get account balances along with last 2 transactions is as follow

query {
  txnApi {
    transactions(first: 2) {
      fromAccount {
        address
        balance
      }
      toAccount {
        address
        balance
      }
      value
    }
  }
}

Sample response:

{
  "data": {
    "txnApi": {
      "transactions": [
        {
          "fromAccount": {
            "address": "a0f2daa8de60d0e911fb468492242d604e1e11ec6f142bfee15757408aff2902",
            "balance": 144045092702546920000
          },
          "toAccount": {
            "address": "a067c6e7143b9eb37ec7737dd00962b3faab0cc693f3cfebecb576273000cd08",
            "balance": 3127829172462000000   //fetched through accountApi
          },
          "value": 1053836004571000000   //fetched through txnApi
        },
        {
          "fromAccount": {
            "address": "a0f2daa8de60d0e911fb468492242d604e1e11ec6f142bfee15757408aff2902",
            "balance": 144045092702546920000
          },
          "toAccount": {
            "address": "a08842d99d5805b4fa1ef87145875c30afa1044881e7790ab20916f6952d3668",
            "balance": 801481817000067100000
          },
          "value": 1003270840501000000
        }
      ]
    }
  }
}

This is quite powerful. So multiple calls can be merged together to return all required information to the client in one round-trip to the server.

Now that you know how to query using GraphQL, try few other queries in Playground browser IDE. You can take advantage of editor’s autocomplete (ctl + space) and schema document features.

In my next few posts, I plan to cover the following areas :
1. Few other API
2. Mutation and Subscription APIs
3. How to invoke GraphQL api from Javascript application

A demo video

If you have any suggestion or feature request, you can drop a comment in this post. Also, if you would like to involve in this project, let me know or just raise a pull request.

Resources:

1. AION : https://aion.network
2. AION GraphQL : https://aion-graphql.com
3. GraphQL : https://graphql.org/
4. AION GraphQL GITHUB : https://github.com/satran004/aion-graphql