@gasfree-kit/evm-4337 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -40,6 +40,54 @@ declare const GAS_FEE_FALLBACKS: Record<string, bigint>;
 /** Fallback fee estimates as human-readable strings. */
 declare const GAS_FEE_ESTIMATES: Record<string, string>;
 
+/** Passkey credential data — app developer must persist this (or use 'persist' storage mode). */
+interface PasskeyCredential {
+    /** WebAuthn credential ID (base64url encoded) */
+    id: string;
+    /** P256 public key coordinates from WebAuthn attestation */
+    publicKey: {
+        x: bigint;
+        y: bigint;
+    };
+    /** On-chain SafeWebAuthnSigner contract address */
+    signerAddress: string;
+    /** The Safe smart account this passkey is linked to */
+    safeAddress: string;
+}
+/** Storage mode for passkey credentials. */
+type PasskeyStorageMode = 'persist' | 'not_persist';
+/** Result from linking a passkey to a Safe. */
+interface PasskeyLinkResult {
+    /** Passkey credential — always returned regardless of storage mode */
+    credential: PasskeyCredential;
+    /** Safe smart account address */
+    safeAddress: string;
+    /** Transaction hash of the addOwner operation */
+    transactionHash: string;
+    /** Whether the SDK persisted the credential internally */
+    persisted: boolean;
+}
+/** Options for passkey registration and linking. */
+interface PasskeyOptions {
+    /** Relying party ID (defaults to window.location.hostname) */
+    rpId?: string;
+    /** Relying party display name */
+    rpName?: string;
+    /** User display name for the passkey credential */
+    userName?: string;
+    /** Credential storage mode. Default: 'not_persist'. Convenience only; not secure storage. */
+    storage?: PasskeyStorageMode;
+}
+/** Config extending EVM4337ClientConfig with passkey-specific options. */
+interface PasskeyConfig extends EVM4337ClientConfig {
+    /** WebAuthn and passkey registration options */
+    passkeyOptions?: PasskeyOptions;
+}
+/** Pre-deployed SafeWebAuthnSignerFactory addresses per chain. */
+declare const SAFE_WEBAUTHN_SIGNER_FACTORY: Record<string, string>;
+/** Pre-deployed FCLP256Verifier addresses per chain. */
+declare const FCL_P256_VERIFIER: Record<string, string>;
+
 /**
  * Set up an ERC-4337 wallet via WDK.
  *
@@ -47,21 +95,17 @@ declare const GAS_FEE_ESTIMATES: Record<string, string>;
  * correct discriminated-union config:
  * - Sponsored mode → EvmErc4337WalletSponsorshipPolicyConfig
  * - Non-sponsored  → EvmErc4337WalletPaymasterTokenConfig
+ *
+ * Optionally links a passkey to the Safe account when passkeyOptions is provided.
  */
-declare function setupErc4337Wallet(seedPhrase: string, config: EVM4337ClientConfig, accountIndex?: number): Promise<{
+declare function setupErc4337Wallet(seedPhrase: string, config: EVM4337ClientConfig, accountIndex?: number, passkeyOptions?: PasskeyOptions): Promise<{
     wallet: _tetherto_wdk_wallet_evm_erc_4337.default;
     account: _tetherto_wdk_wallet_evm_erc_4337.EvmAccount;
     address: string;
+    passkey: PasskeyLinkResult | undefined;
 }>;
 
-declare class TetherEVMERC4337Transfer {
-    /** Default timeout for UserOp confirmation: 120 seconds. */
-    private static readonly USER_OP_TIMEOUT_MS;
-    /**
-     * Wait for a UserOperation to be included on-chain via the Candide bundler.
-     * Times out after USER_OP_TIMEOUT_MS to prevent indefinite hangs.
-     */
-    private static waitForUserOpConfirmation;
+declare class EvmTransfer {
     /**
      * Get transaction fee estimate for a USDT transfer.
      *
@@ -117,10 +161,6 @@ declare class TetherEVMERC4337Transfer {
             amount: string;
         }[];
     }>;
-    /**
-     * Map raw errors into user-friendly messages.
-     */
-    static handleTransferError(error: unknown, chain: string): Error;
 }
 
 /**
@@ -143,4 +183,111 @@ declare function encodeErc20Transfer(to: string, amount: bigint): string;
  */
 declare function feeToUsdt(feeInWei: bigint, nativeTokenPriceUsdt: number): string;
 
-export { type EVM4337ClientConfig, type EvmErc4337NetworkConfig, GAS_FEE_ESTIMATES, GAS_FEE_FALLBACKS, TetherEVMERC4337Transfer, encodeErc20Transfer, feeToUsdt, formatTokenBalance, getErc4337ConfigForChain, setupErc4337Wallet, toUsdtBaseUnitsEvm };
+/**
+ * Wait for a UserOperation to be included on-chain via the Candide bundler.
+ * Times out after USER_OP_TIMEOUT_MS to prevent indefinite hangs.
+ */
+declare function waitForUserOpConfirmation(userOpHash: string, bundlerUrl: string, entryPointAddress: string): Promise<string>;
+/**
+ * Map raw errors into user-friendly messages.
+ */
+declare function handleTransferError(error: unknown, chain: string): Error;
+
+/**
+ * Register a new passkey via WebAuthn and link it to an existing Safe account.
+ *
+ * 1. Validates the Safe is deployed on-chain
+ * 2. Registers a new WebAuthn passkey (triggers biometric prompt)
+ * 3. Checks the signer is not already a Safe owner
+ * 4. Deploys the SafeWebAuthnSigner contract on-chain via the factory
+ * 5. Adds the signer as a Safe owner with threshold 1 (1-of-2)
+ *
+ * The seed phrase signs both the deploy and addOwner transactions.
+ */
+declare function linkPasskeyToSafe(seedPhrase: string, config: EVM4337ClientConfig, passkeyOptions?: PasskeyOptions, accountIndex?: number): Promise<PasskeyLinkResult>;
+/**
+ * Check if a Safe account already has a passkey signer linked.
+ *
+ * Fix #5: properly disposes wallet/account resources.
+ */
+declare function isPasskeyLinked(seedPhrase: string, config: EVM4337ClientConfig, accountIndex?: number): Promise<{
+    linked: boolean;
+    signerAddress?: string;
+}>;
+/**
+ * Remove a passkey signer from the Safe.
+ * Signs the removeOwner tx with the seed phrase.
+ *
+ * Fix #1: Queries the actual Safe owner list to determine the correct
+ * previous owner in the linked list, instead of hardcoding SENTINEL.
+ */
+declare function unlinkPasskeyFromSafe(seedPhrase: string, config: EVM4337ClientConfig, credential: PasskeyCredential, accountIndex?: number): Promise<{
+    transactionHash: string;
+}>;
+
+/**
+ * Passkey-signed ERC-4337 transfers via Safe account.
+ *
+ * Uses Safe4337Pack from @safe-global/relay-kit to handle the full
+ * UserOperation lifecycle: construction, passkey signing (WebAuthn biometric),
+ * paymaster integration, and bundler submission.
+ *
+ * The passkey must first be linked to the Safe via `linkPasskeyToSafe()`.
+ */
+declare class PasskeyTransfer {
+    /**
+     * Send a single token transfer signed by passkey.
+     * Triggers biometric authentication via WebAuthn.
+     */
+    static sendToken(credential: PasskeyCredential, config: EVM4337ClientConfig, tokenAddress: string, amount: string, recipientAddress: string): Promise<{
+        success: boolean;
+        transactionHash: string;
+        chain: _gasfree_kit_core.EvmChain;
+        amount: string;
+    }>;
+    /**
+     * Send a batch token transfer to multiple recipients, signed by passkey.
+     */
+    static sendBatchToken(credential: PasskeyCredential, config: EVM4337ClientConfig, tokenAddress: string, recipients: Array<{
+        address: string;
+        amount: string;
+    }>): Promise<{
+        success: boolean;
+        transactionHash: string;
+        chain: _gasfree_kit_core.EvmChain;
+        recipients: {
+            address: string;
+            amount: string;
+        }[];
+    }>;
+    /**
+     * Check token balance for a passkey-linked Safe account.
+     * Does NOT require biometric — balance is publicly readable via RPC.
+     */
+    static checkTokenBalance(credential: PasskeyCredential, config: EVM4337ClientConfig, tokenAddress: string): Promise<{
+        message: string;
+        success: boolean;
+        data: {
+            tokenBalance: string;
+            decimals: number;
+            usdBalance: string;
+        };
+    }>;
+}
+
+/** Interface for passkey credential persistence. */
+interface CredentialStore {
+    save(credential: PasskeyCredential): Promise<void>;
+    load(safeAddress: string): Promise<PasskeyCredential | null>;
+    remove(safeAddress: string): Promise<void>;
+    listAll(): Promise<PasskeyCredential[]>;
+}
+/**
+ * Auto-detect environment and return the appropriate credential store.
+ *
+ * Fix #10: Stricter browser detection — checks for navigator.credentials
+ * to avoid false positives in SSR/jsdom environments.
+ */
+declare function createCredentialStore(): CredentialStore;
+
+export { type CredentialStore, type EVM4337ClientConfig, type EvmErc4337NetworkConfig, EvmTransfer, FCL_P256_VERIFIER, GAS_FEE_ESTIMATES, GAS_FEE_FALLBACKS, type PasskeyConfig, type PasskeyCredential, type PasskeyLinkResult, type PasskeyOptions, type PasskeyStorageMode, PasskeyTransfer, SAFE_WEBAUTHN_SIGNER_FACTORY, createCredentialStore, encodeErc20Transfer, feeToUsdt, formatTokenBalance, getErc4337ConfigForChain, handleTransferError, isPasskeyLinked, linkPasskeyToSafe, setupErc4337Wallet, toUsdtBaseUnitsEvm, unlinkPasskeyFromSafe, waitForUserOpConfirmation };