SafeMultiChainSigAccount, Simple7702AccountV09 and AllowAllPaymaster

[sherifahmed990]

Summary by CodeRabbit

• New Features
  • Safe v9 and Safe v1.5.0 support, experimental multi‑chain signatures (Merkle proofs) and multi‑chain account flows; Simple7702 v0.9 and EIP‑7702 tooling; expanded paymaster ecosystem (token & sponsor flows, AllowAll, Candide, WorldId); improved bundler client, gas estimation, Tenderly simulation, merkle & multisend utilities, enhanced account factory helpers and allowance/social‑recovery workflows.
• Documentation
  • README: recipes, bundler/paymaster guidance, token‑paymaster steps, version table, AI agent snippet, formatting fixes.
• Bug Fixes
  • Numerous typos and wording corrections.
• Chores
  • Package version bumped; CI build workflow added.

[Sednaoui]

Export UserOperationV9 from main entry point (currently requires importing from abstractionkit/dist/types)

[sherifahmed990]

Export UserOperationV9 from main entry point (currently requires importing from abstractionkit/dist/types)

fixed

[Sednaoui]

There's a bug where WebAuthnSignatureOverrides aren't being passed through properly in formatSignaturesToUseroperationsSignatures.

I am using the isInit override for creating a passkeys example, and it is not propagated to the internal formatSignaturesToUseroperationSignature calls.

[Sednaoui]

MultiChainSignatureMerkleTreeRootTypedDataDomain returns types that require casting to work with viem's signTypedData:

// Current - requires awkward casting                                                                                                                                                       
const signature = await walletClient.signTypedData({                                                                                                                                        
    domain: eip712Data.domain as Parameters<typeof walletClient.signTypedData>[0]['domain'],                                                                                                
    types: eip712Data.types,                                                                                                                                                                
    primaryType: 'MerkleTreeRoot',                                                                                                                                                          
    message: eip712Data.messageValue as unknown as Record<string, unknown>                                                                                                                  
});                                                                                                                                                                                         

We can either:

• Document that primaryType should be 'MerkleTreeRoot' (the type name CrossChainSignatureMerkleTreeRootTypedMessageValue suggests otherwise)
• we can consider making return types compatible with viem's expected types, or provide a helper method

[Sednaoui]

missing JSDoc examples for multichain signing methods

[Sednaoui]

for the EIP-712 Type, developers need to know the correct primary type for EIP-712 signing. There's no way for developers to know it is 'MerkleTreeRoot'.

So I suggest to export it as constant MULTI_CHAIN_SIGNATURE_PRIMARY_TYPE

[Sednaoui]

@sherifahmed990 while doing a demo with SafeMultiChainSigAccount, the second operation when signing with passkeys always fails. I am not sure where is the issue, it might be similar to what we've found with the missing overrides. I will share with you script

[Sednaoui]

formatSignaturesToUseroperationsSignatures and getMultiChainSingleSignatureUserOperationsEip712Hash are using different default safe4337ModuleAddress values:

• getMultiChainSingleSignatureUserOperationsEip712Hash correctly defaults to ExperimentalSafeMultiChainSigAccount.DEFAULT_SAFE_4337_MODULE_ADDRESS (0x22939E...)

• formatSignaturesToUseroperationsSignatures calls getUserOperationEip712Hash_V9 without overriding the address, so it falls through to the base SafeAccount default (0xee8005d7...)

• The instance method signUserOperations() avoids this because it passes this.safe4337ModuleAddress explicitly everywhere. But the static method path (which is the only option for WebAuthn since signing requires browser interaction) hits the mismatch.

The fix should be in formatSignaturesToUseroperationsSignatures. it should default to DEFAULT_SAFE_4337_MODULE_ADDRESS when safe4337ModuleAddress isn't provided, same asgetMultiChainSingleSignatureUserOperationsEip712Hash does.

When isInit: false, formatSignaturesToUseroperationsSignatures computes the WebAuthn signer address using the base class defaults , including the eip7212WebAuthnPrecompileVerifier and eip7212WebAuthnContractVerifier

[Sednaoui]

see comments

[sherifahmed990]

3. formatSignaturesToUseroperationsSignatures (the static external-signer API) throws RangeError("invalid multiChainMerkleProof length.") when called with a single operation.

With 1 hash, generateMerkleProofs produces a proof string that is just the root (32 bytes = 64 hex chars). This proof is passed as multiChainMerkleProof to formatSignaturesToUseroperationSignature, where the length check merkleProofLength < 128 fails and throws.

Meanwhile, signUserOperations with 1 op takes a different path — it calls signUserOperation which sets isMultiChainSignature: true with no multiChainMerkleProof, correctly encoding depth 0.

Fix: add a length==1 special case in formatSignaturesToUseroperationsSignatures that skips the Merkle tree and formats with depth 0, matching the signUserOperations behavior.

abstractionkit/src/account/Safe/SafeMultiChainSigAccount.ts

Lines 582 to 621 in 89d243a

	*/
	public static formatSignaturesToUseroperationsSignatures(
	userOperationsToSign: UserOperationToSign[],
	signerSignaturePairs: SignerSignaturePair[],
	overrides: WebAuthnSignatureOverrides = {},
	): string[] {
	if (userOperationsToSign.length < 1) {
	throw new RangeError("There should be at least one userOperationsToSign");
	}
	const userOperationsHashes: string[] = [];
	userOperationsToSign.forEach(
	(userOperationsToSign, _index) => {
	const userOperationHash = SafeAccount.getUserOperationEip712Hash_V9(
	userOperationsToSign.userOperation,
	userOperationsToSign.chainId,
	{
	validAfter: userOperationsToSign.validAfter,
	validUntil: userOperationsToSign.validUntil,
	safe4337ModuleAddress: overrides.safe4337ModuleAddress,
	},
	);
	userOperationsHashes.push(userOperationHash);
	});
	const [_root, proofs] = generateMerkleProofs(userOperationsHashes);
	const userOpSignatures: string[] = [];
	userOperationsToSign.forEach(
	(_userOperationsToSign, index) => {
	userOpSignatures.push(
	SafeAccount.formatSignaturesToUseroperationSignature(
	signerSignaturePairs,
	{
	...overrides,
	isMultiChainSignature:true,
	multiChainMerkleProof: proofs[index],
	},
	)
	);
	});
	return userOpSignatures;
	}

abstractionkit/src/account/Safe/SafeAccount.ts

Lines 1964 to 2007 in 89d243a

	if(overrides.isMultiChainSignature){
	if(overrides.multiChainMerkleProof != null){
	const merkleProofLength =
	overrides.multiChainMerkleProof.slice(2).length; // wihout 0x prefix
	if(
	// 1 byte has a length of 2 hex chars
	// minimum proof consist of at least two hashes, 2 * 2 * 32 = 128
	merkleProofLength < 128 ||
	// a valid proof length should be a multiple of 2 * 32 = 64
	merkleProofLength % 64 != 0
	){
	throw new RangeError("invalid multiChainMerkleProof length.");
	}
	const merkleTreeDepth = (merkleProofLength / 64) - 1;
	let merkleTreeDepthHex = merkleTreeDepth.toString(16);
	// create a 0x prefixed hex with an even length of chars
	if(merkleTreeDepthHex.length % 2 == 0){
	merkleTreeDepthHex = "0x" + merkleTreeDepthHex;
	}else{
	merkleTreeDepthHex = "0x0" + merkleTreeDepthHex;
	}
	return solidityPacked(
	["bytes1", "uint48", "uint48", "bytes"],
	[
	merkleTreeDepthHex,
	validAfter,
	validUntil,
	overrides.multiChainMerkleProof + signature.slice(2)
	],
	);
	}else{
	//no proof means a single useroperation
	return solidityPacked(
	["bytes1", "uint48", "uint48", "bytes"],
	[
	"0x00", // single useroperation - merkle depth is 0
	validAfter,
	validUntil,
	signature
	],
	);
	}

3baff37

[sherifahmed990]

3. formatSignaturesToUseroperationsSignatures (the static external-signer API) throws RangeError("invalid multiChainMerkleProof length.") when called with a single operation.

With 1 hash, generateMerkleProofs produces a proof string that is just the root (32 bytes = 64 hex chars). This proof is passed as multiChainMerkleProof to formatSignaturesToUseroperationSignature, where the length check merkleProofLength < 128 fails and throws.

Meanwhile, signUserOperations with 1 op takes a different path — it calls signUserOperation which sets isMultiChainSignature: true with no multiChainMerkleProof, correctly encoding depth 0.

Fix: add a length==1 special case in formatSignaturesToUseroperationsSignatures that skips the Merkle tree and formats with depth 0, matching the signUserOperations behavior.

abstractionkit/src/account/Safe/SafeMultiChainSigAccount.ts

Lines 582 to 621 in 89d243a

	*/
	public static formatSignaturesToUseroperationsSignatures(
	userOperationsToSign: UserOperationToSign[],
	signerSignaturePairs: SignerSignaturePair[],
	overrides: WebAuthnSignatureOverrides = {},
	): string[] {
	if (userOperationsToSign.length < 1) {
	throw new RangeError("There should be at least one userOperationsToSign");
	}
	const userOperationsHashes: string[] = [];
	userOperationsToSign.forEach(
	(userOperationsToSign, _index) => {
	const userOperationHash = SafeAccount.getUserOperationEip712Hash_V9(
	userOperationsToSign.userOperation,
	userOperationsToSign.chainId,
	{
	validAfter: userOperationsToSign.validAfter,
	validUntil: userOperationsToSign.validUntil,
	safe4337ModuleAddress: overrides.safe4337ModuleAddress,
	},
	);
	userOperationsHashes.push(userOperationHash);
	});
	const [_root, proofs] = generateMerkleProofs(userOperationsHashes);
	const userOpSignatures: string[] = [];
	userOperationsToSign.forEach(
	(_userOperationsToSign, index) => {
	userOpSignatures.push(
	SafeAccount.formatSignaturesToUseroperationSignature(
	signerSignaturePairs,
	{
	...overrides,
	isMultiChainSignature:true,
	multiChainMerkleProof: proofs[index],
	},
	)
	);
	});
	return userOpSignatures;
	}

abstractionkit/src/account/Safe/SafeAccount.ts

Lines 1964 to 2007 in 89d243a

	if(overrides.isMultiChainSignature){
	if(overrides.multiChainMerkleProof != null){
	const merkleProofLength =
	overrides.multiChainMerkleProof.slice(2).length; // wihout 0x prefix
	if(
	// 1 byte has a length of 2 hex chars
	// minimum proof consist of at least two hashes, 2 * 2 * 32 = 128
	merkleProofLength < 128 ||
	// a valid proof length should be a multiple of 2 * 32 = 64
	merkleProofLength % 64 != 0
	){
	throw new RangeError("invalid multiChainMerkleProof length.");
	}
	const merkleTreeDepth = (merkleProofLength / 64) - 1;
	let merkleTreeDepthHex = merkleTreeDepth.toString(16);
	// create a 0x prefixed hex with an even length of chars
	if(merkleTreeDepthHex.length % 2 == 0){
	merkleTreeDepthHex = "0x" + merkleTreeDepthHex;
	}else{
	merkleTreeDepthHex = "0x0" + merkleTreeDepthHex;
	}
	return solidityPacked(
	["bytes1", "uint48", "uint48", "bytes"],
	[
	merkleTreeDepthHex,
	validAfter,
	validUntil,
	overrides.multiChainMerkleProof + signature.slice(2)
	],
	);
	}else{
	//no proof means a single useroperation
	return solidityPacked(
	["bytes1", "uint48", "uint48", "bytes"],
	[
	"0x00", // single useroperation - merkle depth is 0
	validAfter,
	validUntil,
	signature
	],
	);
	}

c1d5cca

[sherifahmed990]

formatSignaturesToUseroperationsSignatures and getMultiChainSingleSignatureUserOperationsEip712Hash are using different default safe4337ModuleAddress values:

• getMultiChainSingleSignatureUserOperationsEip712Hash correctly defaults to ExperimentalSafeMultiChainSigAccount.DEFAULT_SAFE_4337_MODULE_ADDRESS (0x22939E...)
• formatSignaturesToUseroperationsSignatures calls getUserOperationEip712Hash_V9 without overriding the address, so it falls through to the base SafeAccount default (0xee8005d7...)
• The instance method signUserOperations() avoids this because it passes this.safe4337ModuleAddress explicitly everywhere. But the static method path (which is the only option for WebAuthn since signing requires browser interaction) hits the mismatch.

The fix should be in formatSignaturesToUseroperationsSignatures. it should default to DEFAULT_SAFE_4337_MODULE_ADDRESS when safe4337ModuleAddress isn't provided, same asgetMultiChainSingleSignatureUserOperationsEip712Hash does.

When isInit: false, formatSignaturesToUseroperationsSignatures computes the WebAuthn signer address using the base class defaults , including the eip7212WebAuthnPrecompileVerifier and eip7212WebAuthnContractVerifier

b11d4a6