Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Complete docs #84

Merged
merged 7 commits into from
Sep 20, 2024
Merged

Complete docs #84

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
3174f8e
add more docs
SepehrGanji Dec 28, 2023
9fa6c06
audit packages
SepehrGanji Dec 28, 2023
3fc5cb2
add boxes and tokens docs
SepehrGanji Jan 11, 2024
a8de673
add inputs doc
SepehrGanji Jan 17, 2024
0d5bb78
add Transactions, DataInputs and blockHeader docs
SepehrGanji Jan 18, 2024
ace1e26
Complete query docs
SepehrGanji Jan 21, 2024
969f330
complete mutation docs
SepehrGanji Jan 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 154 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# ergo-graphql

Ergo GraphQL server 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).
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
## Project Setup (Manual)

```
npm install
$ npm ci
```

### Environment file pattern
Expand All @@ -18,8 +18,8 @@ The `.env` file must be placed in the root directory following the pattern descr
DB_HOST = # database host address
DB_PORT = # database host port
DB_NAME = # database name
DB_USER_NAME = # database user name
DB_USER_PWD = # database user password
DB_USER_NAME = # database username
DB_USER_PWD = # database password
DB_SSL = # optional: true or false

ERGO_NODE_ADDRESS = # http ergo node address
Expand All @@ -35,24 +35,168 @@ MAX_QUERY_DEPTH = 5 # optional: maximum query depth
### Compile and run for development

```
npm run dev
$ npm run dev
```

### Compile and run for production

```
npm run build
npm run start
$ npm run build
$ npm run start
```

### Run unit tests

```
npm run test
$ npm run test
```

### Lint

```
npm run 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.

Loading
Loading