{"id":13728385,"url":"https://github.com/astroband/astrograph","last_synced_at":"2025-04-05T14:08:49.629Z","repository":{"id":34146458,"uuid":"133501331","full_name":"astroband/astrograph","owner":"astroband","description":"Access Stellar ledger via GraphQL","archived":false,"fork":false,"pushed_at":"2024-10-08T01:50:32.000Z","size":3685,"stargazers_count":112,"open_issues_count":74,"forks_count":11,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-10-30T08:49:08.172Z","etag":null,"topics":["blockchain","dgraph","graphql","graphql-server","stellar"],"latest_commit_sha":null,"homepage":"https://astrograph.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/astroband.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-15T10:41:19.000Z","updated_at":"2024-07-16T02:19:23.000Z","dependencies_parsed_at":"2023-01-15T05:01:05.373Z","dependency_job_id":"a0c79b1c-754d-4e32-ab83-27a8cf7ad823","html_url":"https://github.com/astroband/astrograph","commit_stats":{"total_commits":872,"total_committers":9,"mean_commits":96.88888888888889,"dds":0.5206422018348624,"last_synced_commit":"63df431d21ae6253c7a564bcda3c657bdc76d108"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astroband%2Fastrograph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astroband%2Fastrograph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astroband%2Fastrograph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/astroband%2Fastrograph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/astroband","download_url":"https://codeload.github.com/astroband/astrograph/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247345854,"owners_count":20924102,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","dgraph","graphql","graphql-server","stellar"],"created_at":"2024-08-03T02:00:41.559Z","updated_at":"2025-04-05T14:08:49.588Z","avatar_url":"https://github.com/astroband.png","language":"TypeScript","readme":"[![Build Status](https://img.shields.io/travis/com/astroband/astrograph/master.svg)](https://travis-ci.com/astroband/astrograph)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=astroband_astrograph\u0026metric=sqale_rating)](https://sonarcloud.io/dashboard?id=astroband_astrograph)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=astroband_astrograph\u0026metric=security_rating)](https://sonarcloud.io/dashboard?id=astroband_astrograph)\n[![License](https://img.shields.io/github/license/astroband/astrograph.svg)](raw/master/LICENSE.txt)\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fastroband%2Fastrograph.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fastroband%2Fastrograph?ref=badge_shield)\n\n# Astrograph\n\n\u003cimg align=\"right\" width=\"150\" height=\"150\"\n     alt=\"Graph of stars reflected in telescope lens, logo of Astrograph\"\n     src=\"https://astrograph.io/logo.svg\"\u003e\n\n**Important** This project is still under heavy active development. Until it reaches 1.0 breaking changes may land without prior notice.\n\nAstrograph is a GraphQL server for the [Stellar](https://www.stellar.org/) network. You can think about it as a GraphQL version of [Horizon](https://github.com/stellar/go/tree/master/services/horizon), the client-facing API server for the Stellar ecosystem. \n\nAstrograph allows you to retrieve various data from the blockchain, as well as allowing you to subscribe to particular events using [GraphQL subscriptions](https://github.com/apollographql/graphql-subscriptions) mechanisms.\n\nAstrograph was initially developed by Evil Martians for [Mobius](https://mobius.network) 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](.github/CONTRIBUTING.md).\n\n\u003ca href=\"https://evilmartians.com/?utm_source=astrograph\"\u003e\n\u003cimg src=\"https://evilmartians.com/badges/sponsored-by-evil-martians.svg\" alt=\"Sponsored by Evil Martians\" width=\"236\" height=\"54\"\u003e\u003c/a\u003e\n\n## Install\n\n### Docker compose\n\nSo the most simple way to launch Astrograph to try it out is with `docker-compose`:\n\n```shell\n# For the pubnet\ndocker-compose -f docker_compose/docker-compose.pubnet.yaml up -d\n# wait a little for the stellar-core and postgres to start up and then run the next command\n# to to enhance core database for the Astrograph needs\ndocker exec -it astrograph-stellar-core-postgres-pubnet psql -U stellar -d stellar -f /init.sql\n\n# For the testnet\ndocker-compose -f docker_compose/docker-compose.testnet.yaml up -d\n# wait a little for the stellar-core and postgres to start up and then run the next command\n# to to enhance core database for the Astrograph needs\ndocker exec -it astrograph-stellar-core-postgres-testnet psql -U stellar -d stellar -f /init.sql\n```\n\nContainers created with these commands export the next ports you can access:\n\n* Astrograph GraphQL sandbox -- `4000`(pubnet) and `5000`(testnet)\n* Stellar core HTTP ports -- `11625` and `11626`(pubnet), `12625` and `12626`(testnet)\n* Elasticsearch HTTP endpoint -- `9200` (pubnet) and `9300` (testnet)\n\nWe chose such port mapping to allow both pubnet and testnet instances to run simultaneously\n\nTo test that Astrograph was setup correctly, visit GraphQL sandbox (http://localhost:4000 for pubnet and http://localhost:5000 for testnet), and\ntry to subscribe to new ledgers:\n\n```graphql\nsubscription {\n  ledgerCreated {\n    seq\n  }\n}\n```\n\nYou should see new ledgers coming. Remember that you should wait for stellar-core to start applying ledgers, so monitor it with stellar-core `info` HTTP-command\n(e.g., like this: `curl localhost:11626/info` for pubnet and `curl localhost:12626/info` for testnet, you need `state` attribute) before running the test above.\n\n## Develop\n\nFor the developing purposes you can setup Astrograph as a standalone js-application:\n\n```shell\n$ git clone https://github.com/astroband/astrograph\n$ cd astrograph\n$ yarn                        # install dependencies\n$ yarn run dev                # for developing purposes\n$ yarn run prod               # for live setup\n$ yarn ts-node src/ingestd.ts # live ingesting for subscriptions\n``` \n\nCreate assets view in database:\n\n```\nCREATE VIEW assets AS\n( SELECT (t.assetcode::text || '-'::text) || t.issuer::text AS id,\n    t.assetcode AS code,\n    t.issuer,\n    a.flags,\n    sum(t.balance) AS \"totalSupply\",\n    sum(t.balance) FILTER (WHERE t.flags = 1) AS \"circulatingSupply\",\n    count(t.accountid) AS \"holdersCount\",\n    count(t.accountid) FILTER (WHERE t.flags = 0) AS \"unauthorizedHoldersCount\",\n    max(t.lastmodified) AS \"lastActivity\"\n   FROM trustlines t JOIN accounts a ON t.issuer::text = a.accountid::text\n  GROUP BY t.issuer, t.assetcode, a.flags\n  ORDER BY (count(t.accountid)) DESC)\nUNION\n SELECT 'native'::text AS id,\n    'XLM'::character varying AS code,\n    NULL::character varying AS issuer,\n    4 AS flags,\n    sum(accounts.balance) AS \"totalSupply\",\n    sum(accounts.balance) AS \"circulatingSupply\",\n    count(*) AS \"holdersCount\",\n    0 AS \"unauthorizedHoldersCount\",\n    max(accounts.lastmodified) AS \"lastActivity\"\n   FROM accounts;\n```\n\n## Configure\n\nHere is the list of available settings:\n\n* `STELLAR_NETWORK` – which Stellar network to use. You can use \"pubnet\"(default) or \"testnet\" shortcuts, any other value will be used as a network passphrase\n* `DATABASE_URL` – database connection URL\n* `PORT` - port (4000 by default)\n* `BIND_ADDRESS` - address to bind (\"0.0.0.0\" by default)\n* `INGEST_INTERVAL` – database polling interval in milliseconds (2000 by default)\n* `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.\n* `DEBUG_SQL` - when set, log sql queries.\n* `SENTRY_DSN` - DSN string for integration with [Sentry](https://sentry.io)\n\nYou can set them all using environmental variables, or you can create the `.env` file in the root of the project, and set them there:\n\n```\nDB=\"stellar_core\"\nDBUSER=\"john\"\n...\n```\n\nIn 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](https://github.com/mobius-network/docker-stellar-core)) and let it ingest some ledgers.\n\nAfter `yarn run dev` [GraphQL playground](https://www.npmjs.com/package/graphql-playground) will be available on `http://localhost:4000`\n\nAlso, in order for subscriptions to work, live ingesting should be started. You can start it with `yarn ts-node src/ingestd.ts` command.\n\n### Testing\n\nAstrograph uses [jest](https://github.com/facebook/jest) for the tests.\n\nYou can run all available tests with `yarn run test` command.\n\nAstrograph ships with integration tests too.\nYou should configure test database connection with `.env.test` file before running them because they are using [database fixture](tests/test_db.sql).\n`.env.test` file presence is mandatory to prevent accidental overwriting your stellar-core database with the fixture!\n\nYou can run unit and integration tests separately, using the next commands:\n\n```\nyarn run test:unit\nyarn run test:integration\n```\n\n## Usage\n\nLet's go straight to some example queries:\n\n### Getting account info\n\n```graphql\nquery {\n  account(id: \"GBSTRUSD7IRX73RQZBL3RQUH6KS3O4NYFY3QCALDLZD77XMZOPWAVTUK\") {\n    id\n    inflationDestination { id }\n    sequenceNumber\n    balances {\n      asset {\n        id\n        code\n        issuer { id }\n      }\n      balance\n      limit\n    }\n    data {\n      name\n      value\n    }\n    signers {\n      signer\n    }\n    ledger {\n      seq\n      header {\n        ledgerVersion\n      }\n    }\n    flags {\n      authRequired\n      authRevocable\n      authImmutable\n    }\n    thresholds {\n      masterWeight\n      low\n      medium\n      high\n    }\n  }\n}\n```\n\nThere is also a corresponding query for multiple accounts:\n\n```graphql\nquery {\n  accounts(id: [\n    \"GCCD6AJOYZCUAQLX32ZJF2MKFFAUJ53PVCFQI3RHWKL3V47QYE2BNAUT\",\n    \"GBSTRUSD7IRX73RQZBL3RQUH6KS3O4NYFY3QCALDLZD77XMZOPWAVTUK\"\n  ]) {\n    # ...\n  }\n}\n```\n\n## Subscriptions\n\nThe most exciting and powerful feature of Astrograph is subscriptions.\n\nGenerally, you can subscribe to the next events: `CREATE`, `UPDATE` and `REMOVE`. To subscribe individually to events you need, you can use the next filters:\n\n* `mutationType[]` – event type(s) to subscribe to.\n* `idEq` and `idIn[]` – stellar account public address you're interested in\n\nThe typical published event contains the next attributes:\n\n* `mutationType` – event type\n* `values` holds new values for changed entity. It is `null` for the `REMOVE` events.\n* Key fields: `id` for account, `account` + `asset` for trust line, etc.\n\nHere are some examples:\n\n### Awaiting for missing account to be created\n\n```graphql\nsubscription {\n  account(args: {\n    idEq: \"GAK3NSB43EVCZKDH4PYGJPCVPOYZ7X7KIR3ZTWSYRKRMJWGG5TABM6TH\",\n    mutationTypeIn: [CREATE]\n  }) {\n   \tid\n    mutationType\n    values {\n      homeDomain\n      thresholds {\n        low\n        medium\n        high\n        masterWeight\n      }\n    }\n  }\n}\n```\n\n### Monitoring account balance\n\n```graphql\nsubscription {\n  balance(args: {\n    idEq: \"GCCD6AJOYZCUAQLX32ZJF2MKFFAUJ53PVCFQI3RHWKL3V47QYE2BNAUT\",\n    mutationTypeIn: [UPDATE]\n  }) {\n    mutationType\n    account { id }\n    values {\n      asset {\n        id\n        code\n        issuer { id }\n      }\n      balance\n    }\n  }\n}\n```\n\nCheck out the [examples](examples) folder for more!\n\n\n## Console\n\nTo show all account trust lines:\n\n```shell\n$ yarn ts-node examples/balance-cli.ts GA4DMQ3VSHIVROQ42PJVJOD7X4PYT5BXAWV672CAWOWIADXC3RGZEOMZ\n```\n\nTo monitor account trust line changes:\n\n```shell\n$ yarn ts-node examples/balance-monitor-cli.ts GA4DMQ3VSHIVROQ42PJVJOD7X4PYT5BXAWV672CAWOWIADXC3RGZEOMZ\n```\n\nAll examples are assuming that Astrograph is running on `localhost:4000`. You can pass URL as a second parameter.\n\n## Benchmark\n\nWe 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](benchmark/index.ts) for details. To implement the fully functional test, we need to implement a dedicated stress test mode.\n\n## Maintainers\n\n* Victor Sokolov (@gzigzigzeo)\n* Timur Ramazanov (@charlie-wasp)\n* Sergey Nebolsin (@nebolsin)\n\n## License\n\nThe project is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT)\n\nParts of the path finding engine include the original code from [stellar-pathfinder-server](https://github.com/future-tense/stellar-pathfinder-server)\nproject created by [Johan Stén](https://github.com/johansten]) and [Future Tense, LLC](https://github.com/future-tense),\nadapted and modified by Astrograph project team.\n\n\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fastroband%2Fastrograph.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fastroband%2Fastrograph?ref=badge_large)","funding_links":[],"categories":["Developer Resources","开发者资源","TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastroband%2Fastrograph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fastroband%2Fastrograph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastroband%2Fastrograph/lists"}