docs: add readme to alchemy packages for npm (#240)

* docs: add readme to alchemy packages for npm * Update site/snippets/ethers-provider.ts Co-authored-by: Ajay Vasisht <[email protected]> * Update site/snippets/ethers-signer.ts Co-authored-by: Ajay Vasisht <[email protected]> * Update packages/ethers/README.md Co-authored-by: Ajay Vasisht <[email protected]> * Update packages/ethers/README.md Co-authored-by: Ajay Vasisht <[email protected]> --------- Co-authored-by: Ajay Vasisht <[email protected]>
alchemyplatform · Nov 13, 2023 · 32bfe92 · 32bfe92
1 parent d637c28
commit 32bfe92
Show file tree

Hide file tree

Showing 10 changed files with 190 additions and 10 deletions.
diff --git a/packages/accounts/README.md b/packages/accounts/README.md
@@ -1,10 +1,10 @@
 # `@alchemy/aa-accounts`
 
-This package contains various implementations of the [`BaseSmartContractAccount`](../core/src/account/base.ts) class defined in `aa-core`. This repo is community maintained and we welcome contributions!
+This package contains various implementations of the [`BaseSmartContractAccount`](https://accountkit.alchemy.com/packages/aa-core/accounts/introduction.html#basesmartcontractaccount) class defined in `aa-core`. This repo is community maintained and we welcome contributions!
 
 ## Getting started
 
-If you are already using the `@alchemy/aa-core` package, you can simply install this package and start using the accounts. If you are not using `@alchemy/aa-core`, you can install it and follow the instructions in the [README](../../README.md) to get started.
+If you are already using the `@alchemy/aa-core` package, you can simply install this package and start using the accounts. If you are not using `@alchemy/aa-core`, you can install it and follow the instructions in the [Getting Started](https://accountkit.alchemy.com/packages/aa-accounts/) docs to get started.
 
 via `yarn`
 
@@ -18,6 +18,12 @@ via `npm`
 npm i -s @alchemy/aa-accounts
 ```
 
+via `pnpm`
+
+```bash
+pnpm i @alchemy/aa-accounts
+```
+
 ## Contributing
 
 If you are looking to add a new account type, please follow the following structure.
@@ -30,7 +36,7 @@ If you are looking to add a new account type, please follow the following struct
 export const MyContractAbi = [] as const; // the as const is important so we can get correct typing from viem
 ```
 
-4. If you need to extend the [`SmartAccountProvider`](../core/src/provider/base.ts) class, add a file called `provider.ts` and add your implementation for `SmartAccountProvider`.
+4. If you need to extend the [`SmartAccountProvider`](https://accountkit.alchemy.com/packages/aa-core/provider/introduction.html) class, add a file called `provider.ts` and add your implementation for `SmartAccountProvider`.
 
 - Ideally, your `Account` impl should _just_ work with the base provider provided by `aa-core`.
 - If not, consider generalizing the use case and updating SmartAccountProvider

diff --git a/packages/alchemy/README.md b/packages/alchemy/README.md
@@ -0,0 +1,51 @@
+# `@alchemy/aa-alchemy`
+
+This package contains `AlchemyProvider`, an implementation of `SmartAccountProvider` class defined in `aa-core`. It also contains middleware for accessing the Alchemy Gas Manager (an [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) Paymaster) and for doing Fee Estimates according to the expectations of the Alchemy [Rundler](https://github.com/alchemyplatform/rundler/tree/main) (an ERC-4337 Bundler). You may also find the util methods helpful. This repo is community maintained and we welcome contributions!
+
+## Getting started
+
+If you are already using the `@alchemy/aa-core` package, you can simply install this package and start using the `AlchemyProvider`. If you are not using `@alchemy/aa-core`, you can install it and follow the instructions in the ["Getting Started"](https://accountkit.alchemy.com/packages/aa-alchemy/) docs to get started.
+
+```bash [yarn]
+yarn add @alchemy/aa-alchemy
+```
+
+```bash [npm]
+npm i -s @alchemy/aa-alchemy
+```
+
+```bash [pnpm]
+pnpm i @alchemy/aa-alchemy
+```
+
+## Usage
+
+You can create `AlchemyProvider` like so:
+
+```typescript
+import {
+  LightSmartContractAccount,
+  getDefaultLightAccountFactoryAddress,
+} from "@alchemy/aa-accounts";
+import { AlchemyProvider } from "@alchemy/aa-alchemy";
+import { LocalAccountSigner, type SmartAccountSigner } from "@alchemy/aa-core";
+import { sepolia } from "viem/chains";
+
+const chain = sepolia;
+const PRIVATE_KEY = "0xYourEOAPrivateKey";
+const eoaSigner: SmartAccountSigner =
+  LocalAccountSigner.privateKeyToAccountSigner(`0x${PRIVATE_KEY}`);
+
+export const provider = new AlchemyProvider({
+  apiKey: "ALCHEMY_API_KEY", // replace with your alchemy api key of the Alchemy app associated with the Gas Manager, get yours at https://dashboard.alchemy.com/
+  chain,
+}).connect(
+  (rpcClient) =>
+    new LightSmartContractAccount({
+      chain,
+      owner: eoaSigner,
+      factoryAddress: getDefaultLightAccountFactoryAddress(chain),
+      rpcClient,
+    })
+);
+```
diff --git a/packages/core/README.md b/packages/core/README.md
@@ -0,0 +1,57 @@
+# `@alchemy/aa-core`
+
+This package contains the core interfaces and components for interacting with 4337 infrastructure. The primary interfaces that it exports are the `SmartAccountProvider` and `BaseSmartContractAccount`.
+
+The `SmartAccountProvider` is an [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) compliant Provider that wraps JSON RPC methods and some Wallet Methods (signing, sendTransaction, etc). With this Provider, you can submit User Operations to RPC providers, estimate gas, configure a Paymaster, send standard JSON RPC requests, and more. It is not opinionated about which RPC provider you are using and is configurable to work with any RPC provider. Because it implements EIP-1193, it can be used with any web3 library.
+
+The `BaseSmartContractAccount` interface defines how you would interact with your Smart Contract Account. Any class that extends `BaseSmartContractAccount` may also expose additional methods that allow its connecting `SmartAccountProvider` to provide ergonic utilities for building and submitting `User Operation`s.
+
+## Getting Started
+
+To get started, first install the package:
+
+```bash [yarn]
+yarn add @alchemy/aa-core
+```
+
+```bash [npm]
+npm i -s @alchemy/aa-core
+```
+
+```bash [pnpm]
+pnpm i @alchemy/aa-core
+```
+
+## Usage
+
+You can create a provider like so:
+
+```typescript
+import {
+  LightSmartContractAccount,
+  getDefaultLightAccountFactoryAddress,
+} from "@alchemy/aa-accounts";
+import {
+  LocalAccountSigner,
+  SmartAccountProvider,
+  SmartAccountSigner,
+} from "@alchemy/aa-core";
+import { polygonMumbai } from "viem/chains";
+
+const chain = polygonMumbai;
+const owner: SmartAccountSigner =
+  LocalAccountSigner.mnemonicToAccountSigner(YOUR_OWNER_MNEMONIC);
+
+export const provider = new SmartAccountProvider({
+  rpcProvider: "https://polygon-mumbai.g.alchemy.com/v2/demo",
+  chain,
+}).connect(
+  (rpcClient) =>
+    new LightSmartContractAccount({
+      chain,
+      factoryAddress: getDefaultLightAccountFactoryAddress(chain),
+      rpcClient,
+      owner,
+    })
+);
+```
diff --git a/packages/ethers/README.md b/packages/ethers/README.md
@@ -0,0 +1,64 @@
+# `@alchemy/aa-ethers`
+
+This package contains `EthersProviderAdapter` and `AccountSigner`, respective extensions of the [`JsonRpcProvider`](https://docs.ethers.org/v5/api/providers/jsonrpc-provider/) and [`Signer`](https://docs.ethers.org/v5/api/signer/#Signer-getaddress) classes defined in [`ethers.js`](https://docs.ethers.org/v5/) external library.
+
+If you currently rely `ethers.js` for web3 development, you can use these `ethers.js`-compatible `JsonRpcProvider` and `Signer` to integrate Account Abstraction into your dApp. You may also find the [`util`](https://accountkit.alchemy.com/packages/aa-ethers/utils/introduction.html) methods helpful.
+
+This repo is community maintained and we welcome contributions!
+
+## Getting started
+
+If you are already using the `@alchemy/aa-core` package, you can simply install this package and start using the `EthersProviderAdapter` and `AccountSigner`. If you are not using `@alchemy/aa-core`, you can install it and follow the instructions in the ["Getting Started"](https://accountkit.alchemy.com/packages/aa-ethers/) docs to get started.
+
+```bash [yarn]
+yarn add @alchemy/aa-ethers
+```
+
+```bash [npm]
+npm i -s @alchemy/aa-ethers
+```
+
+```bash [pnpm]
+pnpm i @alchemy/aa-ethers
+```
+
+## Usage
+
+You can create a provider and connect it to a signer account like so:
+
+```typescript ethers-provider.ts
+import {
+  LightSmartContractAccount,
+  getDefaultLightAccountFactoryAddress,
+} from "@alchemy/aa-accounts";
+import { EthersProviderAdapter } from "@alchemy/aa-ethers";
+import { LocalAccountSigner, SmartAccountSigner } from "@alchemy/aa-core";
+import { Alchemy, Network } from "alchemy-sdk";
+import { polygonMumbai } from "viem/chains";
+
+const chain = polygonMumbai;
+
+// 1. Create a provider using EthersProviderAdapter
+const alchemy = new Alchemy({
+  apiKey: process.env.API_KEY!,
+  network: Network.MATIC_MUMBAI,
+});
+const ethersProvider = await alchemy.config.getProvider();
+
+const provider = EthersProviderAdapter.fromEthersProvider(ethersProvider);
+
+const owner: SmartAccountSigner = LocalAccountSigner.mnemonicToAccountSigner(
+  process.env.YOUR_OWNER_MNEMONIC!
+);
+
+// 2. Connect the provider to the smart account signer
+export const signer = provider.connectToAccount(
+  (rpcClient) =>
+    new LightSmartContractAccount({
+      chain,
+      factoryAddress: getDefaultLightAccountFactoryAddress(chain),
+      rpcClient,
+      owner,
+    })
+);
+```
diff --git a/site/packages/aa-accounts/index.md b/site/packages/aa-accounts/index.md
@@ -32,7 +32,7 @@ yarn add @alchemy/aa-accounts
 ```
 
 ```bash [npm]
-npm i @alchemy/aa-accounts
+npm i -s @alchemy/aa-accounts
 ```
 
 ```bash [pnpm]

diff --git a/site/packages/aa-alchemy/index.md b/site/packages/aa-alchemy/index.md
@@ -19,7 +19,7 @@ next:
 
 # `@alchemy/aa-alchemy`
 
-This package contains `AlchemyProvider`, an implementation of `SmartAccountProvider` class defined in `aa-core`. It also contains middleware for accessing the Alchemy Gas Manager (an [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) Paymaster) and for doing Fee Estimates according to the expectations of the Alchemy Rundler (an ERC-4337 Bundler). You may also find the util methods helpful. This repo is community maintained and we welcome contributions!
+This package contains `AlchemyProvider`, an implementation of `SmartAccountProvider` class defined in `aa-core`. It also contains middleware for accessing the Alchemy Gas Manager (an [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) Paymaster) and for doing Fee Estimates according to the expectations of the Alchemy [Rundler](https://github.com/alchemyplatform/rundler/tree/main) (an ERC-4337 Bundler). You may also find the util methods helpful. This repo is community maintained and we welcome contributions!
 
 ## Getting started
 
@@ -32,7 +32,7 @@ yarn add @alchemy/aa-alchemy
 ```
 
 ```bash [npm]
-npm i @alchemy/aa-alchemy
+npm i -s @alchemy/aa-alchemy
 ```
 
 ```bash [pnpm]

diff --git a/site/packages/aa-core/index.md b/site/packages/aa-core/index.md
@@ -20,7 +20,7 @@ This package contains the core interfaces and components for interacting with 43
 
 The `SmartAccountProvider` is an [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193) compliant Provider that wraps JSON RPC methods and some Wallet Methods (signing, sendTransaction, etc). With this Provider, you can submit User Operations to RPC providers, estimate gas, configure a Paymaster, send standard JSON RPC requests, and more. It is not opinionated about which RPC provider you are using and is configurable to work with any RPC provider. Because it implements EIP-1193, it can be used with any web3 library.
 
-The `BaseSmartContractAccount` interface defines how you would interact with your Smart Contract Account. Any class that extends `BaseSmartContractAccount` may also expose additional methods that allow its connecting `SmartAccountProvider` to provide ergonic utilities for building and submitting User Operations.
+The `BaseSmartContractAccount` interface defines how you would interact with your Smart Contract Account. Any class that extends `BaseSmartContractAccount` may also expose additional methods that allow its connecting `SmartAccountProvider` to provide ergonic utilities for building and submitting `User Operation`s.
 
 ## Getting Started
 
@@ -33,7 +33,7 @@ yarn add @alchemy/aa-core
 ```
 
 ```bash [npm]
-npm i @alchemy/aa-core
+npm i -s @alchemy/aa-core
 ```
 
 ```bash [pnpm]

diff --git a/site/packages/aa-ethers/index.md b/site/packages/aa-ethers/index.md
@@ -19,7 +19,7 @@ next:
 
 # `@alchemy/aa-ethers`
 
-This package contains `EthersProviderAdapter` and `AccountSigner`, respective extensions of the `JsonRpcProvider` and `Signer` classes defined in `ethers.js` external library.
+This package contains `EthersProviderAdapter` and `AccountSigner`, respective extensions of the [`JsonRpcProvider`](https://docs.ethers.org/v5/api/providers/jsonrpc-provider/) and [`Signer`](https://docs.ethers.org/v5/api/signer/#Signer-getaddress) classes defined in [`ethers.js`](https://docs.ethers.org/v5/) external library.
 
 If you currently rely `ethers.js` for web3 development, you can use these `ethers.js`-compatible `JsonRpcProvider` and `Signer` to integrate Account Abstraction into your dApp. You may also find the [`util`](./utils/introduction.md) methods helpful.
 
@@ -36,7 +36,7 @@ yarn add @alchemy/aa-ethers
 ```
 
 ```bash [npm]
-npm i @alchemy/aa-ethers
+npm i -s @alchemy/aa-ethers
 ```
 
 ```bash [pnpm]

diff --git a/site/snippets/ethers-provider.ts b/site/snippets/ethers-provider.ts
@@ -1,6 +1,7 @@
 import { EthersProviderAdapter } from "@alchemy/aa-ethers";
 import { Alchemy, Network } from "alchemy-sdk";
 
+// 1. Create a provider using EthersProviderAdapter
 const alchemy = new Alchemy({
   apiKey: process.env.API_KEY!,
   network: Network.MATIC_MUMBAI,

diff --git a/site/snippets/ethers-signer.ts b/site/snippets/ethers-signer.ts
@@ -12,6 +12,7 @@ const owner: SmartAccountSigner = LocalAccountSigner.mnemonicToAccountSigner(
 
 const chain = polygonMumbai;
 
+// 2. Connect the provider to the smart account signer
 export const signer = provider.connectToAccount(
   (rpcClient) =>
     new LightSmartContractAccount({