diff --git a/docs/onboarding/22 Web3 API/0 Overview.mdx b/docs/onboarding/22 Web3 API/0 Overview.mdx new file mode 100644 index 000000000..dc33305e0 --- /dev/null +++ b/docs/onboarding/22 Web3 API/0 Overview.mdx @@ -0,0 +1,33 @@ +--- +slug: /web3-api +title: Overview +hide_title: true +--- + +:::info +Web3 API is currently in Beta. To try it out, please [contact our business team](https://thirdweb.com/contact-us). +::: + +# Overview + +Web3 API provides a server-side interface for contracts & wallets, without the complexities of wallet and transaction management. + +It offers APIs for contracts, wallets, gas-less configurations & auth that allows developers to go to market and launch production grade applications with cross-EVM chain support with faster speeds, security, and reliability. + +--- + +Building a decentralized application with a seamless user experience at scale requires setting up a backend infrastructure to create & manage wallets, deploy & interact with contracts, and handle user authentication. Web3 API removes this friction by eliminating blockchain constraints related to nonce, funds, gas, and key management. + +![Diagram showing relationship of Web3 API](./assets/web3-api-arch.png) + +## Features + +- **Backend wallets:** Create backend wallets, store their keys securely via a cloud secrets manager like KMS, sign & send any transactions, and move funds at scale with nonce-management. +- **Smart wallets with shared custody:** Create managed, smart wallets with shared custody between the backend wallets & a user’s EOA wallet. +- **Contracts:** Deploy, read, and write to any contract across any blockchain. +- **Auth:** Create permissions to enable users with wallets to directly interact with certain endpoints on the web3api. +- **Sponsored transactions:** Sponsor gas fees for any transactions through the web3 api. + +## Beta Feedback + +If you experience any bugs or have any feedback, please [report it to our support team](https://discord.gg/thirdweb) via Discord. diff --git a/docs/onboarding/22 Web3 API/1 Configuration.mdx b/docs/onboarding/22 Web3 API/1 Configuration.mdx new file mode 100644 index 000000000..13a75d374 --- /dev/null +++ b/docs/onboarding/22 Web3 API/1 Configuration.mdx @@ -0,0 +1,133 @@ +--- +slug: /web3-api/configuration +title: Configuration +hide_title: true +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +:::info +Web3 API is currently in Beta. To try it out, please [contact our business team](https://thirdweb.com/contact-us). +::: + +# Configuration + +## Prerequisites + +Before you begin, ensure you have the following: + +- [ ] Docker +- [ ] PostgreSQL +- [ ] Wallet with funds +- [ ] thirdweb secret key + +## Part 1: Wallet Configuration + +To use web3 API, you will need to initiate it with an admin wallet using one of the following options: + +### Backend Wallet + +1. Setup a `.env` file at the root of your project’s repository +2. Set the following variables in your `.env` file: + + ````json + WALLET_PRIVATE_KEY= + THIRDWEB_SDK_SECRET_KEY= + ``` + ```` + +### AWS KMS + +Web3-API supports AWS KMS for signing & sending transactions over any EVM chain. + +1. Setup a managed key through AWS KMS. + 1. Create an IAM user with programmatic access. Follow the instructions in the AWS documentation on **[creating an IAM user in your AWS account](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console)**. + 2. Enable Create, Get, and Read permissions for your KMS. Learn more about **[authentication and access control for AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html)** in the AWS documentation. + 3. Create a KMS key by following the instructions in the AWS documentation on how to [create keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html). +2. Setup a `.env` file at the root of your repository and set the following variables in this file. + + ```json + # Required for AWS Auth + AWS_ACCESS_KEY_ID= + AWS_SECRET_ACCESS_KEY= + AWS_REGION= + + # Required for AWS KMS Admin Wallet + AWS_KMS_KEY_ID= + ``` + +### Google KMS + +Web3-API supports Google KMS for signing & sending transactions over any EVM chain. + +1. Setup a managed key through Google KMS. + 1. Create an encrypted key with Cloud KMS. Learn how to [Create encryption keys with Cloud KMS](https://cloud.google.com/kms/docs/create-encryption-keys#before-you-begin) from the Google Cloud documentation. + 2. Create a Service Account. Learn how to [Create service accounts](https://cloud.google.com/iam/docs/service-accounts-create) in the Google Cloud documentation. + 3. Create a key with this service account. + 4. Download the JSON file. The JSON file details will be used to authenticate with Google KMS. + 5. Add the following permissions to your service account: `Cloud KMS Admin` and `Cloud KMS CryptoKey Signer/Verifier` +2. Setup a `.env` file at the root of your repository +3. Set the following variables in your `.env` file: + + ```json + # Required for Google Auth + GOOGLE_APPLICATION_CREDENTIAL_EMAIL= + GOOGLE_APPLICATION_CREDENTIAL_PRIVATE_KEY= + + # Required for Google KMS + GOOGLE_APPLICATION_PROJECT_ID= + GOOGLE_KMS_KEY_RING_ID= + GOOGLE_KMS_LOCATION_ID= + GOOGLE_KMS_CRYPTO_KEY_ID= # If created on Google Console + ``` + +## Part 2: Server Configuration + +While in beta, Web3 API only offers self-hosted options. To use Web3 API, you will need to host your own server using a containerization platform such as Docker or Kubernetes. + +### Configure Server Using Docker + +To host your own server with Docker: + +1. [Install Docker](https://docs.docker.com/get-docker/) +2. Add the following variables to your `.env` file at the root of your repository: + + ``` + + # DEFAULT DOCKER + + POSTGRES_HOST=host.docker.internal + POSTGRES_DATABASE_NAME=postgres + POSTGRES_USER=postgres + POSTGRES_PASSWORD=postgres + ``` + +3. To obtain the Postgres Docker Image, navigate to the root of your project and run the following command in your command line: + + ```python + docker run --env-file ./.env -p 5432:5432 --name my-local-postgres -d postgres + ``` + +4. Afterwards, to get the Web3 API Docker Image, navigate to the root of your project and run the following command in your command line: + + ``` + docker run --env-file ./.env -p 3005:3005 --name web3-api thirdweb/web3-api:nightly + ``` + +5. To authenticate, open `localhost:3005` in your browser. +6. Select the `Authorize` option on the dashboard. + + ![Screenshot of how to authorize via Swagger](./assets/authorize-api.png) + +7. Pass in your corresponding secret key created from the thirdweb dashboard and select Authorize. + + ![Screenshot of passing in Bearer auth field](./assets/authorize-bearer.png) + +8. You are now ready to begin developing using APIs. To see a demonstration of endpoints, please visit the `Get Started` tutorial. + +### Authorization Header + +All Requests need to have `Authorization` header with the value of `Bearer ` from the `.env` file. + +For specific examples of implementation, follow along with our Get Started tutorial. diff --git a/docs/onboarding/22 Web3 API/2 Get Started.mdx b/docs/onboarding/22 Web3 API/2 Get Started.mdx new file mode 100644 index 000000000..e4f9d6127 --- /dev/null +++ b/docs/onboarding/22 Web3 API/2 Get Started.mdx @@ -0,0 +1,93 @@ +--- +slug: /web3-api/get-started +title: Get Started +hide_title: true +--- + +:::info +Web3 API is currently in Beta. To try it out, please [contact our business team](https://thirdweb.com/contact-us). +::: + +# Get Started + +Once you have configured your self-hosted server, you can begin development with the Web3 API. + +This guide will provide a few examples of how you can use the Web3 API: + +### Get Balance + +To quickly demonstrate how to use Web3 API in your application, let's create a quick JavaScript script that fetches your wallet's balance on a specific network using the `/wallet/{network}/getBalance` endpoint. + +1. Create a `getBalance.js` at the root of your project’s directory +2. At the top of your file, let’s create a variable to store our network to pass into our path parameter. + + ``` + const network = "mumbai"; + ``` + +3. Configure your HTTP GET request + + ```jsx + const options = { + method: "GET", + headers: { + accept: "application/json", + "content-type": "application/json", + Authorization: `Bearer ${process.env.THIRDWEB_SDK_SECRET_KEY}`, + }, + }; + ``` + +4. Now we can use the `fetch()` function to make an HTTP GET request to our `wallet/${network}/getBalance` endpoint and display the result to our console. + + ``` + fetch(`http://localhost:3005/wallet/${network}/getBalance}`, options) + .then((response) => response.json()) + .then((response) => console.log(response.result.displayValue)) + .catch((err) => console.error(err)); + ``` + +5. Run your script in the command using `node getBalance.js` +6. In the terminal, you will see the amount of Matic you have in your wallet returned. + +### Deploy Contract + +As an example for a POST method, let's modify our script to deploy an ERC20 Contract using `/deployer/{network}/prebuilts/token` + +1. Create a `deployToken.js` at the root of your project’s directory +2. At the top of your file, let’s create a variable to store our network to pass into our path parameter. + + ```jsx + const network = "mumbai"; + ``` + +3. Configure your HTTP POST request body. Modify the `primary_sale_recipient` to your address or the address you want to receive initial funds. + + ```jsx + const options = { + method: "GET", + headers: { + accept: "application/json", + "content-type": "application/json", + Authorization: `Bearer ${process.env.THIRDWEB_SDK_SECRET_KEY}`, + }, + body: JSON.stringify({ + name: "HelloWorldCoin", + description: "A coin to demonstrate how to use Web3 API", + symbol: "HELLO", + primary_sale_recipient: "0x0000000000000000000000000000000000000000", + }), + }; + ``` + +4. Now we can use the `fetch()` function to make an HTTP GET request to our `/deployer/{network}/prebuilts/token` and return the URL for the deployed contract on the dashboard. + + ```jsx + fetch(`http://localhost:3005/deployer/${network}/prebuilts/token`, options) + .then((response) => response.json()) + .then((response) => console.log(`https://thirdweb.com/${network}/${response.result.deployedAddress}`) + .catch((err) => console.error(err)); + ``` + +5. Run your script in the command using `node deployToken.js` +6. To find your contract, redirect from the link returned in the command line. diff --git a/docs/onboarding/22 Web3 API/3 References.mdx b/docs/onboarding/22 Web3 API/3 References.mdx new file mode 100644 index 000000000..753949ebe --- /dev/null +++ b/docs/onboarding/22 Web3 API/3 References.mdx @@ -0,0 +1,13 @@ +--- +slug: /web3-api/reference +title: Reference +hide_title: true +--- + +:::info +Web3 API is currently in Beta. To try it out, please [contact our business team](https://thirdweb.com/contact-us). +::: + +### References + +[>> View the full beta endpoint reference.](https://redocly.github.io/redoc/?url=https://web3-api-akbv.chainsaw-dev.zeet.app/json#tag/Admin-Wallet/operation/adminWalletBalance) diff --git a/docs/onboarding/22 Web3 API/assets/authorize-api.png b/docs/onboarding/22 Web3 API/assets/authorize-api.png new file mode 100644 index 000000000..00f00d29f Binary files /dev/null and b/docs/onboarding/22 Web3 API/assets/authorize-api.png differ diff --git a/docs/onboarding/22 Web3 API/assets/authorize-bearer.png b/docs/onboarding/22 Web3 API/assets/authorize-bearer.png new file mode 100644 index 000000000..e18abd4a8 Binary files /dev/null and b/docs/onboarding/22 Web3 API/assets/authorize-bearer.png differ diff --git a/docs/onboarding/22 Web3 API/assets/web3-api-arch.png b/docs/onboarding/22 Web3 API/assets/web3-api-arch.png new file mode 100644 index 000000000..f9dcbb915 Binary files /dev/null and b/docs/onboarding/22 Web3 API/assets/web3-api-arch.png differ diff --git a/sidebars/onboarding.js b/sidebars/onboarding.js index 10256b493..5266bca98 100644 --- a/sidebars/onboarding.js +++ b/sidebars/onboarding.js @@ -43,6 +43,11 @@ const sidebars = { label: "Smart Wallet", href: "/smart-wallet", }, + { + type: "link", + label: "Web3 API", + href: "/web3-api", + }, { type: "link", label: "Email Wallet", @@ -237,6 +242,13 @@ const sidebars = { }, ], + web3Api: [ + { + type: "autogenerated", + dirName: "22 Web3 API", + }, + ], + sdk: [ { type: "doc", diff --git a/src/theme/DocSidebarItem/Link/index.js b/src/theme/DocSidebarItem/Link/index.js index db560fa33..062303c22 100644 --- a/src/theme/DocSidebarItem/Link/index.js +++ b/src/theme/DocSidebarItem/Link/index.js @@ -45,6 +45,7 @@ export const iconMapping = { Guides: "/assets/resources/guides.svg", CLI: "/assets/product/CLI.png", Glossary: "/assets/icons/journal-album.svg", + "Web3 API": "/assets/product/sdk.png", }; export default function DocSidebarItemLink({ diff --git a/src/theme/DocSidebarItems/index.js b/src/theme/DocSidebarItems/index.js index e8470bc89..44ca619e0 100644 --- a/src/theme/DocSidebarItems/index.js +++ b/src/theme/DocSidebarItems/index.js @@ -57,7 +57,7 @@ function DocSidebarItems({ items, ...props }) { }, { title: "Tools", - items: ["CLI", "Dashboard", "SDKs"], + items: ["CLI", "Dashboard", "SDKs", "Web3 API"], }, { title: "SDK References",