@account-kit/wallet-client 0.1.0-alpha.1 → 0.1.0-alpha.2

package/src/client/actions/requestAccount.ts

@@ -1,7 +1,11 @@
-import type { SmartAccountSigner, SmartContractAccount } from "@aa-sdk/core";
+import {
+  type SmartAccountSigner,
+  type SmartContractAccount,
+} from "@aa-sdk/core";
 import type { Static } from "@sinclair/typebox";
 import { Value } from "@sinclair/typebox/value";
 import type { Address } from "abitype";
+import deepEqual from "deep-equal";
 import { custom, type IsUndefined, type JsonRpcAccount } from "viem";
 import { createAccount } from "../../isomorphic/utils/createAccount.js";
 import type { wallet_requestAccount } from "../../rpc/request.js";
@@ -20,12 +24,29 @@ export type RequestAccountParams<
           { signerAddress: Address }
         >,
         "signerAddress" | "includeCounterfactualInfo"
-      >
+      > & { accountAddress?: Address }
     : never;
 
 // TODO: this could be more specific potentially :shrug:
 export type RequestAccountResult = SmartContractAccount;
 
+/**
+ * Requests an account for the provided signer using the wallet API client.
+ * If an account already exists for the signer, it will always return that account unless a new ID is specified.
+ * If an account already exists, the creationHint will be ignored.
+ *
+ * @param {InnerWalletApiClient} client - The wallet API client to use for the request
+ * @param {SmartAccountSigner} signer - The signer that will be associated with the account
+ * @param {RequestAccountParams} [params] - Optional parameters for requesting a specific account
+ * @param {string} [params.id] - Optional identifier for the account. If specified, a new account with this ID will be created even if one already exists for the signer
+ * @param {object} [params.creationHint] - Optional hints to guide account creation. These are ignored if an account already exists
+ * @returns {Promise<RequestAccountResult>} A Promise that resolves to a SmartContractAccount instance
+ *
+ * @example
+ * // Request an account with default parameters using a local signer
+ * const signer = LocalAccountSigner.privateKeyToAccountSigner("0x...");
+ * const account = await client.requestAccount(signer);
+ */
 export function requestAccount<
   TAccount extends JsonRpcAccount<Address> | undefined =
     | JsonRpcAccount<Address>
@@ -42,9 +63,9 @@ export async function requestAccount(
   params?: RequestAccountParams,
 ): Promise<RequestAccountResult> {
   const args =
-    client.account && !params
+    (client.account && !params) || params?.accountAddress
       ? {
-          accountAddress: client.account.address,
+          accountAddress: params?.accountAddress ?? client.account!.address,
           includeCounterfactualInfo: true,
         }
       : {
@@ -53,12 +74,22 @@ export async function requestAccount(
           includeCounterfactualInfo: true,
         };
 
+  const cachedAccount = client.internal.getAccount();
+  if (
+    cachedAccount &&
+    ((args.accountAddress &&
+      cachedAccount.account.address === args.accountAddress) ||
+      deepEqual(cachedAccount.requestParams, args, { strict: true }))
+  ) {
+    return cachedAccount.account;
+  }
+
   const { counterfactualInfo, accountAddress } = await client.request({
     method: "wallet_requestAccount",
     params: [args],
   });
 
-  return createAccount({
+  const account = await createAccount({
     accountAddress: accountAddress,
     counterfactualInfo: Value.Parse(
       TypeSerializedInitcode,
@@ -68,4 +99,8 @@ export async function requestAccount(
     transport: custom(client.transport),
     signer,
   });
+
+  client.internal.setAccount({ account, requestParams: args });
+
+  return account;
 }

package/src/client/actions/sendPreparedCalls.ts

@@ -1,7 +1,7 @@
 import type { Static, StaticDecode } from "@sinclair/typebox";
 import { toHex } from "viem";
-import type { wallet_sendPreparedCalls } from "../../rpc/request";
-import type { InnerWalletApiClient } from "../../types";
+import type { wallet_sendPreparedCalls } from "../../rpc/request.ts";
+import type { InnerWalletApiClient } from "../../types.ts";
 
 export type SendPreparedCallsParams = Omit<
   StaticDecode<typeof wallet_sendPreparedCalls>["Request"]["params"][0],
@@ -12,6 +12,43 @@ export type SendPreparedCallsResult = Static<
   typeof wallet_sendPreparedCalls
 >["ReturnType"];
 
+/**
+ * Sends prepared calls by submitting a signed user operation.
+ * This method is used after signing the signature request returned from prepareCalls.
+ *
+ * @param {InnerWalletApiClient} client - The wallet API client to use for the request
+ * @param {SendPreparedCallsParams} params - Parameters for sending prepared calls
+ * @param {string} params.type - The user operation type ('user-operation-v060' or 'user-operation-v070')
+ * @param {object} params.data - The user operation data without signature
+ * @param {string} params.chainId - The chain ID in hex format
+ * @param {object} params.signature - The signature object
+ * @param {string} params.signature.type - The signature type (must be 'ecdsa')
+ * @param {string} params.signature.signature - The hex-encoded signature value
+ * @param {object} [params.capabilities] - Optional capabilities to include with the request
+ * @returns {Promise<SendPreparedCallsResult>} A Promise that resolves to the result containing the prepared call IDs
+ *
+ * @example
+ * // First prepare the calls
+ * const preparedCalls = await client.prepareCalls({
+ *   calls: [{
+ *     to: "0x1234...",
+ *     data: "0xabcdef...",
+ *     value: "0x0"
+ *   }],
+ *   capabilities: {
+ *     paymasterService: { policyId: "your-policy-id" }
+ *   }
+ * });
+ *
+ * // Sign the signature request using signSignatureRequest with your signer
+ * const signedRequest = await client.signSignatureRequest(preparedCalls.signatureRequest);
+ *
+ * // Then send the prepared calls with the signature
+ * const result = await client.sendPreparedCalls({
+ *   ...preparedCalls,
+ *   signature: signedRequest.signature,
+ * });
+ */
 export async function sendPreparedCalls(
   client: InnerWalletApiClient,
   params: SendPreparedCallsParams,

package/src/client/actions/signMessage.ts

@@ -5,13 +5,30 @@ import {
   type JsonRpcAccount,
   type SignableMessage,
 } from "viem";
-import type { InnerWalletApiClient } from "../../types";
+import type { InnerWalletApiClient } from "../../types.ts";
 import { requestAccount } from "./requestAccount.js";
 
-export type SignMessageParams = SignableMessage;
+export type SignMessageParams = { message: SignableMessage; account?: Address };
 
 export type SignMessageResult = Hex;
 
+/**
+ * Signs a message using the smart account.
+ * This method requests the account associated with the signer and uses it to sign the message.
+ *
+ * @param {InnerWalletApiClient} client - The wallet API client to use for the request
+ * @param {SmartAccountSigner} signer - The signer of the smart account
+ * @param {SignableMessage} message - The message to sign
+ * @returns {Promise<SignMessageResult>} A Promise that resolves to the signed message as a hex string
+ *
+ * @example
+ * // Sign a simple text message
+ * const signature = await client.signMessage("Hello, world!");
+ *
+ * @example
+ * // Sign a raw hex message
+ * const signature = await client.signMessage({ raw: "0x48656c6c6f2c20776f726c6421" });
+ */
 export async function signMessage<
   TAccount extends JsonRpcAccount<Address> | undefined =
     | JsonRpcAccount<Address>
@@ -27,6 +44,9 @@ export async function signMessage(
   signer: SmartAccountSigner,
   params: SignMessageParams,
 ): Promise<SignMessageResult> {
-  const account = await requestAccount(client, signer);
-  return account.signMessageWith6492({ message: params });
+  const account = await requestAccount(client, signer, {
+    accountAddress: params.account ?? client.account?.address,
+  });
+
+  return account.signMessageWith6492({ message: params.message });
 }

package/src/client/actions/signSignatureRequest.ts

@@ -11,6 +11,37 @@ export type SignSignatureRequestResult = {
   signature: Hex;
 };
 
+/**
+ * Signs a signature request using the provided signer.
+ * This method handles different types of signature requests including personal_sign and eth_signTypedData_v4.
+ *
+ * @param {SmartAccountSigner} signer - The signer to use for signing the request
+ * @param {SignSignatureRequestParams} params - The signature request parameters
+ * @param {string} params.type - The type of signature request ('personal_sign' or 'eth_signTypedData_v4')
+ * @param {any} params.data - The data to sign, format depends on the signature type
+ * @returns {Promise<SignSignatureRequestResult>} A Promise that resolves to the signature result
+ * @returns {string} result.type - The signature type (currently only 'ecdsa' is supported)
+ * @returns {Hex} result.signature - The hex-encoded signature
+ *
+ * @example
+ * // Sign a personal message
+ * const result = await client.signSignatureRequest({
+ *   type: 'personal_sign',
+ *   data: 'Hello, world!'
+ * });
+ *
+ * @example
+ * // Sign typed data (EIP-712)
+ * const result = await client.signSignatureRequest({
+ *   type: 'eth_signTypedData_v4',
+ *   data: {
+ *     domain: { ... },
+ *     types: { ... },
+ *     primaryType: '...',
+ *     message: { ... }
+ *   }
+ * });
+ */
 export function signSignatureRequest(
   signer: SmartAccountSigner,
   params: SignSignatureRequestParams,

package/src/client/actions/signTypedData.ts

@@ -5,13 +5,46 @@ import {
   type JsonRpcAccount,
   type TypedDataDefinition,
 } from "viem";
-import type { InnerWalletApiClient } from "../../types";
+import type { InnerWalletApiClient } from "../../types.ts";
 import { requestAccount } from "./requestAccount.js";
 
-export type SignTypedDataParams = TypedDataDefinition;
+export type SignTypedDataParams = TypedDataDefinition & {
+  account?: Address;
+};
 
 export type SignTypedDataResult = Hex;
 
+/**
+ * Signs typed data (EIP-712) using the smart account.
+ * This method requests the account associated with the signer and uses it to sign the typed data.
+ *
+ * @param {InnerWalletApiClient} client - The wallet API client to use for the request
+ * @param {SmartAccountSigner} signer - The signer of the smart account
+ * @param {TypedDataDefinition} params - The typed data to sign, following EIP-712 format
+ * @returns {Promise<SignTypedDataResult>} A Promise that resolves to the signature as a hex string
+ *
+ * @example
+ * // Sign typed data
+ * const signature = await client.signTypedData({
+ *   domain: {
+ *     name: 'Example DApp',
+ *     version: '1',
+ *     chainId: 1,
+ *     verifyingContract: '0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC'
+ *   },
+ *   types: {
+ *     Person: [
+ *       { name: 'name', type: 'string' },
+ *       { name: 'wallet', type: 'address' }
+ *     ]
+ *   },
+ *   primaryType: 'Person',
+ *   message: {
+ *     name: 'John Doe',
+ *     wallet: '0xAaAaAaAaAaAaAaAaAaAAAAAAAAaaaAaAaAaaAaAa'
+ *   }
+ * });
+ */
 export async function signTypedData<
   TAccount extends JsonRpcAccount<Address> | undefined =
     | JsonRpcAccount<Address>
@@ -27,6 +60,9 @@ export async function signTypedData(
   signer: SmartAccountSigner,
   params: SignTypedDataParams,
 ): Promise<SignTypedDataResult> {
-  const account = await requestAccount(client, signer);
+  const account = await requestAccount(client, signer, {
+    accountAddress: params.account ?? client.account?.address,
+  });
+
   return account.signTypedDataWith6492(params);
 }

package/src/client/client.e2e-test.ts

@@ -32,6 +32,27 @@ describe("Client E2E Tests", () => {
       transport,
     });
 
+    it("should successfully request account with different salt", async () => {
+      const account = await client.requestAccount({
+        id: "2d00c64e-2e55-4925-832e-e288dbf1139e",
+        creationHint: { salt: "0x1" },
+      });
+
+      expect(account.address).toMatchInlineSnapshot(
+        `"0x569bCECaC47Ef9706c4b2370f2891bccd4cdE30c"`,
+      );
+    });
+
+    it("should not cache account if different inputs provided", async () => {
+      const account = await client.requestAccount();
+      const account2 = await client.requestAccount({
+        id: "2d00c64e-2e55-4925-832e-e288dbf1139e",
+        creationHint: { salt: "0x1" },
+      });
+
+      expect(account.address).not.toEqual(account2.address);
+    });
+
     it("should successfully get a counterfactual address", async () => {
       const account = await client.requestAccount();
       expect(account.address).toMatchInlineSnapshot(
@@ -42,14 +63,10 @@ describe("Client E2E Tests", () => {
     it("can correctly sign a message", async () => {
       const account = await client.requestAccount();
       const message = "hello world";
-      const signature = await client.signMessage(message);
-      const publicClient = createPublicClient({
-        chain: arbitrumSepolia,
-        transport,
-      });
+      const signature = await client.signMessage({ message });
       const isValid = await publicClient.verifyMessage({
         address: account.address,
-        message: "hello world",
+        message,
         signature,
       });
       expect(isValid).toBeTrue();
@@ -66,6 +83,43 @@ describe("Client E2E Tests", () => {
       expect(isValid).toBeTrue();
     });
 
+    it("can correctly sign a message with a different account", async () => {
+      const account = await client.requestAccount({
+        id: "2d00c64e-2e55-4925-832e-e288dbf1139e",
+        creationHint: { salt: "0x1" },
+      });
+      const message = "hello world";
+
+      const signature = await client.signMessage({
+        message,
+        account: account.address,
+      });
+      const isValid = await publicClient.verifyMessage({
+        address: account.address,
+        message,
+        signature,
+      });
+      expect(isValid).toBeTrue();
+    });
+
+    it("can correctly sign typed data with a different account", async () => {
+      const account = await client.requestAccount({
+        id: "2d00c64e-2e55-4925-832e-e288dbf1139e",
+        creationHint: { salt: "0x1" },
+      });
+
+      const signature = await client.signTypedData({
+        ...givenTypedData,
+        account: account.address,
+      });
+      const isValid = await publicClient.verifyTypedData({
+        ...givenTypedData,
+        signature,
+        address: account.address,
+      });
+      expect(isValid).toBeTrue();
+    });
+
     it("should successfully send a UO with paymaster", async () => {
       const account = await client.requestAccount();
       const preparedUO = await client.prepareCalls({
@@ -164,14 +218,31 @@ describe("Client E2E Tests", () => {
       );
     });
 
+    it("should successfully request account with different salt", async () => {
+      const account = await client.requestAccount({
+        id: "8670d2d8-2781-49e9-a75c-1eb980271ca9",
+        creationHint: { salt: "0x1" },
+      });
+
+      expect(account.address).toMatchInlineSnapshot(
+        `"0xC9B8271E44f14be83CecfDE1dDb325e9fa15e9Ff"`,
+      );
+    });
+
+    it("should not cache account if different inputs provided", async () => {
+      const account = await client.requestAccount();
+      const account2 = await client.requestAccount({
+        id: "8670d2d8-2781-49e9-a75c-1eb980271ca9",
+        creationHint: { salt: "0x1" },
+      });
+
+      expect(account.address).not.toEqual(account2.address);
+    });
+
     it("can correctly sign a message", async () => {
       const account = await client.requestAccount();
       const message = "hello world";
-      const signature = await client.signMessage(message);
-      const publicClient = createPublicClient({
-        chain: arbitrumSepolia,
-        transport,
-      });
+      const signature = await client.signMessage({ message });
       const isValid = await publicClient.verifyMessage({
         address: account.address,
         message: "hello world",
@@ -191,6 +262,44 @@ describe("Client E2E Tests", () => {
       expect(isValid).toBeTrue();
     });
 
+    it("can correctly sign a message with a different account", async () => {
+      const account = await client.requestAccount({
+        id: "8670d2d8-2781-49e9-a75c-1eb980271ca9",
+        creationHint: { salt: "0x1" },
+      });
+
+      const message = "hello world";
+      const signature = await client.signMessage({
+        message,
+        account: account.address,
+      });
+      const isValid = await publicClient.verifyMessage({
+        address: account.address,
+        message: "hello world",
+        signature,
+      });
+      expect(isValid).toBeTrue();
+    });
+
+    it("can correctly sign typed data with a different account", async () => {
+      const account = await client.requestAccount({
+        id: "8670d2d8-2781-49e9-a75c-1eb980271ca9",
+        creationHint: { salt: "0x1" },
+      });
+
+      const signature = await client.signTypedData({
+        ...givenTypedData,
+        account: account.address,
+      });
+
+      const isValid = await publicClient.verifyTypedData({
+        ...givenTypedData,
+        signature,
+        address: account.address,
+      });
+      expect(isValid).toBeTrue();
+    });
+
     it("should successfully send a UO with paymaster", async () => {
       const account = await client.requestAccount();
       const preparedUO = await client.prepareCalls({

package/src/client/decorator.ts

@@ -1,15 +1,10 @@
 import type { SmartAccountSigner } from "@aa-sdk/core";
-import type {
-  Hex,
-  JsonRpcAccount,
-  SignableMessage,
-  TypedDataDefinition,
-} from "viem";
+import type { Hex, JsonRpcAccount } from "viem";
 import type {
   SendPreparedCallsParams,
   SendPreparedCallsResult,
-} from "../isomorphic/actions/sendPreparedCalls";
-import type { InnerWalletApiClient } from "../types";
+} from "../isomorphic/actions/sendPreparedCalls.ts";
+import type { InnerWalletApiClient } from "../types.ts";
 import {
   createAccount,
   type CreateAccountParams,
@@ -41,13 +36,16 @@ import {
   type RequestAccountResult,
 } from "./actions/requestAccount.js";
 import { sendPreparedCalls } from "./actions/sendPreparedCalls.js";
-import { signMessage } from "./actions/signMessage.js";
+import { signMessage, type SignMessageParams } from "./actions/signMessage.js";
 import {
   signSignatureRequest,
   type SignSignatureRequestParams,
   type SignSignatureRequestResult,
 } from "./actions/signSignatureRequest.js";
-import { signTypedData } from "./actions/signTypedData.js";
+import {
+  signTypedData,
+  type SignTypedDataParams,
+} from "./actions/signTypedData.js";
 
 export type SmartWalletActions<
   TAccount extends JsonRpcAccount | undefined = JsonRpcAccount | undefined,
@@ -69,8 +67,8 @@ export type SmartWalletActions<
   signSignatureRequest: (
     params: SignSignatureRequestParams,
   ) => Promise<SignSignatureRequestResult>;
-  signMessage: (params: SignableMessage) => Promise<Hex>;
-  signTypedData: (params: TypedDataDefinition) => Promise<Hex>;
+  signMessage: (params: SignMessageParams) => Promise<Hex>;
+  signTypedData: (params: SignTypedDataParams) => Promise<Hex>;
   grantPermissions: (
     params: GrantPermissionsParams<TAccount>,
   ) => Promise<GrantPermissionsResult>;

package/src/client/index.ts

@@ -1,19 +1,19 @@
-import { type SmartAccountSigner } from "@aa-sdk/core";
-import { type AlchemyTransport } from "@account-kit/infra";
-import {
-  type Address,
-  type Chain,
-  type IsUndefined,
-  type JsonRpcAccount,
-  type Prettify,
+import type { SmartAccountSigner } from "@aa-sdk/core";
+import type {
+  Address,
+  Chain,
+  IsUndefined,
+  JsonRpcAccount,
+  Prettify,
 } from "viem";
 import { createLocalClient } from "../local/client.js";
 import { createRemoteClient } from "../remote/client.js";
-import type { InnerWalletApiClient } from "../types";
+import type { InnerWalletApiClient } from "../types.ts";
 import {
   smartWalletClientActions,
   type SmartWalletActions,
 } from "./decorator.js";
+import type { AlchemyTransport } from "@account-kit/infra";
 
 export type SmartWalletClientParams<
   TAccount extends JsonRpcAccount<Address> | undefined =
@@ -49,7 +49,38 @@ export function createSmartWalletClient<
   params: SmartWalletClientParams<TAccount>,
 ): InnerWalletApiClient<TAccount> & SmartWalletActions<TAccount>;
 
-export function createSmartWalletClient(params: SmartWalletClientParams) {
+/**
+ * Creates a smart wallet client that can be used to interact with a smart account.
+ *
+ * @param {SmartWalletClientParams} params - The parameters for creating the smart wallet client
+ * @param {AlchemyTransport} params.transport - The Alchemy transport to use
+ * @param {Chain} params.chain - The chain to use
+ * @param {SmartAccountSigner} params.signer - The signer to use for the smart account
+ * @param {"local" | "remote"} params.mode - The client's mode (local or remote).
+ * @param {string} [params.policyId] - The policy ID for gas sponsorship (optional)
+ * @param {Address} [params.account] - The smart account address to use (optional)
+ * @returns {InnerWalletApiClient & SmartWalletActions} - A viem-compatible client
+ *
+ * @example
+ * import { LocalAccountSigner } from "@aa-sdk/core";
+ * import { alchemy, arbitrumSepolia } from "@account-kit/infra";
+ * import { generatePrivateKey } from "viem/accounts";
+ * import { createSmartWalletClient } from "@account-kit/wallet-apis"; // TODO(jh): update this if we change the pkg name to `@account-kit/wallet-client`
+ *
+ * const signer = LocalAccountSigner.privateKeyToAccountSigner(generatePrivateKey());
+ * const transport = alchemy({
+ *   apiKey: "your-alchemy-api-key",
+ * });
+ * const client = createSmartWalletClient({
+ *   transport,
+ *   chain: arbitrumSepolia,
+ *   mode: "remote",
+ *   signer,
+ * });
+ */
+export function createSmartWalletClient(
+  params: SmartWalletClientParams,
+): InnerWalletApiClient & SmartWalletActions {
   const { transport, chain, policyId, mode, account, signer } = params;
 
   const innerClient =

package/src/exports/index.ts

@@ -30,3 +30,4 @@ export { requestAccount } from "../client/actions/requestAccount.js";
 export { signMessage } from "../client/actions/signMessage.js";
 export { signSignatureRequest } from "../client/actions/signSignatureRequest.js";
 export { signTypedData } from "../client/actions/signTypedData.js";
+export { grantPermissions } from "../client/actions/grantPermissions.js";

package/src/exports/internal.ts

@@ -12,5 +12,5 @@ export * from "../rpc/request.js";
 export * as RpcSchemas from "../rpc/request.js";
 export * from "../rpc/schema.js";
 export * from "../schemas.js";
-export type * from "../types";
+export type * from "../types.ts";
 export * from "../utils.js";

package/src/internal/decorator.ts

@@ -0,0 +1,12 @@
+import type { CachedAccount, InternalState } from "../types.ts";
+
+export function internalStateDecorator(): InternalState {
+  let account: CachedAccount | undefined = undefined;
+
+  return {
+    setAccount: (newAccount: CachedAccount) => {
+      account = newAccount;
+    },
+    getAccount: () => account,
+  };
+}