@account-kit/wallet-client 0.0.1-alpha.1

package/src/isomorphic/client.ts

@@ -0,0 +1,81 @@
+import {
+  createSmartAccountClient,
+  type SmartAccountClient,
+  type SmartAccountClientRpcSchema,
+  type SmartContractAccount,
+} from "@aa-sdk/core";
+import {
+  alchemyFeeEstimator,
+  alchemyGasManagerMiddleware,
+  type AlchemyTransport,
+} from "@account-kit/infra";
+import { type Chain, type Transport } from "viem";
+import type { WalletServerViemRpcSchema } from "../rpc/schema";
+import { prepareCalls, type PrepareCallsParams } from "./actions/prepareCalls";
+import {
+  sendPreparedCalls,
+  type SendPreparedCallsParams,
+} from "./actions/sendPreparedCalls";
+import {
+  getCallsStatus,
+  type GetCallsStatusParams,
+} from "./actions/getCallsStatus";
+import {
+  createSession,
+  type CreateSessionParams,
+} from "./actions/createSession";
+
+// let's start with something that takes in as many params as possible, then we can eliminate them as we don't need them
+type ClientParams = {
+  chain: Chain;
+  transport: Transport;
+  policyId?: string;
+};
+
+export function isomorphicClientActions(
+  client: SmartAccountClient<
+    Transport,
+    Chain,
+    SmartContractAccount | undefined,
+    Record<string, unknown>,
+    WalletServerViemRpcSchema
+  >,
+) {
+  return {
+    prepareCalls: (params: PrepareCallsParams) => prepareCalls(client, params),
+    sendPreparedCalls: (params: SendPreparedCallsParams) =>
+      sendPreparedCalls(client, params),
+    getCallsStatus: (params: GetCallsStatusParams) =>
+      getCallsStatus(client, params),
+    createSession: (params: CreateSessionParams) =>
+      createSession(client, params),
+  };
+}
+
+// the isomorphic client likely won't be exposed directly. This client contains the business logic that can be run on the wallet server or on the client
+// if the dev chooses to run the client in "local" mode.
+export function createIsomorphicClient({
+  chain,
+  transport,
+  policyId,
+}: ClientParams): SmartAccountClient<
+  Transport,
+  Chain,
+  SmartContractAccount | undefined,
+  ReturnType<typeof isomorphicClientActions>,
+  WalletServerViemRpcSchema & SmartAccountClientRpcSchema
+> {
+  // This must be a smart account client since as of now we use it to build UOs under the hood
+  const client = createSmartAccountClient({
+    transport,
+    chain,
+    // TODO: we will want to enforce alchemy transport here probably
+    feeEstimator: alchemyFeeEstimator(transport as AlchemyTransport),
+    // TODO: we need to use the other middleware that does gas estimation as well here
+    ...(policyId ? alchemyGasManagerMiddleware(policyId) : {}),
+  }).extend(isomorphicClientActions);
+
+  return client;
+}
+
+export type IsomorphicClient = ReturnType<typeof createIsomorphicClient>;

package/src/isomorphic/utils/createAccount.ts

@@ -0,0 +1,58 @@
+import type { SmartAccountSigner, SmartContractAccount } from "@aa-sdk/core";
+import {
+  createModularAccountV2,
+  type ModularAccountV2,
+} from "@account-kit/smart-contracts";
+import type { StaticDecode } from "@sinclair/typebox";
+import type { Address, Chain, Transport } from "viem";
+import { concatHex, hexToNumber } from "viem";
+import type { TypeSerializedInitcode } from "../../schemas";
+import type { Capabilities } from "../../capabilities";
+import { parsePermissionsContext } from "./parsePermissionsContext";
+
+type CreateAccountParams = {
+  chain: Chain;
+  transport: Transport;
+  signer: SmartAccountSigner;
+  accountAddress: Address;
+  counterfactualInfo: StaticDecode<typeof TypeSerializedInitcode>;
+  capabilities?: StaticDecode<typeof Capabilities>;
+};
+
+/**
+ * Creates a smart account instance from the given parameters.
+ * @param params - The parameters for creating a smart account.
+ * @returns A promise that resolves to the created smart account.
+ */
+export async function createAccount(
+  params: CreateAccountParams,
+): Promise<SmartContractAccount> {
+  const { counterfactualInfo: ci, ...accountParams } = params;
+  // TODO: Implement support for other account types.
+  if (ci.factoryType !== "MAv2.0.0-sma-b") {
+    throw new Error("Only MAv2 SMA-B accounts are currently supported");
+  }
+
+  const parsedContext = parsePermissionsContext(params.capabilities, ci);
+
+  const signerEntity =
+    parsedContext?.contextVersion === "NON_DEFERRED_ACTION"
+      ? {
+          entityId: hexToNumber(parsedContext.entityId),
+          isGlobalValidation: parsedContext.isGlobalValidation,
+        }
+      : undefined;
+
+  return createModularAccountV2({
+    ...accountParams,
+    signerEntity,
+    deferredAction: parsedContext?.deferredAction,
+    initCode: concatHex([ci.factoryAddress, ci.factoryData]),
+  });
+}
+
+export function isModularAccountV2(
+  account: SmartContractAccount,
+): account is ModularAccountV2 {
+  return account.source === "ModularAccountV2";
+}

package/src/isomorphic/utils/createDummySigner.ts

@@ -0,0 +1,26 @@
+import { type SmartAccountSigner } from "@aa-sdk/core";
+import type { TypedData } from "abitype";
+import {
+  type Address,
+  type Hex,
+  type SignableMessage,
+  type TypedDataDefinition,
+} from "viem";
+
+export const createDummySigner = (address: Address): SmartAccountSigner => ({
+  signerType: "",
+  inner: undefined,
+  getAddress: async function (): Promise<`0x${string}`> {
+    return address;
+  },
+  // Not supported on the server
+  signMessage: function (_message: SignableMessage): Promise<Hex> {
+    throw new Error("Function not implemented.");
+  },
+  signTypedData: function <
+    const TTypedData extends TypedData | Record<string, unknown>,
+    TPrimaryType extends keyof TTypedData | "EIP712Domain" = keyof TTypedData,
+  >(_params: TypedDataDefinition<TTypedData, TPrimaryType>): Promise<Hex> {
+    throw new Error("Function not implemented.");
+  },
+});

package/src/isomorphic/utils/parsePermissionsContext.ts

@@ -0,0 +1,33 @@
+import type { StaticDecode } from "@sinclair/typebox";
+import type { PrepareCallsParams } from "../actions/prepareCalls";
+import type { TypeSerializedInitcode } from "../../schemas";
+import { InvalidRequestError } from "ox/RpcResponse";
+import { decodePermissionsContext } from "../../capabilities/permissions/mav2";
+
+export function parsePermissionsContext(
+  capabilities: PrepareCallsParams["capabilities"],
+  parsedCi: StaticDecode<typeof TypeSerializedInitcode>,
+) {
+  if (!capabilities?.permissions?.context) {
+    return undefined;
+  }
+
+  if (
+    capabilities?.permissions?.context &&
+    parsedCi.factoryType !== "MAv2.0.0-sma-b"
+  ) {
+    throw new InvalidRequestError({
+      message: "Permissions are currently only supported by MAv2 accounts",
+    });
+  }
+
+  const context = decodePermissionsContext(capabilities.permissions.context);
+
+  if (context?.contextVersion === "REMOTE_MODE_DEFERRED_ACTION") {
+    throw new InvalidRequestError({
+      message: "Remote mode deferred action not supported in isomorphic client",
+    });
+  }
+
+  return context;
+}

package/src/local/client.ts

@@ -0,0 +1,132 @@
+import { split } from "@aa-sdk/core";
+import { createClient, custom, type Address, type JsonRpcAccount } from "viem";
+import type { PrepareCallsParams } from "../isomorphic/actions/prepareCalls";
+import {
+  createIsomorphicClient,
+  type IsomorphicClient,
+} from "../isomorphic/client";
+import type {
+  CreateInnerClientParams,
+  InnerClientActions,
+  InnerWalletApiClient,
+} from "../types";
+import { assertNever } from "../utils";
+import { signSignatureRequest } from "../client/actions/signSignatureRequest";
+import {
+  encodePermissionsContext,
+  prefixSignatureKeyType,
+} from "../capabilities/permissions/mav2";
+import { buildDeferredActionDigest } from "@account-kit/smart-contracts/experimental";
+
+const localMethods = [
+  "wallet_prepareCalls",
+  "wallet_sendPreparedCalls",
+  "wallet_getCallsStatus",
+  "wallet_createSession",
+] as const satisfies string[];
+type LocalMethod = (typeof localMethods)[number];
+
+export function createLocalClient<
+  TAccount extends JsonRpcAccount<Address> | undefined =
+    | JsonRpcAccount<Address>
+    | undefined,
+>(params: CreateInnerClientParams<TAccount>): InnerWalletApiClient<TAccount>;
+
+export function createLocalClient(
+  params: CreateInnerClientParams,
+): InnerWalletApiClient {
+  const { chain, transport, policyId, account } = params;
+  const isomorphicClient = createIsomorphicClient({
+    transport,
+    chain,
+    policyId,
+  });
+
+  const clientMap: Record<string, ReturnType<typeof createIsomorphicClient>> = {
+    [policyId ?? "default"]: isomorphicClient,
+  };
+
+  const innerTransport = split({
+    overrides: [
+      {
+        methods: localMethods,
+        transport: custom({
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          async request(args: { method: LocalMethod; params: any }) {
+            switch (args.method) {
+              case "wallet_prepareCalls": {
+                const params = args.params[0] as PrepareCallsParams;
+                const capabilityPolicyId =
+                  params.capabilities?.paymasterService?.policyId;
+
+                if (
+                  capabilityPolicyId != null &&
+                  policyId !== capabilityPolicyId &&
+                  !clientMap[capabilityPolicyId]
+                ) {
+                  clientMap[capabilityPolicyId] = createIsomorphicClient({
+                    transport,
+                    chain,
+                    policyId: capabilityPolicyId,
+                  });
+                }
+
+                const client =
+                  clientMap[capabilityPolicyId ?? policyId ?? "default"];
+                return client.prepareCalls(params);
+              }
+              case "wallet_sendPreparedCalls":
+                return isomorphicClient.sendPreparedCalls(args.params[0]);
+              case "wallet_getCallsStatus":
+                return isomorphicClient.getCallsStatus(args.params[0]);
+              case "wallet_createSession": {
+                return isomorphicClient.createSession(args.params[0]);
+              }
+              default:
+                return assertNever(
+                  args.method,
+                  `Unexpected method: ${args.method}`,
+                );
+            }
+          },
+        }),
+      },
+    ],
+    fallback: transport,
+  });
+
+  return createClient({
+    transport: innerTransport,
+    chain,
+    account,
+  }).extend(() => ({
+    policyId,
+    ...innerClientActions(isomorphicClient),
+  }));
+}
+
+const innerClientActions = (
+  isomorphicClient: IsomorphicClient,
+): InnerClientActions => {
+  return {
+    grantPermissions: async (signer, params) => {
+      const { signatureRequest, fullPreSignatureDeferredActionDigest } =
+        await isomorphicClient.createSession(params);
+
+      const { signature } = await signSignatureRequest(
+        signer,
+        signatureRequest,
+      );
+
+      return {
+        context: encodePermissionsContext({
+          contextVersion: "LOCAL_MODE_DEFERRED_ACTION",
+          deferredAction: buildDeferredActionDigest({
+            fullPreSignatureDeferredActionDigest,
+            sig: prefixSignatureKeyType(signature, "secp256k1"),
+          }),
+        }),
+      };
+    },
+  };
+};

package/src/remote/client.ts

@@ -0,0 +1,67 @@
+import { Provider } from "ox";
+import { createClient, custom, type Address, type JsonRpcAccount } from "viem";
+import { WalletServerRpcSchema } from "../rpc/schema";
+import type {
+  CreateInnerClientParams,
+  InnerClientActions,
+  InnerWalletApiClient,
+  InnerWalletApiClientBase,
+} from "../types";
+import { signSignatureRequest } from "../client/actions/signSignatureRequest";
+import { encodePermissionsContext } from "../capabilities/permissions/mav2";
+
+export function createRemoteClient<
+  TAccount extends JsonRpcAccount<Address> | undefined =
+    | JsonRpcAccount<Address>
+    | undefined,
+>(params: CreateInnerClientParams<TAccount>): InnerWalletApiClient<TAccount>;
+
+/**
+ * This is a low-level client just used to make RPC requests in remote mode
+ * This should be wrapped by a higher-level smart account client that provides actions
+ * that uses this client under the hood
+ * @returns
+ */
+export function createRemoteClient(
+  params: CreateInnerClientParams,
+): InnerWalletApiClient {
+  const { transport, chain, account } = params;
+
+  const client = createClient({
+    transport: (opts) =>
+      custom(Provider.from(transport(opts), { schema: WalletServerRpcSchema }))(
+        opts,
+      ),
+    chain,
+    account,
+  }).extend((_client) => ({
+    policyId: params.policyId,
+    ...innerClientActions(_client),
+  }));
+
+  return client;
+}
+
+const innerClientActions = (
+  apiClient: InnerWalletApiClientBase,
+): InnerClientActions => {
+  return {
+    grantPermissions: async (signer, params) => {
+      const { sessionId, signatureRequest } = await apiClient.request({
+        method: "wallet_createSession",
+        params: [params],
+      });
+      const { signature } = await signSignatureRequest(
+        signer,
+        signatureRequest,
+      );
+      return {
+        context: encodePermissionsContext({
+          contextVersion: "REMOTE_MODE_DEFERRED_ACTION",
+          sessionId,
+          signature,
+        }),
+      };
+    },
+  };
+};

package/src/rpc/request.ts

@@ -0,0 +1,258 @@
+import { Type } from "@sinclair/typebox";
+import { Capabilities } from "../capabilities";
+import {
+  PermissionsContext,
+  PermissionsData,
+} from "../capabilities/permissions";
+import {
+  TypeAddress,
+  TypeBase64UrlEncodedString,
+  TypeCreationOptions,
+  TypeHex,
+  TypeSerializedInitcode,
+  TypeSignatureRequest,
+  TypeUserOperationRequest_v6,
+  TypeUserOperationRequest_v7,
+  TypeUuid,
+} from "../schemas";
+
+export const wallet_sendPreparedCalls = Type.Object(
+  {
+    Request: Type.Object({
+      method: Type.Literal("wallet_sendPreparedCalls"),
+      params: Type.Tuple([
+        Type.Object({
+          type: Type.Union([
+            Type.Literal("user-operation-v060"),
+            Type.Literal("user-operation-v070"),
+          ]),
+          data: Type.Union([
+            Type.Omit(TypeUserOperationRequest_v6, ["signature"]),
+            Type.Omit(TypeUserOperationRequest_v7, ["signature"]),
+          ]),
+          chainId: TypeHex(),
+          signature: Type.Object({
+            // ignored, but in the spec can be used when the signature on the UO needs to be formatted differently
+            // potentially useful for deferred actions?
+            type: Type.String(),
+            signature: TypeHex(),
+          }),
+          capabilities: Type.Optional(
+            Type.Object({ permissions: PermissionsContext }),
+          ),
+        }),
+      ]),
+    }),
+    ReturnType: Type.Object({
+      preparedCallIds: Type.Array(TypeHex()),
+    }),
+  },
+  {
+    description:
+      "This method is used after signing the signatureRequest returned from prepareCalls to submit a user operation",
+  },
+);
+
+export const wallet_prepareCalls = Type.Object(
+  {
+    Request: Type.Object({
+      method: Type.Literal("wallet_prepareCalls"),
+      params: Type.Tuple([
+        Type.Object({
+          calls: Type.Array(
+            Type.Object({
+              to: TypeAddress,
+              data: Type.Optional(TypeHex()),
+              value: Type.Optional(TypeHex()),
+            }),
+          ),
+          from: TypeAddress,
+          chainId: TypeHex(),
+          capabilities: Type.Optional(Capabilities),
+        }),
+      ]),
+    }),
+    ReturnType: Type.Object({
+      type: Type.Union([
+        Type.Literal("user-operation-v060"),
+        Type.Literal("user-operation-v070"),
+      ]),
+      data: Type.Union([
+        Type.Omit(TypeUserOperationRequest_v6, ["signature"]),
+        Type.Omit(TypeUserOperationRequest_v7, ["signature"]),
+      ]),
+      chainId: TypeHex(),
+      signatureRequest: TypeSignatureRequest,
+    }),
+  },
+  {
+    description:
+      "This method is used to prepare a user operation for submission. It will return a built user operation and a signature request which needs to be signed by the user before submitting to wallet_sendPreparedCalls",
+  },
+);
+
+export const wallet_requestAccount = Type.Object(
+  {
+    Request: Type.Object({
+      method: Type.Literal("wallet_requestAccount"),
+      params: Type.Tuple([
+        Type.Union([
+          Type.Object({
+            signerAddress: TypeAddress,
+            id: Type.Optional(TypeUuid),
+            creationHint: TypeCreationOptions,
+            includeCounterfactualInfo: Type.Optional(
+              Type.Boolean({ default: false }),
+            ),
+          }),
+          Type.Object({
+            accountAddress: TypeAddress,
+            includeCounterfactualInfo: Type.Optional(
+              Type.Boolean({ default: false }),
+            ),
+          }),
+        ]),
+      ]),
+    }),
+    ReturnType: Type.Object({
+      accountAddress: TypeAddress,
+      id: TypeUuid,
+      counterfactualInfo: Type.Optional(TypeSerializedInitcode),
+    }),
+  },
+  {
+    description: `This method is used to get the smart account address and relevant info for a given signer. If an account does not already exist for a given signer, this method will create one before returning the counterfactual address.`,
+  },
+);
+
+export const wallet_createAccount = Type.Object(
+  {
+    Request: Type.Object({
+      method: Type.Literal("wallet_createAccount"),
+      params: Type.Tuple([
+        Type.Object({
+          signerAddress: TypeAddress,
+          id: Type.Optional(TypeUuid),
+          creationOptions: TypeCreationOptions,
+        }),
+      ]),
+    }),
+    ReturnType: Type.Object({
+      accountAddress: TypeAddress,
+      id: TypeUuid,
+    }),
+  },
+  {
+    description: `This method is used to create a smart account for a given signer. This method is primarly used to import existing accounts. For most cases, you should use wallet_requestAccount instead.`,
+  },
+);
+
+export const wallet_listAccounts = Type.Object(
+  {
+    Request: Type.Object({
+      method: Type.Literal("wallet_listAccounts"),
+      params: Type.Tuple([
+        Type.Object({
+          signerAddress: TypeAddress,
+          limit: Type.Optional(
+            Type.Number({ minimum: 1, maximum: 100, default: 100 }),
+          ),
+          after: Type.Optional(TypeBase64UrlEncodedString),
+        }),
+      ]),
+    }),
+    ReturnType: Type.Object({
+      accounts: Type.Array(
+        Type.Object({
+          accountAddress: TypeAddress,
+          id: TypeUuid,
+        }),
+      ),
+      meta: Type.Object({
+        totalCount: Type.Number(),
+        after: Type.Union([TypeBase64UrlEncodedString, Type.Null()]),
+      }),
+    }),
+  },
+  {
+    description:
+      "This method is used to list all smart accounts for a given signer.",
+  },
+);
+
+export const wallet_createSession = Type.Object({
+  Request: Type.Object({
+    method: Type.Literal("wallet_createSession"),
+    params: Type.Tuple([
+      Type.Intersect([PermissionsData, Type.Object({ account: TypeAddress })]),
+    ]),
+  }),
+  ReturnType: Type.Object({
+    sessionId: TypeHex(),
+    signatureRequest: TypeSignatureRequest,
+  }),
+});
+
+export const wallet_getCallsStatus = Type.Object(
+  {
+    Request: Type.Object({
+      method: Type.Literal("wallet_getCallsStatus"),
+      params: Type.Tuple([
+        TypeHex({
+          description: "The call ID returned from wallet_sendPreparedCalls",
+        }),
+      ]),
+    }),
+    ReturnType: Type.Object({
+      id: TypeHex(),
+      chainId: TypeHex(),
+      atomic: Type.Boolean(),
+      status: Type.Union([
+        Type.Literal(100, {
+          description:
+            "Batch has been received by the wallet but has not completed execution onchain",
+        }),
+        Type.Literal(200, {
+          description:
+            "Batch has been included onchain without reverts, receipts array contains info of all calls",
+        }),
+        Type.Literal(400, {
+          description:
+            "Batch has not been included onchain and wallet will not retry",
+        }),
+        Type.Literal(500, {
+          description:
+            "Batch reverted *completely* and only changes related to gas charge may have been included onchain",
+        }),
+        Type.Literal(600, {
+          description:
+            "Batch reverted *partially* and some changes related to batch calls may have been included onchain",
+        }),
+      ]),
+      receipts: Type.Optional(
+        Type.Array(
+          Type.Object({
+            logs: Type.Array(
+              Type.Object({
+                address: TypeAddress,
+                data: TypeHex(),
+                topics: Type.Array(TypeHex()),
+              }),
+            ),
+            status: TypeHex({
+              description: "0x1 for success, 0x0 for failure",
+            }),
+            blockHash: TypeHex(),
+            blockNumber: TypeHex(),
+            gasUsed: TypeHex(),
+            transactionHash: TypeHex(),
+          }),
+        ),
+      ),
+    }),
+  },
+  {
+    description:
+      "This method is used to get the status of calls IDs returned from wallet_sendPreparedCalls.",
+  },
+);

package/src/rpc/schema.ts

@@ -0,0 +1,40 @@
+import { type Static } from "@sinclair/typebox";
+import { RpcSchema } from "ox";
+import * as Requests from "./request";
+
+export const WalletServerRpcSchema = RpcSchema.from<
+  | Static<typeof Requests.wallet_prepareCalls>
+  | Static<typeof Requests.wallet_sendPreparedCalls>
+  | Static<typeof Requests.wallet_createAccount>
+  | Static<typeof Requests.wallet_requestAccount>
+  | Static<typeof Requests.wallet_listAccounts>
+  | Static<typeof Requests.wallet_createSession>
+  | Static<typeof Requests.wallet_getCallsStatus>
+>();
+
+export type WalletServerRpcSchemaType = typeof WalletServerRpcSchema;
+
+type MethodToViemRpcSchema = {
+  [K in WalletServerRpcSchemaType["Request"]["method"]]: {
+    Method: K;
+    Parameters: Extract<
+      WalletServerRpcSchemaType["Request"],
+      { method: K }
+    >["params"];
+    ReturnType: Extract<
+      WalletServerRpcSchemaType,
+      { Request: { method: K } }
+    >["ReturnType"];
+  };
+};
+
+// TODO: figure out how we can do this without manually listing all the methods
+export type WalletServerViemRpcSchema = [
+  MethodToViemRpcSchema["wallet_createAccount"],
+  MethodToViemRpcSchema["wallet_requestAccount"],
+  MethodToViemRpcSchema["wallet_listAccounts"],
+  MethodToViemRpcSchema["wallet_prepareCalls"],
+  MethodToViemRpcSchema["wallet_sendPreparedCalls"],
+  MethodToViemRpcSchema["wallet_getCallsStatus"],
+  MethodToViemRpcSchema["wallet_createSession"],
+];