Skip to content

Commit 4132d03

Browse files
adam-majfurqanrydhan
adam-maj
and
furqanrydhan
authored
Update readme, first-time ux, & add local wallet (#104)
* cleaning up docs * more tweaks to intro * more info about server * readme updates * switch to pg connection string * postgres connection string * fix openapi / swagger issue, default password for postgres, remove swagger.yml * change up local docker setup * swapping ts-node for tsx * generate local wallet if none passed in * TODO * Fix local wallet generation * Update environment variables * Update README.md * Fix postgres configuration * remove dependency on wallet_keys env * updating the readme * Fix test cases * Update database name * Default database name to postgres --------- Co-authored-by: furqanrydhan <furqan.rydhan@gmail.com>
1 parent e41942e commit 4132d03

File tree

21 files changed

+409
-384
lines changed

21 files changed

+409
-384
lines changed

‎.env.example

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -23,16 +23,11 @@ GOOGLE_KMS_CRYPTO_KEY_ID=<kms_key_id> # If created on Google Console
2323
# -----------------------
2424
# Obtain an Secret Key from thirdweb.com/dashboard
2525
# this enables you to use the default RPCs and extra features
26-
THIRDWEB_SDK_SECRET_KEY=<your_thirdweb_sdk_secret_key>
26+
THIRDWEB_API_SECRET_KEY=<your_thirdweb_api_secret_key>
2727

2828
# DATABASE OPTIONS [Required]
2929
# ----------------
30-
POSTGRES_HOST=localhost
31-
POSTGRES_DATABASE_NAME=postgres
32-
POSTGRES_USER=postgres
33-
POSTGRES_PASSWORD=postgres
34-
POSTGRES_PORT=5432
35-
POSTGRES_USE_SSL=false
30+
POSTGRES_CONNECTION_URL="postgresql://postgres:postgres@localhost:5432/postgres?sslmode=disable"
3631

3732
# SERVING OPTIONS [Optional]
3833
# ---------------

‎Makefile

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ export POSTGRES_PASSWORD=postgres
1010
export POSTGRES_PORT=5432
1111
export POSTGRES_USE_SSL=false
1212
export WALLET_PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
13-
export THIRDWEB_SDK_SECRET_KEY=klRsqmatrdlEpik_pHKgYy_q2YzGe3bTewO1VC26eY_H184Kc7xOVqKVj0mHwOOW2AOx2N-a3GqLCQ7Z9s9-sw
13+
export THIRDWEB_API_SECRET_KEY=klRsqmatrdlEpik_pHKgYy_q2YzGe3bTewO1VC26eY_H184Kc7xOVqKVj0mHwOOW2AOx2N-a3GqLCQ7Z9s9-sw
1414

1515
test-evm: FORCE
1616
docker compose -f docker-compose-test.yml up -d

‎README.md

Lines changed: 69 additions & 162 deletions
Original file line numberDiff line numberDiff line change
@@ -18,200 +18,107 @@
1818

1919
<p align="center"><strong>Best in class web3 SDKs for Browser, Node and Mobile apps</strong></p>
2020

21-
## Requirements
22-
23-
1. Docker
24-
2. Nodesjs (>= v18)
25-
3. PostgreSQL DB
26-
4. ENV Variables (Check `.env.example`)
27-
5. PG-Admin (Optional. PostgreSQL DB GUI)
28-
29-
Check the [How to install required packages](./.github/installations.md) guide for more details.
30-
31-
## API Documentation
32-
33-
View all end-points details (Open API Specification) : https://web3-api-akbv.chainsaw-dev.zeet.app
34-
35-
### Websocket Listener
36-
37-
For updates on your requests, you can either poll using the `get` (`/tranasction/status/<tx_queue_id>`) method or use websockets. [How to use websockets](./.github/websocket_usage.md)
38-
39-
## Environment Variables
40-
41-
| Variable Name | Description | Default Value | Required |
42-
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------- | -------- |
43-
| `HOST` | Host name of the API Server | `localhost` | ❌ |
44-
| `PORT` | Port number of the API Server | `3005` | ❌ |
45-
| `THIRDWEB_API_KEY` | API Key to access ThirdWeb API | | ✅ |
46-
| `POSTGRES_HOST` | PostgreSQL Host Name | | ✅ |
47-
| `POSTGRES_DATABASE_NAME` | PostgreSQL Database Name | | ✅ |
48-
| `POSTGRES_USER` | PostgreSQL Username | | ✅ |
49-
| `POSTGRES_PASSWORD` | PostgreSQL Password | | ✅ |
50-
| `POSTGRES_PORT` | PostgreSQL Port | | ✅ |
51-
| `POSTGRES_USE_SSL` | Flag to indicate whether to use SSL | | ✅ |
52-
| `TRANSACTIONS_TO_BATCH` | Number of transactions to batch process at a time. | `10` | ❌ |
53-
| `CHAIN_OVERRIDES` | Pass your own RPC urls to override the default ones. This can be file or an URL. See example override-rpc-urls.json | | ❌ |
54-
| `OPENAPI_BASE_ORIGIN` | Base URL for Open API Specification. Should be the Base URL of your App. | `http://localhost:3005` | ❌ |
55-
| `THIRDWEB_SDK_SECRET_KEY` | Create an API KEY on Thirdweb Dashboard and copy the SecretKey. | | ✅ |
56-
| `MINED_TX_CRON_ENABLED` | Flag to indicate whether to run the cron job to check mined transactions. | `true` | ❌ |
57-
| `MINED_TX_CRON_SCHEDULE` | Cron Schedule for the cron job to check mined transactions. | `*/30 * * * *` | ❌ |
58-
| `MIN_TX_TO_CHECK_FOR_MINED_STATUS` | Number of transactions to check for mined status at a time. | `50` | ❌ |
59-
60-
## Setup Instructions
61-
62-
1. Create a `.env` file based off `.env.example` with all the variables filled in.
63-
2. Update the `THIRDWEB_SDK_SECRET_KEY` value on the `.env` file
64-
65-
### Authentication
66-
67-
| Required |
68-
| -------- |
69-
70-
All Requests need to have `Authorization` header with the value of `Bearer <YOUR_THIRDWEB_SDK_SECRET_KEY>` from the `.env` file.
71-
72-
### Wallet Setup
73-
74-
| Required |
75-
| -------- |
76-
77-
There are multiple ways to setup a wallet for Web3-API using the below methods:
78-
79-
#### Wallet Private Key
80-
81-
1.Update the `WALLET_PRIVATE_KEY` value on the `.env` file
21+
## Web3API
8222

83-
#### AWS KMS Wallet
23+
Production-grade HTTP server that provides scalable web3 functionality:
8424

85-
Read More on [AWS KMS How To](./.github/aws_kms_how_to.md)
25+
- http interface with server and client authentication
26+
- create & interface with backend web3 wallets (local, aws kms, google kms, smart wallets, etc)
27+
- automatic wallet nonce management
28+
- built in high performance transaction queueing
29+
- intelligent transaction retry and gas management
30+
- read, write and deploy any smart contract on any evm blockchain
31+
- create gasless relayers
32+
- fine grained controls over user access
33+
- run in your own cloud or managed service (coming soon)
34+
- full server-side sdks for many languages & client-side sdks for many frameworks (coming soon)
8635

87-
#### Google KMS Wallet
36+
The server is meant to facilitate blockchain transactions within your existing architecture. It provides a high performance, production grade method to interact with smart contracts on any evm blockchain. The project is still early so if you're looking for specific features, have bugs, or want to give feedback, reach out to us!
8837

89-
Read More on [Google KMS How To](./.github/google_kms_how_to.md)
90-
91-
### Advance Setup : PostgreSQL DB
38+
## Requirements
9239

93-
<details>
40+
1. Docker
41+
2. PostgreSQL DB
9442

95-
<summary>Click to expand</summary>
43+
## Getting Started
9644

97-
You will need a PostgreSQL DB running instance to run the API Server & Worker. You can either run PostgreSQL DB on cloud, on a local instance or on docker. Check [installation guide](./.github/installations.md) for more details.
45+
### Set up required Environment Variables
9846

99-
Once you have PostgreSQL DB running on cloud or a local instance, update the following PostgreSQL DB ENV Variables Value on `.env` file:
47+
Set these variables in the .env file (copy .env.example to get started)
10048

101-
- `POSTGRES_HOST` : PostgreSQL Host Name
102-
- `POSTGRES_DATABASE_NAME` : PostgreSQL Database Name
103-
- `POSTGRES_USER` : PostgreSQL Username
104-
- `POSTGRES_PASSWORD` : PostgreSQL Password
105-
- `POSTGRES_PORT` : PostgreSQL Port (Defaults to 5432)
106-
- `POSTGRES_USE_SSL` : Flag to indicate whether to use SSL
49+
| Variable Name | Description |
50+
| ------------------------- | ------------------------------------------------------------------------------------------------------------- |
51+
| `THIRDWEB_API_SECRET_KEY` | Create an API KEY on thirdweb Dashboard and copy the SecretKey. |
52+
| `POSTGRES_CONNECTION_URL` | Postgres connection string, format: postgresql://[user[:password]@][host][:port][/dbname][?param1=value1&...] |
10753

108-
</details>
54+
### Run the server
10955

110-
## Running in Production Mode
56+
Docker
11157

112-
### Run Docker Image
58+
```
59+
docker run -e .env -p 3005:3005 thirdweb/web3-api
60+
```
11361

114-
| Required: Docker, Postgres |
115-
| -------------------------- |
62+
### Using the server
11663

117-
1. Check [Setup Instruction section](#setup-instructions) to update the `.env` file
118-
2. Check [Advance Setup : PostgreSQL DB](#advance-setup--postgresql-db) section to update the `.env` file
119-
3. Run the below command
120-
<br />
121-
```
122-
docker run --env-file ./.env -p 3005:3005 thirdweb/web3-api:latest
123-
```
64+
- In development mode, go to the server url to see an admin interface
65+
- Every request to the server requires an authentication token, for admin actions use the thirdweb SecretKey. Use the `Authorization` Header to set the value shown below:
66+
- `Authorization: Bearer: <thirdweb SecretKey>`
67+
- Contract API
12468

125-
<details>
126-
<summary>Run on a Server (EC2 Instance/Google Compute/VM) </summary>
69+
- Read from any contract
70+
- GET /contract/[network]/[contract_address]/[func or variable name]
71+
- Write to any contract function
72+
- POST /contract/[network]/[contract_address]/[function name]
73+
- JSON body with params
74+
- Deploy published contracts
75+
- POST /deploy/[network]/[publisher_address]/[published_name]
12776

128-
| Required: A PostgreSQL DB running instance. |
129-
| ------------------------------------------- |
77+
- Wallet API (in development)
13078

131-
1. Clone the project on the remote server
132-
2. Check [Setup Instruction section](#setup-instructions) to update the `.env` file
133-
3. Check [Advance Setup : PostgreSQL DB](#advance-setup--postgresql-db) section to update the `.env` file
134-
4. Update the `HOST` value on the `.env` file to `localhost`. Example: `HOST=localhost`
135-
5. Run: `yarn install`
136-
6. Run: `yarn build && yarn copy-files`
137-
7. Run: `yarn start`
79+
- Create Wallets
80+
- POST /wallet
81+
- Get Wallet Info
82+
- Balances - GET /wallet/[wallet_address]
13883

139-
</details>
140-
<br/>
84+
- Auth API (In development)
85+
- Relayer API (In development)
14186

14287
## Local Development
14388

144-
| Required: Docker |
145-
| ---------------- |
146-
147-
Note: This is the recommended way to run the API locally. It will spin up infra services, i.e., PostgreSQL DB, PG-Admin on Docker and run the API Server & Worker on local machine.
148-
149-
1. Clone the Repo
150-
2. Check [Setup Instruction section](#setup-instructions) to update the `.env` file
151-
3. Run: `yarn install`
152-
4. Run: `yarn dev`
153-
154-
The API defaults to `http://localhost:3005`
155-
156-
We use `docker-compose-infra.yml` to spin up the supporting infra services, a postgres database and the pg-admin GUI.
157-
158-
### Other ways to run locally
159-
160-
<details>
161-
162-
<summary>Click to expand</summary>
163-
164-
<br >
89+
### Requirements
16590

166-
---
167-
168-
### 1. Use only NodeJS/Yarn
169-
170-
---
171-
172-
| REQUIRED: PostgreSQL DB running instance |
173-
| ---------------------------------------- |
174-
175-
1. Clone the Repo
176-
2. Check [Setup Instruction section](#setup-instructions) to update the `.env` file
177-
3. Check [Advance Setup : PostgreSQL DB](#advance-setup--postgresql-db) section to update the `.env` file
178-
4. Run: `yarn install`
179-
5. Run: `yarn dev:server & yarn dev:worker`
180-
181-
The API defaults to `http://localhost:3005`
182-
183-
---
184-
185-
### 2. Use Docker Compose
186-
187-
---
91+
1. Nodesjs (>= v18)
92+
2. Docker
93+
3. PostgreSQL DB
18894

189-
| NOTE: Do not run `yarn install` |
190-
| ------------------------------- |
95+
### Install
19196

192-
In this approach we run everything, i.e., Web3-API Server & Worker, Postgres DB, PG-Admin on Docker.
97+
```
98+
yarn
99+
```
193100

194-
1. Clone the Repo
195-
2. Check [Setup Instruction section](#setup-instructions) to update the `.env` file
196-
3. Update the `HOST` value on the `.env` file to `0.0.0.0`. Example: `HOST=0.0.0.0`
197-
4. Update the `POSTGRES_HOST` value on the `.env` file to `host.docker.internal`. Example : `POSTGRES_HOST=host.docker.internal`
198-
5. Run: `yarn docker`
101+
### Run:
199102

200-
We use `docker-compose.yml` to spin up the API Server & Worker along with supporting infra services, a postgres database and the pg-admin GUI.
103+
```
104+
yarn dev
105+
```
201106

202-
The API defaults to `http://localhost:3005`
107+
This command runs the server, worker and sets up a postgres db, for fine grained control you can use these individually:
203108

204-
</details>
109+
```
110+
yarn dev:server
111+
yarn dev:worker
112+
yarn dev:infra
113+
```
205114

206-
## Local Benchmarking
115+
## User Guide
207116

208-
As a way to support quantifying the robustness of our system, we have added benchmarking. Benchmark results may vary based on the machine that is being used.
117+
View all end-points details (Open API Specification) : [User Guide](./docs/UserGuide.md)
209118

210-
To run the benchmark:
119+
## API Documentation
211120

212-
1. Run local server with `yarn dev`
213-
2. Set-up `.env.benchmark` (For sensible defaults: `cp .env.benchmark.example .env.benchmark`) - you'll need to update the `THIRDWEB_API_SECRET_KEY` at minimum.
214-
3. Run benchmark in a separate terminal with `yarn benchmark`
121+
View all end-points details (Open API Specification) : https://web3-api-akbv.chainsaw-dev.zeet.app
215122

216123
## Contributing
217124

0 commit comments

Comments
 (0)