Update README.md

pinax-network · Aug 13, 2024 · 336493b · 336493b
1 parent e5625a1
commit 336493b
Showing 1 changed file with 102 additions and 40 deletions.
diff --git a/README.md b/README.md
@@ -2,70 +2,121 @@
 
 [![.github/workflows/bun-test.yml](https://github.com/pinax-network/erc20-token-api/actions/workflows/bun-test.yml/badge.svg)](https://github.com/pinax-network/erc20-token-api/actions/workflows/bun-test.yml)
 
-> Tokens information from the erc20 blockchains, powered by [Substreams](https://substreams.streamingfast.io/)
-
+> Tokens information from all EVM blockchains, powered by [Substreams](https://substreams.streamingfast.io/)
 ## REST API
 
 ### Usage
 
-|           Method           | Path                  | Description                                              |
-| :------------------------: | --------------------- | -------------------------------------------------------- |
-|    GET <br>`text/html`     | `/`                   | [Swagger](https://swagger.io/) API playground            |
-| GET <br>`application/json` | `/balance`            | Balances of an account.                                  |
-| GET <br>`application/json` | `/head`               | Information about the current head block in the database |
-| GET <br>`application/json` | `/holders`            | List of holders of a token                               |
-| GET <br>`application/json` | `/supply`             | Total supply for a token                                 |
-| GET <br>`application/json` | `/transfers`          | All transfers related to a token                         |
-| GET <br>`application/json` | `/transfers/{trx_id}` | Specific transfer related to a token                     |
-| GET <br>`application/json` | `/contract/`          | Get Token contract information                           |
+| Method | Path | Query parameters<br>(* = **Required**) | Description |
+| :---: | --- | --- | --- |
+| GET <br>`text/html` | `/` | - | [Swagger](https://swagger.io/) API playground |
+| GET <br>`application/json` | `/chains` | `limit`<br>`page` | Information about the chains and latest head block in the database |
+| GET <br>`application/json` | `/{chain}/balance` | `block_num`<br>`contract`<br>`account*`<br>`limit`<br>`page` | Balances of an account. |
+| GET <br>`application/json` | `/{chain}/holders` | **`contract*`**<br>`limit`<br>`page` | List of holders of a token |
+| GET <br>`application/json` | `/{chain}/supply` | `block_num`<br>`contract*`<br>`limit`<br>`page` | Total supply for a token |
+| GET <br>`application/json` | `/{chain}/tokens` |`contract`<br>`symbol`<br>`name`<br>`limit`<br>`page` | Get info about available tokens |
+| GET <br>`application/json` | `/{chain}/transfers` | `block_range`<br>`from`<br>`to`<br>`contract`<br>`limit`<br>`page` | All transfers related to a token |
+| GET <br>`application/json` | `/{chain}/transfers/{trx_id}` | `limit`<br>`page` | Specific transfer related to a token |
 
 ### Docs
 
-|           Method           | Path       | Description                                        |
-| :------------------------: | ---------- | -------------------------------------------------- |
+| Method | Path | Description |
+| :---: | --- | --- |
 | GET <br>`application/json` | `/openapi` | [OpenAPI](https://www.openapis.org/) specification |
-| GET <br>`application/json` | `/version` | API version and Git short commit hash              |
+| GET <br>`application/json` | `/version` | API version and Git short commit hash |
 
 ### Monitoring
 
-|        Method        | Path       | Description                                  |
-| :------------------: | ---------- | -------------------------------------------- |
-| GET <br>`text/plain` | `/health`  | Checks database connection                   |
+| Method | Path | Description |
+| :---: | --- | --- |
+| GET <br>`text/plain` | `/health` | Checks database connection |
 | GET <br>`text/plain` | `/metrics` | [Prometheus](https://prometheus.io/) metrics |
 
 ## Requirements
 
--   [ClickHouse](clickhouse.com/)
--   (Optional) A [Substream sink](https://substreams.streamingfast.io/reference-and-specs/glossary#sink) for loading data into ClickHouse. We recommend [Substreams Sink ClickHouse](https://github.com/pinax-network/substreams-sink-clickhouse/) or [Substreams Sink SQL](https://github.com/streamingfast/substreams-sink-sql). You should use the generated [`protobuf` files](tsp-output/@typespec/protobuf) to build your substream.
+- [ClickHouse](clickhouse.com/), databases should follow a `{chain}_tokens_{version}` naming scheme. Database tables can be setup using the [`schema.sql`](./schema.sql) definitions created by the [`create_schema.sh`](./create_schema.sh) script.
+- A [Substream sink](https://substreams.streamingfast.io/reference-and-specs/glossary#sink) for loading data into ClickHouse. We recommend [Substreams Sink ClickHouse](https://github.com/pinax-network/substreams-sink-clickhouse/) or [Substreams Sink SQL](https://github.com/pinax-network/substreams-sink-sql). You should use the generated [`protobuf` files](tsp-output/@typespec/protobuf) to build your substream. This Token API makes use of the [`erc20-substreams`](https://github.com/pinax-network/erc20-substreams) substream.
 
-## Quick start
+### API stack architecture
 
-Install [Bun](https://bun.sh/)
+![Token API architecture diagram](token_api_architecture_diagram.png)
+
+### Setting up the database backend (ClickHouse)
+
+#### Without a cluster
+
+Example on how to set up the ClickHouse backend for sinking [EOS](https://pinax.network/en/chain/eos) data.
+
+1. Start the ClickHouse server
 
 ```console
-$ bun install
-$ bun dev
+clickhouse server
 ```
 
-**Tests**
+2. Create the token database
 
 ```console
-$ bun lint
-$ bun test
+echo "CREATE DATABASE eth_tokens_v1" | clickhouse client -h <host> --port 9000 -d <database> -u <user> --password <password>
+```
+
+3. Run the [`create_schema.sh`](./create_schema.sh) script
+
+```console
+./create_schema.sh -o /tmp/schema.sql
+```
+
+4. Execute the schema
+
+```console
+cat /tmp/schema.sql | clickhouse client -h <host> --port 9000 -d <database> -u <user> --password <password>
+```
+
+5. Run the [sink](https://github.com/pinax-network/substreams-sink-sql)
+
+```console
+substreams-sink-sql run clickhouse://<username>:<password>@<host>:9000/eth_tokens_v1 \
+https://github.com/pinax-network/erc20-substreams/releases/download/v0.0.2/erc20-substreams-v0.0.2.spkg `#Substreams package` \
+-e eth.substreams.pinax.network:443 `#Substreams endpoint` \
+1: `#Block range <start>:<end>` \
+--undo-buffer-size 1 --on-module-hash-mistmatch=warn --batch-block-flush-interval 100 --development-mode `#Additional flags`
+```
+
+6. Start the API
+
+```console
+# Will be available on locahost:8080 by default, Make sure --database exclude chains
+erc20-token-api --host <host> --database tokens_v1 --username <username> --password <password> --verbose
+```
+
+#### With a cluster
+
+If you run ClickHouse in a [cluster](https://clickhouse.com/docs/en/architecture/cluster-deployment), change step 2 & 3:
+
+2. Create the token database
+
+```console
+echo "CREATE DATABASE eth_tokens_v1 ON CLUSTER <cluster>" | clickhouse client -h <host> --port 9000 -d <database> -u <user> --password <password>
+```
+
+3. Run the [`create_schema.sh`](./create_schema.sh) script
+
+```console
+./create_schema.sh -o /tmp/schema.sql -c <cluster>
 ```
 
-## [`Bun` Binary Releases](https://github.com/pinax-network/erc20-token-api/releases)
+
+## [`Bun` Binary Releases](https://github.com/pinax-network/antelope-token-api/releases)
 
 > [!WARNING]
 > Linux x86 only
 
 ```console
-$ wget https://github.com/pinax-network/erc20-token-api/releases/download/v0.0.1/erc20-token-api
+$ wget https://github.com/pinax-network/erc20-token-api/releases/download/v1.0.1/erc20-token-api
 $ chmod +x ./erc20-token-api
-$ ./erc20-token-api --help
+$ ./erc20-token-api --help                                                                                                       
 Usage: erc20-token-api [options]
 
-Token balances, supply and transfers from the erc20 blockchains
+Token balances, supply and transfers from the Antelope blockchains
 
 Options:
   -V, --version            output the version number
@@ -101,32 +152,43 @@ VERBOSE=true
 
 ## Docker environment
 
--   Pull from GitHub Container registry
-
-**For latest release**
+- Pull from GitHub Container registry
 
+**For latest tagged release**
 ```bash
 docker pull ghcr.io/pinax-network/erc20-token-api:latest
 ```
 
-**For head of `develop` branch**
-
+**For head of `main` branch**
 ```bash
 docker pull ghcr.io/pinax-network/erc20-token-api:develop
 ```
 
--   Build from source
-
+- Build from source
 ```bash
 docker build -t erc20-token-api .
 ```
 
--   Run with `.env` file
-
+- Run with `.env` file
 ```bash
 docker run -it --rm --env-file .env ghcr.io/pinax-network/erc20-token-api
 ```
 
 ## Contributing
 
 See [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+### Quick start
+
+Install [Bun](https://bun.sh/)
+
+```console
+$ bun install
+$ bun dev
+```
+
+**Tests**
+```console
+$ bun lint
+$ bun test
+```