abstractionkit 0.3.0 → 0.3.1

package/dist/index.iife.js

@@ -1115,11 +1115,14 @@ var abstractionkit = (function(exports, ethers) {
 					state_override_set
 				]);
 				const res = jsonRpcResult;
-				return {
+				const gasEstimationResult = {
 					callGasLimit: BigInt(res.callGasLimit),
 					preVerificationGas: BigInt(res.preVerificationGas),
 					verificationGasLimit: BigInt(res.verificationGasLimit)
 				};
+				if (res.paymasterVerificationGasLimit != null) gasEstimationResult.paymasterVerificationGasLimit = BigInt(res.paymasterVerificationGasLimit);
+				if (res.paymasterPostOpGasLimit != null) gasEstimationResult.paymasterPostOpGasLimit = BigInt(res.paymasterPostOpGasLimit);
+				return gasEstimationResult;
 			} catch (err) {
 				throw new AbstractionKitError("BUNDLER_ERROR", "bundler eth_estimateUserOperationGas rpc call failed", { cause: ensureError(err) });
 			}
@@ -3804,7 +3807,7 @@ var abstractionkit = (function(exports, ethers) {
 	* @param toolVersion - tool version, defaults to current abstractionkit version
 	* @returns the onchain idenetifier as a hex string (not 0x prefixed)
 	*/
-	function generateOnChainIdentifier(project, platform = "Web", tool = "abstractionkit", toolVersion = "0.3.0") {
+	function generateOnChainIdentifier(project, platform = "Web", tool = "abstractionkit", toolVersion = "0.3.1") {
 		const identifierPrefix = "5afe";
 		const identifierVersion = "00";
 		const projectHash = (0, ethers.keccak256)("0x" + Buffer.from(project, "utf8").toString("hex")).slice(-20);
@@ -4192,36 +4195,39 @@ var abstractionkit = (function(exports, ethers) {
 		* @param overrides - overrides for the default values
 		* @returns signature
 		*/
-		static formatSignaturesToUseroperationsSignatures(userOperationsToSign, signerSignaturePairs, overrides = {}) {
+		static formatSignaturesToUseroperationsSignatures(userOperationsToSign, signerSignaturePairs) {
 			if (userOperationsToSign.length < 1) throw new RangeError("There should be at least one userOperationsToSign");
-			const resolvedOverrides = {
+			const defaultOverrides = {
 				eip7212WebAuthnPrecompileVerifier: SafeMultiChainSigAccountV1.DEFAULT_WEB_AUTHN_PRECOMPILE,
 				eip7212WebAuthnContractVerifier: SafeMultiChainSigAccountV1.DEFAULT_WEB_AUTHN_DAIMO_VERIFIER,
 				webAuthnSignerFactory: SafeMultiChainSigAccountV1.DEFAULT_WEB_AUTHN_SIGNER_FACTORY,
 				webAuthnSignerSingleton: SafeMultiChainSigAccountV1.DEFAULT_WEB_AUTHN_SIGNER_SINGLETON,
 				webAuthnSignerProxyCreationCode: SafeMultiChainSigAccountV1.DEFAULT_WEB_AUTHN_SIGNER_PROXY_CREATION_CODE,
 				safe4337ModuleAddress: SafeMultiChainSigAccountV1.DEFAULT_SAFE_4337_MODULE_ADDRESS,
-				webAuthnSharedSigner: SafeMultiChainSigAccountV1.DEFAULT_WEB_AUTHN_SHARED_SIGNER,
-				...overrides
+				webAuthnSharedSigner: SafeMultiChainSigAccountV1.DEFAULT_WEB_AUTHN_SHARED_SIGNER
 			};
 			if (userOperationsToSign.length === 1) return [SafeAccount.formatSignaturesToUseroperationSignature(signerSignaturePairs, {
-				...resolvedOverrides,
+				...defaultOverrides,
+				...userOperationsToSign[0].overrides,
+				validAfter: userOperationsToSign[0].validAfter,
+				validUntil: userOperationsToSign[0].validUntil,
 				isMultiChainSignature: true
 			})];
 			const userOperationsHashes = [];
-			userOperationsToSign.forEach((userOperationsToSign, _index) => {
-				const userOperationHash = SafeAccount.getUserOperationEip712Hash_V9(userOperationsToSign.userOperation, userOperationsToSign.chainId, {
-					validAfter: userOperationsToSign.validAfter,
-					validUntil: userOperationsToSign.validUntil,
-					safe4337ModuleAddress: resolvedOverrides.safe4337ModuleAddress
+			userOperationsToSign.forEach((userOperationToSign, _index) => {
+				const userOperationHash = SafeAccount.getUserOperationEip712Hash_V9(userOperationToSign.userOperation, userOperationToSign.chainId, {
+					validAfter: userOperationToSign.validAfter,
+					validUntil: userOperationToSign.validUntil,
+					safe4337ModuleAddress: userOperationToSign.overrides?.safe4337ModuleAddress ?? defaultOverrides.safe4337ModuleAddress
 				});
 				userOperationsHashes.push(userOperationHash);
 			});
 			const [_root, proofs] = generateMerkleProofs(userOperationsHashes);
 			const userOpSignatures = [];
-			userOperationsToSign.forEach((_userOperationsToSign, index) => {
+			userOperationsToSign.forEach((userOperationToSign, index) => {
 				userOpSignatures.push(SafeAccount.formatSignaturesToUseroperationSignature(signerSignaturePairs, {
-					...resolvedOverrides,
+					...defaultOverrides,
+					...userOperationToSign.overrides,
 					isMultiChainSignature: true,
 					multiChainMerkleProof: proofs[index]
 				}));
@@ -6523,9 +6529,9 @@ var abstractionkit = (function(exports, ethers) {
 	/** Buffer added to verificationGasLimit for paymasterAndData verification overhead */
 	const PAYMASTER_V06_VERIFICATION_OVERHEAD = 40000n;
 	/** Max value for uint256 */
-	const UINT256_MAX = 115792089237316195423570985008687907853269984665640564039457584007913129639935n;
+	const UINT256_MAX$1 = 115792089237316195423570985008687907853269984665640564039457584007913129639935n;
 	/** Multiplier for token approve amount to cover paymasterAndData cost variance */
-	const TOKEN_APPROVE_AMOUNT_MULTIPLIER = 2n;
+	const TOKEN_APPROVE_AMOUNT_MULTIPLIER$1 = 2n;
 	/**
 	* ERC-20 tokens that require resetting their allowance to 0 before setting a
 	* new approval amount (e.g. USDT on mainnet).
@@ -6535,7 +6541,7 @@ var abstractionkit = (function(exports, ethers) {
 	* please open an issue at https://github.com/candidelabs/abstractionkit/issues
 	* or use the `resetApproval` override as a workaround.
 	*/
-	const TOKENS_REQUIRING_ALLOWANCE_RESET = ["0xdac17f958d2ee523a2206206994597c13d831ec7"];
+	const TOKENS_REQUIRING_ALLOWANCE_RESET$1 = ["0xdac17f958d2ee523a2206206994597c13d831ec7"];
 	/**
 	* Client for the Candide Paymaster service.
 	* Supports both gas sponsorship (sponsor paymaster) and ERC-20 token payment for gas (token paymaster).
@@ -6875,12 +6881,12 @@ var abstractionkit = (function(exports, ethers) {
 					if (epData == null) throw new RangeError(`UserOperation for entrypoint ${entrypoint} is not supported`);
 					this.setDummyPaymasterFields(userOp, epData);
 					const oldCallData = userOp.callData;
-					const requiresAllowanceReset = overrides?.resetApproval ?? TOKENS_REQUIRING_ALLOWANCE_RESET.includes(context.token.toLowerCase());
-					let callDataWithApprove = smartAccount.prependTokenPaymasterApproveToCallData(userOp.callData, context.token, epData.paymasterMetadata.address, UINT256_MAX);
+					const requiresAllowanceReset = overrides?.resetApproval ?? TOKENS_REQUIRING_ALLOWANCE_RESET$1.includes(context.token.toLowerCase());
+					let callDataWithApprove = smartAccount.prependTokenPaymasterApproveToCallData(userOp.callData, context.token, epData.paymasterMetadata.address, UINT256_MAX$1);
 					if (requiresAllowanceReset) callDataWithApprove = smartAccount.prependTokenPaymasterApproveToCallData(callDataWithApprove, context.token, epData.paymasterMetadata.address, 0n);
 					userOp.callData = callDataWithApprove;
 					await this.estimateAndApplyGasLimits(userOp, bundlerRpc, entrypoint, overrides ?? {});
-					const approveAmount = await this.calculateUserOperationErc20TokenMaxGasCost(smartAccount, userOp, context.token) * TOKEN_APPROVE_AMOUNT_MULTIPLIER;
+					const approveAmount = await this.calculateUserOperationErc20TokenMaxGasCost(smartAccount, userOp, context.token) * TOKEN_APPROVE_AMOUNT_MULTIPLIER$1;
 					callDataWithApprove = smartAccount.prependTokenPaymasterApproveToCallData(oldCallData, context.token, epData.paymasterMetadata.address, approveAmount);
 					if (requiresAllowanceReset) callDataWithApprove = smartAccount.prependTokenPaymasterApproveToCallData(callDataWithApprove, context.token, epData.paymasterMetadata.address, 0n);
 					userOp.callData = callDataWithApprove;
@@ -6960,6 +6966,396 @@ var abstractionkit = (function(exports, ethers) {
 		}
 	};
 	//#endregion
+	//#region src/paymaster/Erc7677Paymaster.ts
+	/** Max value for uint256 */
+	const UINT256_MAX = 115792089237316195423570985008687907853269984665640564039457584007913129639935n;
+	/** Multiplier for token approve amount to cover paymasterAndData cost variance */
+	const TOKEN_APPROVE_AMOUNT_MULTIPLIER = 2n;
+	/**
+	* ERC-20 tokens that require resetting their allowance to 0 before setting a
+	* new approval amount (e.g. USDT on mainnet).
+	*/
+	const TOKENS_REQUIRING_ALLOWANCE_RESET = ["0xdac17f958d2ee523a2206206994597c13d831ec7"];
+	/**
+	* Time-to-live for cached Candide `pm_supportedERC20Tokens` responses, applied
+	* only when the fetch is initiated for an exchange-rate lookup. Stub-data
+	* lookups (paymaster address + dummyPaymasterAndData) reuse the cache
+	* indefinitely since those fields are effectively static per EP.
+	*/
+	const CANDIDE_TOKEN_QUOTE_TTL_MS = 45e3;
+	var Erc7677Paymaster = class Erc7677Paymaster extends Paymaster {
+		/** The paymaster JSON-RPC endpoint URL */
+		rpcUrl;
+		/** Cached chain ID (hex string). Passed via constructor or resolved from the bundler at first use. */
+		chainId;
+		/** Detected or explicitly set paymaster provider. `null` means no provider-specific features. */
+		provider;
+		/**
+		* Cached Candide `pm_supportedERC20Tokens` response, keyed by lowercase
+		* entrypoint. Used for both token quotes and stub data to avoid a second
+		* round-trip (`pm_getPaymasterStubData`) for Candide-hosted paymasters.
+		*
+		* The cache is indefinite for stub-data lookups but has a TTL for
+		* exchange-rate lookups — see {@link CANDIDE_TOKEN_QUOTE_TTL_MS}.
+		*/
+		candideCache = /* @__PURE__ */ new Map();
+		/**
+		* Detect the paymaster provider from the RPC URL hostname.
+		* Returns `null` for unknown hosts or malformed URLs.
+		*
+		* Hostname-based (not substring) so that proxies or paths containing a
+		* provider name (e.g. `https://my-proxy.com/pimlico-compat/...`) are not
+		* misidentified.
+		*/
+		static detectProvider(rpcUrl) {
+			let host;
+			try {
+				host = new URL(rpcUrl).hostname.toLowerCase();
+			} catch {
+				return null;
+			}
+			if (host === "pimlico.io" || host.endsWith(".pimlico.io")) return "pimlico";
+			if (host === "candide.dev" || host.endsWith(".candide.dev")) return "candide";
+			return null;
+		}
+		/**
+		* @param rpcUrl - Paymaster JSON-RPC endpoint. Can be the same URL as the
+		*   bundler when the provider bundles both (Candide, Pimlico, Alchemy);
+		*   can also be a separate paymaster-only endpoint.
+		* @param options
+		* @param options.chainId - Optional chain id as a bigint (e.g. `1n` for
+		*   mainnet). When provided, avoids a lookup at first use. Otherwise,
+		*   resolved from the bundler via `eth_chainId` on the first call.
+		* @param options.provider - Paymaster provider. `"auto"` (default) detects
+		*   from the RPC URL. Set explicitly to override, or `null` to disable.
+		*/
+		constructor(rpcUrl, options = {}) {
+			super();
+			this.rpcUrl = rpcUrl;
+			this.chainId = options.chainId != null ? "0x" + options.chainId.toString(16) : null;
+			if (options.provider === void 0 || options.provider === "auto") this.provider = Erc7677Paymaster.detectProvider(rpcUrl);
+			else this.provider = options.provider;
+		}
+		/**
+		* Resolve the chain id, querying the bundler if not provided at construction.
+		*/
+		async getChainId(bundlerRpc) {
+			if (this.chainId != null) return this.chainId;
+			const id = await new Bundler(bundlerRpc).chainId();
+			this.chainId = id;
+			return id;
+		}
+		/**
+		* Determine the EntryPoint address from the UserOperation shape.
+		* V6 ops have `initCode`, V8+ ops have `eip7702Auth`, V7 is the default.
+		*/
+		resolveEntrypoint(smartAccount, userOperation) {
+			if (smartAccount.entrypointAddress != null && smartAccount.entrypointAddress.trim() !== "") return smartAccount.entrypointAddress;
+			if ("initCode" in userOperation) return ENTRYPOINT_V6;
+			if ("eip7702Auth" in userOperation) return ENTRYPOINT_V8;
+			return ENTRYPOINT_V7;
+		}
+		/**
+		* Low-level ERC-7677 `pm_getPaymasterStubData` call.
+		* Returns dummy paymaster fields intended for gas estimation.
+		*
+		* Most consumers should prefer {@link createPaymasterUserOperation}, which
+		* runs the full stub → estimate → final pipeline. Use this directly if you
+		* need to drive the flow manually.
+		*/
+		async getPaymasterStubData(userOperation, entrypoint, chainIdHex, context = {}) {
+			try {
+				return await sendJsonRpcRequest(this.rpcUrl, "pm_getPaymasterStubData", [
+					userOperation,
+					entrypoint,
+					chainIdHex,
+					context
+				]);
+			} catch (err) {
+				throw new AbstractionKitError("PAYMASTER_ERROR", "pm_getPaymasterStubData failed", { cause: ensureError(err) });
+			}
+		}
+		/**
+		* Low-level ERC-7677 `pm_getPaymasterData` call.
+		* Returns the final signed paymaster fields.
+		*/
+		async getPaymasterData(userOperation, entrypoint, chainIdHex, context = {}) {
+			try {
+				return await sendJsonRpcRequest(this.rpcUrl, "pm_getPaymasterData", [
+					userOperation,
+					entrypoint,
+					chainIdHex,
+					context
+				]);
+			} catch (err) {
+				throw new AbstractionKitError("PAYMASTER_ERROR", "pm_getPaymasterData failed", { cause: ensureError(err) });
+			}
+		}
+		/**
+		* Send an arbitrary JSON-RPC request through the paymaster endpoint.
+		* Useful for provider-specific methods that fall outside the ERC-7677 spec.
+		*
+		* @param method - The JSON-RPC method name
+		* @param params - The JSON-RPC params array
+		* @returns The `result` field from the JSON-RPC response
+		*/
+		async sendRPCRequest(method, params = []) {
+			try {
+				return await sendJsonRpcRequest(this.rpcUrl, method, params);
+			} catch (err) {
+				throw new AbstractionKitError("PAYMASTER_ERROR", `sendRPCRequest(${method}) failed`, { cause: ensureError(err) });
+			}
+		}
+		/**
+		* Runs the full ERC-7677 pipeline and returns a UserOperation with paymaster
+		* fields populated. The caller is responsible for signing and sending.
+		*
+		* @param smartAccount - Provides the target EntryPoint; not mutated.
+		* @param userOperation - Starting UserOperation. Not mutated — a shallow copy is returned.
+		* @param bundlerRpc - Bundler URL used for gas estimation and, if
+		*   `options.chainId` was not provided to the constructor, chain-id lookup.
+		* @param context - Provider-specific paymaster context
+		*   (e.g. `{ sponsorshipPolicyId }` or `{ token }`).
+		* @param overrides - Gas estimation overrides and state-override set.
+		*
+		* @returns The UserOperation with paymaster + gas fields populated.
+		*/
+		async createPaymasterUserOperation(smartAccount, userOperation, bundlerRpc, context = {}, overrides = {}) {
+			try {
+				const userOp = { ...userOperation };
+				const entrypoint = overrides.entrypoint ?? this.resolveEntrypoint(smartAccount, userOp);
+				const chainIdHex = await this.getChainId(bundlerRpc);
+				if (context.token != null && typeof context.token === "string") return this.tokenPaymasterFlow(smartAccount, userOp, context.token, bundlerRpc, entrypoint, chainIdHex, context, overrides);
+				return this.sponsoredFlow(userOp, bundlerRpc, entrypoint, chainIdHex, context, overrides);
+			} catch (err) {
+				const error = ensureError(err);
+				if (error instanceof AbstractionKitError) throw error;
+				throw new AbstractionKitError("PAYMASTER_ERROR", "createPaymasterUserOperation failed", { cause: error });
+			}
+		}
+		/**
+		* Merge paymaster fields into a UserOperation. Handles both v0.6
+		* (`paymasterAndData`) and v0.7+ split fields.
+		*/
+		applyPaymasterFields(userOp, fields) {
+			if ("initCode" in userOp) {
+				if (fields.paymasterAndData != null) userOp.paymasterAndData = fields.paymasterAndData;
+				return;
+			}
+			if (fields.paymaster != null) userOp.paymaster = fields.paymaster;
+			if (fields.paymasterData != null) userOp.paymasterData = fields.paymasterData;
+			if (fields.paymasterVerificationGasLimit != null) userOp.paymasterVerificationGasLimit = BigInt(fields.paymasterVerificationGasLimit);
+			if (fields.paymasterPostOpGasLimit != null) userOp.paymasterPostOpGasLimit = BigInt(fields.paymasterPostOpGasLimit);
+		}
+		/**
+		* Estimate gas limits via the bundler and apply them (with multipliers).
+		* Reads paymaster gas fields back from the bundler when present — some
+		* providers' `pm_getPaymasterStubData` returns `paymasterPostOpGasLimit: 0x1`
+		* as a placeholder, relying on the bundler's estimate for the real value.
+		*
+		* Mirrors CandidePaymaster.estimateAndApplyGasLimits default multipliers
+		* (5%/10%/10% on preVerification/verification/call) for consistent UX.
+		*/
+		async estimateAndApplyGasLimits(userOp, bundlerRpc, entrypoint, overrides) {
+			let preVerificationGas = userOp.preVerificationGas;
+			let verificationGasLimit = userOp.verificationGasLimit;
+			let callGasLimit = userOp.callGasLimit;
+			if (overrides.preVerificationGas == null || overrides.verificationGasLimit == null || overrides.callGasLimit == null) {
+				if (bundlerRpc == null) throw new AbstractionKitError("BAD_DATA", "bundlerRpc can't be null if preVerificationGas, verificationGasLimit and callGasLimit are not overridden");
+				const bundler = new Bundler(bundlerRpc);
+				userOp.callGasLimit = 0n;
+				userOp.verificationGasLimit = 0n;
+				userOp.preVerificationGas = 0n;
+				const skipFeeZeroing = this.provider === "pimlico";
+				const inputMaxFeePerGas = userOp.maxFeePerGas;
+				const inputMaxPriorityFeePerGas = userOp.maxPriorityFeePerGas;
+				if (!skipFeeZeroing) {
+					userOp.maxFeePerGas = 0n;
+					userOp.maxPriorityFeePerGas = 0n;
+				}
+				const estimation = await bundler.estimateUserOperationGas(userOp, entrypoint, overrides.state_override_set);
+				if (!skipFeeZeroing) {
+					userOp.maxFeePerGas = inputMaxFeePerGas;
+					userOp.maxPriorityFeePerGas = inputMaxPriorityFeePerGas;
+				}
+				if (estimation.preVerificationGas > preVerificationGas) preVerificationGas = estimation.preVerificationGas;
+				if (estimation.verificationGasLimit > verificationGasLimit) verificationGasLimit = estimation.verificationGasLimit;
+				if (estimation.callGasLimit > callGasLimit) callGasLimit = estimation.callGasLimit;
+				if ("paymaster" in userOp && estimation.paymasterVerificationGasLimit != null) userOp.paymasterVerificationGasLimit = estimation.paymasterVerificationGasLimit;
+				if ("paymaster" in userOp && estimation.paymasterPostOpGasLimit != null) userOp.paymasterPostOpGasLimit = estimation.paymasterPostOpGasLimit;
+			}
+			if (typeof overrides.preVerificationGas === "bigint" && overrides.preVerificationGas < 0n) throw new RangeError("preVerificationGas override can't be negative");
+			if (typeof overrides.verificationGasLimit === "bigint" && overrides.verificationGasLimit < 0n) throw new RangeError("verificationGasLimit override can't be negative");
+			if (typeof overrides.callGasLimit === "bigint" && overrides.callGasLimit < 0n) throw new RangeError("callGasLimit override can't be negative");
+			const applyMultiplier = (value, multiplier) => value + value * BigInt(Math.round((multiplier ?? 0) * 100)) / 10000n;
+			userOp.preVerificationGas = overrides.preVerificationGas ?? applyMultiplier(preVerificationGas, overrides.preVerificationGasPercentageMultiplier ?? 5);
+			userOp.verificationGasLimit = overrides.verificationGasLimit ?? applyMultiplier(verificationGasLimit, overrides.verificationGasLimitPercentageMultiplier ?? 10);
+			userOp.callGasLimit = overrides.callGasLimit ?? applyMultiplier(callGasLimit, overrides.callGasLimitPercentageMultiplier ?? 10);
+			if (entrypoint.toLowerCase() === "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789".toLowerCase()) userOp.verificationGasLimit += 40000n;
+		}
+		/**
+		* Fetch token exchange rate and paymaster address via Pimlico's
+		* `pimlico_getTokenQuotes` RPC.
+		*
+		* @returns `exchangeRate` as a bigint scaled by 10^18 (the value of 1 ETH
+		*   expressed in the token's smallest unit). Used to compute the token
+		*   approval amount via `(exchangeRate * gasCostWei) / 10^18`.
+		*/
+		async fetchPimlicoTokenQuote(tokenAddress, entrypoint, chainIdHex) {
+			const quotes = (await sendJsonRpcRequest(this.rpcUrl, "pimlico_getTokenQuotes", [
+				{ tokens: [tokenAddress] },
+				entrypoint,
+				chainIdHex
+			]))?.quotes;
+			if (!Array.isArray(quotes) || quotes.length === 0) throw new AbstractionKitError("PAYMASTER_ERROR", `pimlico_getTokenQuotes returned no quotes for token ${tokenAddress}`);
+			const quote = quotes.find((q) => q.token.toLowerCase() === tokenAddress.toLowerCase());
+			if (quote == null) throw new AbstractionKitError("PAYMASTER_ERROR", `pimlico_getTokenQuotes did not include token ${tokenAddress}`);
+			return {
+				exchangeRate: BigInt(quote.exchangeRate),
+				paymasterAddress: quote.paymaster
+			};
+		}
+		/**
+		* Fetch (and cache) Candide's `pm_supportedERC20Tokens` response for the
+		* given entrypoint. The response carries both exchange rates and the
+		* `dummyPaymasterAndData` used for gas estimation, so one round-trip
+		* suffices for the entire paymaster flow.
+		*
+		* @param options.enforceTTL - When true, re-fetches if the cached entry is
+		*   older than {@link CANDIDE_TOKEN_QUOTE_TTL_MS}. Set by exchange-rate
+		*   lookups (where staleness matters). Stub-data lookups leave this false
+		*   and reuse the cache indefinitely — the paymaster address and
+		*   `dummyPaymasterAndData` are effectively static per paymaster version.
+		*/
+		async fetchCandideSupportedTokens(entrypoint, options = {}) {
+			const key = entrypoint.toLowerCase();
+			const cached = this.candideCache.get(key);
+			const isStale = cached != null && options.enforceTTL === true && Date.now() - cached.fetchedAt > CANDIDE_TOKEN_QUOTE_TTL_MS;
+			if (cached != null && !isStale) return cached.data;
+			const result = await sendJsonRpcRequest(this.rpcUrl, "pm_supportedERC20Tokens", [entrypoint]);
+			this.candideCache.set(key, {
+				data: result,
+				fetchedAt: Date.now()
+			});
+			return result;
+		}
+		/**
+		* Fetch token exchange rate and paymaster address via Candide's
+		* `pm_supportedERC20Tokens` RPC.
+		*
+		* @returns `exchangeRate` as a bigint scaled by 10^18 (the value of 1 ETH
+		*   expressed in the token's smallest unit). Used to compute the token
+		*   approval amount via `(exchangeRate * gasCostWei) / 10^18`.
+		*/
+		async fetchCandideTokenQuote(tokenAddress, entrypoint) {
+			const result = await this.fetchCandideSupportedTokens(entrypoint, { enforceTTL: true });
+			const token = result.tokens?.find((t) => t.address.toLowerCase() === tokenAddress.toLowerCase());
+			if (token == null) throw new AbstractionKitError("PAYMASTER_ERROR", `${tokenAddress} token is not supported by the Candide paymaster`);
+			return {
+				exchangeRate: BigInt(token.exchangeRate),
+				paymasterAddress: result.paymasterMetadata.address
+			};
+		}
+		/**
+		* Convert Candide's `dummyPaymasterAndData` metadata into a stub result
+		* compatible with {@link applyPaymasterFields}. Handles both v0.6
+		* (concatenated hex string) and v0.7+ (structured) shapes.
+		*/
+		candideStubFromMetadata(metadata) {
+			const dummy = metadata.dummyPaymasterAndData;
+			if (typeof dummy === "string") return { paymasterAndData: dummy };
+			return {
+				paymaster: dummy.paymaster,
+				paymasterData: dummy.paymasterData,
+				paymasterVerificationGasLimit: dummy.paymasterVerificationGasLimit,
+				paymasterPostOpGasLimit: dummy.paymasterPostOpGasLimit
+			};
+		}
+		/**
+		* Get stub paymaster data. For Candide-hosted paymasters this derives the
+		* stub from the cached `pm_supportedERC20Tokens` response (no extra
+		* round-trip). For other providers, falls back to `pm_getPaymasterStubData`.
+		*/
+		async getStubData(userOperation, entrypoint, chainIdHex, context) {
+			if (this.provider === "candide") {
+				const response = await this.fetchCandideSupportedTokens(entrypoint);
+				return this.candideStubFromMetadata(response.paymasterMetadata);
+			}
+			return this.getPaymasterStubData(userOperation, entrypoint, chainIdHex, context);
+		}
+		/**
+		* Route to the correct provider-specific token quote fetcher.
+		* Returns `null` when no provider is configured.
+		*/
+		async fetchProviderTokenQuote(tokenAddress, entrypoint, chainIdHex) {
+			switch (this.provider) {
+				case "pimlico": return this.fetchPimlicoTokenQuote(tokenAddress, entrypoint, chainIdHex);
+				case "candide": return this.fetchCandideTokenQuote(tokenAddress, entrypoint);
+				default: return null;
+			}
+		}
+		/**
+		* Internal token paymaster pipeline. Called from `createPaymasterUserOperation`
+		* when `context.token` is set and the smart account supports approval prepending.
+		*
+		* Three cases:
+		* - **Provider detected**: exchange rate + paymaster address from provider RPC.
+		* - **No provider, `context.exchangeRate` set**: uses provided rate, paymaster
+		*   address from stub.
+		* - **No provider, no rate**: falls through to the regular sponsored flow
+		*   (developer already handled approval).
+		*/
+		async tokenPaymasterFlow(smartAccount, userOp, tokenAddress, bundlerRpc, entrypoint, chainIdHex, context, overrides) {
+			let exchangeRate;
+			let paymasterAddress = null;
+			const providerQuote = await this.fetchProviderTokenQuote(tokenAddress, entrypoint, chainIdHex);
+			if (providerQuote != null) {
+				exchangeRate = providerQuote.exchangeRate;
+				paymasterAddress = providerQuote.paymasterAddress;
+			} else if (context.exchangeRate != null) {
+				try {
+					exchangeRate = BigInt(context.exchangeRate);
+				} catch (err) {
+					throw new AbstractionKitError("PAYMASTER_ERROR", `context.exchangeRate could not be parsed as a bigint: ${String(context.exchangeRate)}`, { cause: ensureError(err) });
+				}
+				if (exchangeRate <= 0n) throw new AbstractionKitError("PAYMASTER_ERROR", `context.exchangeRate must be > 0, got ${exchangeRate}`);
+			} else return this.sponsoredFlow(userOp, bundlerRpc, entrypoint, chainIdHex, context, overrides);
+			const stub = await this.getStubData(userOp, entrypoint, chainIdHex, context);
+			this.applyPaymasterFields(userOp, stub);
+			if (paymasterAddress == null) if (context.paymasterAddress != null) paymasterAddress = context.paymasterAddress;
+			else if ("initCode" in userOp && stub.paymasterAndData != null) paymasterAddress = "0x" + stub.paymasterAndData.slice(2, 42);
+			else if (stub.paymaster != null) paymasterAddress = stub.paymaster;
+			else throw new AbstractionKitError("PAYMASTER_ERROR", "pm_getPaymasterStubData did not return a paymaster address. Pass paymasterAddress in the context or set a provider.");
+			const originalCallData = userOp.callData;
+			const requiresAllowanceReset = overrides.resetApproval ?? TOKENS_REQUIRING_ALLOWANCE_RESET.includes(tokenAddress.toLowerCase());
+			let callDataWithApprove = smartAccount.prependTokenPaymasterApproveToCallData(userOp.callData, tokenAddress, paymasterAddress, UINT256_MAX);
+			if (requiresAllowanceReset) callDataWithApprove = smartAccount.prependTokenPaymasterApproveToCallData(callDataWithApprove, tokenAddress, paymasterAddress, 0n);
+			userOp.callData = callDataWithApprove;
+			await this.estimateAndApplyGasLimits(userOp, bundlerRpc, entrypoint, overrides);
+			const maxGasCostWei = calculateUserOperationMaxGasCost(userOp);
+			const approveAmount = exchangeRate * maxGasCostWei / 10n ** 18n * TOKEN_APPROVE_AMOUNT_MULTIPLIER;
+			callDataWithApprove = smartAccount.prependTokenPaymasterApproveToCallData(originalCallData, tokenAddress, paymasterAddress, approveAmount);
+			if (requiresAllowanceReset) callDataWithApprove = smartAccount.prependTokenPaymasterApproveToCallData(callDataWithApprove, tokenAddress, paymasterAddress, 0n);
+			userOp.callData = callDataWithApprove;
+			const final = await this.getPaymasterData(userOp, entrypoint, chainIdHex, context);
+			this.applyPaymasterFields(userOp, final);
+			return userOp;
+		}
+		/**
+		* The regular (non-token) sponsored flow: stub → estimate → final.
+		* Extracted to allow `tokenPaymasterFlow` to fall through to it for Case C.
+		*/
+		async sponsoredFlow(userOp, bundlerRpc, entrypoint, chainIdHex, context, overrides) {
+			const stub = await this.getStubData(userOp, entrypoint, chainIdHex, context);
+			this.applyPaymasterFields(userOp, stub);
+			await this.estimateAndApplyGasLimits(userOp, bundlerRpc, entrypoint, overrides);
+			if (stub.isFinal === true) return userOp;
+			const final = await this.getPaymasterData(userOp, entrypoint, chainIdHex, context);
+			this.applyPaymasterFields(userOp, final);
+			return userOp;
+		}
+	};
+	//#endregion
 	//#region src/paymaster/AllowAllPaymaster.ts
 	/**
 	* A paymaster that sponsors all UserOperations unconditionally.
@@ -7105,6 +7501,7 @@ var abstractionkit = (function(exports, ethers) {
 		ENTRYPOINT_V9: () => ENTRYPOINT_V9,
 		EOADummySignerSignaturePair: () => EOADummySignerSignaturePair,
 		EXECUTE_RECOVERY_PRIMARY_TYPE: () => EXECUTE_RECOVERY_PRIMARY_TYPE,
+		Erc7677Paymaster: () => Erc7677Paymaster,
 		ExperimentalAllowAllParallelPaymaster: () => ExperimentalAllowAllParallelPaymaster,
 		GasOption: () => GasOption,
 		Operation: () => Operation,
@@ -7178,6 +7575,7 @@ var abstractionkit = (function(exports, ethers) {
 	exports.ENTRYPOINT_V9 = ENTRYPOINT_V9;
 	exports.EOADummySignerSignaturePair = EOADummySignerSignaturePair;
 	exports.EXECUTE_RECOVERY_PRIMARY_TYPE = EXECUTE_RECOVERY_PRIMARY_TYPE;
+	exports.Erc7677Paymaster = Erc7677Paymaster;
 	exports.ExperimentalAllowAllParallelPaymaster = ExperimentalAllowAllParallelPaymaster;
 	exports.GasOption = GasOption;
 	exports.Operation = Operation;