|
13 | 13 | </a> |
14 | 14 | </p> |
15 | 15 |
|
16 | | -<p align="center"><strong>The most powerful backend engine for web3 apps.</strong></p> |
| 16 | +Engine is a backend HTTP server that calls smart contracts with your managed backend wallets. |
17 | 17 |
|
18 | | -## Table of contents |
19 | | - |
20 | | -- [Introduction](#introduction) |
21 | | -- [Getting started](#getting-started) |
22 | | - - [Setup environment variables](#setup-environment-variables) |
23 | | - - [Run the server](#run-the-server) |
24 | | - - [Using the server](#using-the-server) |
25 | | -- [Resources](#resources) |
26 | | - - [Using Engine](#using-engine) |
27 | | - - [Other Resources](#other-resources) |
28 | | -- [Security](#security) |
29 | | - |
30 | | -## Introduction |
31 | | - |
32 | | -thirdweb engine is a backend server that provides a HTTP interface to interact with any smart contract on any evm chain. Engine handles creating and managing backend wallets, enabling high throughput with automatic nonce and gas management. |
33 | | - |
34 | | -The high level functionality of thirdweb engine: |
| 18 | +[**Read the documentation**](https://portal.thirdweb.com/engine) for features, setup, configuration, guides, and references. |
35 | 19 |
|
36 | 20 | <!-- Source: https://whimsical.com/engine-architecture-2G6rXEvUM2HFmVwKxPWyzS --> |
37 | 21 | <img src="./docs/images/overview.png" alt="Overview" width="820"> |
38 | 22 |
|
39 | | -- Create & transact with **backend wallets** (Local, AWS KMS, Google KMS, etc.) |
40 | | -- High reliability transaction execution with **wallet nonce management**, **automatic transaction retrying** and **gas management** |
41 | | -- Deploy and interact with [erc-4337](https://eips.ethereum.org/EIPS/eip-4337) smart wallets, handle session keys & sending user operations |
42 | | -- Deploy published smart contracts (any EVM chain) |
43 | | -- Read, write and interact with smart contracts (any evm chain) |
44 | | -- Run in your own cloud or use the thirdweb managed service |
45 | | -- Fine-grained user access controls & wallet based client-side authentication [Coming Soon] |
46 | | -- Gasless relayer, bundler, and paymaster for gasless transactions [Coming Soon] |
47 | | - |
48 | | -This project is in `alpha` - if you're looking for specific features & or want to give feedback, reach out to us! |
49 | | - |
50 | | -## Requirements |
51 | | - |
52 | | -1. Docker |
53 | | -2. Postgres DB |
54 | | - |
55 | | -## Getting started |
56 | | - |
57 | | -### Setup environment variables |
58 | | - |
59 | | -Set these environment variables to get started. |
60 | | - |
61 | | -| Variable Name | Description | |
62 | | -| ------------------------- | ---------------------------------------------------------------------------------------------------------------- | |
63 | | -| `THIRDWEB_API_SECRET_KEY` | Create an API KEY on thirdweb Dashboard and copy the SecretKey. | |
64 | | -| `POSTGRES_CONNECTION_URL` | Postgres connection string, format: postgresql://[user[:password]@][host][:port][/dbname][?param1=value1&...] | |
65 | | -| `ADMIN_WALLET_ADDRESS` | The initial admin wallet address that can connect to this engine instance from the thirdweb dashboard for setup. | |
66 | | - |
67 | | -### Run the server |
68 | | - |
69 | | -Run the server using Docker with the following command. |
70 | | - |
71 | | -``` |
72 | | -docker run \ |
73 | | - -e THIRDWEB_API_SECRET_KEY="<your-api-secret-key>" \ |
74 | | - -e POSTGRES_CONNECTION_URL="<your-connection-url>" \ |
75 | | - -e ADMIN_WALLET_ADDRESS="<your-admin-wallet-address>" \ |
76 | | - -p 3005:3005 \ |
77 | | - thirdweb/engine:latest |
78 | | -``` |
79 | | - |
80 | | -### Using the server |
81 | | - |
82 | | -- 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: |
83 | | - - `Authorization: Bearer <thirdweb SecretKey>` |
84 | | -- Every write request to the server also requires the `x-backend-wallet-address` header to specify which admin wallet to send a transaction with. Use the following format to set this header: |
85 | | - |
86 | | - - `x-backend-wallet-address: 0x3ecdbf3b911d0e9052b64850693888b008e18373` |
87 | | - |
88 | | -- Here's the link to the [full API reference](https://redocly.github.io/redoc/?url=https://demo.web3api.thirdweb.com/json), or in development mode, go to the server root url to see the reference. |
89 | | - |
90 | | -> NOTE: To use the server in `https` mode on `localhost`, set the env variable `ENABLE_HTTPS` to `true`. This is only recommended for development purposes, when integrating your local Engine Instance with the thirdweb dashboard. |
91 | | -
|
92 | | -## Resources |
93 | | - |
94 | | -#### Using Engine |
95 | | - |
96 | | -- [User Guide](./docs/1-user-guide.md) - Setup an engine instance. |
97 | | -- [Smart Wallets Guide](./docs/2-smart-wallets.md) - Deploy, manage, and transact with smart wallets with engine. |
98 | | -- [Webhook Guide](./docs/3-webhook-guide.md) - Setup webhooks with engine. |
99 | | -- [Websocket Guide](./docs/4-websocket-guide.md) - Listen for transaction updates via websockets. |
100 | | -- [Load Testing Guide](./docs/addons/load-testing.md) - Load test engine for your use case. |
101 | | -- [AWS KMS Setup](./docs/kms/aws_kms_how_to.md) - Setup engine to use AWS KMS to manage wallets. |
102 | | -- [Google KMS Setup](./docs/kms/google_kms_how_to.md) - Setup engine to use Google KMS to manage wallets. |
103 | | - |
104 | | -#### Other Resources |
105 | | - |
106 | | -- [Frequently Asked Questions](./docs/addons/faqs.md) - The most common questions & answers. |
107 | | -- [Contributing to Engine](./docs/addons/contributing.md) - Contribute to this project! |
108 | | -- [Full API Playground](https://web3-api-akbv.chainsaw-dev.zeet.app) - Full playground to interact with engine yourself. |
109 | | -- [Community Discord Server](https://discord.gg/thirdweb) - Join our community to discuss ideas & issues or just to hangout 😄 |
110 | | - |
111 | | -## Security |
112 | | - |
113 | | -If you believe you have found a security vulnerability in any of our packages, we kindly ask you not to open a public issue; and to disclose this to us by emailing `security@thirdweb.com`. |
| 23 | +## Features |
| 24 | + |
| 25 | +- Managed backend wallets |
| 26 | +- Contract calls and deployments ([all EVM blockchains](https://thirdweb.com/chainlist) + private subnets) |
| 27 | +- Parallel transactions with retries |
| 28 | +- Account abstraction with session tokens |
| 29 | +- Gasless transactions |
| 30 | +- Wallet and contract webhooks |
| 31 | +- And [much more!](https://portal.thirdweb.com/engine) |
| 32 | + |
| 33 | +## Quickstart |
| 34 | + |
| 35 | +1. Install [Docker](https://docs.docker.com/get-docker/). |
| 36 | +1. Run Postgres. |
| 37 | + ```bash |
| 38 | + docker run -p 5432:5432 -e POSTGRES_PASSWORD=postgres -d postgres |
| 39 | + ``` |
| 40 | +1. Run Engine. |
| 41 | + ```bash |
| 42 | + docker run \ |
| 43 | + -e THIRDWEB_API_SECRET_KEY="<thirdweb_secret_key>" \ |
| 44 | + -e ADMIN_WALLET_ADDRESS="<admin_wallet_address>" \ |
| 45 | + -e POSTGRES_CONNECTION_URL="postgresql://postgres:postgres@host.docker.internal:5432/postgres?sslmode=disable" \ |
| 46 | + -e ENABLE_HTTPS=true \ |
| 47 | + -p 3005:3005 \ |
| 48 | + --pull=always \ |
| 49 | + --cpus="0.5" \ |
| 50 | + thirdweb/engine:latest |
| 51 | + ``` |
| 52 | +1. Navigate to the [Engine dashboard](https://thirdweb.com/dashboard/engine). |
| 53 | + - CORS error? Load https://localhost:3005 in your browser first. |
| 54 | +1. Create or import a [local wallet](https://portal.thirdweb.com/engine/backend-wallets). |
| 55 | + |
| 56 | +Learn more: [Getting Started](https://portal.thirdweb.com/engine/getting-started) |
| 57 | + |
| 58 | +> **Production:** Deploy Postgres and Engine to your cloud provider. Consider creating [KMS backend wallets](https://portal.thirdweb.com/engine/backend-wallets). |
| 59 | +
|
| 60 | +## Contributing |
| 61 | + |
| 62 | +We welcome external contributions! See [how to contribute to thirdweb repos]. Please try to follow the existing code style and conventions. |
| 63 | + |
| 64 | +## Get in touch |
| 65 | + |
| 66 | +- Support: [Join the Discord](https://discord.gg/thirdweb) |
| 67 | +- Twitter: [@thirdweb](https://twitter.com/thirdweb) |
| 68 | +- Report a vulnerability: security@thirdweb.com |
0 commit comments