You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+107-3Lines changed: 107 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,51 @@
1
1
# Hypercerts API
2
2
3
-
The hypercerts API is the touchpoint for developers to interact with the hypercerts ecosystem. It provides endpoints for data upload and fetch, a GraphQL API for querying (on-chain) state and a health check endpoint.
3
+
The hypercerts API is the touchpoint for developers to interact with the hypercerts ecosystem. It provides endpoints for data upload and fetching, a GraphQL API for querying (on-chain) state and a health check endpoint.
4
4
5
-
## Endpoints
5
+
## Getting started
6
+
7
+
### Environment variables
8
+
9
+
#### W3UP
10
+
11
+
In `env.template` you'll find KEY and PROOF which are [w3up](https://web3.storage/docs/w3up-client/) key and proofs which you need to set up yourself for local otherwise you'll be superadmin 😉
12
+
13
+
#### Supabase JS
14
+
15
+
SupabaseJS is used to connect to both the the caching and data service. The local variables are deterministic and provided in the template.
16
+
17
+
#### Kysely
18
+
19
+
Kysely is implemented in favor of SupabaseJS as it allows for more flexibility and complexity in queries. To connect to the database you need to set the `CACHING_DATABASE_URL` and `DATA_DATABASE_URL` in the `.env` file. By default, the local variables are set to the local Supabase instance.
20
+
21
+
#### Sentry
22
+
23
+
Sentry is used for monitoring and error reporting. You can read more about it [here](https://docs.sentry.io/platforms/javascript/guides/node/configuration/env-vars/). When Sentry is set to `local` it will be disabled by default.
24
+
25
+
#### RPCs
26
+
27
+
The API implements a fallback to the first available RPC. You can set the RPCs in the `.env` file.
28
+
29
+
### Supabase
30
+
31
+
* Install Docker
32
+
*`git submodule init`
33
+
*`git submodule update --remote`
34
+
*`pnpm supabase:start:all`
35
+
36
+
This will spin up 2 Supabase instances in Docker, one for the indexer service (caching) and one for the data service (static data) which are both exposed by the API.
37
+
38
+
From both instances, you can get their respective keys and add them to the env vars. When in doubt you can run `supabase status` to fetch the keys again. By default this is not needed for local development.
39
+
40
+
### Run the API locally
41
+
42
+
`pnpm dev`
43
+
44
+
This will run a live production instance by running `swc` to compile the code and `nodemon` to restart the server on changes.
45
+
46
+
You can then find the API at `localhost:4000/spec` (Swagger instance) and the GraphQL at `localhost:4000/v1/graphql`
-`build`: Denerates the OpenAPI specification and routes using `tsoa`, and then compiles the TypeScript code into JavaScript using `swc`. The compiled code is output to the `dist` directory.
17
60
-`start`: Starts the application in production mode.
18
61
-`lint`: Runs `eslint` on the codebase to check for linting errors.
19
-
-`test`: Runs tests using `vitest`.
62
+
-`test`: Runs tests using `vitest`
63
+
64
+
## Data
65
+
66
+
The API service exposes data from two sources:
67
+
68
+
- The static data service which contains off-chain data like user data, hypercert collections, signed order messages, etc.
69
+
- The indexer service which contains on-chain data about hypercerts and the linked data on IPFS (hypercerts, ownerships, metadata, attestations, etc.)
70
+
71
+
### Static data service
72
+
73
+
The static data service is a Supabase database which is exposed by the API. This means that you can create, update and delete data through the API. For read functionality we recommend using the GraphQL API and playground to carefully compose the data model needed for your use case.
74
+
75
+
### Indexer service
76
+
77
+
The indexer service monitors our supported chains for relevant events and handles those events accordingly. All data exposed by the indexer service is available in different sources as well, like IPFS for metadata and EAS for attestations.
78
+
79
+
## Validations
80
+
81
+
The API also provides an upload and validation endpoint for hypercert and allow list data. In the [live docs](https://api.hypercerts.org/spec) you can find the endpoint and docs. Generally, by using `validate` you can post the data for validation without it being uploaded to IPFS.
82
+
83
+
## Architecture
84
+
85
+
```mermaid
86
+
graph TB
87
+
Client[Client Applications]
88
+
API[Hypercerts API :4000]
89
+
90
+
subgraph "API Endpoints"
91
+
Swagger["/spec\nSwagger Documentation"]
92
+
GraphQL["/v1/graphql\nGraphQL Endpoint"]
93
+
Upload["Upload & Validation\nEndpoints"]
94
+
end
95
+
96
+
subgraph "Data Services"
97
+
Static[("Static Data Service\n(Supabase DB)\n- User Data\n- Collections\n- Signed Orders")]
0 commit comments