@crossmint/client-sdk-smart-wallet 0.1.0

package/src/blockchain/BlockchainNetworks.ts

@@ -0,0 +1,121 @@
+import {
+    BUNDLER_RPC,
+    PM_BASE_RPC,
+    PM_BASE_SEPOLIA_RPC,
+    ZD_AMOY_PROJECT_ID,
+    ZD_ARBITRUM_NOVA_PROJECT_ID,
+    ZD_ARBITRUM_PROJECT_ID,
+    ZD_ARBITRUM_SEPOLIA_PROJECT_ID,
+    ZD_ASTAR_PROJECT_ID,
+    ZD_BASE_PROJECT_ID,
+    ZD_BASE_SEPOLIA_PROJECT_ID,
+    ZD_BSC_PROJECT_ID,
+    ZD_ETHEREUM_PROJECT_ID,
+    ZD_GOERLI_PROJECT_ID,
+    ZD_OPTIMISM_PROJECT_ID,
+    ZD_OPTIMISM_SEPOLIA_PROJECT_ID,
+    ZD_POLYGON_PROJECT_ID,
+    ZD_SEPOLIA_PROJECT_ID,
+    ZD_ZKATANA_PROJECT_ID,
+    ZD_ZKYOTO_PROJECT_ID,
+} from "@/utils/constants";
+import {
+    arbitrum,
+    arbitrumNova,
+    arbitrumSepolia,
+    astarZkEVM,
+    astarZkyoto,
+    base,
+    baseSepolia,
+    bsc,
+    goerli,
+    mainnet,
+    optimism,
+    optimismSepolia,
+    polygon,
+    polygonAmoy,
+    sepolia,
+} from "viem/chains";
+
+import { EVMBlockchainIncludingTestnet } from "@crossmint/common-sdk-base";
+
+export const getZeroDevProjectIdByBlockchain = (chain: EVMBlockchainIncludingTestnet) => {
+    const zeroDevProjectId = new Map<EVMBlockchainIncludingTestnet, string | null>([
+        ["ethereum", ZD_ETHEREUM_PROJECT_ID],
+        ["polygon", ZD_POLYGON_PROJECT_ID],
+        ["bsc", ZD_BSC_PROJECT_ID],
+        ["optimism", ZD_OPTIMISM_PROJECT_ID],
+        ["arbitrum", ZD_ARBITRUM_PROJECT_ID],
+        ["ethereum-goerli", ZD_GOERLI_PROJECT_ID],
+        ["ethereum-sepolia", ZD_SEPOLIA_PROJECT_ID],
+        ["polygon-amoy", ZD_AMOY_PROJECT_ID],
+        ["zkatana", ZD_ZKATANA_PROJECT_ID],
+        ["zkyoto", ZD_ZKYOTO_PROJECT_ID],
+        ["arbitrum-sepolia", ZD_ARBITRUM_SEPOLIA_PROJECT_ID],
+        ["base-goerli", null],
+        ["base-sepolia", ZD_BASE_SEPOLIA_PROJECT_ID],
+        ["bsc-testnet", null],
+        ["optimism-goerli", null],
+        ["optimism-sepolia", ZD_OPTIMISM_SEPOLIA_PROJECT_ID],
+        ["zora-goerli", null],
+        ["zora-sepolia", null],
+        ["base", ZD_BASE_PROJECT_ID],
+        ["zora", null],
+        ["arbitrumnova", ZD_ARBITRUM_NOVA_PROJECT_ID],
+        ["astar-zkevm", ZD_ASTAR_PROJECT_ID],
+        ["apex", null],
+    ]).get(chain)!;
+
+    if (zeroDevProjectId == null) {
+        throw new Error(`ZeroDev project id not found for chain ${chain}`);
+    }
+    return zeroDevProjectId;
+};
+
+export const getViemNetwork = (cmChain: EVMBlockchainIncludingTestnet) => {
+    switch (cmChain) {
+        case "ethereum":
+            return mainnet;
+        case "ethereum-goerli":
+            return goerli;
+        case "ethereum-sepolia":
+            return sepolia;
+        case "polygon":
+            return polygon;
+        case "polygon-amoy":
+            return polygonAmoy;
+        case "optimism":
+            return optimism;
+        case "optimism-sepolia":
+            return optimismSepolia;
+        case "arbitrum":
+            return arbitrum;
+        case "arbitrumnova":
+            return arbitrumNova;
+        case "arbitrum-sepolia":
+            return arbitrumSepolia;
+        case "base":
+            return base;
+        case "base-sepolia":
+            return baseSepolia;
+        case "zkyoto":
+            return astarZkyoto;
+        case "astar-zkevm":
+            return astarZkEVM;
+        case "bsc":
+            return bsc;
+        default:
+            throw new Error(`Unsupported network: ${cmChain}`);
+    }
+};
+
+export const getBundlerRPC = (chain: EVMBlockchainIncludingTestnet) => {
+    switch (chain) {
+        case EVMBlockchainIncludingTestnet.BASE_SEPOLIA:
+            return PM_BASE_SEPOLIA_RPC;
+        case EVMBlockchainIncludingTestnet.BASE:
+            return PM_BASE_RPC;
+        default:
+            return BUNDLER_RPC + getZeroDevProjectIdByBlockchain(chain) + "?bundlerProvider=STACKUP";
+    }
+};

package/src/blockchain/token/index.ts

@@ -0,0 +1 @@
+export * from "./Tokens";

package/src/blockchain/transfer.ts

@@ -0,0 +1,54 @@
+import { Abi, Account, Address, erc20Abi, erc721Abi } from "viem";
+
+import erc1155Abi from "../ABI/ERC1155.json";
+import type { ERC20TransferType, SFTTransferType, TransferType } from "../types/Tokens";
+
+type TransferInputParams = {
+    from: Account;
+    contract: Address;
+    to: Address;
+    config: TransferType;
+};
+
+type TransferSimulationParams = {
+    account: Account;
+    address: Address;
+    abi: Abi;
+    functionName: string;
+    args: any[];
+    tokenId?: string;
+};
+
+export function transferParams({ contract, config, from, to }: TransferInputParams): TransferSimulationParams {
+    switch (config.token.type) {
+        case "ft": {
+            return {
+                account: from,
+                address: contract,
+                abi: erc20Abi,
+                functionName: "transfer",
+                args: [to, (config as ERC20TransferType).amount],
+            };
+        }
+        case "sft": {
+            return {
+                account: from,
+                address: contract,
+                abi: erc1155Abi as Abi,
+                functionName: "safeTransferFrom",
+                args: [from.address, to, config.token.tokenId, (config as SFTTransferType).quantity, "0x00"],
+                tokenId: config.token.tokenId,
+            };
+        }
+        case "nft": {
+            return {
+                account: from,
+                address: contract,
+                abi: erc721Abi,
+                functionName: "safeTransferFrom",
+                args: [from.address, to, config.token.tokenId],
+                tokenId: config.token.tokenId,
+            };
+        }
+    }
+}

package/src/blockchain/wallets/EVMSmartWallet.ts

@@ -0,0 +1,109 @@
+import { logError } from "@/services/logging";
+import { type HttpTransport, type PublicClient, isAddress, publicActions } from "viem";
+
+import { EVMBlockchainIncludingTestnet } from "@crossmint/common-sdk-base";
+
+import type { CrossmintWalletService } from "../../api/CrossmintWalletService";
+import { TransferError } from "../../error";
+import type { TransferType } from "../../types/Tokens";
+import { SmartWalletClient } from "../../types/internal";
+import { SCW_SERVICE } from "../../utils/constants";
+import { LoggerWrapper, errorToJSON } from "../../utils/log";
+import { transferParams } from "../transfer";
+
+/**
+ * Smart wallet interface for EVM chains enhanced with Crossmint capabilities.
+ * Core functionality is exposed via [viem](https://viem.sh/) clients within the `client` property of the class.
+ */
+export class EVMSmartWallet extends LoggerWrapper {
+    public readonly chain: EVMBlockchainIncludingTestnet;
+
+    /**
+     * [viem](https://viem.sh/) clients that provide an interface for core wallet functionality.
+     */
+    public readonly client: {
+        /**
+         * An interface to interact with the smart wallet, execute transactions, sign messages, etc.
+         */
+        wallet: SmartWalletClient;
+
+        /**
+         * An interface to read onchain data, fetch transactions, retrieve account balances, etc. Corresponds to public [JSON-RPC API](https://ethereum.org/en/developers/docs/apis/json-rpc/) methods.
+         */
+        public: PublicClient;
+    };
+
+    constructor(
+        private readonly crossmintService: CrossmintWalletService,
+        private readonly accountClient: SmartWalletClient,
+        publicClient: PublicClient<HttpTransport>,
+        chain: EVMBlockchainIncludingTestnet
+    ) {
+        super("EVMSmartWallet", { chain, address: accountClient.account.address });
+        this.chain = chain;
+        this.client = {
+            wallet: accountClient,
+            public: publicClient,
+        };
+    }
+
+    /**
+     * The address of the smart wallet.
+     */
+    public get address() {
+        return this.accountClient.account.address;
+    }
+
+    /**
+     * @returns The transaction hash.
+     */
+    public async transferToken(toAddress: string, config: TransferType): Promise<string> {
+        return this.logPerformance("TRANSFER", async () => {
+            if (this.chain !== config.token.chain) {
+                throw new Error(
+                    `Chain mismatch: Expected ${config.token.chain}, but got ${this.chain}. Ensure you are interacting with the correct blockchain.`
+                );
+            }
+
+            if (!isAddress(toAddress)) {
+                throw new Error(`Invalid recipient address: '${toAddress}' is not a valid EVM address.`);
+            }
+
+            if (!isAddress(config.token.contractAddress)) {
+                throw new Error(
+                    `Invalid contract address: '${config.token.contractAddress}' is not a valid EVM address.`
+                );
+            }
+
+            const tx = transferParams({
+                contract: config.token.contractAddress,
+                to: toAddress,
+                from: this.accountClient.account,
+                config,
+            });
+
+            try {
+                const client = this.accountClient.extend(publicActions);
+                const { request } = await client.simulateContract(tx);
+                return await client.writeContract(request);
+            } catch (error) {
+                logError("[TRANSFER] - ERROR_TRANSFERRING_TOKEN", {
+                    service: SCW_SERVICE,
+                    error: errorToJSON(error),
+                    tokenId: tx.tokenId,
+                    contractAddress: config.token.contractAddress,
+                    chain: config.token.chain,
+                });
+                const tokenIdString = tx.tokenId == null ? "" : `:${tx.tokenId}}`;
+                throw new TransferError(`Error transferring token ${config.token.contractAddress}${tokenIdString}`);
+            }
+        });
+    }
+
+    /**
+     * @returns A list of NFTs owned by the wallet.
+     */
+    public async nfts() {
+        return this.crossmintService.fetchNFTs(this.address, this.chain);
+    }
+}

package/src/blockchain/wallets/clientDecorator.ts

@@ -0,0 +1,127 @@
+import { SmartWalletSDKError } from "@/error";
+import { ErrorProcessor } from "@/error/processor";
+import { logInfo } from "@/services/logging";
+import { usesGelatoBundler } from "@/utils/blockchain";
+import { logPerformance } from "@/utils/log";
+import type { SmartAccountClient } from "permissionless";
+import type { EntryPoint } from "permissionless/types/entrypoint";
+import { stringify } from "viem";
+
+import { EVMBlockchainIncludingTestnet } from "@crossmint/common-sdk-base";
+
+const transactionMethods = [
+    "sendTransaction",
+    "writeContract",
+    "sendUserOperation",
+] as const satisfies readonly (keyof SmartAccountClient<EntryPoint>)[];
+
+const signingMethods = [
+    "signMessage",
+    "signTypedData",
+] as const satisfies readonly (keyof SmartAccountClient<EntryPoint>)[];
+
+type TxnMethod = (typeof transactionMethods)[number];
+type SignMethod = (typeof signingMethods)[number];
+
+function isTxnMethod(method: string): method is TxnMethod {
+    return transactionMethods.includes(method as any);
+}
+
+function isSignMethod(method: string): method is SignMethod {
+    return signingMethods.includes(method as any);
+}
+
+/**
+ * A decorator class for SmartAccountClient instances. It enhances the client with:
+ * - Error handling & logging.
+ * - Performance metrics.
+ * - Automatic formatting of transactions for Gelato bundler compatibility.
+ *  */
+export class ClientDecorator {
+    constructor(private readonly errorProcessor: ErrorProcessor) {}
+
+    public decorate<Client extends SmartAccountClient<EntryPoint>>({
+        crossmintChain,
+        smartAccountClient,
+    }: {
+        crossmintChain: EVMBlockchainIncludingTestnet;
+        smartAccountClient: Client;
+    }): Client {
+        return new Proxy(smartAccountClient, {
+            get: (target, prop, receiver) => {
+                const originalMethod = Reflect.get(target, prop, receiver);
+
+                if (
+                    typeof originalMethod !== "function" ||
+                    typeof prop !== "string" ||
+                    !(isSignMethod(prop) || isTxnMethod(prop))
+                ) {
+                    return originalMethod;
+                }
+
+                return (...args: any[]) =>
+                    logPerformance(`CrossmintSmartWallet.${prop}`, () =>
+                        this.execute(target, prop, originalMethod, args, crossmintChain)
+                    );
+            },
+        }) as Client;
+    }
+
+    private async execute<M extends TxnMethod | SignMethod>(
+        target: SmartAccountClient<EntryPoint>,
+        prop: M,
+        // eslint-disable-next-line @typescript-eslint/ban-types
+        originalMethod: Function,
+        args: any[],
+        crossmintChain: EVMBlockchainIncludingTestnet
+    ) {
+        try {
+            logInfo(`[CrossmintSmartWallet.${prop}] - params: ${stringify(args)}`);
+            const processed = isTxnMethod(prop) ? this.processTxnArgs(prop, crossmintChain, args) : args;
+            return await originalMethod.call(target, ...processed);
+        } catch (error: any) {
+            const description = isTxnMethod(prop) ? "signing" : "sending transaction";
+            throw this.errorProcessor.map(
+                error,
+                new SmartWalletSDKError(`Error ${description}: ${error.message}`, stringify(error))
+            );
+        }
+    }
+
+    private processTxnArgs(prop: TxnMethod, crossmintChain: EVMBlockchainIncludingTestnet, args: any[]): any[] {
+        if (prop === "sendUserOperation") {
+            const [{ userOperation, middleware, account }] = args as Parameters<
+                SmartAccountClient<EntryPoint>["sendUserOperation"]
+            >;
+            return [
+                {
+                    middleware,
+                    account,
+                    userOperation: this.addGelatoBundlerProperties(crossmintChain, userOperation),
+                },
+                ...args.slice(1),
+            ];
+        }
+
+        const [txn] = args as
+            | Parameters<SmartAccountClient<EntryPoint>["sendTransaction"]>
+            | Parameters<SmartAccountClient<EntryPoint>["writeContract"]>;
+
+        return [this.addGelatoBundlerProperties(crossmintChain, txn), ...args.slice(1)];
+    }
+
+    /*
+     * Chain that ZD uses Gelato as for bundler require special parameters:
+     * https://docs.zerodev.app/sdk/faqs/use-with-gelato#transaction-configuration
+     */
+    private addGelatoBundlerProperties(
+        crossmintChain: EVMBlockchainIncludingTestnet,
+        txnParams: { maxFeePerGas?: bigint; maxPriorityFeePerGas?: bigint }
+    ) {
+        if (usesGelatoBundler(crossmintChain)) {
+            return { ...txnParams, maxFeePerGas: "0x0" as any, maxPriorityFeePerGas: "0x0" as any };
+        }
+
+        return txnParams;
+    }
+}

package/src/blockchain/wallets/eoa.ts

@@ -0,0 +1,49 @@
+import { EOASignerData } from "@/types/API";
+import type { EOASigner, WalletParams } from "@/types/Config";
+import { AccountAndSigner, WalletCreationParams } from "@/types/internal";
+import { equalsIgnoreCase } from "@/utils/helpers";
+import { createOwnerSigner } from "@/utils/signer";
+import { signerToEcdsaValidator } from "@zerodev/ecdsa-validator";
+import { createKernelAccount } from "@zerodev/sdk";
+
+import { AdminMismatchError } from "../../error";
+
+export interface EOAWalletParams extends WalletCreationParams {
+    walletParams: WalletParams & { signer: EOASigner };
+}
+
+export class EOAAccountService {
+    public async get(
+        { chain, publicClient, entryPoint, walletParams, kernelVersion, user }: EOAWalletParams,
+        existingSignerConfig?: EOASignerData
+    ): Promise<AccountAndSigner> {
+        const eoa = await createOwnerSigner({
+            chain,
+            walletParams,
+        });
+
+        if (existingSignerConfig != null && !equalsIgnoreCase(eoa.address, existingSignerConfig.eoaAddress)) {
+            throw new AdminMismatchError(
+                `User '${user.id}' has an existing wallet with an eoa signer '${existingSignerConfig.eoaAddress}', this does not match input eoa signer '${eoa.address}'.`,
+                existingSignerConfig,
+                { type: "eoa", eoaAddress: existingSignerConfig.eoaAddress }
+            );
+        }
+
+        const ecdsaValidator = await signerToEcdsaValidator(publicClient, {
+            signer: eoa,
+            entryPoint: entryPoint.address,
+            kernelVersion,
+        });
+        const account = await createKernelAccount(publicClient, {
+            plugins: {
+                sudo: ecdsaValidator,
+            },
+            index: BigInt(0),
+            entryPoint: entryPoint.address,
+            kernelVersion,
+        });
+
+        return { account, signerData: { eoaAddress: eoa.address, type: "eoa" } };
+    }
+}

package/src/blockchain/wallets/index.ts

@@ -0,0 +1 @@
+export * from "./EVMSmartWallet";

package/src/blockchain/wallets/passkey.ts

@@ -0,0 +1,117 @@
+import type { CrossmintWalletService } from "@/api/CrossmintWalletService";
+import { type PasskeySignerData, displayPasskey } from "@/types/API";
+import type { PasskeySigner, UserParams, WalletParams } from "@/types/Config";
+import type { AccountAndSigner, PasskeyValidatorSerializedData, WalletCreationParams } from "@/types/internal";
+import { PasskeyValidatorContractVersion, WebAuthnMode, toPasskeyValidator } from "@zerodev/passkey-validator";
+import { type KernelValidator, createKernelAccount } from "@zerodev/sdk";
+import { WebAuthnKey, toWebAuthnKey } from "@zerodev/webauthn-key";
+import type { EntryPoint } from "permissionless/types/entrypoint";
+
+import { PasskeyMismatchError } from "../../error";
+
+export interface PasskeyWalletParams extends WalletCreationParams {
+    walletParams: WalletParams & { signer: PasskeySigner };
+}
+
+export function isPasskeyParams(params: WalletCreationParams): params is PasskeyWalletParams {
+    return (params.walletParams.signer as PasskeySigner).type === "PASSKEY";
+}
+
+type PasskeyValidator = KernelValidator<EntryPoint, "WebAuthnValidator"> & {
+    getSerializedData: () => string;
+};
+
+export class PasskeyAccountService {
+    constructor(private readonly crossmintService: CrossmintWalletService) {}
+
+    public async get(
+        { user, publicClient, walletParams, entryPoint, kernelVersion }: PasskeyWalletParams,
+        existingSignerConfig?: PasskeySignerData
+    ): Promise<AccountAndSigner> {
+        const inputPasskeyName = walletParams.signer.passkeyName ?? user.id;
+        if (existingSignerConfig != null && existingSignerConfig.passkeyName !== inputPasskeyName) {
+            throw new PasskeyMismatchError(
+                `User '${user.id}' has an existing wallet created with a passkey named '${existingSignerConfig.passkeyName}', this does match input passkey name '${inputPasskeyName}'.`,
+                displayPasskey(existingSignerConfig)
+            );
+        }
+
+        const passkey = await this.getPasskey(user, inputPasskeyName, existingSignerConfig);
+
+        const latestValidatorVersion = PasskeyValidatorContractVersion.V0_0_2;
+        const validatorContractVersion =
+            existingSignerConfig == null ? latestValidatorVersion : existingSignerConfig.validatorContractVersion;
+        const validator = await toPasskeyValidator(publicClient, {
+            webAuthnKey: passkey,
+            entryPoint: entryPoint.address,
+            validatorContractVersion,
+            kernelVersion,
+        });
+
+        const kernelAccount = await createKernelAccount(publicClient, {
+            plugins: { sudo: validator },
+            entryPoint: entryPoint.address,
+            kernelVersion,
+        });
+
+        return {
+            signerData: this.getSignerData(validator, validatorContractVersion, inputPasskeyName),
+            account: kernelAccount,
+        };
+    }
+
+    private async getPasskey(
+        user: UserParams,
+        passkeyName: string,
+        existing?: PasskeySignerData
+    ): Promise<WebAuthnKey> {
+        if (existing != null) {
+            return {
+                pubX: BigInt(existing.pubKeyX),
+                pubY: BigInt(existing.pubKeyY),
+                authenticatorId: existing.authenticatorId,
+                authenticatorIdHash: existing.authenticatorIdHash,
+            };
+        }
+
+        return toWebAuthnKey({
+            passkeyName,
+            passkeyServerUrl: this.crossmintService.getPasskeyServerUrl(),
+            mode: WebAuthnMode.Register,
+            passkeyServerHeaders: this.createPasskeysServerHeaders(user),
+        });
+    }
+
+    private getSignerData(
+        validator: PasskeyValidator,
+        validatorContractVersion: PasskeyValidatorContractVersion,
+        passkeyName: string
+    ): PasskeySignerData {
+        return {
+            ...deserializePasskeyValidatorData(validator.getSerializedData()),
+            passkeyName,
+            validatorContractVersion,
+            domain: window.location.hostname,
+            type: "passkeys",
+        };
+    }
+
+    private createPasskeysServerHeaders(user: UserParams) {
+        return {
+            "x-api-key": this.crossmintService.crossmintAPIHeaders["x-api-key"],
+            Authorization: `Bearer ${user.jwt}`,
+        };
+    }
+}
+
+const deserializePasskeyValidatorData = (params: string) => {
+    const uint8Array = base64ToBytes(params);
+    const jsonString = new TextDecoder().decode(uint8Array);
+
+    return JSON.parse(jsonString) as PasskeyValidatorSerializedData;
+};
+
+function base64ToBytes(base64: string) {
+    const binString = atob(base64);
+    return Uint8Array.from(binString, (m) => m.codePointAt(0) as number);
+}

package/src/blockchain/wallets/paymaster.ts

@@ -0,0 +1,49 @@
+import { PAYMASTER_RPC, PM_BASE_RPC, PM_BASE_SEPOLIA_RPC } from "@/utils/constants";
+import { createZeroDevPaymasterClient } from "@zerodev/sdk";
+import { Middleware } from "permissionless/actions/smartAccount";
+import { EntryPoint } from "permissionless/types/entrypoint";
+import { http } from "viem";
+
+import { EVMBlockchainIncludingTestnet } from "@crossmint/common-sdk-base";
+
+import { usesGelatoBundler } from "../../utils/blockchain";
+import { getViemNetwork, getZeroDevProjectIdByBlockchain } from "../BlockchainNetworks";
+
+export function usePaymaster(chain: EVMBlockchainIncludingTestnet) {
+    return !usesGelatoBundler(chain);
+}
+
+const getPaymasterRPC = (chain: EVMBlockchainIncludingTestnet) => {
+    switch (chain) {
+        case EVMBlockchainIncludingTestnet.BASE_SEPOLIA:
+            return PM_BASE_SEPOLIA_RPC;
+        case EVMBlockchainIncludingTestnet.BASE:
+            return PM_BASE_RPC;
+        default:
+            return PAYMASTER_RPC + getZeroDevProjectIdByBlockchain(chain) + "?paymasterProvider=STACKUP";
+    }
+};
+
+export function paymasterMiddleware({
+    entryPoint,
+    chain,
+}: {
+    entryPoint: EntryPoint;
+    chain: EVMBlockchainIncludingTestnet;
+}): Middleware<EntryPoint> {
+    return {
+        middleware: {
+            sponsorUserOperation: async ({ userOperation }) => {
+                const paymasterClient = createZeroDevPaymasterClient({
+                    chain: getViemNetwork(chain),
+                    transport: http(getPaymasterRPC(chain)),
+                    entryPoint,
+                });
+                return paymasterClient.sponsorUserOperation({
+                    userOperation,
+                    entryPoint,
+                });
+            },
+        },
+    };
+}