@fastxyz/allset-sdk 0.1.10 → 0.1.12

package/dist/node/eip7702.d.ts

@@ -0,0 +1,54 @@
+/**
+ * eip7702.ts — EIP-7702 smartDeposit via AllSet Portal relay
+ *
+ * Flow:
+ *   1. Check ERC-20 balance; throw InsufficientBalanceError if < amount
+ *   2. POST /userop/prepare  → backend assembles UserOp + paymasterData (3 retries)
+ *   3. Pin delegate address against TRUSTED_DELEGATES allowlist
+ *   4. Sign EIP-7702 authorization (re-delegate EOA to v0.8 impl)
+ *   5. Sign UserOperation (EIP-712, v0.8)
+ *   6. POST /userop/submit  → backend calls Pimlico eth_sendUserOperation
+ *
+ * Private key never leaves the SDK.
+ * Pimlico API key never touches the SDK.
+ * Gas is paid in USDC via ERC-20 Paymaster.
+ * Chain is inferred from rpcUrl (backend calls eth_chainId) — no hardcoded chain list.
+ */
+import { type Address, type Hash, type Hex } from 'viem';
+export interface SmartDepositParams {
+    /**
+     * EOA private key — stays local, never sent to backend.
+     * The EOA should be quiescent during this call: do not send other
+     * transactions from this key concurrently. EIP-7702 authorization
+     * signing binds to the account nonce, and a concurrent tx from
+     * another process will silently invalidate the delegation.
+     */
+    privateKey: Hex;
+    /** EVM JSON-RPC URL — used for balance check and forwarded to backend for chainId detection */
+    rpcUrl: string;
+    /** AllSet Portal backend base URL, e.g. https://api.allset.xyz */
+    allsetApiUrl: string;
+    /** ERC-20 token to deposit (e.g. USDC on Base) */
+    tokenAddress: Address;
+    /** Exact token amount to deposit (raw, with decimals); throws if balance is insufficient */
+    amount: bigint;
+    /** AllSet bridge contract address */
+    bridgeAddress: Address;
+    /** Encoded bridge.deposit(...) calldata from encodeDepositCalldata() */
+    depositCalldata: Hex;
+    /** Per-request HTTP timeout in ms for backend POSTs (default: 60000) */
+    requestTimeoutMs?: number;
+}
+export interface SmartDepositResult {
+    txHash: Hash;
+    userOpHash: Hash;
+    userAddress: Address;
+}
+export declare class InsufficientBalanceError extends Error {
+    readonly balance: bigint;
+    readonly required: bigint;
+    readonly tokenAddress: Address;
+    constructor(balance: bigint, required: bigint, tokenAddress: Address);
+}
+export declare function smartDeposit(params: SmartDepositParams): Promise<SmartDepositResult>;
+//# sourceMappingURL=eip7702.d.ts.map

package/dist/node/eip7702.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eip7702.d.ts","sourceRoot":"","sources":["../../src/node/eip7702.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAML,KAAK,OAAO,EACZ,KAAK,IAAI,EACT,KAAK,GAAG,EACT,MAAM,MAAM,CAAC;AA4Dd,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,UAAU,EAAE,GAAG,CAAC;IAChB,+FAA+F;IAC/F,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,YAAY,EAAE,OAAO,CAAC;IACtB,4FAA4F;IAC5F,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,aAAa,EAAE,OAAO,CAAC;IACvB,wEAAwE;IACxE,eAAe,EAAE,GAAG,CAAC;IACrB,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,IAAI,CAAC;IACb,UAAU,EAAE,IAAI,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,qBAAa,wBAAyB,SAAQ,KAAK;aAE/B,OAAO,EAAE,MAAM;aACf,QAAQ,EAAE,MAAM;aAChB,YAAY,EAAE,OAAO;gBAFrB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,OAAO;CAOxC;AA6HD,wBAAsB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA2K1F"}

package/dist/node/eip7702.js

@@ -0,0 +1,275 @@
+/**
+ * eip7702.ts — EIP-7702 smartDeposit via AllSet Portal relay
+ *
+ * Flow:
+ *   1. Check ERC-20 balance; throw InsufficientBalanceError if < amount
+ *   2. POST /userop/prepare  → backend assembles UserOp + paymasterData (3 retries)
+ *   3. Pin delegate address against TRUSTED_DELEGATES allowlist
+ *   4. Sign EIP-7702 authorization (re-delegate EOA to v0.8 impl)
+ *   5. Sign UserOperation (EIP-712, v0.8)
+ *   6. POST /userop/submit  → backend calls Pimlico eth_sendUserOperation
+ *
+ * Private key never leaves the SDK.
+ * Pimlico API key never touches the SDK.
+ * Gas is paid in USDC via ERC-20 Paymaster.
+ * Chain is inferred from rpcUrl (backend calls eth_chainId) — no hardcoded chain list.
+ */
+import { createPublicClient, encodeAbiParameters, http, keccak256, parseAbi, } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { getUserOperationTypedData } from 'viem/account-abstraction';
+const ENTRY_POINT_V08 = '0x4337084D9E255Ff0702461CF8895CE9E3b5Ff108';
+/**
+ * Allowlist of trusted EIP-7702 delegate addresses (lowercase).
+ * smartDeposit will throw if the backend returns a delegate not in this set,
+ * preventing a compromised backend from delegating EOAs to a malicious contract.
+ */
+const TRUSTED_DELEGATES = new Set([
+    '0xe6cae83bde06e4c305530e199d7217f42808555b', // Simple7702Account v0.8
+]);
+const ERC20_BALANCEOF_ABI = parseAbi([
+    'function balanceOf(address account) view returns (uint256)',
+]);
+/**
+ * Encode a number/bigint as an even-length 0x-prefixed hex string.
+ * Some strict bundler parsers expect byte-aligned hex — pad to even length.
+ */
+function toEvenHex(n) {
+    let h = n.toString(16);
+    if (h.length % 2 !== 0)
+        h = `0${h}`;
+    return `0x${h}`;
+}
+/**
+ * POST JSON with a hard timeout via AbortController.
+ * Node's global fetch has no default timeout.
+ */
+async function postJson(url, body, timeoutMs) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: ac.signal,
+        });
+        if (!res.ok) {
+            const err = await res.text();
+            throw new Error(`POST ${url} failed (${res.status}): ${err}`);
+        }
+        return (await res.json());
+    }
+    catch (e) {
+        if (e.name === 'AbortError') {
+            throw new Error(`POST ${url} timed out after ${timeoutMs}ms`);
+        }
+        throw e;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export class InsufficientBalanceError extends Error {
+    balance;
+    required;
+    tokenAddress;
+    constructor(balance, required, tokenAddress) {
+        super(`Insufficient token balance: have ${balance}, need ${required} (token ${tokenAddress})`);
+        this.balance = balance;
+        this.required = required;
+        this.tokenAddress = tokenAddress;
+        this.name = 'InsufficientBalanceError';
+    }
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Convert the backend's hex-string UserOp to viem's bigint-typed UserOperation<'0.8'>.
+ */
+function parseUserOp(raw) {
+    return {
+        sender: raw.sender,
+        nonce: BigInt(raw.nonce),
+        callData: raw.callData,
+        callGasLimit: BigInt(raw.callGasLimit),
+        verificationGasLimit: BigInt(raw.verificationGasLimit),
+        preVerificationGas: BigInt(raw.preVerificationGas),
+        maxFeePerGas: BigInt(raw.maxFeePerGas),
+        maxPriorityFeePerGas: BigInt(raw.maxPriorityFeePerGas),
+        ...(raw.paymaster && { paymaster: raw.paymaster }),
+        ...(raw.paymasterVerificationGasLimit && {
+            paymasterVerificationGasLimit: BigInt(raw.paymasterVerificationGasLimit),
+        }),
+        ...(raw.paymasterPostOpGasLimit && {
+            paymasterPostOpGasLimit: BigInt(raw.paymasterPostOpGasLimit),
+        }),
+        ...(raw.paymasterData && { paymasterData: raw.paymasterData }),
+        ...(raw.factory && { factory: raw.factory }),
+        ...(raw.factoryData && { factoryData: raw.factoryData }),
+        signature: '0x',
+    };
+}
+/**
+ * Convert UserOperation<'0.8'> bigint fields → hex strings for JSON serialization.
+ * The Go backend expects all numeric fields as 0x-prefixed hex strings.
+ */
+function serializeUserOp(op) {
+    const toHex = (n) => `0x${n.toString(16)}`;
+    return {
+        sender: op.sender,
+        nonce: toHex(op.nonce),
+        callData: op.callData,
+        callGasLimit: toHex(op.callGasLimit),
+        verificationGasLimit: toHex(op.verificationGasLimit),
+        preVerificationGas: toHex(op.preVerificationGas),
+        maxFeePerGas: toHex(op.maxFeePerGas),
+        maxPriorityFeePerGas: toHex(op.maxPriorityFeePerGas),
+        ...(op.paymaster && { paymaster: op.paymaster }),
+        ...(op.paymasterVerificationGasLimit !== undefined && {
+            paymasterVerificationGasLimit: toHex(op.paymasterVerificationGasLimit),
+        }),
+        ...(op.paymasterPostOpGasLimit !== undefined && {
+            paymasterPostOpGasLimit: toHex(op.paymasterPostOpGasLimit),
+        }),
+        ...(op.paymasterData && { paymasterData: op.paymasterData }),
+        ...(op.factory && { factory: op.factory }),
+        ...(op.factoryData && { factoryData: op.factoryData }),
+        ...(op.signature && { signature: op.signature }),
+    };
+}
+// ─── Main function ─────────────────────────────────────────────────────────────
+export async function smartDeposit(params) {
+    const { privateKey, rpcUrl, allsetApiUrl, tokenAddress, amount, bridgeAddress, depositCalldata, requestTimeoutMs = 60_000, } = params;
+    const eoa = privateKeyToAccount(privateKey);
+    // No chain object needed — chainId is fetched dynamically from the RPC
+    const publicClient = createPublicClient({ transport: http(rpcUrl) });
+    // Step 1: One-shot balance check — caller is responsible for funding the EOA first
+    const tokenBalance = (await publicClient.readContract({
+        address: tokenAddress,
+        abi: ERC20_BALANCEOF_ABI,
+        functionName: 'balanceOf',
+        args: [eoa.address],
+    }));
+    if (tokenBalance < amount) {
+        throw new InsufficientBalanceError(tokenBalance, amount, tokenAddress);
+    }
+    // Fetch chainId once — used for EIP-7702 auth and UserOp signing
+    const chainId = await publicClient.getChainId();
+    // Step 2: Build request auth signature (proves caller owns the private key).
+    // Preimage: abi.encode(domainTag, chainId, nonce, from, tokenAddress, amount, bridgeAddress, depositCalldata, timestamp)
+    // - Domain tag prevents cross-protocol signature collisions.
+    // - chainId prevents cross-chain replay.
+    // - nonce (random 32 bytes) prevents in-protocol replay; backend must track used nonces.
+    // - abi.encode (not encodePacked) eliminates dynamic-field collision ambiguity.
+    const timestamp = Math.floor(Date.now() / 1000);
+    const nonceBytes = crypto.getRandomValues(new Uint8Array(32));
+    const nonce = `0x${Array.from(nonceBytes, (b) => b.toString(16).padStart(2, '0')).join('')}`;
+    const DOMAIN_TAG = 'AllSet Portal authSig v1';
+    const msgHash = keccak256(encodeAbiParameters([
+        { type: 'string' },
+        { type: 'uint256' },
+        { type: 'bytes32' },
+        { type: 'address' },
+        { type: 'address' },
+        { type: 'uint256' },
+        { type: 'address' },
+        { type: 'bytes' },
+        { type: 'uint256' },
+    ], [
+        DOMAIN_TAG,
+        BigInt(chainId),
+        nonce,
+        eoa.address,
+        tokenAddress,
+        amount,
+        bridgeAddress,
+        depositCalldata,
+        BigInt(timestamp),
+    ]));
+    const authSig = await eoa.signMessage({ message: { raw: msgHash } });
+    // Step 3: POST /userop/prepare (3 attempts with exponential backoff: 0, 500, 1500ms)
+    const prepareReq = {
+        rpcUrl,
+        from: eoa.address,
+        tokenAddress,
+        amount: amount.toString(),
+        bridgeAddress,
+        depositCalldata,
+        chainId,
+        nonce,
+        timestamp,
+        authSig,
+    };
+    const PREPARE_DELAYS = [0, 500, 1500];
+    let prepared;
+    for (let attempt = 0; attempt < PREPARE_DELAYS.length; attempt++) {
+        if (PREPARE_DELAYS[attempt] > 0) {
+            await new Promise((r) => setTimeout(r, PREPARE_DELAYS[attempt]));
+        }
+        try {
+            prepared = await postJson(`${allsetApiUrl}/userop/prepare`, prepareReq, requestTimeoutMs);
+            break;
+        }
+        catch (e) {
+            const isLast = attempt === PREPARE_DELAYS.length - 1;
+            // Retry on network errors and 5xx/429 (message contains status code)
+            const msg = e.message ?? '';
+            const isRetryable = !msg.match(/POST .+ failed \([1-4][0-9]{2}\)/) || msg.includes('(429)') || msg.includes('(5');
+            if (isLast || !isRetryable)
+                throw e;
+        }
+    }
+    // Step 4: Pin delegate address against trusted allowlist
+    if (!TRUSTED_DELEGATES.has(prepared.delegate7702Address.toLowerCase())) {
+        throw new Error(`smartDeposit: untrusted delegate address returned by backend: ${prepared.delegate7702Address}`);
+    }
+    // Step 5: Sign EIP-7702 authorization.
+    // We always re-sign to ensure the EOA is delegated to the correct v0.8 impl,
+    // even if a prior (possibly outdated) delegation exists.
+    let eip7702Auth;
+    if (prepared.needsAuthorization) {
+        // Use 'pending' so mempool txs from this EOA are counted in the nonce.
+        const accountNonce = await publicClient.getTransactionCount({
+            address: eoa.address,
+            blockTag: 'pending',
+        });
+        const signed = await eoa.signAuthorization({
+            address: prepared.delegate7702Address,
+            chainId,
+            nonce: accountNonce,
+        });
+        const yParity = signed.yParity ?? 0;
+        eip7702Auth = {
+            address: prepared.delegate7702Address,
+            chainId: toEvenHex(chainId),
+            nonce: toEvenHex(accountNonce),
+            yParity: toEvenHex(yParity),
+            r: `0x${BigInt(signed.r).toString(16).padStart(64, '0')}`,
+            s: `0x${BigInt(signed.s).toString(16).padStart(64, '0')}`,
+        };
+    }
+    // Step 6: Parse backend response + sign UserOperation (v0.8 uses EIP-712 typed data)
+    const userOpToSign = parseUserOp(prepared.unsignedUserOp);
+    // v0.8 requires EIP-712 signTypedData, NOT signMessage/personal_sign
+    const typedData = getUserOperationTypedData({
+        chainId,
+        entryPointAddress: ENTRY_POINT_V08,
+        userOperation: { ...userOpToSign, signature: '0x' },
+    });
+    const signature = await eoa.signTypedData(typedData);
+    const signedUserOp = { ...userOpToSign, signature };
+    // Step 7: POST /userop/submit (single attempt — UserOps are not idempotent)
+    const serialized = serializeUserOp(signedUserOp);
+    if (eip7702Auth) {
+        serialized.eip7702Auth = eip7702Auth;
+    }
+    const submitReq = {
+        rpcUrl,
+        signedUserOp: serialized,
+    };
+    const { txHash, userOpHash: returnedUserOpHash } = await postJson(`${allsetApiUrl}/userop/submit`, submitReq, requestTimeoutMs);
+    return {
+        txHash,
+        userOpHash: returnedUserOpHash,
+        userAddress: eoa.address,
+    };
+}

package/dist/node/index.d.ts

@@ -1,4 +1,5 @@
 export * from '../core/index.js';
+export * from './eip7702.js';
 export { AllSetProvider, getAllSetDir, getEvmKeysDir as getAllSetEvmKeysDir, ensureAllSetDirs, initUserConfig, } from './provider.js';
 export { createEvmExecutor, createEvmWallet, getEvmKeysDir, } from './evm-executor.js';
 export { loadNetworksConfig, getNetworkConfig, getChainConfig, getTokenConfig, clearConfigCache, } from './config.js';

package/dist/node/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AAEjC,OAAO,EACL,cAAc,EACd,YAAY,EACZ,aAAa,IAAI,mBAAmB,EACpC,gBAAgB,EAChB,cAAc,GACf,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,aAAa,GACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAChE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC9F,YAAY,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE3D,wBAAsB,OAAO,CAC3B,GAAG,IAAI,EAAE,UAAU,CAAC,cAAc,aAAa,EAAE,OAAO,CAAC,GACxD,UAAU,CAAC,cAAc,aAAa,EAAE,OAAO,CAAC,CAGlD;AAED,wBAAsB,aAAa,CACjC,GAAG,IAAI,EAAE,UAAU,CAAC,cAAc,aAAa,EAAE,aAAa,CAAC,GAC9D,UAAU,CAAC,cAAc,aAAa,EAAE,aAAa,CAAC,CAGxD;AAED,wBAAsB,aAAa,CACjC,GAAG,IAAI,EAAE,UAAU,CAAC,cAAc,aAAa,EAAE,aAAa,CAAC,GAC9D,UAAU,CAAC,cAAc,aAAa,EAAE,aAAa,CAAC,CAGxD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAE7B,OAAO,EACL,cAAc,EACd,YAAY,EACZ,aAAa,IAAI,mBAAmB,EACpC,gBAAgB,EAChB,cAAc,GACf,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,aAAa,GACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAChE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC9F,YAAY,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE3D,wBAAsB,OAAO,CAC3B,GAAG,IAAI,EAAE,UAAU,CAAC,cAAc,aAAa,EAAE,OAAO,CAAC,GACxD,UAAU,CAAC,cAAc,aAAa,EAAE,OAAO,CAAC,CAGlD;AAED,wBAAsB,aAAa,CACjC,GAAG,IAAI,EAAE,UAAU,CAAC,cAAc,aAAa,EAAE,aAAa,CAAC,GAC9D,UAAU,CAAC,cAAc,aAAa,EAAE,aAAa,CAAC,CAGxD;AAED,wBAAsB,aAAa,CACjC,GAAG,IAAI,EAAE,UAAU,CAAC,cAAc,aAAa,EAAE,aAAa,CAAC,GAC9D,UAAU,CAAC,cAAc,aAAa,EAAE,aAAa,CAAC,CAGxD"}

package/dist/node/index.js

@@ -1,4 +1,5 @@
 export * from '../core/index.js';
+export * from './eip7702.js';
 export { AllSetProvider, getAllSetDir, getEvmKeysDir as getAllSetEvmKeysDir, ensureAllSetDirs, initUserConfig, } from './provider.js';
 export { createEvmExecutor, createEvmWallet, getEvmKeysDir, } from './evm-executor.js';
 export { loadNetworksConfig, getNetworkConfig, getChainConfig, getTokenConfig, clearConfigCache, } from './config.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastxyz/allset-sdk",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "AllSet SDK for AllSet bridge flows between Fast and EVM testnets",
   "keywords": [
     "allset",
@@ -76,6 +76,7 @@
   "devDependencies": {
     "@fastxyz/sdk": "^0.2.5",
     "@types/node": "^22.19.11",
+    "permissionless": "^0.3",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   }