@coinbase/cdp-core 0.0.98 → 0.0.100

package/dist/native-types/viem/signAndWrapTypedData.d.ts

@@ -1,20 +1,127 @@
 import { Hash } from 'viem';
 import { EvmAddress, Hex, EIP712TypedData } from '../types.js';
+/**
+ * Options for signing and wrapping EIP-712 typed data with a smart account.
+ */
 export interface SignAndWrapTypedDataForSmartAccountOptions {
+    /** The smart account to sign with. */
     smartAccount: EvmAddress;
+    /** The owner address to sign with. */
     ownerAddress: EvmAddress;
+    /** The hash to sign. */
     hash: Hash;
+    /** The chain ID to sign with. */
     chainId: number;
 }
+/**
+ * Result of signing and wrapping typed data for a smart account.
+ */
 export interface SignAndWrapTypedDataForSmartAccountResult {
+    /** The signature ready for smart contract use. */
     signature: Hex;
 }
+/**
+ * Signs and wraps an EIP-712 message for a smart account using the required Coinbase Smart Wallet signature format.
+ *
+ * **Important: Coinbase Smart Wallet Contract Requirements**
+ *
+ * Due to the Coinbase Smart Wallet contract implementation (ERC-1271), CDP Smart Wallets have
+ * specific requirements for EIP-712 message signing:
+ *
+ * 1. **Replay-Safe Hashing**: All typed messages must be wrapped in a replay-safe hash that
+ *    includes the chain ID and smart account address. This prevents the same signature from
+ *    being valid across different chains or accounts.
+ *
+ * 2. **Signature Wrapping**: The resulting signature must be wrapped in a `SignatureWrapper`
+ *    struct that identifies which owner signed and contains the signature data in the format
+ *    expected by the smart contract's `isValidSignature()` method.
+ *
+ * This function handles both requirements automatically, making it safe and convenient for
+ * developers to sign EIP-712 messages with CDP Smart Wallets.
+ *
+ * @param {SignAndWrapTypedDataForSmartAccountOptions} options - Parameters for signing and wrapping the EIP-712 message.
+ * @returns A promise that resolves to the signature that can be used with smart contracts.
+ *
+ * @example
+ * ```ts
+ * const result = await signAndWrapTypedDataForSmartAccount({
+ *   smartAccount: smartAccount,
+ *   chainId: 1n,
+ *   ownerAddress: ownerAddress,
+ *   typedData: {
+ *     domain: {
+ *       name: "Permit2",
+ *       chainId: 1,
+ *       verifyingContract: "0x000000000022D473030F116dDEE9F6B43aC78BA3",
+ *     },
+ *     types: {
+ *       EIP712Domain: [
+ *         { name: "name", type: "string" },
+ *         { name: "chainId", type: "uint256" },
+ *         { name: "verifyingContract", type: "address" },
+ *       ],
+ *       PermitTransferFrom: [
+ *         { name: "permitted", type: "TokenPermissions" },
+ *         { name: "spender", type: "address" },
+ *         { name: "nonce", type: "uint256" },
+ *         { name: "deadline", type: "uint256" },
+ *       ],
+ *       TokenPermissions: [
+ *         { name: "token", type: "address" },
+ *         { name: "amount", type: "uint256" },
+ *       ],
+ *     },
+ *     primaryType: "PermitTransferFrom",
+ *     message: {
+ *       permitted: {
+ *         token: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ *         amount: "1000000",
+ *       },
+ *       spender: "0xFfFfFfFFfFFfFFfFFfFFFFFffFFFffffFfFFFfFf",
+ *       nonce: "0",
+ *       deadline: "1717123200",
+ *     },
+ *   },
+ * });
+ *
+ * // Use result.signature for smart contract calls
+ * console.log(`Signature: ${result.signature}`);
+ * ```
+ */
 export declare function signAndWrapTypedDataForSmartAccount(options: SignAndWrapTypedDataForSmartAccountOptions): Promise<SignAndWrapTypedDataForSmartAccountResult>;
+/**
+ * Creates a replay-safe EIP-712 typed data structure by wrapping the original typed data with
+ * chain ID and smart account address.
+ *
+ * **Coinbase Smart Wallet Requirement**: Due to the Coinbase Smart Wallet contract's ERC-1271
+ * implementation, all EIP-712 messages must be wrapped in a replay-safe hash before signing.
+ * This prevents signature replay attacks across different chains or smart account addresses.
+ *
+ * The smart contract's `isValidSignature()` method expects signatures to be validated against
+ * this replay-safe hash, not the original message hash.
+ *
+ * @param params - The replay-safe hash parameters
+ * @param params.hash - The hash to sign
+ * @param params.chainId - The chain ID to sign with
+ * @param params.smartAccountAddress - The smart account address for additional context
+ * @returns The EIP-712 typed data structure for the replay-safe hash
+ */
 export declare function createReplaySafeTypedData({ hash, chainId, smartAccountAddress, }: {
     hash: Hash;
     chainId: number;
     smartAccountAddress: EvmAddress;
 }): EIP712TypedData;
+/**
+ * Builds a signature wrapper for Coinbase Smart Wallets by decomposing a hex signature
+ * into r, s, v components and encoding them in the format expected by the smart contract.
+ *
+ * All signatures on Coinbase Smart Wallets must be wrapped in this format to identify
+ * which owner signed and provide the signature data.
+ *
+ * @param params - The signature parameters
+ * @param params.signatureHex - The hex signature to wrap (65 bytes: r + s + v)
+ * @returns The encoded signature wrapper in the format expected by the smart contract
+ */
 export declare function createSmartAccountSignatureWrapper({ signatureHex }: {
     signatureHex: Hex;
 }): Hex;

package/dist/native-types/viem/toViemAccount.d.ts

@@ -1,2 +1,17 @@
 import { Address, LocalAccount } from 'viem';
+/**
+ * Converts a CDP EVM account into a Viem-compatible LocalAccount.
+ * This enables the CDP account to be used with any library or framework that accepts Viem accounts.
+ *
+ * @param address - The EVM address to create a Viem account for
+ * @returns A Viem LocalAccount that can sign messages and transactions using CDP's signing functions
+ * @throws If the user is not authenticated or the address is not in the user's EVM accounts
+ *
+ * @example
+ * ```typescript lines
+ * const user = await getCurrentUser();
+ * const evmAccount = user.evmAccountObjects[0]?.address;
+ * const viemAccount = await toViemAccount(evmAccount);
+ * ```
+ */
 export declare function toViemAccount(address: Address): LocalAccount;

package/dist/types/actions/authenticateWithJWT.d.ts

@@ -1,4 +1,68 @@
 import { AuthenticateWithJWTResult } from '../types.js';
+/**
+ * Authenticates an end user using a developer-issued JWT from a third-party identity provider
+ * (e.g., Auth0, Firebase, Cognito, custom OIDC).
+ *
+ * This function validates the JWT, auto-creates the user if they don't exist, and provisions
+ * wallets based on your configuration.
+ *
+ * @param options - Optional options for the authentication.
+ * @param options.idempotencyKey - Optional idempotency key for safe retries.
+ *
+ * **Important**: Before using this function, you must:
+ * 1. Configure custom auth in the CDP Portal (JWKS endpoint, issuer, etc.)
+ * 2. Provide a `customAuth.getJwt` callback in your config to handle JWT refresh
+ *
+ * @example
+ * ```typescript lines
+ * // React - With Auth0
+ * import { useAuth0 } from '@auth0/auth0-react';
+ * import { initialize, authenticateWithJWT } from '@coinbase/cdp-core';
+ *
+ * const { getAccessTokenSilently } = useAuth0();
+ *
+ * await initialize({
+ *   projectId: 'my-project',
+ *   customAuth: {
+ *     getJwt: getAccessTokenSilently
+ *   },
+ *   ethereum: { createOnLogin: 'eoa' }
+ * });
+ *
+ * const result = await authenticateWithJWT();
+ * console.log(result.user); // Authenticated user with wallet
+ * ```
+ *
+ * @example
+ * ```typescript lines
+ * // React Native - With Auth0
+ * import { useAuth0 } from 'react-native-auth0';
+ * import { initialize, authenticateWithJWT } from '@coinbase/cdp-core';
+ *
+ * const { authorize, getCredentials } = useAuth0();
+ *
+ * await initialize({
+ *   projectId: 'my-project',
+ *   customAuth: {
+ *     getJwt: async () => {
+ *       const creds = await getCredentials();
+ *       return creds?.accessToken;
+ *     }
+ *   },
+ *   ethereum: { createOnLogin: 'eoa' }
+ * });
+ *
+ * // User clicks sign in - triggers Auth0 login
+ * await authorize();
+ *
+ * // Then authenticate with CDP
+ * const result = await authenticateWithJWT();
+ * console.log(result.user); // Authenticated user with wallet
+ * ```
+ *
+ * @returns The authentication result with user and wallet information
+ * @throws {CustomAuthError} If customAuth.getJwt callback is not configured or JWT retrieval fails
+ */
 export declare const authenticateWithJWT: (options?: {
     idempotencyKey?: string;
 }) => Promise<AuthenticateWithJWTResult>;

package/dist/types/actions/cancelMfaVerification.d.ts

@@ -1 +1,20 @@
+/**
+ * Cancels the current MFA verification flow.
+ *
+ * Call this when the user dismisses the MFA UI without completing verification.
+ * The original operation that triggered MFA will reject with an error.
+ *
+ * @example
+ * ```typescript
+ * // In your MFA modal's cancel button handler
+ * function MfaModal() {
+ *   const handleCancel = () => {
+ *     cancelMfaVerification();
+ *     closeModal();
+ *   };
+ *
+ *   return <button onClick={handleCancel}>Cancel</button>;
+ * }
+ * ```
+ */
 export declare const cancelMfaVerification: () => void;

package/dist/types/actions/createDelegation.d.ts

@@ -1,8 +1,26 @@
+/**
+ * Options for creating a delegation that allows a developer to sign on behalf of an end user.
+ */
 export type CreateDelegationOptions = {
+    /** The date until which the delegation is valid (ISO 8601 string). */
     expiresAt: string;
+    /** Optional idempotency key for safe retries. */
     idempotencyKey?: string;
 };
+/**
+ * Result of creating a delegation for an end user.
+ */
 export type CreateDelegationResult = {
+    /** The unique identifier for the delegation. */
     delegationId: string;
 };
+/**
+ * Creates a delegation that allows a developer to sign on behalf of an end user for the specified duration.
+ * The end user must be authenticated to authorize this delegation.
+ *
+ * @param options - Options for creating the delegation.
+ * @returns The delegation ID.
+ * @throws {InputValidationError} If `expiresAt` is not a valid date or is not in the future.
+ * @throws Error if the user is not signed in.
+ */
 export declare function createDelegation(options: CreateDelegationOptions): Promise<CreateDelegationResult>;

package/dist/types/actions/createEvmEip7702Delegation.d.ts

@@ -1,12 +1,39 @@
 import { EvmAddress } from '../types.js';
 import { EvmEip7702DelegationNetwork } from '@coinbase/cdp-api-client';
+/**
+ * Result of creating an EIP-7702 delegation.
+ */
 export type CreateEvmEip7702DelegationResult = {
+    /** The unique identifier for the delegation operation. Use this to poll the operation status. */
     delegationOperationId: string;
 };
+/**
+ * Options for creating an EIP-7702 delegation for an EVM EOA account.
+ */
 export type CreateEvmEip7702DelegationOptions = {
+    /** The 0x-prefixed address of the EVM EOA account to delegate. Must belong to the current user. */
     address: EvmAddress;
+    /** The network to create the delegation on. */
     network: EvmEip7702DelegationNetwork;
+    /**
+     * Whether to configure spend permissions for the upgraded, delegated account.
+     * When enabled, the account can grant permissions for third parties to spend on its behalf.
+     * Defaults to false.
+     */
     enableSpendPermissions?: boolean;
+    /** Optional idempotency key for safe retries. */
     idempotencyKey?: string;
 };
+/**
+ * Creates an EIP-7702 delegation for an end user's EVM EOA account, upgrading it with smart account capabilities.
+ *
+ * This endpoint retrieves delegation artifacts from onchain, signs the EIP-7702 authorization,
+ * submits a Type 4 transaction, and creates an associated smart account object. After success,
+ * the local auth state is refreshed so the new smart account appears in the user's account list.
+ *
+ * @param options - Options for creating the EIP-7702 delegation.
+ * @returns The delegation operation ID for polling the operation status.
+ * @throws Error if the user is not signed in.
+ * @throws Error if the address does not belong to the current user.
+ */
 export declare function createEvmEip7702Delegation(options: CreateEvmEip7702DelegationOptions): Promise<CreateEvmEip7702DelegationResult>;

package/dist/types/actions/createEvmEoaAccount.d.ts

@@ -1,5 +1,17 @@
 import { Address } from 'viem';
+/**
+ * Options for creating an EVM EOA account.
+ */
 export type CreateEvmEoaAccountOptions = {
+    /** Optional idempotency key for safe retries. */
     idempotencyKey?: string;
 };
+/**
+ * Creates an EVM EOA (Externally Owned Account) for the current user.
+ * Multiple EVM EOA accounts can be created per user.
+ *
+ * @param options - Optional options for creating the account.
+ * @returns The address of the newly created EVM EOA account.
+ * @throws Error if the user is not signed in.
+ */
 export declare function createEvmEoaAccount(options?: CreateEvmEoaAccountOptions): Promise<Address>;

package/dist/types/actions/createEvmSmartAccount.d.ts

@@ -1,7 +1,32 @@
 import { EvmAddress } from '../types.js';
+/**
+ * Options for creating a Smart Account.
+ */
 export type CreateEvmSmartAccountOptions = {
+    /**
+     * Optional owner address for the smart account.
+     * If not provided, a new EOA will be created as the owner.
+     * If the owner already controls a smart account, an error will be thrown.
+     */
     owner?: EvmAddress;
+    /**
+     * Whether to enable spend permissions for the smart account.
+     * Setting this to true is necessary in order to create spend permissions.
+     * Only new accounts can be created with spend permissions enabled.
+     * Defaults to false.
+     */
     enableSpendPermissions?: boolean;
+    /** Optional idempotency key for safe retries. */
     idempotencyKey?: string;
 };
+/**
+ * Creates an EVM Smart Account for the current user.
+ * Multiple EVM Smart Accounts can be created per user.
+ * If no owner is provided, a new EVM EOA account will be created automatically as the owner.
+ *
+ * @param options - Options for creating the EVM Smart Account.
+ * @returns The address of the newly created EVM Smart Account.
+ * @throws Error if the user is not signed in.
+ * @throws Error if the provided owner already controls a smart account.
+ */
 export declare function createEvmSmartAccount(options?: CreateEvmSmartAccountOptions): Promise<EvmAddress>;

package/dist/types/actions/createKeyExportIframe.d.ts

@@ -1,18 +1,166 @@
 import { SecureIframeStatus, SecureIframeTheme } from '../secureIframe/types.js';
+/**
+ * Options for setting up a key export iframe.
+ */
 export interface CreateKeyExportIframeOptions {
+    /**
+     * The address of the account to export.
+     */
     address: string;
+    /**
+     * The target element: either a CSS selector string or an HTMLElement container.
+     * An iframe will be created and appended to the target container.
+     */
     target: string | HTMLElement;
+    /**
+     * The project ID for authentication.
+     */
     projectId: string;
+    /**
+     * The label for the button displayed in the iframe.
+     */
     label?: string;
+    /**
+     * The label to display when the key is copied successfully.
+     */
     copiedLabel?: string;
+    /**
+     * Whether to show an icon in the button.
+     *
+     * @default true
+     */
     icon?: boolean;
+    /**
+     * Theme overrides for the iframe button.
+     */
     theme?: Partial<SecureIframeTheme>;
+    /**
+     * Callback invoked when the iframe status changes.
+     */
     onStatusUpdate?: (status: SecureIframeStatus, message?: string) => void;
 }
+/**
+ * Result of setting up a key export iframe.
+ */
 export interface CreateKeyExportIframeResult {
+    /**
+     * The iframe element that was set up.
+     */
     iframe: HTMLIFrameElement;
+    /**
+     * Function to clean up event listeners and remove the iframe.
+     */
     cleanup: () => void;
+    /**
+     * Function to update the theme of the iframe.
+     */
     updateTheme: (theme: Partial<SecureIframeTheme>) => void;
 }
+/**
+ * Sets up a secure iframe for exporting EVM private keys.
+ *
+ * This function handles the communication with a secure iframe that safely
+ * exports EVM private keys to the user's clipboard without exposing them to the
+ * JavaScript context.
+ *
+ * The iframe will be automatically cleaned up when the session expires (status "expired").
+ * The `cleanup` function is idempotent, so it's safe to call it in your teardown code
+ * even if the iframe has already been cleaned up due to expiration.
+ *
+ * @param {CreateKeyExportIframeOptions} options - Configuration options for the EVM key export iframe.
+ * @returns {CreateKeyExportIframeResult} An object containing the iframe element, cleanup function, and theme update function.
+ *
+ * @example
+ * ```typescript
+ * // Using a CSS selector for the container
+ * const { iframe, cleanup } = await createEvmKeyExportIframe({
+ *   address: "0x1234...",
+ *   target: "#key-export-container",
+ *   projectId: "your-project-id",
+ *   label: "Copy Private Key",
+ *   onStatusUpdate: (status, message) => {
+ *     if (status === "success") {
+ *       console.log("Key copied!");
+ *     } else if (status === "error") {
+ *       console.error("Error:", message);
+ *     }
+ *   }
+ * });
+ *
+ * // Later, clean up. Iframe will auto cleanup when it expires.
+ * cleanup();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using an HTMLElement container directly
+ * const container = document.getElementById("my-container") as HTMLElement;
+ * const { cleanup, updateTheme } = await createEvmKeyExportIframe({
+ *   address: "0x1234...",
+ *   target: container,
+ *   projectId: "your-project-id",
+ *   theme: {
+ *     buttonBg: "#0052ff",
+ *     buttonText: "#ffffff"
+ *   }
+ * });
+ *
+ * // Update theme later
+ * updateTheme({ buttonBg: "#ff0000" });
+ * ```
+ */
 export declare function createEvmKeyExportIframe(options: CreateKeyExportIframeOptions): Promise<CreateKeyExportIframeResult>;
+/**
+ * Sets up a secure iframe for exporting Solana private keys.
+ *
+ * This function handles the communication with a secure iframe that safely
+ * exports Solana private keys to the user's clipboard without exposing them to the
+ * JavaScript context.
+ *
+ * The iframe will be automatically cleaned up when the session expires (status "expired").
+ * The `cleanup` function is idempotent, so it's safe to call it in your teardown code
+ * even if the iframe has already been cleaned up due to expiration.
+ *
+ * @param {CreateKeyExportIframeOptions} options - Configuration options for the Solana key export iframe.
+ * @returns {CreateKeyExportIframeResult} An object containing the iframe element, cleanup function, and theme update function.
+ *
+ * @example
+ * ```typescript
+ * // Using a CSS selector for the container
+ * const { iframe, cleanup } = await createSolanaKeyExportIframe({
+ *   address: "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
+ *   target: "#key-export-container",
+ *   projectId: "your-project-id",
+ *   label: "Copy Private Key",
+ *   onStatusUpdate: (status, message) => {
+ *     if (status === "success") {
+ *       console.log("Key copied!");
+ *     } else if (status === "error") {
+ *       console.error("Error:", message);
+ *     }
+ *   }
+ * });
+ *
+ * // Later, clean up. Iframe will auto cleanup when it expires.
+ * cleanup();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using an HTMLElement container directly
+ * const container = document.getElementById("my-container") as HTMLElement;
+ * const { cleanup, updateTheme } = await createSolanaKeyExportIframe({
+ *   address: "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
+ *   target: container,
+ *   projectId: "your-project-id",
+ *   theme: {
+ *     buttonBg: "#9945ff",
+ *     buttonText: "#ffffff"
+ *   }
+ * });
+ *
+ * // Update theme later
+ * updateTheme({ buttonBg: "#ff0000" });
+ * ```
+ */
 export declare function createSolanaKeyExportIframe(options: CreateKeyExportIframeOptions): Promise<CreateKeyExportIframeResult>;

package/dist/types/actions/createSolanaAccount.d.ts

@@ -1,5 +1,17 @@
 import { SolanaAddress } from '../types.js';
+/**
+ * Options for creating a Solana account.
+ */
 export type CreateSolanaAccountOptions = {
+    /** Optional idempotency key for safe retries. */
     idempotencyKey?: string;
 };
+/**
+ * Creates a Solana account for the current user.
+ * Multiple Solana accounts can be created per user.
+ *
+ * @param options - Optional options for creating the account.
+ * @returns The address of the newly created Solana account.
+ * @throws Error if the user is not signed in.
+ */
 export declare function createSolanaAccount(options?: CreateSolanaAccountOptions): Promise<SolanaAddress>;

package/dist/types/actions/createSpendPermission.d.ts

@@ -1,14 +1,50 @@
 import { SpendPermissionNetwork } from '@coinbase/cdp-api-client';
 import { SpendPermissionInput } from '../spend-permissions/types.js';
 import { EvmAddress, Hex } from '../types.js';
+/**
+ * Input for creating a spend permission.
+ * The permission owner is automatically detected from the current user.
+ */
 export type CreateSpendPermissionOptions = Omit<SpendPermissionInput, "account"> & {
+    /** The EVM Smart Account to create the spend permission for. */
     evmSmartAccount: EvmAddress;
+    /** The network to create the spend permission on. */
     network: SpendPermissionNetwork;
+    /**
+     * Whether to use the CDP Paymaster for the user operation.
+     *
+     * Only available on Base. Enabled by default on Base Sepolia.
+     */
     useCdpPaymaster?: boolean;
+    /** The URL of the paymaster to use for the user operation. */
     paymasterUrl?: string;
+    /** Optional idempotency key for safe retries. */
     idempotencyKey?: string;
 };
+/**
+ * Result of createSpendPermission.
+ */
 export type CreateSpendPermissionResult = {
+    /** The user operation hash. */
     userOperationHash: Hex;
 };
+/**
+ * Creates a spend permission for the user's EVM Smart Account.
+ *
+ * @param options - The options for creating the spend permission.
+ * @example
+ * ```typescript lines
+ * const result = await createSpendPermission({
+ *   network: "base-sepolia",
+ *   spender: "0x5678...",
+ *   token: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", // ETH
+ *   allowance: "1000000000000000000", // 1 ETH in wei
+ *   period: 86400, // 24 hours
+ *   start: Math.floor(Date.now() / 1000),
+ *   end: Math.floor(Date.now() / 1000) + 86400 * 30, // 30 days from now
+ *   useCdpPaymaster: true
+ * });
+ * ```
+ * @returns The result of the spend permission creation.
+ */
 export declare const createSpendPermission: (options: CreateSpendPermissionOptions) => Promise<CreateSpendPermissionResult>;