https://github.com/nautls/ergo-graphql
Ergo Platform GraphQL server
https://github.com/nautls/ergo-graphql
blockchain ergo explorer graphql
Last synced: 5 days ago
JSON representation
Ergo Platform GraphQL server
- Host: GitHub
- URL: https://github.com/nautls/ergo-graphql
- Owner: nautls
- License: mit
- Created: 2022-05-16T00:11:41.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2024-11-20T01:41:57.000Z (6 months ago)
- Last Synced: 2025-04-27T01:33:17.481Z (9 days ago)
- Topics: blockchain, ergo, explorer, graphql
- Language: TypeScript
- Homepage:
- Size: 1.82 MB
- Stars: 16
- Watchers: 2
- Forks: 0
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-ergo - Ergo GraphQL - graphql) (🛠️ Development Tooling <a id="development-tooling"></a> / 🔌 Node Interaction & APIs <a id="node-interaction--apis"></a>)
README
# ergo-graphql
Ergo GraphQL server is on top of [Ergo Platform's explorer database schema](https://github.com/ergoplatform/explorer-backend/blob/master/modules/explorer-core/src/main/resources/db/V9__Schema.sql).
This repository also includes a [TypeScript package for client-side static typing](/packages/ts-types/).
## Project Setup (Manual)
```
$ npm ci
```
### Environment file pattern
The `.env` file must be placed in the root directory following the pattern described below.
```env
DB_HOST = # database host address
DB_PORT = # database host port
DB_NAME = # database name
DB_USER_NAME = # database username
DB_USER_PWD = # database password
DB_SSL = # optional: true or false
ERGO_NODE_ADDRESS = # http ergo node address
REDIS_HOST = localhost # optional: redis host address
REDIS_PORT = 6379 # optional: redis host port
REDIS_USER_NAME = # optional: redis username
REDIS_USER_PWD = # optional: redis user password
MAX_QUERY_DEPTH = 5 # optional: maximum query depth
```
### Compile and run for development
```
$ npm run dev
```
### Compile and run for production
```
$ npm run build
$ npm run start
```
### Run unit tests
```
$ npm run test
```
### Lint
```
$ npm run lint
```
## Project Setup (Docker)
You can use Docker to setup the project, or just the redis, as well.
### Building the `ergo-graphql` Docker image
```
$ docker -t ergo-graphql build .
```
Using docker-compose, you can run the whole project, or just the redis container.
### Running the redis container
```
$ docker compose up -d redis # For older versions, use docker-compose
```
### Running the whole project
```
$ docker compose up -d
```
## Requesting Data
You can either install some REST-API client (like [Insomnia](https://insomnia.rest/) and [Postman](https://www.postman.com/)). Or you can use curl to send a query as well:
```
$ curl -H 'Content-Type: application/json' -X POST -d '{"query": "query {...}"}' http://server.url
```
We have a set of queries/mutation as well:
### Boxes (Query)
With this query, you can get boxes of the ergo blockchain. The arguments of this query are:
- `skip`(Int): How many items to skip; Default value is 0.
- `take`(Int): How many items to take; Default value is 50.
- `boxId`(String): To filter a unique box by id; It's deprecated, please use `boxIds` instead.
- `boxIds`([String!]): To filter a set of unique boxes by id.
- `registers`(Registers): To filter boxes that have special registers
from R4 to R9. Note that `registers` filter should be used in combination with `spent` and at least one of `boxId`, `transactionId`, `headerId`, `address`, `ergoTree` or `ergoTreeTemplateHash` fields.
- `transactionId`(String): To filter output boxes of a unique transaction.
- `headerId`(String): To filter boxes by their header id.
- `spent`(Boolean): To filter spent or unspent boxes.
- `tokenId`(String): To filter boxes which contain a certain token.
- `address`(String): To filter boxes of a specific address; It's deprecated, please use `addresses` instead.
- `addresses`([String!]): To filter boxes that belong to an array of addresses.
- `ergoTree`(String): To filter boxes that have specific ergo trees; It's deprecated, please use `ergoTrees` instead.
- `ergoTrees`([String!]): To filter boxes that have ergo trees belonging to an array.
- `ergoTreeTemplateHash`(String): To filter boxes that have a certain ergo tree template hash.
- `minHeight`(Int): To get boxes after a certain height in the blockchain (inclusive).
- `maxHeight`(Int): To get boxes before a certain height in the blockchain (inclusive).
- `heightType`(HeightFilterType): It could be either `settlement` or `creation` which indicated the type of height you want to filter boxes by.
### Tokens (Query)
Get tokens that have been minted on the ergo blockchain. The arguments of this query are:
- `skip`(Int): How many items to skip; Default value is 0.
- `take`(Int): How many items to take; Default value is 50.
- `tokenId`(String): To filter a unique token by its id; It's deprecated, please use `tokenIds` instead.
- `tokenIds`([String!]): To filter a set of unique tokens by id.
- `boxId`(String): To filter tokens by their minting box id.
- `name`(String): To filter tokens by their names. You can use wildcards like "name*". Keep in mind that the number of wildcard chars can't exceed 2.
### Inputs (Query)
To get input boxes of transactions in the ergo blockchain. The arguments of this query are:
- `skip`(Int): How many items to skip; Default value is 0.
- `take`(Int): How many items to take; Default value is 50.
- `transactionId`(String): To get input boxes of a special transaction.
- `boxId`(String): To filter a unique box by id.
- `headerId`(String): To get input boxes of a special header.
### Transactions (Query)
To get the transactions of Ergo Blockchain. The arguments of this query are:
- `skip`(Int): How many items to skip; Default value is 0.
- `take`(Int): How many items to take; Default value is 50.
- `transactionId`(String): To filter a unique transaction by is id; It's deprecated, please use `transactionIds` instead.
- `transactionIds`([String!]): To filter a set of unique transactions by id.
- `headerId`(String): To filter transaction by the header id.
- `inclusionHeight`(int): To filter transactions by the block height in which they included in the blockchain.
- `address`(String): To filter transactions of an specific address; It's deprecated, please use `addresses` instead.
- `addresses`([String!]): To filter transactions that belong to a set of addresses.
- `minHeight`(Int): To filter transactions occurring after a certain height.
- `maxHeight`(Int): To filter transactions occurring before a certain height.
### DataInputs (Query)
To get information about boxes that have been used as data input in the blockchain. The arguments of this query are:
- `skip`(Int): How many items to skip; Default value is 0.
- `take`(Int): How many items to take; Default value is 50.
- `transactionId`(String): To filter dataInputs of an specific transaction, filtering by its id.
- `boxId`(String): To filter data inputs by box id.
- `headerId`(String): To filter dataInputs of a block which has a specific headerId.
### BlockHeaders (Query)
To get info about the block headers of the blockchain. The arguments of this query are:
- `skip`(Int): How many items to skip; Default value is 0.
- `take`(Int): How many items to take; Default value is 10.
- `headerId`(String): To filter headers by their id.
- `parentId`(String): To fetch a block header using its parent id.
- `height`(Int): To retrieve a block header at a certain height.
### Addresses (Query)
To get information about some addresses on the blockchain. The argument of this query are:
- `addresses`([String!]): The list of addresses to filter.
### Mempool (Query)
To get mempool boxes of the blockchain. This query does not have any arguments/filters.
### Block (Query)
To get info about the block headers of the blockchain. The arguments of this query are:
- `skip`(Int): How many items to skip; Default value is 0.
- `take`(Int): How many items to take; Default value is 10.
- `headerId`(String): To filter the block by header id.
- `height`(Int): To filter a block with certain height.
- `minHeight`(Int): To filter all blocks after a certain height.
- `maxHeight`(Int): To filter all block before a certain height.
### State (Query)
To get the state of the graphql instance. This status contains `difficulty`, `height`, and the `network`.
This query does not have any arguments/filters.
### Info (Query)
To check info of the running graphql instance. This contains `version` for now.
### CheckTransaction (Mutation)
To check whether a transaction is valid. It will return transaction id if it's valid, and empty string otherwise.
The input of ths mutation is signedTransaction of type `SignedTransaction` which is:
```
type SignedTransaction {
id: String!
inpts: [TransactionInput!]!
dataInputs: [TransactionDataInput!]!
outputs: [TransactionOutput!]!
size: Int
}
```
### SubmitTransaction (Mutation)
To submit a transaction into the ergo blockchain. This will send the tx to the instance's node; if the operation suceeds it'll return the id of transaction. Input is the same `SignedTransaction` as defined above.