@alchemy/wallet-apis 0.0.0-alpha.12

package/src/actions/grantPermissions.ts

@@ -0,0 +1,125 @@
+import {
+  toHex,
+  type Address,
+  type Hex,
+  type IsUndefined,
+  type Prettify,
+  concatHex,
+} from "viem";
+import type { InnerWalletApiClient } from "../types.ts";
+import type { WalletServerRpcSchemaType } from "@alchemy/wallet-api-types/rpc";
+import { signSignatureRequest } from "./signSignatureRequest.js";
+import { AccountNotFoundError } from "@alchemy/common";
+import { LOGGER } from "../logger.js";
+import type { OptionalChainId } from "../types.ts";
+
+type RpcSchema = Extract<
+  WalletServerRpcSchemaType,
+  {
+    Request: {
+      method: "wallet_createSession";
+    };
+  }
+>;
+
+export type GrantPermissionsParams<
+  TAccount extends Address | undefined = Address | undefined,
+> = Prettify<
+  OptionalChainId<Omit<RpcSchema["Request"]["params"][0], "account">> &
+    (IsUndefined<TAccount> extends true
+      ? { account: Address }
+      : { account?: never })
+>;
+
+export type GrantPermissionsResult = Prettify<{
+  context: Hex;
+}>;
+
+/**
+ * Grants permissions to a smart account by creating a session.
+ * This allows another key to perform operations on behalf of the account.
+ *
+ * @param {InnerWalletApiClient} client - The wallet API client to use for the request
+ * @param {GrantPermissionsParams} params - The parameters for granting permissions
+ * @param {Address} [params.account] - The account address (required if client was not initialized with an account)
+ * @param {number} params.expirySec - Unix timestamp when the permissions expire
+ * @param {sessionKeyData} params.key - The session key information
+ * @param {string} params.key.publicKey - The public key of the session key
+ * @param {string} params.key.type - The type of the key (e.g., "secp256k1")
+ * @param {Array} params.permissions - Array of permission objects defining what the session key can do
+ * @returns {Promise<GrantPermissionsResult>} A Promise that resolves to the result containing a context identifier
+ *
+ * @example
+ * ```ts
+ * // Create a session key and grant root permissions
+ * const sessionKey = LocalAccountSigner.generatePrivateKeySigner();
+ * const account = await client.requestAccount();
+ *
+ * const permissions = await client.grantPermissions({
+ *   account: account.address,
+ *   expirySec: Math.floor(Date.now() / 1000) + 60 * 60, // 1 hour from now
+ *   key: {
+ *     publicKey: await sessionKey.getAddress(),
+ *     type: "secp256k1",
+ *   },
+ *   permissions: [{ type: "root" }],
+ * });
+ *
+ * // Use the permissions to prepare a call
+ * const preparedCalls = await client.prepareCalls({
+ *   calls: [{ to: zeroAddress, value: "0x0" }],
+ *   from: account.address,
+ *   capabilities: {
+ *     paymasterService: {
+ *       policyId: "your-paymaster-policy-id",
+ *     },
+ *     permissions,
+ *   },
+ * });
+ *
+ * // Sign with the session key
+ * const signedCalls = await signPreparedCalls(sessionKey, preparedCalls);
+ *
+ * // Send the prepared call using the session key
+ * const result = await client.sendPreparedCalls({
+ *   ...signedCalls,
+ *   capabilities: {
+ *     permissions,
+ *   },
+ * });
+ * ```
+ */
+export async function grantPermissions<
+  TAccount extends Address | undefined = Address | undefined,
+>(
+  client: InnerWalletApiClient,
+  params: GrantPermissionsParams<TAccount>,
+): Promise<GrantPermissionsResult> {
+  const account = params.account ?? client.account?.address;
+  if (!account) {
+    LOGGER.warn("grantPermissions:no-account");
+    throw new AccountNotFoundError();
+  }
+  LOGGER.debug("grantPermissions:start", { expirySec: params.expirySec });
+  const { sessionId, signatureRequest } = await client.request({
+    method: "wallet_createSession",
+    params: [
+      {
+        ...params,
+        account,
+        chainId: params.chainId ?? toHex(client.chain.id),
+      },
+    ],
+  });
+
+  const signature = await signSignatureRequest(client, signatureRequest);
+  const res = {
+    context: concatHex([
+      "0x00", // Remote mode.
+      sessionId,
+      signature.data,
+    ]),
+  } as const;
+  LOGGER.debug("grantPermissions:done");
+  return res;
+}

package/src/actions/listAccounts.ts

@@ -0,0 +1,66 @@
+import type { InnerWalletApiClient } from "../types.ts";
+import { LOGGER } from "../logger.js";
+import type { Address, Prettify } from "viem";
+import type { WalletServerRpcSchemaType } from "@alchemy/wallet-api-types/rpc";
+
+type RpcSchema = Extract<
+  WalletServerRpcSchemaType,
+  {
+    Request: {
+      method: "wallet_listAccounts";
+    };
+  }
+>;
+
+export type ListAccountsParams = Prettify<
+  Omit<RpcSchema["Request"]["params"][0], "signerAddress"> & {
+    signerAddress?: Address;
+  }
+>;
+
+export type ListAccountsResult = Prettify<RpcSchema["ReturnType"]>;
+
+/**
+ * Lists all smart accounts for a given signer using the wallet API client.
+ *
+ * @param {InnerWalletApiClient} client - The wallet API client to use for the request
+ * @param {ListAccountsParams} params - Parameters for listing accounts
+ * @param {string} params.signerAddress - The address of the signer to list accounts for
+ * @param {number} [params.limit] - Optional maximum number of accounts to return (default: 100, max: 100)
+ * @param {string} [params.after] - Optional pagination cursor for fetching subsequent pages
+ * @returns {Promise<ListAccountsResult>} A Promise that resolves to the list of accounts and pagination metadata
+ *
+ * @example
+ * ```ts
+ * // Fetch the first page of accounts
+ * const firstPage = await client.listAccounts({
+ *   signerAddress: "0x123...",
+ *   limit: 10
+ * });
+ *
+ * // If an 'after' cursor exists, use it to fetch the next page
+ * const nextPage = await client.listAccounts({
+ *   signerAddress: "0x123...",
+ *   limit: 10,
+ *   after: firstPage.meta.after
+ * });
+ * ```
+ */
+export async function listAccounts(
+  client: InnerWalletApiClient,
+  params: ListAccountsParams,
+): Promise<ListAccountsResult> {
+  const signerAddress = params.signerAddress ?? client.owner.account.address;
+  LOGGER.debug("listAccounts:start", { hasAfter: !!params.after });
+  const res = await client.request({
+    method: "wallet_listAccounts",
+    params: [
+      {
+        ...params,
+        signerAddress,
+      },
+    ],
+  });
+  LOGGER.debug("listAccounts:done", { count: res.accounts.length });
+  return res;
+}

package/src/actions/prepareCalls.ts

@@ -0,0 +1,85 @@
+import { toHex, type Address, type IsUndefined, type Prettify } from "viem";
+import type { InnerWalletApiClient, OptionalChainId } from "../types.ts";
+import { AccountNotFoundError } from "@alchemy/common";
+import { LOGGER } from "../logger.js";
+import { mergeClientCapabilities } from "../utils/capabilities.js";
+import type { WalletServerRpcSchemaType } from "@alchemy/wallet-api-types/rpc";
+
+type RpcSchema = Extract<
+  WalletServerRpcSchemaType,
+  {
+    Request: {
+      method: "wallet_prepareCalls";
+    };
+  }
+>;
+
+export type PrepareCallsParams<
+  TAccount extends Address | undefined = Address | undefined,
+> = Prettify<
+  OptionalChainId<Omit<RpcSchema["Request"]["params"][0], "from">> &
+    (IsUndefined<TAccount> extends true ? { from: Address } : { from?: never })
+>;
+
+export type PrepareCallsResult = Prettify<RpcSchema["ReturnType"]>;
+
+/**
+ * Prepares a set of contract calls for execution by building a user operation.
+ * Returns the built user operation and a signature request that needs to be signed
+ * before submitting to sendPreparedCalls.
+ *
+ * @param {InnerWalletApiClient<TAccount>} client - The wallet API client to use for the request
+ * @param {PrepareCallsParams<TAccount>} params - Parameters for preparing calls
+ * @param {Array<{to: Address, data?: Hex, value?: Hex}>} params.calls - Array of contract calls to execute
+ * @param {Address} [params.from] - The address to execute the calls from (required if the client wasn't initialized with an account)
+ * @param {object} [params.capabilities] - Optional capabilities to include with the request
+ * @returns {Promise<PrepareCallsResult>} A Promise that resolves to the prepared calls result containing
+ * the user operation data and signature request
+ *
+ * @example
+ * ```ts
+ * // Prepare a sponsored user operation call
+ * const result = await client.prepareCalls({
+ *   calls: [{
+ *     to: "0x1234...",
+ *     data: "0xabcdef...",
+ *     value: "0x0"
+ *   }],
+ *   capabilities: {
+ *     paymasterService: { policyId: "your-policy-id" }
+ *   }
+ * });
+ * ```
+ */
+export async function prepareCalls<
+  TAccount extends Address | undefined = Address | undefined,
+>(
+  client: InnerWalletApiClient,
+  params: PrepareCallsParams<TAccount>,
+): Promise<PrepareCallsResult> {
+  const from = params.from ?? client.account?.address;
+  if (!from) {
+    LOGGER.warn("prepareCalls:no-from", { hasClientAccount: !!client.account });
+    throw new AccountNotFoundError();
+  }
+
+  const capabilities = mergeClientCapabilities(client, params.capabilities);
+
+  LOGGER.debug("prepareCalls:start", {
+    callsCount: params.calls?.length,
+    hasCapabilities: !!params.capabilities,
+  });
+  const res = await client.request({
+    method: "wallet_prepareCalls",
+    params: [
+      {
+        ...params,
+        chainId: params.chainId ?? toHex(client.chain.id),
+        from,
+        capabilities,
+      },
+    ],
+  });
+  LOGGER.debug("prepareCalls:done");
+  return res;
+}

package/src/actions/prepareSign.ts

@@ -0,0 +1,67 @@
+import type { InnerWalletApiClient, OptionalChainId } from "../types.ts";
+import { toHex, type Address, type IsUndefined, type Prettify } from "viem";
+import type { WalletServerRpcSchemaType } from "@alchemy/wallet-api-types/rpc";
+import { AccountNotFoundError } from "@alchemy/common";
+import { LOGGER } from "../logger.js";
+
+type RpcSchema = Extract<
+  WalletServerRpcSchemaType,
+  {
+    Request: {
+      method: "wallet_prepareSign";
+    };
+  }
+>;
+
+export type PrepareSignParams<
+  TAccount extends Address | undefined = Address | undefined,
+> = Prettify<
+  OptionalChainId<Omit<RpcSchema["Request"]["params"][0], "from">> &
+    (IsUndefined<TAccount> extends true ? { from: Address } : { from?: never })
+>;
+
+export type PrepareSignResult = Prettify<RpcSchema["ReturnType"]>;
+
+/**
+ * Prepares a signature request for signing messages or transactions.
+ *
+ * @param {InnerWalletApiClient} client - The wallet API client to use for the request
+ * @param {PrepareSignParams} params - Parameters for preparing the signature request
+ * @returns {Promise<PrepareSignResult>} A Promise that resolves to the prepare sign result containing a signature request
+ *
+ * @example
+ * ```ts
+ * // Prepare a message to be signed
+ * const result = await client.prepareSign({
+ *    from: "0x1234...",
+ *    type: "personal_sign",
+ *    data: "Hello, world!",
+ * });
+ * ```
+ */
+export async function prepareSign<
+  TAccount extends Address | undefined = Address | undefined,
+>(
+  client: InnerWalletApiClient,
+  params: PrepareSignParams<TAccount>,
+): Promise<PrepareSignResult> {
+  const from = params.from ?? client.account?.address;
+  if (!from) {
+    LOGGER.warn("prepareSign:no-from", { hasClientAccount: !!client.account });
+    throw new AccountNotFoundError();
+  }
+
+  LOGGER.debug("prepareSign:start", { type: params.signatureRequest.type });
+  const res = await client.request({
+    method: "wallet_prepareSign",
+    params: [
+      {
+        ...params,
+        from,
+        chainId: params.chainId ?? toHex(client.chain.id),
+      },
+    ],
+  });
+  LOGGER.debug("prepareSign:done");
+  return res;
+}

package/src/actions/requestAccount.ts

@@ -0,0 +1,100 @@
+import type { Address } from "abitype";
+import type { Prettify, UnionOmit } from "viem";
+import type { WalletServerRpcSchemaType } from "@alchemy/wallet-api-types/rpc";
+import deepEqual from "deep-equal";
+import type { InnerWalletApiClient, OptionalSignerAddress } from "../types";
+import { LOGGER } from "../logger.js";
+
+type RpcSchema = Extract<
+  WalletServerRpcSchemaType,
+  {
+    Request: {
+      method: "wallet_requestAccount";
+    };
+  }
+>;
+
+export type RequestAccountParams = Prettify<
+  OptionalSignerAddress<
+    UnionOmit<RpcSchema["Request"]["params"][0], "includeCounterfactualInfo">
+  >
+>;
+
+export type RequestAccountResult = Prettify<{ address: Address }>;
+
+/**
+ * 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 {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 an object containing a smart account address
+ *
+ * @example
+ * ```ts
+ * // Request an account with default parameters using a local signer
+ * const signer = LocalAccountSigner.privateKeyToAccountSigner("0x...");
+ * const account = await client.requestAccount(signer);
+ * ```
+ */
+export async function requestAccount(
+  client: InnerWalletApiClient,
+  params?: RequestAccountParams,
+): Promise<RequestAccountResult> {
+  LOGGER.debug("requestAccount:start", {
+    hasParams: !!params,
+    hasAccountOnClient: !!client.account,
+  });
+  const args =
+    client.account && !params
+      ? {
+          accountAddress: client.account.address,
+          includeCounterfactualInfo: true,
+        }
+      : params != null && "accountAddress" in params
+        ? {
+            accountAddress: params.accountAddress,
+            includeCounterfactualInfo: true,
+          }
+        : {
+            ...params,
+            signerAddress:
+              (params && "signerAddress" in params
+                ? params.signerAddress
+                : undefined) ?? client.owner.account.address,
+            includeCounterfactualInfo: true,
+          };
+
+  const cachedAccount = client.internal?.getAccount();
+
+  if (
+    cachedAccount &&
+    ((args.accountAddress && cachedAccount.address === args.accountAddress) ||
+      deepEqual(cachedAccount.requestParams, args, { strict: true }))
+  ) {
+    LOGGER.debug("requestAccount:cache-hit", {
+      address: cachedAccount.address,
+    });
+    return {
+      address: cachedAccount.address,
+    };
+  }
+
+  const resp = await client.request({
+    method: "wallet_requestAccount",
+    params: [args],
+  });
+
+  client.internal?.setAccount({
+    address: resp.accountAddress,
+    requestParams: args,
+  });
+
+  LOGGER.debug("requestAccount:done", { address: resp.accountAddress });
+  return {
+    address: resp.accountAddress,
+  };
+}

package/src/actions/sendCalls.ts

@@ -0,0 +1,67 @@
+import type { Address, Prettify } from "viem";
+import type { InnerWalletApiClient } from "../types.js";
+import { prepareCalls, type PrepareCallsParams } from "./prepareCalls.js";
+import { signPreparedCalls } from "./signPreparedCalls.js";
+import {
+  sendPreparedCalls,
+  type SendPreparedCallsResult,
+} from "./sendPreparedCalls.js";
+import { LOGGER } from "../logger.js";
+
+export type SendCallsParams<
+  TAccount extends Address | undefined = Address | undefined,
+> = Prettify<PrepareCallsParams<TAccount>>;
+
+export type SendCallsResult = Prettify<SendPreparedCallsResult>;
+
+/**
+ * Prepares, signs, and submits calls. This function internally calls `prepareCalls`, `signPreparedCalls`, and `sendPreparedCalls`.
+ *
+ * @param {InnerWalletApiClient} client - The wallet API client to use for the request
+ * @param {PrepareCallsParams<TAccount>} params - Parameters for sending calls
+ * @param {Array<{to: Address, data?: Hex, value?: Hex}>} params.calls - Array of contract calls to execute
+ * @param {Address} [params.from] - The address to execute the calls from (required if the client wasn't initialized with an account)
+ * @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
+ * ```ts
+ * const result = await client.sendCalls({
+ *   calls: [{
+ *     to: "0x1234...",
+ *     data: "0xabcdef...",
+ *     value: "0x0"
+ *   }],
+ *   capabilities: {
+ *     paymasterService: { policyId: "your-policy-id" }
+ *   }
+ * });
+ *
+ * // The result contains the prepared call IDs
+ * console.log(result.preparedCallIds);
+ * ```
+ */
+export async function sendCalls<
+  TAccount extends Address | undefined = Address | undefined,
+>(
+  client: InnerWalletApiClient,
+  params: SendCallsParams<TAccount>,
+): Promise<SendCallsResult> {
+  LOGGER.info("sendCalls:start", {
+    calls: params.calls?.length,
+    hasCapabilities: !!params.capabilities,
+  });
+  const calls = await prepareCalls(client, params);
+
+  const signedCalls = await signPreparedCalls(client, calls);
+
+  const res = await sendPreparedCalls(client, {
+    ...signedCalls,
+    // The only capability that is supported in sendPreparedCalls is permissions.
+    ...(params.capabilities?.permissions != null
+      ? { capabilities: { permissions: params.capabilities.permissions } }
+      : {}),
+  });
+  LOGGER.info("sendCalls:done");
+  return res;
+}

package/src/actions/sendPreparedCalls.ts

@@ -0,0 +1,70 @@
+import { toHex, type Prettify } from "viem";
+import type { WalletServerRpcSchemaType } from "@alchemy/wallet-api-types/rpc";
+import type { InnerWalletApiClient, OptionalChainId } from "../types.ts";
+import { LOGGER } from "../logger.js";
+
+type RpcSchema = Extract<
+  WalletServerRpcSchemaType,
+  {
+    Request: {
+      method: "wallet_sendPreparedCalls";
+    };
+  }
+>;
+
+export type SendPreparedCallsParams = Prettify<
+  OptionalChainId<RpcSchema["Request"]["params"][0]>
+>;
+
+export type SendPreparedCallsResult = Prettify<RpcSchema["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
+ * @returns {Promise<SendPreparedCallsResult>} A Promise that resolves to the result containing the prepared call IDs
+ *
+ * @example
+ * ```ts
+ * // First prepare the calls
+ * const preparedCalls = await client.prepareCalls({
+ *   calls: [{
+ *     to: "0x1234...",
+ *     data: "0xabcdef...",
+ *     value: "0x0"
+ *   }],
+ *   capabilities: {
+ *     paymasterService: { policyId: "your-policy-id" }
+ *   }
+ * });
+ *
+ * // Then sign the calls
+ * const signedCalls = await client.signPreparedCalls(preparedCalls);
+ *
+ * // Then send the prepared calls with the signature
+ * const result = await client.sendPreparedCalls({
+ *   signedCalls,
+ * });
+ * ```
+ */
+export async function sendPreparedCalls(
+  client: InnerWalletApiClient,
+  params: SendPreparedCallsParams,
+): Promise<SendPreparedCallsResult> {
+  LOGGER.debug("sendPreparedCalls:start", { type: params.type });
+  const res = await client.request({
+    method: "wallet_sendPreparedCalls",
+    params: [
+      params.type === "array"
+        ? params
+        : {
+            ...params,
+            chainId: params.chainId ?? toHex(client.chain.id),
+          },
+    ],
+  });
+  LOGGER.debug("sendPreparedCalls:done");
+  return res;
+}

package/src/actions/signMessage.ts

@@ -0,0 +1,74 @@
+import {
+  type Address,
+  type Hex,
+  type Prettify,
+  type SignableMessage,
+} from "viem";
+import type { InnerWalletApiClient } from "../types.js";
+import { requestAccount } from "./requestAccount.js";
+import { prepareSign } from "./prepareSign.js";
+import { signSignatureRequest } from "./signSignatureRequest.js";
+import { formatSign } from "./formatSign.js";
+import { signableMessageToJsonSafe } from "../utils/format.js";
+import { LOGGER } from "../logger.js";
+
+export type SignMessageParams = Prettify<{
+  message: SignableMessage;
+  account?: Address;
+}>;
+
+export type SignMessageResult = Prettify<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 {SignMessageParams} params - Parameters for signing the message
+ * @param {SignableMessage} params.message - The message to sign using EIP-191. Can be a string, or object with raw bytes.
+ * @param {Address} [params.account] - Optional account address to use for signing. If not provided, uses the client's current account.
+ * @returns {Promise<SignMessageResult>} A Promise that resolves to the signed message as a hex string
+ *
+ * @example
+ * ```ts
+ * // Sign a simple text message
+ * const signature = await client.signMessage("Hello, world!");
+ *
+ * // Sign a raw hex message
+ * const signature = await client.signMessage({ raw: "0x48656c6c6f2c20776f726c6421" });
+ * ```
+ */
+export async function signMessage(
+  client: InnerWalletApiClient,
+  params: SignMessageParams,
+): Promise<SignMessageResult> {
+  const accountAddress = params.account ?? client.account?.address;
+  LOGGER.debug("signMessage:start", {
+    hasExplicitAccount: params.account != null,
+  });
+
+  const account = await requestAccount(
+    client,
+    accountAddress != null ? { accountAddress } : undefined,
+  );
+
+  const prepared = await prepareSign(client, {
+    from: account.address,
+    signatureRequest: {
+      type: "personal_sign",
+      data: signableMessageToJsonSafe(params.message),
+    },
+  });
+
+  const signed = await signSignatureRequest(client, prepared.signatureRequest);
+
+  const formatted = await formatSign(client, {
+    from: account.address,
+    signature: {
+      type: "ecdsa",
+      data: signed.data,
+    },
+  });
+  LOGGER.debug("signMessage:done", { from: account.address });
+  return formatted.signature;
+}