Skip to content
Access Stellar ledger via GraphQL
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Move CoC to .github, add codeowners and contributing.md Feb 20, 2019
_experimental Memoize Keypair.master() Jan 16, 2019
benchmark Benchmark script + README update Sep 11, 2018
dgraph dgraph alpha Nov 9, 2018
examples Fix balance subscription on trustline remove event Apr 10, 2019
scripts
src Keep ingesting on errors Apr 16, 2019
tests
.dockerignore .dockerignore, two-stage build, fixed tsc build error in resolvers Sep 18, 2018
.gitignore Cleanup project configuration and Travis setup (#116) Feb 18, 2019
.prettierignore WIP Apollo GraphQL + pg-promise + TypeScript Aug 1, 2018
.prettierrc Working account query with flags and thresholds Aug 10, 2018
.travis.yml Enable Travis cache + full blame history for Sonar Mar 18, 2019
LICENSE.txt CoC, LICENSE, Contributing Sep 4, 2018
README.md
codecov.yml Cleanup project configuration and Travis setup (#116) Feb 18, 2019
graphql.config.json WIP Apollo GraphQL + pg-promise + TypeScript Aug 1, 2018
nodemon.json Transactions WIP Aug 7, 2018
package.json Update tslint & fix reported issues Apr 9, 2019
sonar-project.properties
tsconfig.build.json Cleanup project configuration and Travis setup (#116) Feb 18, 2019
tsconfig.json Cleanup project configuration and Travis setup (#116) Feb 18, 2019
tslint.json Update tslint & fix reported issues Apr 9, 2019
yarn.lock

README.md

Build Status Maintainability Rating Security Rating License

Astrograph

Important This project is still under heavy active development. Until it reaches 1.0 breaking changes may land without prior notice.

Astrograph is a GraphQL server for the Stellar network. You can think about it as a GraphQL version of Horizon, the client-facing API server for the Stellar ecosystem.

Astrograph allows you to retrieve various data from the blockchain, as well as allowing you to subscribe to particular events using GraphQL subscriptions mechanisms.

Astrograph was initially developed by Evil Martians for Mobius under the MIT license. We continue our work on Astrograph for the benefit of the broader Stellar developer community. Anyone is welcome to contribute to Astrograph, just read CONTRIBUTING.md.

Sponsored by Evil Martians

Install

You can install Astrograph, using yarn:

$ git clone https://github.com/astroband/astrograph
$ cd astrograph
$ yarn                        # install dependencies
$ yarn run dev                # for developing purposes
$ yarn run prod               # for live setup
$ yarn ts-node src/ingestd.ts # live ingesting for subscriptions

Configure

Here is the list of available settings:

  • STELLAR_NETWORK – which Stellar network to use ("pubnet" or "testnet", "pubnet" by default)
  • DB – stellar-core database name ("stellar" by default)
  • DBPORT – database port to connect to (5432 by default)
  • DBHOST – database host to connect to
  • DBUSER – database user to connect with ("stellar" by default)
  • DBPASSWORD – password to access the database (no password by default)
  • PORT - port (4000 by default)
  • BIND_ADDRESS - address to bind ("0.0.0.0" by default)
  • INGEST_INTERVAL – database polling interval in milliseconds (2000 by default)
  • DEBUG_LEDGER – when set, Astrograph will start ingesting ledgers, starting from that. It's useful for debugging. Pass -1 to force ingest from first ledger existing in database.
  • DEBUG_SQL - when set, log sql queries.
  • SENTRY_DSN - DSN string for integration with Sentry

You can set them all using environmental variables, or you can create the .env file in the root of the project, and set them there:

DB="stellar_core"
DBUSER="john"
...

Develop

In order to develop locally, you need to get the stellar-core database. The easiest way to get it is to run stellar-core node in docker (check docker-stellar-core) and let it ingest some ledgers.

After yarn run dev GraphQL playground will be available on http://localhost:4000

Also, in order for subscriptions to work, live ingesting should be started. You can start it with yarn ts-node src/ingestd.ts command.

Testing

Astrograph uses jest for the tests.

You can run all available tests with yarn run test command.

Astrograph ships with integration tests too. You should configure test database connection with .env.test file before running them because they are using database fixture. .env.test file presence is mandatory to prevent accidental overwriting your stellar-core database with the fixture!

You can run unit and integration tests separately, using the next commands:

yarn run test:unit
yarn run test:integration

Usage

Let's go straight to some example queries:

Getting account info

query {
  account(id: "GBSTRUSD7IRX73RQZBL3RQUH6KS3O4NYFY3QCALDLZD77XMZOPWAVTUK") {
    id
    inflationDestination { id }
    sequenceNumber
    balances {
      asset {
        code
        native
        issuer { id }
      }
      balance
      limit
    }
    data {
      name
      value
    }
    signers {
      signer
    }
    ledger {
      seq
      header {
        ledgerVersion
      }
    }
    flags {
      authRequired
      authRevokable
      authImmutable
    }
    thresholds {
      masterWeight
      low
      medium
      high
    }
  }
}

There is also a corresponding query for multiple accounts:

query {
  accounts(id: [
    "GCCD6AJOYZCUAQLX32ZJF2MKFFAUJ53PVCFQI3RHWKL3V47QYE2BNAUT",
    "GBSTRUSD7IRX73RQZBL3RQUH6KS3O4NYFY3QCALDLZD77XMZOPWAVTUK"
  ]) {
    # ...
  }
}

NOTE: Please note that native balance is returned inside a trustline too, and is marked with the boolean flag.

Subscriptions

The most exciting and powerful feature of Astrograph is subscriptions.

Generally, you can subscribe to the next events: CREATE, UPDATE and REMOVE. To subscribe individually to events you need, you can use the next filters:

  • mutationType[] – event type(s) to subscribe to.
  • idEq and idIn[] – stellar account public address you're interested in

The typical published event contains the next attributes:

  • mutationType – event type
  • values holds new values for changed entity. It is null for the REMOVE events.
  • Key fields: id for account, account + asset for trust line, etc.

Here are some examples:

Awaiting for missing account to be created

subscription {
  account(args: {
    idEq: "GAK3NSB43EVCZKDH4PYGJPCVPOYZ7X7KIR3ZTWSYRKRMJWGG5TABM6TH",
    mutationTypeIn: [CREATE]
  }) {
   	id
    mutationType
    values {
      homeDomain
      thresholds {
        low
        medium
        high
        masterWeight
      }
    }
  }
}

Monitoring account balance

subscription {
  balance(args: {
    idEq: "GCCD6AJOYZCUAQLX32ZJF2MKFFAUJ53PVCFQI3RHWKL3V47QYE2BNAUT",
    mutationTypeIn: [UPDATE]
  }) {
    mutationType
    account { id }
    values {
      asset {
        code
        issuer { id }
        native
      }
      balance
    }
  }
}

Check out the examples folder for more!

Console

To show all account trust lines:

$ yarn ts-node examples/balance-cli.ts GA4DMQ3VSHIVROQ42PJVJOD7X4PYT5BXAWV672CAWOWIADXC3RGZEOMZ

To monitor account trust line changes:

$ yarn ts-node examples/balance-monitor-cli.ts GA4DMQ3VSHIVROQ42PJVJOD7X4PYT5BXAWV672CAWOWIADXC3RGZEOMZ

All examples are assuming that Astrograph is running on localhost:4000. You can pass URL as a second parameter.

Benchmark

We haven't done full stress tests yet. Despite that, it looks like the server on MBP mid 14 with 16GB RAM survives approx 7k concurrent connections with no losses. Check the benchmark script for details. To implement the fully functional test, we need to implement a dedicated stress test mode.

Maintainers

  • Victor Sokolov (@gzigzigzeo)
  • Timur Ramazanov (@charlie-wasp)
  • Sergey Nebolsin (@nebolsin)

License

The project is available as open source under the terms of the MIT License

You can’t perform that action at this time.