Try Astrograph: Your GraphQL lens for Stellar blockchain

Blockchain meets GraphQL with the beta release of Astrograph —a robust Node/TypeScript server that provides a single endpoint to explore the entirety of  Stellar network. It also offers reliable WebSocket-based subscriptions, allowing you to build real-time tools for the mature distributed ecosystem faster and with less effort. You can check out the new tool right now in our dedicated playground .

A non-profit Stellar Development Foundation is on a mission to develop the new world’s economy with a blockchain-based infrastructure that is designed to integrate naturally with traditional banks and payment systems. It is based on a fast consensus-based protocol that does not involve resource-draining mining and solves the problem of transaction speeds that is becoming more and more of an issue in the world of  Bitcoin . An integrated distributed exchange makes it easier to trade third-party currencies, including the so-called stable coins that are backed by real currency reserves (one example is the  Stronghold USD , recently endorsed by IBM).

With the focus on the real economy, Stellar becomes more and more appealing to financial institutions and large corporations that are looking into ways to move money across borders at high speeds and low costs.

After working on commercial Stellar-based solutions, we have contributed to the ecosystem by co-authoring a Stellar Web Authentication proposal. Now we see an even bigger opportunity to give back to the community.

Meet Astrograph , a GraphQL interface to Stellar blockchain.

With this first beta release, we are open-sourcing a research project that we have been working on for the past few months. We believe that a new tool will make Stellar even more appealing to developers and lower the barrier for entry into its ecosystem.

You can experiment with GraphQL access to Stellar network by using Astrograph’s playground , or by running test requests from your client applications against the API that is publicly available at  https://demo.astrograph.io/graphql .

Just keep in mind that the schema is still work in progress and is subject to change, so we do not recommend to rely on this endpoint in production.

A GraphQL alternative to Horizon

The promise of any blockchain is full accountability, and Stellar is no exception: anything that happens on a network, be it a creation of a new account, a transfer of an asset, or a token offering, is baked into the ledger. Everything that ever happened on the network can be scrutinized, and if you swear by the REST philosophy, Stellar already got you covered.

While stellar-core implements the blockchain itself, a service called Horizon allows clients to  explore the network by sending HTTP requests to the selection of REST API endpoints: one for accounts, one for operations, one for assets, and so on. You can also stream information from certain endpoints by subscribing to  Server-Sent Events .

Being a RESTful service, Horizon comes with inherent limitations: you get either a set of entities or a single entity, depending on the endpoint. If you need more sophisticated filtering, you have first to retrieve a large set of records from the API, and then iterate over it in your application code.

Here is the list of things that are either impossible or require some hackery to implement, like resorting to SQL queries directly into stellar-core or Horizon databases (provided you run your own nodes):

• Monitoring events concerning a specific asset . If you are a token issuer, it is not easy to get a grip on all activities associated with your asset.
• Complex queries, like getting all accounts having a specific signer.
• Filtering operations for a specific account by type, asset involved, or payment destination.

That makes building complex dashboards, common in financial applications, less trivial than it might seem by glancing at the Horizon documentation.

REST as an approach is perfect for the resource-oriented structure of the classic web, but it falls short when we start dealing with replicated state machines , such as Stellar.

The linked-list nature of a blockchain does not map well to relational or RESTful concepts. A ledger is, in fact, an enormous graph, so it is better to treat it like one.

Astrograph solves most of the problems above by allowing you to make infinitely flexible queries with GraphQL: a format much more suited for the purpose.

Let’ see it in action!

A single endpoint to rule them all

Getting started with Astrograph does not require any installation or setup. If you are familiar with GraphQL and basic Stellar concepts, you can go directly to the playground on the project’s website, examine the available schema and form your own queries.

Here’s how to get information on the given account’s balance and its signers with Astrograph:

query {
  account(id: "GB6NVEN5HSUBKMYCE5ZOWSK5K23TBWRUQLZY3KNMXUZ3AQ2ESC4MY4AQ") {
    id
    sequenceNumber
    balances {
      asset {
        native
        issuer {
          id
        }
        code
      }
      balance
      limit
      authorized
    }
    signers {
      signer
      weight
    }
  }
}

The result will be roughly the same as you can achieve by sending a traditional GET request to the Horizon’s /accounts endpoint. In case you also need a list of the  last 10 operations involving the account, you will need to send another request to the  /operations endpoint.

With Astrograph, you can get all the data you need in a single request to a single endpoint, just by appending a field to your GraphQL query:

query {
  account(id: "GB6NVEN5HSUBKMYCE5ZOWSK5K23TBWRUQLZY3KNMXUZ3AQ2ESC4MY4AQ") {
    # ...
    signers {
      signer
      weight
    }
    operations(last: 10) {
      nodes {
        id
        kind
        dateTime
        # Including the amount and the currency code for payments
        ... on PaymentOperation {
          amount
          asset { code }
        }
      }
    }
  }
}

Astrograph makes coming up with evolved queries easy and intuitive, as GraphQL is self-documenting by nature, and you can explore the current schema in real time.

The schema description in Astrograph’s playground reflects the current state of the project

In this early release, we support top-level queries for accounts , assets , ledgers , offers , transactions , and  operations . Other Horizon endpoints such as effects or  paths are still work in progress, and we will keep adding support for them in the future releases.

Effortless real-time subscriptions

The world of finance as we know it is built on real-time tools. From ticker tape to  Bloomberg Terminal to  Google Finance —whoever gets the hand on a pulse of a market, gets the edge. Blockchain economy is not the exception.

Stellar is designed for trading. Some of the tokens issued on a network are built to represent fiat currencies, with services like StellarX allowing you to engage in Forex-like trading entirely through blockchain. Such platforms currently rely on Horizon streams that allow receiving push updates from select REST API endpoints.

The real-time functionality in Horizon is implemented with Server-Sent Events. For instance, if you want to follow all operations for a given account in real-time, all you have at your disposal is a regular /operations endpoint with no filtering options. Your application will get a constant stream of  all operations happening on the network, and it would be your duty to pick the ones you want. You can either do it directly on the client (also keeping in mind that each new subscription with SSE will result in a new open HTTP connection, and there is a  browser limit to the number of simultaneous per-server connections), or you can filter incoming stream on the back-end and use your own implementation of SSE or WebSockets to push relevant updates to the client.

With Astrograph, you can get just the real-time data you want without any hassle.

Subscriptions are built into a GraphQL specification and are widely supported in popular front-end and back-end libraries, such as Apollo . As everything happens over WebSockets on a single connection to a single endpoint with filtering capabilities built-in, all you need to do is to write a few lines of code and let the ecosystem handle the rest. It makes developing data-intensive real-time applications like online wallets or cryptocurrency exchanges much easier from the engineering point of view.

Try pasting this snippet into the Astrograph Playground to follow operations involving Stellar’s native currency Lumens across the network in real time. Every time the operation is of type Payment , you’ll be able to see the account IDs of a sender and a receiver.

subscription {
  operations(asset: "native") {
    kind
    # You can specify which attributes you need for each operation type
    ... on PaymentOperation {
      amount
      sourceAccount {
        id
      }
      destination {
        id
      }
    }
  }
}

With the same ease, you can subscribe to (and filter) all events related to accounts, offers, trustlines , or data entries. We plan to add more subscriptions as the project evolves. Follow the schema updates on  Astrograph Playground to stay in the loop.

We are also not limiting ourselves to generic subscriptions like the ones offered by Horizon. We are open to adding more specific offerings that are tailored to common Stellar applications. For the demonstration purposes, we came up with a tick subscription that makes it dead easy to monitor best bid/ask prices for any pair of assets issued on Stellar.

Let’s say we want to follow the exchange rate between Stronghold USD to Lumens in real time like it’s done on the Astrograph’s landing page . Given Apollo Client already configured, here is the simplest possible TypeScript code that just logs real-time values to the console:

import { gql } from "graphql-tag";
import ApolloClient from "apollo-client";

// The asset code and the issuer's public key
const SELLING = "USD-GBSTRUSD7IRX73RQZBL3RQUH6KS3O4NYFY3QCALDLZD77XMZOPWAVTUK";
// Native Lumens
const BUYING = "native";

// Form the subscription request
const SUBSCRIPTION = gql`
  subscription tick($selling: AssetID!, $buying: AssetID!) {
    tick(selling: $selling, buying: $buying) {
      bestBid
      bestAsk
    }
  }
`;

// assuming apolloClient is initialized
apolloClient
  .subscribe({
    query: SUBSCRIPTION,
    variables: {
      selling: SELLING,
      buying: BUYING
    }
  })
  .subscribe({
    next(data: any) {
      const values = data.data.tick;
      console.log(
        `[${new Date().toISOString()}]`,
        "BID/ASK:",
        `${values.bestBid}/${values.bestAsk}`
      );
    }
  });

Instead of USD from Stronghold , you can monitor a price of EUR represented by Tempo or Chinese Yuan from RippleFox —all you need is to change is an ID of an asset.

Check the full example for a CLI implementation of the ticker in the  examples folder in the Astrograph’s repo . You can also run this example locally like this:

$ git clone https://github.com/astroband/astrograph.git
$ cd astrograph && yarn && yarn exec ts-node examples/tick.ts

Next challenge: Historical records

In its current form, Astrograph is perfect for browsing the current state of the Stellar network. It does not yet offer a way to perform deep searches over the history of several ledgers that would be required for analytical applications like fraud detection.

The way storage is currently implemented in stellar-core and Horizon is a tradeoff between efficiency and ease of querying: it’s a combination of disk and database storage with two different approaches to relational schema design. Some of the data remains in the Stellar’s native XDR format, designed to be transmitted quickly and stored efficiently, while some of the data is decoded and repackaged for ease of querying.

This approach works, but the structure of XDR is document-oriented by design. It does not map well to relational databases, plus it changes slightly between protocol versions, forcing to opt for loosely structured JSON columns in PostgreSQL that currently underlies Stellar’s persistence.

Keeping all that in mind, we started working on the implementation of our own ingestion mechanism for Astrograph. As the Stellar network can be seen as a graph with myriads of edges (account is connected to many assets through trustlines, assets are related to issuing accounts which are connected to one or more signers, who in turn have their own transactions, and so on), we have invested into experimenting with graph databases and made a particularly good progress with DGraph .

However, our working proof of concept was not suitable for production due to ingestion time and disk space constraints. Now we are looking into augmenting graph-based storage solutions with fast indexing engines such as Elasticsearch , and we already had some promising progress.

We are optimistic about adding ingestion capabilities to Astrograph in future releases.

Talk to us

Astrograph is an  open-source project , currently powered by the Apollo Server in the backend and is written entirely in TypeScript. We have considered both Go and Rust as alternatives, yet we came to the conclusion that Apollo/TS combination gives us a much cleaner, shorter, and more readable code, plus the ecosystem around GraphQL is inherently JS-oriented.

Cloning the GitHub repository and making a pull request is a welcome way to contribute to the project, but not the only one.

As trying out Astrograph does not require any installation or setup and you can explore Stellar through GraphQL right in our playground , we welcome you to start testing your queries.

With this beta release, we primarily want to see how our current schema fits your real-world needs and how it can be improved. Are you building a product based on a Stellar network and think you can benefit from GraphQL’s flexibility and ease of use? Feel free totell us about your specific needs so we can introduce more queries, connections, or filters.

Do you have a use case for real-time subscriptions in your application and see the possibility to write less code for more value? Together, we can come up with a subscription type that can fit your specific needs.

It is hard for us to imagine all possible applications for Astrograph without the voice of blockchain enthusiasts who are passionate about the Stellar ecosystem. Help us make sure that our open-source project serves its purpose: to provide a modern and powerful tool for any Stellar developer out there.

If you feel like your Stellar-oriented codebase might become leaner with Astrograph, or if you were waiting to start working with blockchain but needed an easier way in—also feel free todrop us a line, we have enough experience in commercial projects for Stellar ecosystem to help you out.