@gasfree-kit/evm-4337 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,338 @@
+# @gasfree-kit/evm-4337
+
+ERC-4337 USDT transfers for EVM chains using WDK-backed Safe smart accounts.
+
+This package gives you:
+
+- standard seed-phrase driven transfers
+- sponsored mode, where a paymaster covers gas
+- token-paid mode, where gas is charged in USDT
+- optional passkey linking and passkey-signed transfers
+
+## How It Works
+
+```
+ ┌──────────────────────┐
+ │       Your app       │
+ └──────────┬───────────┘
+            │
+            v
+ ┌──────────────────────┐
+ │ @gasfree-kit/evm-4337│
+ └──────────┬───────────┘
+            │
+            v
+ ┌──────────────────────┐       ┌──────────────────────┐
+ │  WDK wallet manager  │──────>│  Safe smart account   │
+ └──────────────────────┘       └──────────┬───────────┘
+                                           │
+                                           v
+                                ┌──────────────────────┐
+ ┌──────────────────────┐       │    UserOperation      │
+ │      Paymaster       │·····> │     (ERC-4337)        │
+ │                      │       └──────────┬───────────┘
+ │  sponsors gas or     │                  │
+ │  charges in USDT     │                  v
+ └──────────────────────┘       ┌──────────────────────┐
+                                │       Bundler         │
+                                └──────────┬───────────┘
+                                           │
+                                           v
+                                ┌──────────────────────┐
+                                │      EVM chain        │
+                                └──────────────────────┘
+```
+
+```mermaid
+flowchart TD
+  A["Your app"] --> B["@gasfree-kit/evm-4337"]
+  B --> C["WDK wallet manager"]
+  C --> D["Safe smart account"]
+  D --> E["ERC-4337 UserOperation"]
+  F["Paymaster"] -.->|sponsors or charges USDT| E
+  E --> G["Bundler"]
+  G --> H["EVM chain"]
+```
+
+## Supported Chains
+
+| Chain    | Chain ID | Typical fallback fee estimate |
+| -------- | -------- | ----------------------------- |
+| Ethereum | 1        | `1.40` USDT                   |
+| Base     | 8453     | `0.15` USDT                   |
+| Arbitrum | 42161    | `0.10` USDT                   |
+| Optimism | 10       | `0.10` USDT                   |
+| Polygon  | 137      | `0.10` USDT                   |
+| Celo     | 42220    | `0.05` USDT                   |
+| Plasma   | 9745     | `0.05` USDT                   |
+
+## Installation
+
+```bash
+npm install @gasfree-kit/evm-4337
+```
+
+Required peer dependency:
+
+```bash
+npm install @tetherto/wdk-wallet-evm-erc-4337
+```
+
+Optional passkey peer dependencies:
+
+```bash
+npm install @safe-global/protocol-kit @safe-global/relay-kit
+```
+
+## Choose Your Gas Mode
+
+| Mode       | When to use it                    | Required config                                  |
+| ---------- | --------------------------------- | ------------------------------------------------ |
+| Sponsored  | Your paymaster fully covers gas   | `isSponsored: true` and `sponsorshipPolicyId`    |
+| Token-paid | Gas is deducted from USDT balance | `isSponsored: false` and a paymaster/token setup |
+
+## Quick Start
+
+### 1. Create a config
+
+Sponsored mode:
+
+```ts
+import type { EVM4337ClientConfig } from '@gasfree-kit/evm-4337';
+
+const sponsoredConfig: EVM4337ClientConfig = {
+  chain: 'base',
+  rpcUrl: 'https://mainnet.base.org',
+  bundlerUrl: 'https://your-bundler.example.com',
+  paymasterUrl: 'https://your-paymaster.example.com',
+  isSponsored: true,
+  sponsorshipPolicyId: 'your-policy-id',
+};
+```
+
+Token-paid mode:
+
+```ts
+const tokenPaidConfig: EVM4337ClientConfig = {
+  chain: 'base',
+  rpcUrl: 'https://mainnet.base.org',
+  bundlerUrl: 'https://your-bundler.example.com',
+  paymasterUrl: 'https://your-paymaster.example.com',
+  isSponsored: false,
+  paymasterAddress: '0xYourPaymasterAddress',
+  // Optional:
+  // paymasterTokenAddress: '0xYourUSDTLikeToken'
+};
+```
+
+### 2. Generate a seed phrase
+
+```ts
+import { generateSeedPhrase } from '@gasfree-kit/core';
+
+const seedPhrase = await generateSeedPhrase();
+```
+
+### 3. Set up the Safe smart account
+
+```ts
+import { setupErc4337Wallet } from '@gasfree-kit/evm-4337';
+
+const { wallet, account, address } = await setupErc4337Wallet(seedPhrase, sponsoredConfig);
+
+console.log(address); // Safe address
+```
+
+### 4. Check balance
+
+```ts
+import { EvmTransfer } from '@gasfree-kit/evm-4337';
+import { EVM_CHAINS } from '@gasfree-kit/core';
+
+const balance = await EvmTransfer.checkTokenBalance(
+  seedPhrase,
+  sponsoredConfig,
+  EVM_CHAINS.base.usdtAddress,
+);
+
+console.log(balance.data.usdBalance);
+```
+
+### 5. Estimate fees
+
+```ts
+const estimate = await EvmTransfer.getTransactionEstimateFee(
+  seedPhrase,
+  sponsoredConfig,
+  '0x1111111111111111111111111111111111111111',
+);
+
+console.log(estimate.data.fee);
+```
+
+### 6. Send a transfer
+
+```ts
+const result = await EvmTransfer.sendToken(
+  seedPhrase,
+  sponsoredConfig,
+  EVM_CHAINS.base.usdtAddress,
+  '50.00',
+  '0x1111111111111111111111111111111111111111',
+);
+
+console.log(result.transactionHash);
+```
+
+### 7. Send a batch transfer
+
+```ts
+const batch = await EvmTransfer.sendBatchToken(
+  seedPhrase,
+  sponsoredConfig,
+  EVM_CHAINS.base.usdtAddress,
+  [
+    { address: '0x1111111111111111111111111111111111111111', amount: '25.00' },
+    { address: '0x2222222222222222222222222222222222222222', amount: '10.00' },
+  ],
+);
+```
+
+## Passkey Flow
+
+Passkeys are optional. They let you add a WebAuthn signer to an existing Safe so transfers can be approved with biometrics instead of a seed phrase.
+
+Important:
+
+- the Safe must already be deployed on-chain before you link a passkey
+- `storage: 'persist'` is convenience storage only, not hardened secret storage
+
+### Passkey diagram
+
+```
+ ┌──────────────────────┐
+ │  Seed phrase owner   │──────┐
+ └──────────────────────┘      │
+                               v
+                      ┌──────────────────────┐
+                      │  Safe smart account   │
+                      └──────────┬───────────┘
+ ┌──────────────────────┐      │
+ │  Passkey (WebAuthn)  │──────┘
+ └──────────────────────┘
+                                │
+                                v
+                      ┌──────────────────────┐
+                      │  Signed UserOperation │
+                      └──────────┬───────────┘
+                                │
+                                v
+                      ┌──────────────────────┐
+                      │  Bundler + Paymaster  │
+                      └──────────┬───────────┘
+                                │
+                                v
+                      ┌──────────────────────┐
+                      │       EVM chain       │
+                      └──────────────────────┘
+```
+
+```mermaid
+flowchart TD
+  A["Seed phrase owner"] --> C["Safe smart account"]
+  B["Passkey (WebAuthn)"] --> C
+  C --> D["Signed UserOperation"]
+  D --> E["Bundler + Paymaster"]
+  E --> F["EVM chain"]
+```
+
+### Link a passkey to an existing Safe
+
+```ts
+import { linkPasskeyToSafe } from '@gasfree-kit/evm-4337';
+
+const passkey = await linkPasskeyToSafe(seedPhrase, sponsoredConfig, {
+  rpName: 'My App',
+  userName: 'user@example.com',
+  storage: 'not_persist',
+});
+
+console.log(passkey.safeAddress);
+console.log(passkey.credential.signerAddress);
+```
+
+### Check whether a passkey is linked
+
+```ts
+import { isPasskeyLinked } from '@gasfree-kit/evm-4337';
+
+const status = await isPasskeyLinked(seedPhrase, sponsoredConfig);
+
+if (status.linked) {
+  console.log(status.signerAddress);
+}
+```
+
+### Send a transfer with a passkey
+
+```ts
+import { PasskeyTransfer } from '@gasfree-kit/evm-4337';
+import { EVM_CHAINS } from '@gasfree-kit/core';
+
+const tx = await PasskeyTransfer.sendToken(
+  passkey.credential,
+  sponsoredConfig,
+  EVM_CHAINS.base.usdtAddress,
+  '10.00',
+  '0x1111111111111111111111111111111111111111',
+);
+```
+
+### Remove a passkey owner
+
+```ts
+import { unlinkPasskeyFromSafe } from '@gasfree-kit/evm-4337';
+
+await unlinkPasskeyFromSafe(seedPhrase, sponsoredConfig, passkey.credential);
+```
+
+## Main Exports
+
+| Export                                                                         | What it does                                                                 |
+| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| `setupErc4337Wallet`                                                           | Creates a WDK-backed ERC-4337 wallet and resolves the Safe address           |
+| `EvmTransfer`                                                                  | Estimates, checks balance, sends single transfers, and sends batch transfers |
+| `PasskeyTransfer`                                                              | Sends passkey-signed transfers after a passkey has been linked               |
+| `linkPasskeyToSafe`                                                            | Registers a passkey and adds its signer to the Safe owner set                |
+| `isPasskeyLinked`                                                              | Checks whether a stored passkey is still an owner on-chain                   |
+| `unlinkPasskeyFromSafe`                                                        | Removes a passkey signer from the Safe                                       |
+| `getErc4337ConfigForChain`                                                     | Normalizes the public client config into runtime config                      |
+| `GAS_FEE_FALLBACKS` and `GAS_FEE_ESTIMATES`                                    | Exposes fallback fee heuristics per chain                                    |
+| `toUsdtBaseUnitsEvm`, `formatTokenBalance`, `feeToUsdt`, `encodeErc20Transfer` | Utility helpers for amounts and calldata                                     |
+
+## Export Example
+
+```ts
+import {
+  setupErc4337Wallet,
+  EvmTransfer,
+  PasskeyTransfer,
+  linkPasskeyToSafe,
+  isPasskeyLinked,
+  unlinkPasskeyFromSafe,
+  getErc4337ConfigForChain,
+  GAS_FEE_FALLBACKS,
+  GAS_FEE_ESTIMATES,
+} from '@gasfree-kit/evm-4337';
+```
+
+## Notes
+
+- `sponsorshipPolicyId` is required when `isSponsored` is `true`
+- self-transfers are blocked
+- token-paid mode checks that the USDT balance can cover the transfer and gas reserve
+- passkey linking verifies the signer deployment before adding it as an owner
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -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 };