abstractionkit 0.3.0 → 0.3.1

package/dist/index.mjs

@@ -1103,11 +1103,14 @@ var Bundler = class {
 				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) });
 		}
@@ -3792,7 +3795,7 @@ var SafeAccount = class SafeAccount extends SmartAccount {
 * @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 = keccak256("0x" + Buffer.from(project, "utf8").toString("hex")).slice(-20);
@@ -4180,36 +4183,39 @@ var SafeMultiChainSigAccountV1 = class SafeMultiChainSigAccountV1 extends SafeAc
 	* @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]
 			}));
@@ -6511,9 +6517,9 @@ var Paymaster = class {};
 /** 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).
@@ -6523,7 +6529,7 @@ const TOKEN_APPROVE_AMOUNT_MULTIPLIER = 2n;
 * 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).
@@ -6863,12 +6869,12 @@ var CandidePaymaster = class CandidePaymaster extends Paymaster {
 				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;
@@ -6948,6 +6954,396 @@ var CandidePaymaster = class CandidePaymaster extends Paymaster {
 	}
 };
 //#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.
@@ -7093,6 +7489,7 @@ var abstractionkit_exports = /* @__PURE__ */ __exportAll({
 	ENTRYPOINT_V9: () => ENTRYPOINT_V9,
 	EOADummySignerSignaturePair: () => EOADummySignerSignaturePair,
 	EXECUTE_RECOVERY_PRIMARY_TYPE: () => EXECUTE_RECOVERY_PRIMARY_TYPE,
+	Erc7677Paymaster: () => Erc7677Paymaster,
 	ExperimentalAllowAllParallelPaymaster: () => ExperimentalAllowAllParallelPaymaster,
 	GasOption: () => GasOption,
 	Operation: () => Operation,
@@ -7143,6 +7540,6 @@ var abstractionkit_exports = /* @__PURE__ */ __exportAll({
 	simulateUserOperationWithTenderlyAndCreateShareLink: () => simulateUserOperationWithTenderlyAndCreateShareLink
 });
 //#endregion
-export { ALLOWANCE_MODULE_V0_1_0_ADDRESS, AbstractionKitError, AllowanceModule, BaseUserOperationDummyValues, Bundler, CALIBUR_CANDIDE_V0_1_0_SINGLETON_ADDRESS, CALIBUR_UNISWAP_V1_0_0_SINGLETON_ADDRESS, Calibur7702Account, CaliburKeyType, CandidePaymaster, DEFAULT_SECP256R1_PRECOMPILE_ADDRESS, EIP712_MULTI_CHAIN_OPERATIONS_PRIMARY_TYPE, EIP712_MULTI_CHAIN_OPERATIONS_TYPE, EIP712_RECOVERY_MODULE_TYPE, EIP712_SAFE_OPERATION_PRIMARY_TYPE, EIP712_SAFE_OPERATION_V6_TYPE, EIP712_SAFE_OPERATION_V7_TYPE, ENTRYPOINT_V6, ENTRYPOINT_V7, ENTRYPOINT_V8, ENTRYPOINT_V9, EOADummySignerSignaturePair, EXECUTE_RECOVERY_PRIMARY_TYPE, ExperimentalAllowAllParallelPaymaster, GasOption, Operation, PolygonChain, SAFE_MESSAGE_MODULE_TYPE, SAFE_MESSAGE_PRIMARY_TYPE, SafeAccountFactory, SafeAccountV0_2_0, SafeAccountV0_3_0, SafeAccountV1_5_0_M_0_3_0, SafeModuleExecutorFunctionSelector, SafeMultiChainSigAccountV1, SendUseroperationResponse, Simple7702Account, Simple7702AccountV09, SmartAccount, SmartAccountFactory, SocialRecoveryModule, SocialRecoveryModuleGracePeriodSelector, WebauthnDummySignerSignaturePair, WorldIdPermissionlessPaymaster, ZeroAddress, abstractionkit_exports as abstractionkit, calculateUserOperationMaxGasCost, callTenderlySimulateBundle, createAndSignEip7702DelegationAuthorization, createAndSignEip7702RawTransaction, createAndSignLegacyRawTransaction, createCallData, createEip7702DelegationAuthorizationHash, createEip7702TransactionHash, createUserOperationHash, createWorldIdSignal, fetchAccountNonce, fetchGasPrice, getBalanceOf, getDelegatedAddress, getDepositInfo, getFunctionSelector, getSafeMessageEip712Data, sendJsonRpcRequest, shareTenderlySimulationAndCreateLink, signHash, simulateSenderCallDataWithTenderly, simulateSenderCallDataWithTenderlyAndCreateShareLink, simulateUserOperationCallDataWithTenderly, simulateUserOperationCallDataWithTenderlyAndCreateShareLink, simulateUserOperationWithTenderly, simulateUserOperationWithTenderlyAndCreateShareLink };
+export { ALLOWANCE_MODULE_V0_1_0_ADDRESS, AbstractionKitError, AllowanceModule, BaseUserOperationDummyValues, Bundler, CALIBUR_CANDIDE_V0_1_0_SINGLETON_ADDRESS, CALIBUR_UNISWAP_V1_0_0_SINGLETON_ADDRESS, Calibur7702Account, CaliburKeyType, CandidePaymaster, DEFAULT_SECP256R1_PRECOMPILE_ADDRESS, EIP712_MULTI_CHAIN_OPERATIONS_PRIMARY_TYPE, EIP712_MULTI_CHAIN_OPERATIONS_TYPE, EIP712_RECOVERY_MODULE_TYPE, EIP712_SAFE_OPERATION_PRIMARY_TYPE, EIP712_SAFE_OPERATION_V6_TYPE, EIP712_SAFE_OPERATION_V7_TYPE, ENTRYPOINT_V6, ENTRYPOINT_V7, ENTRYPOINT_V8, ENTRYPOINT_V9, EOADummySignerSignaturePair, EXECUTE_RECOVERY_PRIMARY_TYPE, Erc7677Paymaster, ExperimentalAllowAllParallelPaymaster, GasOption, Operation, PolygonChain, SAFE_MESSAGE_MODULE_TYPE, SAFE_MESSAGE_PRIMARY_TYPE, SafeAccountFactory, SafeAccountV0_2_0, SafeAccountV0_3_0, SafeAccountV1_5_0_M_0_3_0, SafeModuleExecutorFunctionSelector, SafeMultiChainSigAccountV1, SendUseroperationResponse, Simple7702Account, Simple7702AccountV09, SmartAccount, SmartAccountFactory, SocialRecoveryModule, SocialRecoveryModuleGracePeriodSelector, WebauthnDummySignerSignaturePair, WorldIdPermissionlessPaymaster, ZeroAddress, abstractionkit_exports as abstractionkit, calculateUserOperationMaxGasCost, callTenderlySimulateBundle, createAndSignEip7702DelegationAuthorization, createAndSignEip7702RawTransaction, createAndSignLegacyRawTransaction, createCallData, createEip7702DelegationAuthorizationHash, createEip7702TransactionHash, createUserOperationHash, createWorldIdSignal, fetchAccountNonce, fetchGasPrice, getBalanceOf, getDelegatedAddress, getDepositInfo, getFunctionSelector, getSafeMessageEip712Data, sendJsonRpcRequest, shareTenderlySimulationAndCreateLink, signHash, simulateSenderCallDataWithTenderly, simulateSenderCallDataWithTenderlyAndCreateShareLink, simulateUserOperationCallDataWithTenderly, simulateUserOperationCallDataWithTenderlyAndCreateShareLink, simulateUserOperationWithTenderly, simulateUserOperationWithTenderlyAndCreateShareLink };
 
 //# sourceMappingURL=index.mjs.map