Simple lookup endpoints (#1)

- Endpoints for each of the DB tables - `/actions` - `/blocks` - `/dbops` - `/transactions` - Simple parameter matching (e.g. `account`, `date`, etc.) - Reworked `README` and Bun scripts
pinax-network · Aug 29, 2024 · e0e58f8 · e0e58f8
1 parent 4fa011d
commit e0e58f8
Show file tree

Hide file tree

Showing 17 changed files with 1,974 additions and 922 deletions.
diff --git a/.gitignore b/.gitignore
@@ -137,6 +137,6 @@ dist
 cursor.lock
 
 # CLI
-antelope-token-api
+antelope-transactions-api
 
 *.db
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,6 +1,6 @@
-# Contributing to Antelope Token API
+# Contributing to Antelope Transactions API
 
-Welcome to the Antelope Token API repository ! You'll find here guidelines on how the repository is set up and how to possibly contribute to it.
+Welcome to the Antelope Transactions API repository ! You'll find here guidelines on how the repository is set up and how to possibly contribute to it.
 
 <!-- TODO: Link to Pinax Discord -->
 
@@ -20,12 +20,12 @@ Welcome to the Antelope Token API repository ! You'll find here guidelines on ho
 > [!NOTE]
 > Make sure you have read the [documentation](README.md) first !
 
-Before you ask a question, it is best to search for existing [Issues](https://github.com/pinax-network/antelope-token-api/issues) that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to search the internet for answers first.
+Before you ask a question, it is best to search for existing [Issues](https://github.com/pinax-network/antelope-transactions-api/issues) that might help you. In case you have found a suitable issue and still need clarification, you can write your question in this issue. It is also advisable to search the internet for answers first.
 
 <!-- TODO: Issue VS Tech support in Discord ? -->
 If you then still feel the need to ask a question and need clarification, we recommend the following:
 
-- Open an [Issue](https://github.com/pinax-network/antelope-token-api/issues/new).
+- Open an [Issue](https://github.com/pinax-network/antelope-transactions-api/issues/new).
 - Provide as much context as you can about what you're running into.
 - Provide project and platform versions depending on what seems relevant.
 
@@ -42,9 +42,9 @@ If you then still feel the need to ask a question and need clarification, we rec
 
 A good bug report shouldn't leave others needing to chase you up for more information. Therefore, we ask you to investigate carefully, collect information and describe the issue in detail in your report. Please complete the following steps in advance to help fix any potential bug as fast as possible.
 
-- Make sure that you are using the [latest version](https://github.com/pinax-network/antelope-token-api/releases). If you're using the binary, you can check with `antelope-token-api --version`.
+- Make sure that you are using the [latest version](https://github.com/pinax-network/antelope-transactions-api/releases). If you're using the binary, you can check with `antelope-transactions-api --version`.
 - Determine if your bug is really a bug and not an error on your side e.g. using incompatible environment components/versions (make sure that you have read the [documentation](README.md). If you are looking for support, you might want to check [this section](#asking-questions)).
-- To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error in the [bug tracker](https://github.com/pinax-network/antelope-token-api/issues?q=label%3Abug).
+- To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error in the [bug tracker](https://github.com/pinax-network/antelope-transactions-api/issues?q=label%3Abug).
 - Also make sure to search the internet (including Stack Overflow) to see if users outside the GitHub community have discussed the issue.
 - Collect information about the bug:
   - Stack trace if possible
@@ -61,31 +61,31 @@ A good bug report shouldn't leave others needing to chase you up for more inform
 
 We use GitHub issues to track bugs and errors. If you run into an issue with the project:
 
-- Open an [Issue](https://github.com/pinax-network/antelope-token-api/issues/new?assignees=0237h&labels=bug&projects=&template=bug_report.md&title=).
+- Open an [Issue](https://github.com/pinax-network/antelope-transactions-api/issues/new?assignees=0237h&labels=bug&projects=&template=bug_report.md&title=).
 - Explain the behavior you would expect and the actual behavior.
 - Please provide as much context as possible and describe the *reproduction steps* that someone else can follow to recreate the issue on their own. This usually includes your code. For good bug reports you should isolate the problem and create a reduced test case.
 - Provide the information you collected in the previous section.
 
 ### Suggesting Enhancements
 
-This section guides you through submitting an enhancement suggestion for Antelope Token API, **including completely new features and minor improvements to existing functionality**. Following these guidelines will help maintainers and the community to understand your suggestion and find related suggestions.
+This section guides you through submitting an enhancement suggestion for Antelope Transactions API, **including completely new features and minor improvements to existing functionality**. Following these guidelines will help maintainers and the community to understand your suggestion and find related suggestions.
 
 #### Before Submitting an Enhancement
 
-- Make sure that you are using the [latest version](https://github.com/pinax-network/antelope-token-api/releases). If you're using the binary, you can check with `antelope-token-api --version`.
+- Make sure that you are using the [latest version](https://github.com/pinax-network/antelope-transactions-api/releases). If you're using the binary, you can check with `antelope-transactions-api --version`.
 - Read the [documentation](README.md) carefully and find out if the functionality is already covered, maybe by an individual configuration.
-- Perform a [search](https://github.com/pinax-network/antelope-token-api/issues) to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
+- Perform a [search](https://github.com/pinax-network/antelope-transactions-api/issues) to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
 - Find out whether your idea fits with the scope and aims of the project. Keep in mind that features should be useful to the majority of users and not just a small subset.
 
 #### How Do I Submit a Good Enhancement Suggestion?
 
-Enhancement suggestions are tracked as [GitHub issues](https://github.com/pinax-network/antelope-token-api/issues).
+Enhancement suggestions are tracked as [GitHub issues](https://github.com/pinax-network/antelope-transactions-api/issues).
 
-- Open an [Issue](https://github.com/pinax-network/antelope-token-api/issues/new?assignees=0237h&labels=feature&projects=&template=feature_request.md&title=).
+- Open an [Issue](https://github.com/pinax-network/antelope-transactions-api/issues/new?assignees=0237h&labels=feature&projects=&template=feature_request.md&title=).
 - Use a **clear and descriptive title** for the issue to identify the suggestion.
 - Provide a **step-by-step description of the suggested enhancement** in as many details as possible.
 - **Describe the current behavior** and **explain which behavior you expected to see instead** and why. At this point you can also tell which alternatives do not work for you.
-- **Explain why this enhancement would be useful** to most Antelope Token API users. You may also want to point out the other projects that solved it better and which could serve as inspiration.
+- **Explain why this enhancement would be useful** to most Antelope Transactions API users. You may also want to point out the other projects that solved it better and which could serve as inspiration.
 
 ### Submitting PRs
 

diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Antelope Transactions API
 
-[![.github/workflows/bun-test.yml](https://github.com/pinax-network/antelope-token-api/actions/workflows/bun-test.yml/badge.svg)](https://github.com/pinax-network/antelope-token-api/actions/workflows/bun-test.yml)
+[![.github/workflows/bun-test.yml](https://github.com/pinax-network/antelope-transactions-api/actions/workflows/bun-test.yml/badge.svg)](https://github.com/pinax-network/antelope-transactions-api/actions/workflows/bun-test.yml)
 
 > Transactions information from the Antelope blockchains, powered by [Substreams](https://substreams.streamingfast.io/)
 
@@ -14,15 +14,18 @@
 | Method | Path | Query parameters<br>(* = **Required**) | Description |
 | :---: | --- | --- | --- |
 | GET <br>`text/html` | `/` | - | [Swagger](https://swagger.io/) API playground |
-| GET <br>`application/json` | `/balance` | **`account*`**<br>`contract`<br>`symcode`<br>`limit`<br>`page` | Balances of an account |
-| GET <br>`application/json` | `/balance/historical` | **`account*`**<br>`block_num`<br>`contract`<br>`symcode`<br>`limit`<br>`page` | Historical token balances |
-| GET <br>`application/json` | `/head` | `limit`<br>`page` | Head block information |
-| GET <br>`application/json` | `/holders` | **`contract*`**<br>**`symcode*`**<br>`limit`<br>`page` | List of holders of a token |
-| GET <br>`application/json` | `/supply` | `block_num`<br>`issuer`<br>**`contract*`**<br>**`symcode*`**<br>`limit`<br>`page` | Total supply for a token |
-| GET <br>`application/json` | `/tokens` | `limit`<br>`page` | List of available tokens |
-| GET <br>`application/json` | `/transfers` | `block_range`<br>**`contract*`**<br>**`symcode*`**<br>`limit`<br>`page` | All transfers related to a token |
-| GET <br>`application/json` | `/transfers/account` | **`account*`**<br>`block_range`<br>`from`<br>`to`<br>`contract`<br>`symcode`<br>`limit`<br>`page` | All transfers related to an account |
-| GET <br>`application/json` | `/transfers/id` | **`trx_id*`**<br>`limit`<br>`page` | Specific transfer related to a token |
+| GET<br>`application/json` | `/actions/name/{name}` | **`name*`** | Actions by name |
+| GET<br>`application/json` | `/actions/account/{account}` | **`account*`** | Actions by account |
+| GET<br>`application/json` | `/actions/date/{date}` | **`date*`** | Actions by date |
+| GET<br>`application/json` | `/blocks/date/{date}` | **`date*`** | Blocks by date |
+| GET<br>`application/json` | `/blocks/hash/{hash}` | **`hash*`** | Blocks by hash |
+| GET<br>`application/json` | `/blocks/number/{number}` | **`number*`** | Blocks by number |
+| GET<br>`application/json` | `/dbops/contract/{contract}` | **`contract*`** | DBOps by contract |
+| GET<br>`application/json` | `/dbops/scope/{scope}` | **`scope*`** | DBOps by scope |
+| GET<br>`application/json` | `/dbops/pk/{pk}` | **`pk*`** | DBOps by primary key |
+| GET<br>`application/json` | `/dbops/date/{date}` | **`date*`** | DBOps by date |
+| GET<br>`application/json` | `/transactions/hash/{hash}` | **`hash*`** | Transactions by hash |
+| GET<br>`application/json` | `/transactions/date/{date}` | **`date*`** | Transactions by date |
 
 ### Docs
 
@@ -53,18 +56,16 @@ Use the `Variables` tab at the bottom to add your API key:
 
 ### Additional notes
 
-- For the `block_range` parameter in `transfers`, you can pass a single integer value (low bound) or an array of two values (inclusive range).
-- Use the `from` and `to` field for transfers of an account to further filter the results (i.e. incoming or outgoing transactions from/to another account).
 - Don't forget to request the `meta` fields in the response to get access to pagination and statistics !
 
 ## Requirements
 
-- [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](static/@typespec/protobuf) to build your substream. This Token API makes use of the [`substreams-antelope-tokens`](https://github.com/pinax-network/substreams-antelope-tokens/) substream.
+- [ClickHouse](clickhouse.com/), databases should follow a `{chain}_transactions_{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](static/@typespec/protobuf) to build your substream. This Transactions API makes use of the [`substreams-raw-blocks`](https://github.com/pinax-network/substreams-raw-blocks/) Antelope substream.
 
 ### API stack architecture
 
-![Token API architecture diagram](token_api_architecture_diagram.png)
+![API architecture diagram](api_architecture_diagram.png)
 
 ### Setting up the database backend (ClickHouse)
 
@@ -78,10 +79,10 @@ Example on how to set up the ClickHouse backend for sinking [EOS](https://pinax.
 clickhouse server
 ```
 
-2. Create the token database
+2. Create the transactions database
 
 ```console
-echo "CREATE DATABASE eos_tokens_v1" | clickhouse client -h <host> --port 9000 -d <database> -u <user> --password <password>
+echo "CREATE DATABASE eos_transactions_v1" | clickhouse client -h <host> --port 9000 -d <database> -u <user> --password <password>
 ```
 
 3. Run the [`create_schema.sh`](./create_schema.sh) script
@@ -99,8 +100,8 @@ cat /tmp/schema.sql | clickhouse client -h <host> --port 9000 -d <database> -u <
 5. Run the [sink](https://github.com/pinax-network/substreams-sink-sql)
 
 ```console
-substreams-sink-sql run clickhouse://<username>:<password>@<host>:9000/eos_tokens_v1 \
-https://github.com/pinax-network/substreams-antelope-tokens/releases/download/v0.4.0/antelope-tokens-v0.4.0.spkg `#Substreams package` \
+substreams-sink-sql run clickhouse://<username>:<password>@<host>:9000/eos_transactions_v1 \
+https://github.com/pinax-network/substreams-raw-blocks/releases/download/antelope-v0.1.0/raw-blocks-antelope-v0.1.0.spkg `#Substreams package` \
 -e eos.substreams.pinax.network:443 `#Substreams endpoint` \
 1: `#Block range <start>:<end>` \
 --final-blocks-only --undo-buffer-size 1 --on-module-hash-mistmatch=warn --batch-block-flush-interval 100 --development-mode `#Additional flags`
@@ -110,17 +111,17 @@ https://github.com/pinax-network/substreams-antelope-tokens/releases/download/v0
 
 ```console
 # Will be available on locahost:8080 by default
-antelope-token-api --host <host> --database eos_tokens_v1 --username <username> --password <password> --verbose
+antelope-transactions-api --host <host> --database eos_transactions_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
+2. Create the transactions database
 
 ```console
-echo "CREATE DATABASE eos_tokens_v1 ON CLUSTER <cluster>" | clickhouse client -h <host> --port 9000 -d <database> -u <user> --password <password>
+echo "CREATE DATABASE eos_transactions_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
@@ -129,19 +130,20 @@ echo "CREATE DATABASE eos_tokens_v1 ON CLUSTER <cluster>" | clickhouse client -h
 ./create_schema.sh -o /tmp/schema.sql -c <cluster>
 ```
 
+4. 5. 6. Follow the same steps as without a cluster.
 
-## [`Bun` Binary Releases](https://github.com/pinax-network/antelope-token-api/releases)
+## [`Bun` Binary Releases](https://github.com/pinax-network/antelope-transactions-api/releases)
 
 > [!WARNING]
 > Linux x86 only
 
 ```console
-$ wget https://github.com/pinax-network/antelope-token-api/releases/download/v4.0.0/antelope-token-api
-$ chmod +x ./antelope-token-api
-$ ./antelope-token-api --help                                                                                                       
-Usage: antelope-token-api [options]
+$ wget https://github.com/pinax-network/antelope-transactions-api/releases/download/v0.1.0/antelope-transactions-api
+$ chmod +x ./antelope-transactions-api
+$ ./antelope-transactions-api --help                                                                          
+Usage: antelope-transactions-api [options]
 
-Token balances, supply and transfers from the Antelope blockchains
+Transactions information from the Antelope blockchains
 
 Options:
   -V, --version            output the version number
@@ -180,22 +182,22 @@ VERBOSE=true
 
 **For latest tagged release**
 ```bash
-docker pull ghcr.io/pinax-network/antelope-token-api:latest
+docker pull ghcr.io/pinax-network/antelope-transactions-api:latest
 ```
 
 **For head of `main` branch**
 ```bash
-docker pull ghcr.io/pinax-network/antelope-token-api:develop
+docker pull ghcr.io/pinax-network/antelope-transactions-api:develop
 ```
 
 - Build from source
 ```bash
-docker build -t antelope-token-api .
+docker build -t antelope-transactions-api .
 ```
 
 - Run with `.env` file
 ```bash
-docker run -it --rm --env-file .env ghcr.io/pinax-network/antelope-token-api
+docker run -it --rm --env-file .env ghcr.io/pinax-network/antelope-transactions-api
 ```
 
 ## Contributing

diff --git a/token_api_architecture_diagram.png → api_architecture_diagram.png b/token_api_architecture_diagram.png → api_architecture_diagram.png
diff --git a/create_schema.sh b/create_schema.sh
@@ -56,10 +56,10 @@ CREATE TABLE IF NOT EXISTS cursors $ON_CLUSTER_DIRECTIVE
 CREATE TABLE IF NOT EXISTS blocks $ON_CLUSTER_DIRECTIVE
 (
     -- clock --
-    block_time                                    DateTime64(3, 'UTC'),
-    block_number                                  UInt64,
-    block_date                                    Date,
-    block_hash                                    String COMMENT 'Hash',
+    time                                    DateTime64(3, 'UTC'),
+    number                                  UInt64,
+    date                                    Date,
+    hash                                    String COMMENT 'Hash',
 
     -- header --
     parent_hash                             String COMMENT 'Hash',
@@ -88,8 +88,8 @@ CREATE TABLE IF NOT EXISTS blocks $ON_CLUSTER_DIRECTIVE
     total_db_ops                            UInt64,
 )
     ENGINE = $ENGINE_DEFAULT
-        PRIMARY KEY (block_date, block_number)
-        ORDER BY (block_date, block_number, block_hash)
+        PRIMARY KEY (date, number)
+        ORDER BY (date, number, hash)
         COMMENT 'Antelope block header';
 
 CREATE TABLE IF NOT EXISTS transactions $ON_CLUSTER_DIRECTIVE

diff --git a/index.ts b/index.ts
@@ -13,7 +13,7 @@ import { APIErrorResponse } from "./src/utils.js";
 import { usageOperationsToEndpointsMap, type EndpointReturnTypes, type UsageEndpoints, type ValidPathParams, type ValidUserParams } from "./src/types/api.js";
 import { paths } from './src/types/zod.gen.js';
 
-async function AntelopeTokenAPI() {
+async function AntelopeTransactionsAPI() {
     const app = new Hono();
 
     // Tracking all incoming requests
@@ -95,7 +95,7 @@ async function AntelopeTokenAPI() {
                     ctx,
                     endpoint,
                     {
-                        ...path_params.data as SafeParseSuccess<ValidPathParams<typeof endpoint>>,
+                        ...path_params.data,
                         ...query_params.data
                     } as ValidUserParams<typeof endpoint>
                 );
@@ -172,4 +172,4 @@ async function AntelopeTokenAPI() {
     return app;
 }
 
-export default await AntelopeTokenAPI();
+export default await AntelopeTransactionsAPI();