feat: edit documentation for Account Abstraction and add Smart Backend Wallets #5516
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,5 @@ | ||
| import { createMetadata, Details } from "@doc"; | ||
| import { Callout } from "@doc"; | ||
|
|
||
| export const metadata = createMetadata({ | ||
| title: "Backend Wallets | thirdweb Engine", | ||
|
|
@@ -12,6 +13,50 @@ Engine performs blockchain actions using backend wallets that you own and manage | |
|
|
||
| There are multiple options for securing backend wallets. | ||
|
|
||
| ## Smart Backend Wallets | ||
|
Contributor
There was a problem hiding this comment. IMO less detail around "how it works" so we can focus the content on "why you should care" and "how to use it".
|
||
|
|
||
| Smart backend wallets are the recommended way to perform blockchain operations with Engine. Each smart backend wallet consists of an EOA (managed internally by Engine) and a smart account (using thirdweb's default account implementation). | ||
|
|
||
| ### Benefits | ||
|
|
||
| Smart backend wallets inherit smart account benefits and offer several advantages over traditional EOAs: | ||
|
|
||
| - **Gas Management**: Built-in paymaster eliminates the need to maintain gas tokens. This means you never need to hold crypto or top up gas. | ||
| - **Better Nonce Management**: Smart accounts use multi-dimensional nonces, which are more efficient than EOAs. | ||
| - **Simple Integration**: Works with all existing Engine endpoints without any code changes. | ||
|
|
||
| ### How it works | ||
|
|
||
| The smart account is automatically deployed the first time you send a transaction on a chain. You don't need to think about deploying or managing the smart account - Engine handles everything behind the scenes. All transactions are sent as UserOperations to the EntryPoint contract on chain. | ||
|
|
||
| <Details summary="How are Smart Backend Wallets different from existing engine AA features?"> | ||
|
Contributor
There was a problem hiding this comment. Nit: always capitalize Engine (product name) |
||
| Unlike the [previous account abstraction implementation in | ||
| Engine](account-abstraction) where you had to manage both the account address | ||
| (`x-account-address`) and the backend wallet address | ||
| (`x-backend-wallet-address`) separately, smart backend wallets simplify this. | ||
|
Contributor
There was a problem hiding this comment. Nit: I've also been capitalizing Smart Backend Wallets. "backend wallet" = a concept, lowercase is fine |
||
| The backend wallet address is now the smart account address itself. | ||
| </Details> | ||
|
|
||
| <Details summary="When not to use Smart Backend Wallets?"> | ||
|
Contributor
There was a problem hiding this comment. Hm would someone need this, or would we build this in the future? Maybe this just belongs in an FAQ section at the bottom: ## FAQ
#### Can I import a smart account?
No, importing a smart account is currently not supported. |
||
| At this time, Smart Backend Wallets do not allow for importing a smart | ||
| account. In use cases where you need to import a smart account (such as with | ||
| session keys), you should use [Engine AA features that utilise the | ||
| `x-account-address` header](account-abstraction). | ||
| </Details> | ||
|
|
||
| ### Configuration Types | ||
|
|
||
| - `smart:local` - Smart account backed by a local key | ||
|
Contributor
There was a problem hiding this comment. "backed up locally in Engine" or something. Don't need to reference the EOA |
||
| - `smart:aws-kms` - Smart account backed by AWS KMS | ||
| - `smart:gcp-kms` - Smart account backed by Google Cloud KMS | ||
|
|
||
| For AWS and Google Cloud KMS options, follow the setup instructions in the respective sections below. | ||
|
Contributor
There was a problem hiding this comment.
|
||
|
|
||
| ### Pricing | ||
|
|
||
| Smart backend wallets have no additional costs to use with your Engine instance. Transactions sent from smart backend wallets follow the [same billing model as regular account abstraction transactions with thirdweb](/connect/account-abstraction/infrastructure#pricing--billing). | ||
|
Contributor
There was a problem hiding this comment. We should note the customer is charged for mainnet usage only.
|
||
| Smart accounts need to be deployed on each chain. This costs gas and is billed to your account like any other transaction. | ||
|
Contributor
There was a problem hiding this comment. A little more clear:
|
||
|
|
||
| ## Local wallet | ||
|
|
||
| A [local wallet](/references/wallets/v2/LocalWallet) is a wallet created or imported from a private key. Ensure your private key is backed up before transacting with a local wallet in a production environment. | ||
|
|
@@ -31,7 +76,7 @@ An [AWS KMS Wallet](/references/wallets/v2/AwsKmsWallet) is a wallet securely st | |
| - `kms:Sign` | ||
| - `kms:CreateAlias` | ||
| - `kms:Verify` | ||
| 1. On the user page, navigate to **Security credentials > Access keys**. | ||
| 1. Select **Create access key** to get an **Access Key** and **Secret Key**. | ||
| 1. In the dashboard, navigate to **Configuration > Backend Wallets**. | ||
| 1. Select **AWS KMS** and provide the following: | ||
|
|
@@ -50,7 +95,6 @@ An [AWS KMS Wallet](/references/wallets/v2/AwsKmsWallet) is a wallet securely st | |
| - AWS KMS Key ID (example: `0489da75-9830-4a5a-97e3-e4a6df7775b3`) | ||
| - AWS KMS ARN (example: `arn:aws:kms:us-west-1:632186309261:key/0489da75-9830-4a5a-97e3-e4a6df7775b3`) | ||
|
|
||
| ## Google Cloud KMS wallet | ||
|
|
||
| #### Setup | ||
|
|
@@ -71,6 +115,7 @@ An [AWS KMS Wallet](/references/wallets/v2/AwsKmsWallet) is a wallet securely st | |
| This is the Project ID of the GCP project where the key was created. | ||
|
|
||
| **Where to find**: | ||
|
|
||
| - Navigate to the Google Cloud Console. | ||
| - Click on the project dropdown at the top of the page. | ||
| - The Project ID is displayed under your project's name. | ||
|
|
@@ -82,6 +127,7 @@ An [AWS KMS Wallet](/references/wallets/v2/AwsKmsWallet) is a wallet securely st | |
| This is the location where the keyring was created (e.g., us-central1, europe-west1). | ||
|
|
||
| **Where to find**: | ||
|
|
||
| - In the Google Cloud Console, go to **Security > Cryptographic Keys**. | ||
| - Click on the keyring that contains your key. | ||
| - The location is displayed in the Location field. | ||
|
|
@@ -93,6 +139,7 @@ An [AWS KMS Wallet](/references/wallets/v2/AwsKmsWallet) is a wallet securely st | |
| This is the ID of the keyring where your key is stored. | ||
|
|
||
| **Where to find**: | ||
|
|
||
| - In the Google Cloud Console, go to **Security > Cryptographic Keys**. | ||
| - Select the keyring that contains your key. | ||
| - The KeyRing ID is displayed in the list or the URL. | ||
|
|
@@ -104,6 +151,7 @@ An [AWS KMS Wallet](/references/wallets/v2/AwsKmsWallet) is a wallet securely st | |
| This is the email associated with the service account used for accessing the KMS key. | ||
|
|
||
| **Where to find**: | ||
|
|
||
| - In the Google Cloud Console, go to **IAM & Admin > Service Accounts**. | ||
| - Find the service account you are using. its email will be in the format: `[email protected]` | ||
|
|
||
|
|
@@ -114,6 +162,7 @@ An [AWS KMS Wallet](/references/wallets/v2/AwsKmsWallet) is a wallet securely st | |
| This is the private key of the service account that is used for authenticating API requests. | ||
|
|
||
| **Where to find**: | ||
|
|
||
| - Open the JSON file downloaded above. | ||
| - Copy the value of the `private_key` field. | ||
|
|
||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this prompt is unclear.
Engine's concept of "account abstraction" typically refers to Engine backend EOA wallets managing smart accounts.
So this callout is suggesting a different type of account abstraction that they may be looking for (which is incompatible with the above AA use cases).
I think we can downplay the fact that smart backend wallets are AA-based and just mention the benefits. I wouldn't put too much detail here since it's hard to convey what it is without the person just reading the other page.
Let's also put this below the intro sentence (line 24 below) since the developer doesn't even know what this page is about yet, and we're prompting them they might be looking for something else.