abstractionkit 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 0.3.2
+
+### New Features
+
+- **`signUserOperationWithSigner(s)` + `ExternalSigner` (capability-oriented signing API)**: new async method on every account class for integrating viem, ethers Signers, hardware wallets, HSMs, MPC, WebAuthn, or Uint8Array-only signers without passing raw private keys. Each account declares its accepted schemes via a static `ACCEPTED_SIGNING_SCHEMES: ReadonlyArray<"hash" | "typedData">`, and incompatible signers fail offline with an actionable error. The method naming mirrors the parameter arity:
+  - Safe accounts (multi-signer): `signUserOperationWithSigners(op, signers[], chainId)` — plural.
+  - Simple7702 / Calibur (single signer): `signUserOperationWithSigner(op, signer, chainId)` — singular.
+
+  Call-site is one line:
+  ```ts
+  import { fromViem } from "abstractionkit"
+  userOp.signature = await safe.signUserOperationWithSigners(
+      userOp, [fromViem(account)], chainId,
+  )
+  ```
+
+- **`ExternalSigner` interface**: `{ address, signHash?, signTypedData? }` discriminated union that enforces at least one of the two methods at compile time. Accepts any signer that matches the shape (viem local account, viem WalletClient, ethers Wallet, hardware wallet, MPC, WebAuthn, Uint8Array-held keys). The library has zero runtime dependency on viem or ethers for this surface.
+- **`fromPrivateKey(pk)` / `fromViem(account)` / `fromEthersWallet(wallet)` / `fromViemWalletClient(client)` adapters**: one-line factories returning an `ExternalSigner`. Structural types only. `fromViem` / `fromViemWalletClient` require viem ≥ 2.0; `fromEthersWallet` requires ethers ≥ 6.0.
+- **`SignHashFn` / `SignTypedDataFn` / `TypedData` / `SigningScheme` / `SignContext` / `MultiOpSignContext` types** exported from the package root for implementers of custom signers.
+- **`SignContext` forwarded to signers, narrowly typed per signing path**: signers receive a context as the second arg of `signHash` / `signTypedData` so custom validator implementations can inspect the userOp. `Signer<C>` is generic over context (default `C = SignContext` for single-op `{userOperation, chainId, entryPoint}`; opt into `ExternalSigner<MultiOpSignContext>` for `signUserOperationsWithSigners`'s `{userOperations[], entryPoint}`). Built-in adapters return `Signer<unknown>` and work everywhere. See `src/signer/types.ts`.
+- **`SafeMultiChainSigAccountV1.signUserOperationsWithSigners`**: new async multi-op variant that signs a Merkle-rooted bundle of UserOperations with a single signature across chains, using `ExternalSigner[]`.
+
+### Breaking Changes
+
+> **Note on versioning.** The callback-API removal below is a breaking change for callers of `signUserOperationWithSigner`'s prior callback shape on `Calibur7702Account`. Calibur is not yet in use in any production environment; we're communicating directly with the developers currently building against it to coordinate the migration.
+
+- **`SafeAccount.baseSignSingleUserOperation` is now `protected static`.** Previously `public static`, which leaked an internal helper into the package surface. All callers should use the version-specific subclass methods that wrap it (`SafeAccountV0_2_0#signUserOperation`, `SafeAccountV0_3_0#signUserOperation`, etc.) — they auto-inject the correct entrypoint and 4337 module addresses. Migration:
+  ```ts
+  // Before:
+  const sig = SafeAccount.baseSignSingleUserOperation(
+    op, [pk], chainId,
+    SafeAccountV0_3_0.DEFAULT_ENTRYPOINT_ADDRESS,
+    SafeAccountV0_3_0.DEFAULT_SAFE_4337_MODULE_ADDRESS,
+  );
+  // After:
+  const sig = safeV3.signUserOperation(op, [pk], chainId);
+  ```
+  `baseSignUserOperationWithSigners` (introduced earlier in this Unreleased window) is also `protected static` for the same reason; no migration needed since it was never on a released `latest` tag.
+- **`ViemLocalAccountLike` / `ViemWalletClientLike` / `EthersWalletLike` are no longer exported.** They're internal structural shapes the adapters match against; pass concrete viem / ethers instances directly to `fromViem` / `fromViemWalletClient` / `fromEthersWallet`. If you need to type a wrapper, use `Parameters<typeof fromViem>[0]` (etc.).
+- **Callback signing API removed.** `signUserOperationWithSigner(op, callback, chainId)` as introduced in the original signer PR is gone, along with the `SignerFunction`, `AddressedSignerFunction`, `SignerInput`, `SignerResult`, and `SignerTypedData` types. The callback method name is now reused for the new capability-oriented API on single-signer accounts (Simple7702, Calibur) with a different parameter shape. Migration:
+  ```ts
+  // Before:
+  const signer = async ({ userOpHash }) => ({
+    signature: wallet.signingKey.sign(userOpHash).serialized,
+  });
+  userOp.signature = await account.signUserOperationWithSigner(userOp, signer, chainId);
+
+  // After — Simple7702 / Calibur (single signer):
+  import { fromEthersWallet } from "abstractionkit";
+  userOp.signature = await account.signUserOperationWithSigner(
+    userOp, fromEthersWallet(wallet), chainId,
+  );
+
+  // After — Safe accounts (multi-signer, plural method name):
+  userOp.signature = await safe.signUserOperationWithSigners(
+    userOp, [fromEthersWallet(wallet)], chainId,
+  );
+  ```
+
+### Migration: Signing with a raw private key
+
+The existing sync `signUserOperation(op, pk[] | pk, chainId): string` method on every account **is untouched**. If your code passes a hex private-key string directly, no change needed. The new `signUserOperationWithSigner(s)` methods are Signers-only — they do NOT accept bare pk strings. To sign with a pk string via the new API, wrap explicitly:
+
+```ts
+import { fromPrivateKey } from "abstractionkit";
+userOp.signature = await safe.signUserOperationWithSigners(
+  userOp, [fromPrivateKey(pk)], chainId,
+);
+```
+
 ## 0.3.1
 
 ### New Features

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";
 /**
@@ -1582,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
@@ -1692,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
@@ -1757,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
@@ -3161,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
@@ -3807,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.1") {
+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);
@@ -3884,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;
@@ -4102,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
@@ -4152,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
@@ -4628,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)`.
-	*
-	* By default signs with the root key. To sign with a registered
-	* secondary key, pass its key hash via `overrides.keyHash`.
+	* 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.
 	*
-	* @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.
@@ -5126,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
@@ -6129,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
@@ -6371,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
@@ -7536,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,
@@ -7616,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;