Skip to content

feat: edit documentation for Account Abstraction and add Smart Backend Wallets #5516

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Dec 2, 2024
Merged

feat: edit documentation for Account Abstraction and add Smart Backend Wallets #5516

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c06f611
feat: edit documentation for Account Abstraction and add Smart Backen…
d4mr Nov 25, 2024
cce67d3
fix: correct typo in backend wallets documentation
d4mr Nov 25, 2024
3abd74d
fix: improve clarity in backend wallets documentation
d4mr Nov 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion apps/portal/src/app/engine/features/account-abstraction/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { createMetadata } from "@doc";
import { createMetadata, Callout } from "@doc";

export const metadata = createMetadata({
title: "Account Abstraction | thirdweb Engine",
Expand All @@ -8,6 +8,19 @@ export const metadata = createMetadata({

# Account Abstraction

<Callout variant="info" title="Looking to use account abstraction for your backend operations?">
Copy link
Contributor

@arcoraven arcoraven Nov 26, 2024

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.

Your backend wallets can be smart accounts too!

Use Smart Backend Wallets to get the benefits of account abstraction for your backend wallets, including:
...
Learn more about Smart Backend Wallets

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.

Consider using [Smart Backend Wallets](/engine/features/backend-wallets#smart-backend-wallets) instead. They combine EOA and smart account management into a single wallet, with automatic deployment and simplified integration:

- No need to deploy or manage account factories
- No separate account and backend wallet addresses to track
- Works with all existing Engine endpoints without modification
- Built-in transaction batching and recovery
- Automatic gas management with paymaster

Smart backend wallets are recommended when you need account abstraction for your own backend operations. Use the approach described below when you need to manage smart accounts for your users.

</Callout>

Use Engine to deploy, manage, and transact with smart accounts on behalf of your users.

## Deploy an account factory
Expand Down
52 changes: 50 additions & 2 deletions apps/portal/src/app/engine/features/backend-wallets/page.mdx
View file
Open in desktop
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",
Expand All @@ -12,6 +13,49 @@ Engine performs blockchain actions using backend wallets that you own and manage

There are multiple options for securing backend wallets.

## Smart Backend Wallets
Copy link
Contributor

@arcoraven arcoraven Nov 26, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO less detail around "how it works" so we can focus the content on "why you should care" and "how to use it".

  • Remove the note about EOA internally managed and default factory. It's sufficient to just say "it uses a smart account".
  • Probably remove comment on multi-dimensional nonces. We can just say "Higher throughput: Transactions are sent from thirdweb's bundler to maximize onchain throughput."


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 for gas.
- **Better Nonce Management**: Smart accounts use multi-dimensnal nonces, which are more efficient than EOAs.
Copy link
Contributor

@graphite-app graphite-app bot Nov 25, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There appears to be a typo in "multi-dimensnal" - it should be "multi-dimensional". This affects readability of an otherwise well-written technical explanation.

Spotted by Graphite Reviewer

Is this helpful? React 👍 or 👎 to let us know.

Copy link
Contributor

@graphite-app graphite-app bot Nov 25, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There appears to be a typo in "multi-dimensnal" - it should be "multi-dimensional". This affects readability of an otherwise well-written technical explanation.

Spotted by Graphite Reviewer

Is this helpful? React 👍 or 👎 to let us know.

- **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?">
Copy link
Contributor

@arcoraven arcoraven Nov 26, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Contributor

@arcoraven arcoraven Nov 26, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: I've also been capitalizing Smart Backend Wallets.

"backend wallet" = a concept, lowercase is fine
"Smart Backend Wallet" = product/feature name (like "Contract Subscriptions")

The backend wallet address is now the smart account address itself.
</Details>

<Details summary="When not to use Smart Backend Wallets?">
Copy link
Contributor

@arcoraven arcoraven Nov 26, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Contributor

@arcoraven arcoraven Nov 26, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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.
Copy link
Contributor

@arcoraven arcoraven Nov 26, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To configure AWS and Google Cloud KMS, ...


### 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). (Smart accounts need to be deployed on each chain which costs gas that is paid by the user.)

## 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.
Expand All @@ -31,7 +75,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. 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:
Expand All @@ -50,7 +94,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
Expand All @@ -71,6 +114,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.
Expand All @@ -82,6 +126,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.
Expand All @@ -93,6 +138,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.
Expand All @@ -104,6 +150,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]`

Expand All @@ -114,6 +161,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.

Expand Down
Loading