Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
481 changes: 243 additions & 238 deletions docs/docs.yml

Large diffs are not rendered by default.

16 changes: 16 additions & 0 deletions docs/pages/concepts/bundler-client.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
---
title: Bundler Client
description: What is the Bundler Client?
---

# Bundler Client

The Bundler Client is similar to the [Smart Account Client](/wallets/concepts/smart-account-client) but is account agnostic. The Bundler Client only exposes methods for interacting directly with Bundler RPC and ETH RPC
methods. The client also exposes the same methods as `viem`'s [`PublicClient`](https://viem.sh/docs/actions/public/introduction). In the vast majority of cases, you will not be using this client directly and will instead be using the [Smart Account Client](/wallets/concepts/smart-account-client) which wraps an instance of the Bundler Client
and provides the same actions as the Bundler Client.

The Bundler Client is EIP-1193 compliant, meaning it can easily be swapped out in place of other web3 providers (eg. `window.ethereum`).

## Bundler Client actions

Similarly to the Smart Account Client, the Bundler Client is extended with a set of actions that make it easier to interact with RPC methods. The actions are all defined in [`@aa-sdk/core`](https://github.com/alchemyplatform/aa-sdk/tree/v4.x.x/aa-sdk/core/src/actions/bundler). For detailed documentation on these methods, check out the [SDK Reference Docs](/wallets/reference/aa-sdk/core).
117 changes: 117 additions & 0 deletions docs/pages/concepts/intro-to-account-kit.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
---
title: Intro to Account Kit
description: Introduction to Account Kit and Account Abstraction
---

# Intro to Account Kit

Account Kit is your all-in-one toolkit for building zero-friction sign-up and transaction flows. But what’s **really** happening under the hood?

Account Kit abstracts away the complexity of smart accounts, but as a builder it’s useful to have a foundational understanding of how it works. This way, you can make informed decisions and unlock the full potential of account abstraction.

Unlike other embedded wallet providers that only solve sign-up and key management, Account Kit goes further by streamlining the transaction flow with features like gas sponsorship. How? Through **Account Abstraction** and **smart accounts** 🚀 **Let’s break it down.**

## Smart accounts: programmable wallets, not EOAs

<div style={{ display: "flex", flexWrap: "wrap", alignItems: "flex-start" }}>
<div style={{ flex: "1", marginRight: "10px" }}>
With Account Kit, you’ll deploy a **Smart Contract Account (SCA)** for each
user instead of an Externally Owned Account (EOA). This smart account will
securely store the user's assets, such as tokens or NFTs.
</div>
<div style={{ flex: "0 0 30%" }}>
<img
src="/images/account-kit/smartaccount.png"
alt="Alt text"
style={{ width: "100%" }}
/>
</div>
</div>

#### What is a smart account?

Unlike EOAs, SCAs are programmable and can include logic. When we refer to SCAs, or smart accounts, we are typically talking about [ERC-4337](https://www.alchemy.com/overviews/what-is-account-abstraction) smart accounts.

Account Kit comes with enterprise-grade, audited smart account implementations. We recommend using [Modular Account v2](/wallets/smart-contracts/modular-account-v2/overview). Learn more and [choose](/wallets/smart-contracts/choosing-a-smart-account) the smart account that best fits your needs or bring your own smart account.

#### Why smart accounts?

Smart accounts unlock powerful Account Abstraction features like gas sponsorship and transaction batching enabling you to create seamless transaction experiences (more on this [later](#gas-manager-sponsor-gas)).

Smart accounts provide flexibility, security, and additional functionality over EOAs. Features like social recovery, two-factor authentication, multi-owner support, and ownership transfer become possible with smart accounts.

In Account Kit, this concept will manifest as a [Smart Contract Account](/wallets/concepts/smart-contract-account).

## Signer: web2 login and key management

<div style={{ display: "flex", flexWrap: "wrap", alignItems: "flex-start" }}>
<div style={{ flex: "1", marginRight: "10px" }}>
A **Signer** is a service (e.g., Turnkey or Magic) or application (e.g., MetaMask) that manages a private key and signs transactions. The signature is only valid if the signer is an owner of the smart account.

</div>
<div style={{ flex: "0 0 30%" }}>
<img
src="/images/account-kit/smartaccount+signer.png"
alt="Alt text"
style={{ width: "100%" }}
/>
</div>
</div>
[Using Account Kit](/wallets/react/getting-started), you can secure a user’s Smart Account with email, social login, or passkeys, using our non-custodial Signer infrastructure. Smart accounts support advanced use cases, such as multiple owners and ownership transfer, offering more utility than EOAs.

With this setup, users can sign-up, log in, and sign transactions using familiar web2 user experiences.

In Account Kit, this concept will manifest as a [Smart Account Signer](/wallets/concepts/smart-account-signer).

## Bundler: transactions → user operations

<div style={{ display: "flex", flexWrap: "wrap", alignItems: "flex-start" }}>
<div style={{ flex: "1", marginRight: "10px" }}>
With Account Kit, [sending transactions](/wallets/react/send-user-operations) is as simple as sending “normal” EOA transactions. However, under the hood, you’re actually sending [**User Operations (UOs)**](https://www.alchemy.com/overviews/user-operations) — a standardized pseudo-transaction object — to a **Bundler**.

</div>
<div style={{ flex: "0 0 30%" }}>
<img
src="/images/account-kit/smartaccount+signer+bundler.png"
alt="Alt text"
style={{ width: "100%" }}
/>
</div>
</div>

A User Operation (UO) is an ABI-encoded struct that describes a transaction to be sent on behalf of a user. Since SCAs cannot initiate transactions on chains without native account abstraction support, they send UOs instead. The Bundler will gather UOs from multiple smart accounts (senders) and bundle them into a single on-chain transaction.

A huge benefit of smart accounts is the ability to [batch transactions](/wallets/react/send-user-operations#batch-user-operation) in one UO creating simpler user experiences. For example, you can now approve and swap in one click, rather than signing, waiting, and sending multiple transactions.

In Account Kit, this concept will manifest as a [Bundler Client](/wallets/concepts/bundler-client), but for simplicity you may only need a [Smart Account Client](/wallets/concepts/smart-account-client).

## Gas Manager: sponsor gas

<div style={{ display: "flex", flexWrap: "wrap", alignItems: "flex-start" }}>
<div style={{ flex: "1", marginRight: "10px" }}>
With gas sponsorship, your users won’t need to worry about having assets in their accounts to pay for gas. Using [Account Kit](/wallets/react/sponsor-gas), simply configure a gas manager policy, insert your policy ID into the SDK, and let our Gas Manager handle the rest.

</div>
<div style={{ flex: "0 0 30%" }}>
<img
src="/images/account-kit/smartaccount+signer+bundler+paymaster.png"
alt="Alt text"
style={{ width: "100%" }}
/>
</div>
</div>

## Conclusion

Account Kit makes it easy to build a web2 user experience from sign-up to transaction. It includes everything you need to bring users onchain:

- Non-custodial **Signer** to authenticate with web2 login
- Secure and flexible **smart accounts** to store assets
- **Gas Manager** to sponsor gas
- Reliable and scalable **Bundler** to land user operations

Account Abstraction might seem complex, but Account Kit abstracts away the intricacies, allowing you to focus on building great user experiences.

**Now, get started with the [quickstart](/wallets/react/quickstart)!**

Want to learn more? Explore our [Account Abstraction education hub](https://www.alchemy.com/learn/account-abstraction)
31 changes: 31 additions & 0 deletions docs/pages/concepts/middleware.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
---
title: Middleware
description: What is Middleware?
---

# Middleware

The [Smart Account Client](/wallets/concepts/smart-account-client) is extended with a series of middleware. When building user operations for signing and sending, the flow can be pretty involved.
Sending a UO requires you to get the latest nonce for an account, check if the account is deployed to set the `initCode` or `factory` and `factoryData` in the user operation, estimate fees, estimate gas, and then sign the user operation.
If you want to use a paymaster, you need to generate some `dummyPaymasterAndData` to use during gas estimation, and after estimating gas you can request gas sponsorship from your paymaster.
Middleware allows you to avoid having to write the same flows over and over when all you want to do is call a contract with some data or send some ETH to a destination.

## Middleware order

<Tip>
When using the [React](/wallets/react/overview),
[Core](/wallets/core/overview), or [Infra](/wallets/infra/overview) packages,
the Smart Account Clients are already configured to use the appropriate
middleware for your needs. If you want to sponsor gas, the Smart Account
Clients in these packages abstract the relevant middleware away from you since
all you need is a `policyId` to sponsor gas with Alchemy.
</Tip>

As mentioned above, the client can be configured with a series of middleware that always run in the same order:

1. `dummyPaymasterAndData` - Generates a dummy paymaster and data for gas estimation if using a paymaster (default: noop)
2. `feeEstimator` - Estimates the fees for a user operation. If you are using our RPCs, it's important to use the [`alchemyFeeEstimator`](/wallets/reference/account-kit/infra/functions/alchemyFeeEstimator) middleware.
3. `gasEstimator` - Estimates the gas limits for a user operation. The default middleware calls the underlying bundler RPC to `eth_estimateUserOperationGas`.
4. `customMiddleware` - Allows you define custom middleware to run before requesting sponsorship if there are any additional steps you need to take before requesting sponsorship. (default: noop)
5. `paymasterAndData` - Requests a gas sponsorship from a paymaster. (default: noop)
6. `userOperationSimulator` - Simulates a user operation to check if it will be successful. (default: noop)
79 changes: 79 additions & 0 deletions docs/pages/concepts/smart-account-client.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
---
title: Smart Account Client
description: What is the Smart Account Client?
---

# Smart Account Client

The [`SmartAccountClient`](#TODO/link-to-type) is an extension of `viem`'s [Client](https://viem.sh/docs/clients/custom#build-your-own-client) which allows you to interact
with [Smart Contract Accounts](/wallets/concepts/smart-contract-account). You can use the Smart Account Client to send User Operations, sign messages with your account, sponsor gas,
and other account-related actions.

The client is also EIP-1193 compliant, meaning it can easily be swapped out in place of other web3 providers (eg. `window.ethereum`).

## Account hoisting

<Tip>
If you're using the [React](/wallets/react/overview) or
[Core](/wallets/core/overview) packages, the Smart Account Clients already
handle hoisting and creation of account instances. The [Smart
Contracts](/wallets/smart-contracts/overview) package exports client
definitions for hoisted instances of the Smart Contract Accounts.
</Tip>

When creating a Smart Account Client, you have two options:

1. You can pass an account instance directly into the client constructor. Doing so will use that account for all of the actions you perform with the client, and you won't have to
pass in the account each time you call a method. This is known as **"account hoisting"**.
2. You can create a client without passing in an account. As a result, you'll have to pass in an account instance to each method you call on the client. This is really useful if you
want to manage multiple instances of an account in your app, and want to use one client for all of them.

Let's see an example:

```ts twoslash
import {
createAlchemySmartAccountClient,
sepolia,
alchemy,
} from "@account-kit/infra";
import { createLightAccount } from "@account-kit/smart-contracts";
import { LocalAccountSigner } from "@aa-sdk/core";
import { http } from "viem";
import { generatePrivateKey } from "viem/accounts";

// with account hoisting
const transport = alchemy({ apiKey: "your-api-key" });
const hoistedClient = createAlchemySmartAccountClient({
transport,
chain: sepolia,
account: await createLightAccount({
signer: LocalAccountSigner.privateKeyToAccountSigner(generatePrivateKey()),
chain: sepolia,
transport,
}),
});

const signature = await hoistedClient.signMessage({ message: "Hello world! " });

// without account hoisting
const nonHoistedClient = createAlchemySmartAccountClient({
transport,
chain: sepolia,
});

const lightAccount = await createLightAccount({
signer: LocalAccountSigner.privateKeyToAccountSigner(generatePrivateKey()),
chain: sepolia,
transport,
});

const signature2 = await nonHoistedClient.signMessage({
message: "Hello world! ",
account: lightAccount,
});
```

## Smart Account Client actions

Because the Smart Account Clients are extensions of viem's clients, they support extensions via the `.extend` method. The base client already includes a [number of actions](https://github.com/alchemyplatform/aa-sdk/tree/v4.x.x/aa-sdk/core/src/actions/smartAccount) by default.
You can find additional details about these actions in the [`@aa-sdk/core` documentation](/wallets/reference/aa-sdk/core).
Loading
Loading