abstractionkit 0.3.0 → 0.3.2

package/dist/index.cjs

@@ -805,6 +805,52 @@ async function handlefetchGasPrice(providerRpc, polygonGasStation, gasLevel = Ga
 	return [maxFeePerGas, maxPriorityFeePerGas];
 }
 //#endregion
+//#region src/signer/negotiate.ts
+/**
+* Pick the best mutually-supported signing scheme for one signer against an
+* account's accepted schemes. Later in the `accepted` array = lower preference;
+* the account ranks by preference.
+*
+* Throws a detailed {@link AbstractionKitError} if no scheme overlaps,
+* citing the signer's address, what the account accepts, and what the
+* signer can do.
+*/
+function pickScheme(signer, accepted, context) {
+	const signerCan = [];
+	if (typeof signer.signTypedData === "function") signerCan.push("typedData");
+	if (typeof signer.signHash === "function") signerCan.push("hash");
+	for (const scheme of accepted) if (signerCan.includes(scheme)) return scheme;
+	throw new AbstractionKitError("BAD_DATA", buildMismatchMessage({
+		accountName: context.accountName,
+		signerIndex: context.signerIndex,
+		signerAddress: signer.address,
+		accepted,
+		signerCan
+	}));
+}
+function buildMismatchMessage(params) {
+	const { accountName, signerIndex, signerAddress, accepted, signerCan } = params;
+	const canStr = signerCan.length > 0 ? signerCan.join(", ") : "none";
+	return `No compatible signing scheme for signer[${signerIndex}] ${signerAddress}. ${accountName} accepts: [${accepted.join(", ")}]; signer provides: [${canStr}]. ` + (signerCan.length === 0 ? "Signer must implement at least one of `signHash` or `signTypedData`. " : "") + "Hint: `fromViem` / `fromEthersWallet` give both; `fromViemWalletClient` gives only `typedData` (use Safe for JSON-RPC wallets).";
+}
+/**
+* Invoke a signer for one scheme. Keeps the dispatch in one place so the
+* account-side code stays linear. `typedData` is optional: accounts that
+* only accept the `"hash"` scheme (Simple7702, Calibur) pass just `hash`.
+*
+* `context` is always forwarded to the signer so power-user implementations
+* can inspect the userOp.
+*/
+async function invokeSigner(signer, scheme, payload) {
+	if (scheme === "typedData") {
+		if (typeof signer.signTypedData !== "function") throw new AbstractionKitError("BAD_DATA", `signer ${signer.address} is missing signTypedData`);
+		if (!payload.typedData) throw new AbstractionKitError("BAD_DATA", `scheme "typedData" selected but no typedData payload provided`);
+		return signer.signTypedData(payload.typedData, payload.context);
+	}
+	if (typeof signer.signHash !== "function") throw new AbstractionKitError("BAD_DATA", `signer ${signer.address} is missing signHash`);
+	return signer.signHash(payload.hash, payload.context);
+}
+//#endregion
 //#region src/utils7702.ts
 const SET_CODE_TX_TYPE = "0x04";
 /**
@@ -1115,11 +1161,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) });
 		}
@@ -1579,6 +1628,30 @@ var BaseSimple7702Account = class BaseSimple7702Account extends SmartAccount {
 		return new ethers.Wallet(privateKey).signingKey.sign(userOperationHash).serialized;
 	}
 	/**
+	* Schemes Simple7702 accepts from a Signer. Only raw-hash ECDSA, since
+	* the delegatee verifies a plain signature over the userOp hash.
+	*/
+	static ACCEPTED_SIGNING_SCHEMES = ["hash"];
+	/**
+	* Sign a UserOperation with an {@link AkSigner}. Signer must implement
+	* `signHash`, since Simple7702 only verifies raw ECDSA over the userOp
+	* hash. JSON-RPC wallets and anything that only provides `signTypedData`
+	* fail offline with a specific error.
+	*/
+	async baseSignUserOperationWithSigner(useroperation, signer, chainId) {
+		return invokeSigner(signer, pickScheme(signer, BaseSimple7702Account.ACCEPTED_SIGNING_SCHEMES, {
+			accountName: "Simple7702 (raw ECDSA over userOpHash)",
+			signerIndex: 0
+		}), {
+			hash: createUserOperationHash(useroperation, this.entrypointAddress, chainId),
+			context: {
+				userOperation: useroperation,
+				chainId,
+				entryPoint: this.entrypointAddress
+			}
+		});
+	}
+	/**
 	* Submit a signed UserOperation to a bundler for on-chain inclusion.
 	* @param userOperation - The signed UserOperation to submit
 	* @param bundlerRpc - Bundler RPC endpoint
@@ -1689,6 +1762,18 @@ var Simple7702Account = class Simple7702Account extends BaseSimple7702Account {
 		return this.baseSignUserOperation(useroperation, privateKey, chainId);
 	}
 	/**
+	* Sign a {@link UserOperationV8} using an {@link ExternalSigner}.
+	* Simple7702 only accepts raw-hash ECDSA; signers without `signHash`
+	* fail offline with an actionable error.
+	*
+	* For signing with a raw private-key string, use the sync
+	* {@link signUserOperation} method, or wrap explicitly with
+	* `fromPrivateKey(pk)`.
+	*/
+	async signUserOperationWithSigner(useroperation, signer, chainId) {
+		return this.baseSignUserOperationWithSigner(useroperation, signer, chainId);
+	}
+	/**
 	* Send a signed {@link UserOperationV8} to a bundler for on-chain inclusion.
 	* @param userOperation - The signed UserOperation to submit
 	* @param bundlerRpc - Bundler RPC endpoint
@@ -1754,6 +1839,15 @@ var Simple7702AccountV09 = class Simple7702AccountV09 extends BaseSimple7702Acco
 		return this.baseSignUserOperation(useroperation, privateKey, chainId);
 	}
 	/**
+	* Sign a {@link UserOperationV9} using an {@link ExternalSigner}.
+	* Simple7702 only accepts raw-hash ECDSA; signers without `signHash`
+	* fail offline with an actionable error. For a raw pk string, use the
+	* sync {@link signUserOperation} method or wrap with `fromPrivateKey`.
+	*/
+	async signUserOperationWithSigner(useroperation, signer, chainId) {
+		return this.baseSignUserOperationWithSigner(useroperation, signer, chainId);
+	}
+	/**
 	* Send a signed {@link UserOperationV9} to a bundler for on-chain inclusion.
 	* @param userOperation - The signed UserOperation to submit
 	* @param bundlerRpc - Bundler RPC endpoint
@@ -3158,6 +3252,68 @@ var SafeAccount = class SafeAccount extends SmartAccount {
 		});
 	}
 	/**
+	* Schemes Safe accepts from a {@link Signer}, in preference order.
+	* `typedData` is preferred because wallets can display structured fields
+	* rather than a hex blob; `hash` is accepted as a fallback for signers
+	* that only support raw ECDSA.
+	*/
+	static ACCEPTED_SIGNING_SCHEMES = ["typedData", "hash"];
+	/**
+	* Sign a UserOperation using one or more {@link Signer}s. This is the
+	* capability-oriented signing path: each signer declares what it can do
+	* (`signHash`, `signTypedData`, both) and the account picks the best
+	* match per signer. Incompatible signers fail offline with an actionable
+	* error rather than a silent bundler rejection.
+	*
+	* Signers are invoked in parallel. For interactive wallets that share a
+	* popup session, sequence the prompts inside your Signer implementation.
+	*
+	* @param useroperation - UserOperation to sign
+	* @param signers - Signer instances (`fromViem(account)`, `fromEthersWallet(wallet)`, etc.)
+	* @param chainId - target chain id
+	* @param entrypointAddress - target EntryPoint
+	* @param safe4337ModuleAddress - Safe 4337 module
+	* @param overrides - optional validAfter / validUntil / multi-chain flag
+	* @returns formatted signature
+	*/
+	static async baseSignUserOperationWithSigners(useroperation, signers, chainId, entrypointAddress, safe4337ModuleAddress, context, overrides = {}) {
+		const validAfter = overrides.validAfter ?? 0n;
+		const validUntil = overrides.validUntil ?? 0n;
+		if (signers.length < 1) throw new RangeError("There should be at least one signer");
+		const typedDataRaw = SafeAccount.getUserOperationEip712Data(useroperation, chainId, {
+			validAfter,
+			validUntil,
+			entrypointAddress,
+			safe4337ModuleAddress
+		});
+		const userOpHash = ethers.TypedDataEncoder.hash(typedDataRaw.domain, typedDataRaw.types, typedDataRaw.messageValue);
+		const { EIP712Domain: _drop, ...primaryTypes } = typedDataRaw.types;
+		const typedData = {
+			domain: typedDataRaw.domain,
+			types: primaryTypes,
+			primaryType: EIP712_SAFE_OPERATION_PRIMARY_TYPE,
+			message: typedDataRaw.messageValue
+		};
+		const normalizedAddresses = signers.map((signer) => (0, ethers.getAddress)(signer.address));
+		const schemes = signers.map((signer, signerIndex) => pickScheme(signer, SafeAccount.ACCEPTED_SIGNING_SCHEMES, {
+			accountName: "Safe (EIP-712 or raw hash over SafeOp digest)",
+			signerIndex
+		}));
+		const signerSignaturePairs = (await Promise.all(signers.map((signer, i) => invokeSigner(signer, schemes[i], {
+			hash: userOpHash,
+			typedData,
+			context
+		})))).map((signature, i) => ({
+			signer: normalizedAddresses[i],
+			signature
+		}));
+		return SafeAccount.formatSignaturesToUseroperationSignature(signerSignaturePairs, {
+			validAfter,
+			validUntil,
+			isMultiChainSignature: overrides.isMultiChainSignature
+		});
+	}
+	/**
 	* compute the deterministic address for a webauthn proxy verifier based on a
 	* webauthn public key(x, y)
 	* @param x - webauthn public key x parameter
@@ -3804,7 +3960,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.2") {
 	const identifierPrefix = "5afe";
 	const identifierVersion = "00";
 	const projectHash = (0, ethers.keccak256)("0x" + Buffer.from(project, "utf8").toString("hex")).slice(-20);
@@ -3881,6 +4037,17 @@ const DEFAULT_WEB_AUTHN_DAIMO_VERIFIER_V_0_2_1 = "0xc2b78104907F722DABAc4C69f826
 * with the Daimo P256 verifier instead of the FCL P256 verifier
 * used by the base SafeAccount class.
 * @see {@link https://github.com/safe-fndn/safe-modules/blob/04e65efbce634e776cc8c1fbe90061f09e09a71b/modules/passkey/CHANGELOG.md?plain=1#L23}
+*
+* @remarks Signer typing on this class is asymmetric:
+* - {@link signUserOperationWithSigners} (singular Operation) signs one op
+*   and uses {@link SignContext} like every other account.
+* - {@link signUserOperationsWithSigners} (plural Operations) signs a bundle
+*   under one signature and uses {@link MultiOpSignContext}.
+*
+* To author one signer that works on both methods, type it as
+* `ExternalSigner<unknown>` (the shape returned by the built-in adapters).
+* The two narrow context types exist so signers that DO read the context
+* get accurate, non-optional fields per path.
 */
 var SafeMultiChainSigAccountV1 = class SafeMultiChainSigAccountV1 extends SafeAccount {
 	static DEFAULT_ENTRYPOINT_ADDRESS = ENTRYPOINT_V9;
@@ -4099,6 +4266,23 @@ var SafeMultiChainSigAccountV1 = class SafeMultiChainSigAccountV1 extends SafeAc
 		});
 	}
 	/**
+	* Sign a single UserOperation for multi-chain using one or more
+	* {@link AkSigner} instances. See
+	* {@link SafeAccountV0_3_0.signUserOperationWithSigners} for the full
+	* design rationale. Sets the multi-chain flag automatically.
+	*/
+	signUserOperationWithSigners(userOperation, signers, chainId, overrides = {}) {
+		const context = {
+			userOperation,
+			chainId,
+			entryPoint: this.entrypointAddress
+		};
+		return SafeAccount.baseSignUserOperationWithSigners(userOperation, signers, chainId, this.entrypointAddress, this.safe4337ModuleAddress, context, {
+			...overrides,
+			isMultiChainSignature: true
+		});
+	}
+	/**
 	* sign a list of useroperations - multi chain signature
 	* @param useroperation - useroperation to sign
 	* @param privateKeys - for the signers
@@ -4149,6 +4333,86 @@ var SafeMultiChainSigAccountV1 = class SafeMultiChainSigAccountV1 extends SafeAc
 		})];
 	}
 	/**
+	* Sign a list of UserOperations with a single multi-chain signature,
+	* using {@link AkSigner} instances typed for {@link MultiOpSignContext}
+	* (viem, ethers, hardware wallet, HSM, MPC, Uint8Array-only). Each
+	* signer signs the Merkle root of the UserOperation EIP-712 hashes via
+	* raw-hash signing. `signTypedData` isn't exposed here because the
+	* Merkle root is opaque and has no meaningful typed-data display.
+	*
+	* Signers always receive {@link MultiOpSignContext} regardless of bundle
+	* length, so multi-op-typed signers can rely on `ctx.userOperations`
+	* being defined. Pre-built adapters `fromPrivateKey`, `fromViem`, and
+	* `fromEthersWallet` return a universal `Signer<unknown>` and work
+	* here without retyping; user-defined single-op signers
+	* (`Signer<SignContext>`) do not — they would receive a context shape
+	* they didn't declare. `fromViemWalletClient` is **not** usable on the
+	* multi-op Merkle path: it only exposes `signTypedData`, and the
+	* Merkle root has no meaningful typed-data display. {@link pickScheme}
+	* rejects it offline with an actionable error.
+	*
+	* @param userOperationsToSign - UserOperations + chain IDs + validity windows
+	* @param signers - one Signer per owner (any order; sorted by address on-chain)
+	* @returns one signature per input UserOperation, in the same order
+	*/
+	async signUserOperationsWithSigners(userOperationsToSign, signers) {
+		if (userOperationsToSign.length < 1) throw new RangeError("There should be at least one userOperationsToSign");
+		if (signers.length < 1) throw new RangeError("There should be at least one signer");
+		const context = {
+			userOperations: userOperationsToSign.map((u) => ({
+				userOperation: u.userOperation,
+				chainId: u.chainId
+			})),
+			entryPoint: this.entrypointAddress
+		};
+		if (userOperationsToSign.length > 1) {
+			const userOperationsHashes = [];
+			userOperationsToSign.forEach((uopToSign) => {
+				const userOperationHash = SafeAccount.getUserOperationEip712Hash_V9(uopToSign.userOperation, uopToSign.chainId, {
+					validAfter: uopToSign.validAfter,
+					validUntil: uopToSign.validUntil,
+					safe4337ModuleAddress: this.safe4337ModuleAddress,
+					entrypointAddress: this.entrypointAddress
+				});
+				userOperationsHashes.push(userOperationHash);
+			});
+			const [root, proofs] = generateMerkleProofs(userOperationsHashes);
+			const merkleTreeRootHash = ethers.TypedDataEncoder.hash({ verifyingContract: this.safe4337ModuleAddress }, EIP712_MULTI_CHAIN_OPERATIONS_TYPE, { merkleTreeRoot: root });
+			const normalizedAddresses = signers.map((signer) => (0, ethers.getAddress)(signer.address));
+			signers.forEach((signer, i) => {
+				pickScheme(signer, ["hash"], {
+					accountName: "SafeMultiChainSigAccountV1 (multi-op Merkle root)",
+					signerIndex: i
+				});
+			});
+			const signatures = await Promise.all(signers.map((signer) => invokeSigner(signer, "hash", {
+				hash: merkleTreeRootHash,
+				context
+			})));
+			const signerSignaturePairs = signers.map((_signer, i) => ({
+				signer: normalizedAddresses[i],
+				signature: signatures[i]
+			}));
+			const userOpSignatures = [];
+			userOperationsToSign.forEach((uopToSign, index) => {
+				userOpSignatures.push(SafeAccount.formatSignaturesToUseroperationSignature(signerSignaturePairs, {
+					validAfter: uopToSign.validAfter,
+					validUntil: uopToSign.validUntil,
+					isMultiChainSignature: true,
+					multiChainMerkleProof: proofs[index]
+				}));
+			});
+			return userOpSignatures;
+		} else {
+			const u = userOperationsToSign[0];
+			return [await SafeAccount.baseSignUserOperationWithSigners(u.userOperation, signers, u.chainId, this.entrypointAddress, this.safe4337ModuleAddress, context, {
+				validAfter: u.validAfter,
+				validUntil: u.validUntil,
+				isMultiChainSignature: true
+			})];
+		}
+	}
+	/**
 	* Compute the EIP-712 hash of a multi-chain Merkle tree root for a set of UserOperations.
 	* This hash is what signers sign to approve multiple cross-chain operations at once.
 	* @param userOperationsToSignsToSign - list of UserOperations with their target chain IDs
@@ -4192,36 +4456,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]
 			}));
@@ -4622,34 +4889,42 @@ var Calibur7702Account = class Calibur7702Account extends SmartAccount {
 		return Calibur7702Account.wrapSignature(keyHash, ecdsaSig, hookData);
 	}
 	/**
-	* Sign a UserOperation with an external signer (viem, ethers Signer,
-	* hardware wallet, MPC signer, etc.).
-	* Computes the UserOperation hash and wraps the returned signature in
-	* Calibur's format: `abi.encode(keyHash, ecdsaSig, hookData)`.
+	* Schemes Calibur accepts from a Signer. Only raw-hash ECDSA, since
+	* the account verifies a plain signature over the userOp hash, then
+	* wraps with `(keyHash, signature, hookData)`.
+	*/
+	static ACCEPTED_SIGNING_SCHEMES = ["hash"];
+	/**
+	* Sign a UserOperation using an {@link ExternalSigner}. Calibur only
+	* accepts raw-hash ECDSA; signers without `signHash` fail offline with
+	* an actionable error.
 	*
-	* By default signs with the root key. To sign with a registered
-	* secondary key, pass its key hash via `overrides.keyHash`.
-	*
-	* @param userOperation - The UserOperation to sign
-	* @param signer - Async signing function: `(hash: string) => Promise<string>`
-	* @param chainId - Target chain ID
-	* @param overrides - Optional overrides (keyHash for secondary keys, hookData)
-	* @returns Promise resolving to the hex-encoded wrapped signature
+	* For signing with a raw private-key string, use the sync
+	* {@link signUserOperation} method, or wrap explicitly with
+	* `fromPrivateKey(pk)`. For secondary (non-root) keys, pass the key
+	* hash via `overrides.keyHash`.
 	*
 	* @example
-	* // Sign with a viem wallet client
+	* import { fromViem, fromEthersWallet } from "abstractionkit";
 	* userOp.signature = await account.signUserOperationWithSigner(
-	*   userOp,
-	*   (hash) => walletClient.signMessage({ message: { raw: hash } }),
-	*   chainId,
+	*   userOp, fromViem(privateKeyToAccount(pk)), chainId,
 	* );
 	*/
 	async signUserOperationWithSigner(userOperation, signer, chainId, overrides = {}) {
-		const userOperationHash = createUserOperationHash(userOperation, this.entrypointAddress, chainId);
+		const signature = await invokeSigner(signer, pickScheme(signer, Calibur7702Account.ACCEPTED_SIGNING_SCHEMES, {
+			accountName: "Calibur (raw ECDSA over userOpHash)",
+			signerIndex: 0
+		}), {
+			hash: createUserOperationHash(userOperation, this.entrypointAddress, chainId),
+			context: {
+				userOperation,
+				chainId,
+				entryPoint: this.entrypointAddress
+			}
+		});
 		const keyHash = overrides.keyHash ?? ROOT_KEY_HASH;
 		const hookData = overrides.hookData ?? "0x";
-		const ecdsaSig = await signer(userOperationHash);
-		return Calibur7702Account.wrapSignature(keyHash, ecdsaSig, hookData);
+		return Calibur7702Account.wrapSignature(keyHash, signature, hookData);
 	}
 	/**
 	* Format a WebAuthn (passkey) assertion into Calibur's signature format.
@@ -5120,6 +5395,88 @@ var Calibur7702Account = class Calibur7702Account extends SmartAccount {
 	}
 };
 //#endregion
+//#region src/signer/adapters.ts
+/**
+* Build a Signer from a raw private key. Uses the library's existing
+* ethers dependency internally, so no additional packages are required on
+* the caller side. Supports both raw-hash and typed-data signing.
+*
+* Prefer this when all you have is a private key (test suites, server-side
+* scripts, scripts with env-injected keys, etc.). If you already hold a
+* viem Account or ethers Wallet from elsewhere in your app, pass it to
+* {@link fromViem} or {@link fromEthersWallet} instead.
+*
+* @example
+* import { fromPrivateKey } from "abstractionkit";
+* const signer = fromPrivateKey(process.env.PRIVATE_KEY!);
+* userOp.signature = await safe.signUserOperationWithSigners(userOp, [signer], chainId);
+*/
+function fromPrivateKey(privateKey) {
+	const wallet = new ethers.Wallet(privateKey);
+	return {
+		address: (0, ethers.getAddress)(wallet.address),
+		signHash: async (hash) => wallet.signingKey.sign(hash).serialized,
+		signTypedData: async (td) => await wallet.signTypedData(td.domain, td.types, td.message)
+	};
+}
+/**
+* Adapt a viem Local Account (e.g. `privateKeyToAccount(pk)`) to a Signer.
+* Supports both raw-hash and typed-data signing.
+*
+* @remarks Requires viem &gt;= 2.0.
+*/
+function fromViem(account) {
+	return {
+		address: account.address,
+		signHash: (hash) => account.sign({ hash }),
+		signTypedData: (td) => account.signTypedData({
+			domain: td.domain,
+			types: td.types,
+			primaryType: td.primaryType,
+			message: td.message
+		})
+	};
+}
+/**
+* Adapt a viem WalletClient to a Signer. WalletClient is the client-style
+* API dApps use to drive browser / JSON-RPC wallets, so only typed-data
+* signing is exposed (JSON-RPC wallets can't sign raw hashes).
+*
+* Requires the client to have been constructed with an `account` (local or
+* JSON-RPC). For local accounts, pass that directly to `fromViem` instead
+* if you want raw-hash fallback.
+*
+* @remarks Requires viem &gt;= 2.0.
+*/
+function fromViemWalletClient(client) {
+	if (!client.account) throw new Error("fromViemWalletClient: client has no `account` configured. Construct with `createWalletClient({ account, transport, chain })`.");
+	const account = client.account;
+	const signTypedData = client.signTypedData;
+	return {
+		address: account.address,
+		signTypedData: (td) => signTypedData({
+			account,
+			domain: td.domain,
+			types: td.types,
+			primaryType: td.primaryType,
+			message: td.message
+		})
+	};
+}
+/**
+* Adapt an ethers `Wallet` / `HDNodeWallet` to a Signer. Supports both
+* raw-hash and typed-data signing.
+*
+* @remarks Requires ethers &gt;= 6.0.
+*/
+function fromEthersWallet(wallet) {
+	return {
+		address: wallet.address,
+		signHash: async (hash) => wallet.signingKey.sign(hash).serialized,
+		signTypedData: async (td) => await wallet.signTypedData(td.domain, td.types, td.message)
+	};
+}
+//#endregion
 //#region src/account/Safe/modules/SafeModule.ts
 /**
 * Abstract base class for Safe modules. Provides shared utilities for
@@ -6123,6 +6480,45 @@ var SafeAccountV0_3_0 = class SafeAccountV0_3_0 extends SafeAccount {
 	signUserOperation(useroperation, privateKeys, chainId, overrides = {}) {
 		return SafeAccount.baseSignSingleUserOperation(useroperation, privateKeys, chainId, this.entrypointAddress, this.safe4337ModuleAddress, overrides);
 	}
+	/**
+	* Sign a UserOperation using one or more {@link ExternalSigner} instances.
+	* Capability-oriented entry point: each Signer declares what it can do
+	* (`signHash`, `signTypedData`, both) and the account picks the best
+	* match per signer. Incompatible signers fail offline with an actionable
+	* error — no silent bundler rejections.
+	*
+	* This method is for external signers only (viem, ethers, hardware
+	* wallets, MPC, HSMs, Uint8Array-only signers). If you just have a raw
+	* private-key string, use the sync {@link signUserOperation} method
+	* instead, or wrap explicitly with `fromPrivateKey(pk)`.
+	*
+	* Prebuilt adapters: `fromViem`, `fromEthersWallet`,
+	* `fromViemWalletClient`, `fromPrivateKey`. Custom signers just need to
+	* match the `ExternalSigner` shape.
+	*
+	* @example
+	* import { fromViem } from "abstractionkit";
+	* import { privateKeyToAccount } from "viem/accounts";
+	*
+	* const signer = fromViem(privateKeyToAccount(pk));
+	* userOp.signature = await account.signUserOperationWithSigners(
+	*   userOp, [signer], chainId,
+	* );
+	*
+	* @param useroperation - UserOperation to sign
+	* @param signers - one ExternalSigner per owner (any order)
+	* @param chainId - target chain ID
+	* @param overrides - optional validAfter / validUntil / multi-chain flag
+	* @returns Promise resolving to the formatted signature string
+	*/
+	signUserOperationWithSigners(useroperation, signers, chainId, overrides = {}) {
+		const context = {
+			userOperation: useroperation,
+			chainId,
+			entryPoint: this.entrypointAddress
+		};
+		return SafeAccount.baseSignUserOperationWithSigners(useroperation, signers, chainId, this.entrypointAddress, this.safe4337ModuleAddress, context, overrides);
+	}
 };
 //#endregion
 //#region src/account/Safe/SafeAccountV0_2_0.ts
@@ -6365,6 +6761,19 @@ var SafeAccountV0_2_0 = class SafeAccountV0_2_0 extends SafeAccount {
 	signUserOperation(useroperation, privateKeys, chainId, overrides = {}) {
 		return SafeAccount.baseSignSingleUserOperation(useroperation, privateKeys, chainId, this.entrypointAddress, this.safe4337ModuleAddress, overrides);
 	}
+	/**
+	* Sign a UserOperation using one or more {@link AkSigner} instances.
+	* See {@link SafeAccountV0_3_0.signUserOperationWithSigners} for full
+	* design rationale and examples.
+	*/
+	signUserOperationWithSigners(useroperation, signers, chainId, overrides = {}) {
+		const context = {
+			userOperation: useroperation,
+			chainId,
+			entryPoint: this.entrypointAddress
+		};
+		return SafeAccount.baseSignUserOperationWithSigners(useroperation, signers, chainId, this.entrypointAddress, this.safe4337ModuleAddress, context, overrides);
+	}
 };
 //#endregion
 //#region src/account/Safe/SafeAccountV1_5_0_M_0_3_0.ts
@@ -6523,9 +6932,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).
@@ -6535,7 +6944,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).
@@ -6875,12 +7284,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;
@@ -6960,6 +7369,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.
@@ -7105,6 +7904,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,
@@ -7139,6 +7939,10 @@ var abstractionkit_exports = /* @__PURE__ */ __exportAll({
 	createWorldIdSignal: () => createWorldIdSignal,
 	fetchAccountNonce: () => fetchAccountNonce,
 	fetchGasPrice: () => fetchGasPrice,
+	fromEthersWallet: () => fromEthersWallet,
+	fromPrivateKey: () => fromPrivateKey,
+	fromViem: () => fromViem,
+	fromViemWalletClient: () => fromViemWalletClient,
 	getBalanceOf: () => getBalanceOf,
 	getDelegatedAddress: () => getDelegatedAddress,
 	getDepositInfo: () => getDepositInfo,
@@ -7178,6 +7982,7 @@ exports.ENTRYPOINT_V8 = ENTRYPOINT_V8;
 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;
@@ -7218,6 +8023,10 @@ exports.createUserOperationHash = createUserOperationHash;
 exports.createWorldIdSignal = createWorldIdSignal;
 exports.fetchAccountNonce = fetchAccountNonce;
 exports.fetchGasPrice = fetchGasPrice;
+exports.fromEthersWallet = fromEthersWallet;
+exports.fromPrivateKey = fromPrivateKey;
+exports.fromViem = fromViem;
+exports.fromViemWalletClient = fromViemWalletClient;
 exports.getBalanceOf = getBalanceOf;
 exports.getDelegatedAddress = getDelegatedAddress;
 exports.getDepositInfo = getDepositInfo;