# Safe Unified Account **SafeMultiChainSigAccountV1** is the recommended Safe account class for new AbstractionKit examples. It works for normal single-chain Safe transactions and enables chain abstraction for multichain Safe Accounts. It extends the standard Safe Account with multichain signature support via Merkle trees, allowing you to sign UserOperations for multiple chains with a single signature. Uses EntryPoint v0.9 and EIP-712 typed data with Merkle proofs. ## Audits[​](#audits "Direct link to Audits") * [Audit Report by Nethermind (NM-0874)](https://github.com/candidelabs/safe-4337-multi-chain-signature-module/blob/main/audit/NM_0874_Candide_safe.pdf) To learn more about the contracts, visit the [Safe 4337 Multi-Chain Signature Module repository](https://github.com/candidelabs/safe-4337-multi-chain-signature-module). ## Import[​](#import "Direct link to Import") ``` import { SafeMultiChainSigAccountV1 as SafeAccount } from "abstractionkit"; ``` ## How to Use[​](#how-to-use "Direct link to How to Use") ``` const ownerPublicAddress = "0xBdbc5FBC9cA8C3F514D073eC3de840Ac84FC6D31"; const smartAccount = SafeAccount.initializeNewAccount([ownerPublicAddress]); console.log("Account address:", smartAccount.accountAddress); ``` This class inherits all methods from [Safe Account](https://docs.candide.dev/wallet/abstractionkit/safe-account.md). The methods below are specific to multichain operations or override the base class with multichain defaults. ## Compatibility with Safe Account V3[​](#compatibility-with-safe-account-v3 "Direct link to Compatibility with Safe Account V3") `SafeMultiChainSigAccountV1` is API-compatible with [`SafeAccountV0_3_0`](https://docs.candide.dev/wallet/abstractionkit/safe-account-v3.md). Both extend the same `SafeAccount` base and expose the same methods with the same signatures, so moving to EntryPoint v0.9 is a change of account class — not a separate integration: | Method | `SafeAccountV0_3_0` | `SafeMultiChainSigAccountV1` | | ----------------------------------------------------------------- | ------------------- | ---------------------------- | | `createAccountAddress(owners, overrides)` | ✅ | ✅ | | `initializeNewAccount(owners, overrides)` | ✅ | ✅ | | `isDeployed(address, rpc)` | ✅ | ✅ | | `createUserOperation(txs, nodeRpc, bundlerRpc, overrides)` | ✅ | ✅ | | `estimateUserOperationGas(userOp, bundlerRpc, overrides)` | ✅ | ✅ | | `signUserOperation(userOp, privateKeys, chainId, options)` | ✅ | ✅ | | `signUserOperationWithSigners(userOp, signers, chainId, options)` | ✅ | ✅ | | `sendUserOperation(userOp, bundlerRpc)` | ✅ | ✅ | Both classes take the same `InitCodeOverrides` shape, so an integration that already threads `entrypointAddress`, `safe4337ModuleAddress`, `safeModuleSetupAddress`, `safeAccountSingleton`, `safeAccountFactoryAddress` and `c2Nonce` through its config needs no new plumbing. The multichain APIs — `signUserOperations`, `signUserOperationsWithSigners`, the Merkle-root EIP-712 helpers and the WebAuthn verifier helpers — are additional methods. Opt into them for chain abstraction, or ignore them and the account behaves as a single-chain Safe. A few differences to be aware of when migrating: * **New accounts get a different address.** A different Safe module and EntryPoint derive a different counterfactual address for the same owner, so `SafeMultiChainSigAccountV1` and `SafeAccountV0_3_0` never refer to the same undeployed account. * **Deployed accounts must be migrated first.** Attaching `SafeMultiChainSigAccountV1` to a Safe that was deployed through `SafeAccountV0_3_0` is not sufficient. Two pieces of Safe configuration have to change first: the v0.9 module must be enabled on the Safe, and the Safe's fallback handler must be updated to point at it. Until both land, the account cannot be used on EntryPoint v0.9 and UserOperations sent to it will fail. Build the batch with [`createMigrateToSafeMultiChainSigAccountV1MetaTransactions`](https://docs.candide.dev/wallet/abstractionkit/safe-account-v3.md#createmigratetosafemultichainsigaccountv1metatransactions) and send it as a UserOperation from the v0.7 account itself; once it lands, attach the same address to `SafeMultiChainSigAccountV1`. * **The UserOperation type is `UserOperationV9`.** It adds a nullable `eip7702Auth` field to the v0.7 shape; every other field, including the gas fields and the paymaster and factory fields, is unchanged. * **Signatures always use the multichain encoding.** `isMultiChainSignature` is set for you, including on single-chain UserOperations — the single-op path signs the leaf SafeOp hash directly rather than a Merkle root. This is handled inside AbstractionKit; you only need it when [formatting a signature yourself](#manual-eip-712-signing-for-a-single-useroperation). * **Your bundler and paymaster must serve EntryPoint v0.9.** Check that the v0.9 EntryPoint and the Safe multichain signature module are deployed on your target chains before predicting addresses for them. ## Methods[​](#methods "Direct link to Methods") ### initializeNewAccount[​](#initializenewaccount "Direct link to initializeNewAccount") Initializes a new SafeMultiChainSigAccountV1 from a list of owners. Only needed on the first transaction when the account has not been deployed yet. * example.ts * Param Types * Return Type example.ts ``` import { SafeMultiChainSigAccountV1 as SafeAccount } from "abstractionkit"; const ownerPublicAddress = "0xBdbc5FBC9cA8C3F514D073eC3de840Ac84FC6D31"; const smartAccount = SafeAccount.initializeNewAccount([ownerPublicAddress]); console.log("Account address (sender): " + smartAccount.accountAddress); ``` | key | type | description | | :--------------------------------------------------------------------- | :---------------------------------------- | :--------------------------------------------------------------------------------------------------------- | | `owners[]` | `object` | Pass the owner(s) address(es) of the account. It can be a single owner account, a multi-sig, or a WebAuthn | | `owners[].Signer` | `ECDSAPublicAddress \| WebauthnPublicKey` | Signer type which can be either an ECDSA public address or a Webauthn public key | | `initCodeOverrides?` | `object` | Override values to change the initialization default values | | `initCodeOverrides?.threshold?` | `number` | Signature threshold, defines how many signatures are required. Default is 1. | | `initCodeOverrides?.c2Nonce?` | `bigint` | Create2 nonce used to generate different sender addresses from the same owners. Default is 0. | | `initCodeOverrides?.entrypointAddress?` | `string` | Address of the entry point for transactions or contracts. | | `initCodeOverrides?.safe4337ModuleAddress?` | `string` | Address of the Safe 4337 module. | | `initCodeOverrides?.safeModuleSetupAddress?` | `string` | Address used for setting up the Safe module. | | `initCodeOverrides?.safeAccountSingleton?` | `SafeAccountSingleton` | Safe contract singleton address. Default is "0x29fcB43b46531BcA003ddC8FCB67FFE91900C762". | | `initCodeOverrides?.safeAccountFactoryAddress?` | `string` | Address of the Safe Factory. Default is "0x4e1DCf7AD4e460CfD30791CCC4F9c8a4f820ec67". | | `initCodeOverrides?.multisendContractAddress?` | `string` | Address of the Safe 4337 multisend contract. Default is "0xa581c4A4DB7175302464fF3C06380BC3270b4037". | | `initCodeOverrides?.webAuthnSharedSigner?` | `string` | Shared signer used for WebAuthn-based authentication. | | `initCodeOverrides?.eip7212WebAuthnPrecompileVerifierForSharedSigner?` | `string` | Verifier contract for WebAuthn precompile, related to the shared signer. | | `initCodeOverrides?.eip7212WebAuthnContractVerifierForSharedSigner?` | `string` | Contract verifier for WebAuthn-based shared signer, compliant with EIP-7212. | | `initCodeOverrides?.onChainIdentifierParams?` | `OnChainIdentifierParamsType` | Parameters for on-chain identifier tracking. | | `initCodeOverrides?.onChainIdentifier?` | `string` | Pre-computed on-chain identifier string. | | key | type | description | | :--------------- | :------- | :-------------------------------------- | | `ECDSASignature` | `string` | ECDSA signature represented as a string | WebauthnPublicKey | key | type | description | | :------------------ | :----------------- | :------------------------------------------------------------------------ | | `authenticatorData` | `ArrayBuffer` | Binary data returned by the authenticator during the Webauthn process | | `clientDataFields` | `string` | Fields associated with the client's Webauthn request data | | `rs` | `[bigint, bigint]` | Array of two bigints representing the 'r' and 's' values of the signature | | key | type | description | | :------------------ | :------------------ | :------------------------------------------------------------------- | | `SafeAccount class` | `SafeAccountV0_3_0` | An instance of the Safe V3 Account and the initialization parameters | #### Source code[​](#source-code "Direct link to Source code") [initializeNewAccount](https://github.com/candidelabs/abstractionkit/blob/v0.4.0/src/account/Safe/SafeMultiChainSigAccount.ts#L155) ### createUserOperation[​](#createuseroperation "Direct link to createUserOperation") Creates a UserOperation for multichain signing. This overrides the base SafeAccount method to always set `isMultiChainSignature: true` and use EntryPoint v0.9. Determines the nonce, fetches gas prices, estimates gas limits, and returns a UserOperation to be signed. You can override any of these values using the overrides parameter. * example.ts * Param Types * Return Type example.ts ``` import { SafeMultiChainSigAccountV1 as SafeAccount, MetaTransaction, } from "abstractionkit"; const smartAccount = SafeAccount.initializeNewAccount([ownerPublicAddress]); const transaction: MetaTransaction = { to: "0xTargetAddress", value: 0n, data: "0x", }; const userOperation = await smartAccount.createUserOperation( [transaction], "https://rpc-node-url", "https://bundler-url", ); ``` | Param Name | Param Type | Description | | :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Transactions | MetaTransaction\[]key type descriptionMetaTransaction object MetaTransaction is the type of transaction to construct a Safe operation. MetaTransaction.to string To address, or the the target contract address for the transaction MetaTransaction.value BigNumberish Value transfered if making a native token transfer. (usually 0n for contract interaction with non-native tokens like erc-20 tokens) MetaTransaction.data BytesLike The call data for the transaction MetaTransaction.operation Operation: enum Default to 0 for a Call. 1 for a Delegate Call. (Optional) | MetaTransaction is the type of a transaction to construct a Safe operation | | Provider RPC | string | The node URL. It is used to fetch the current nonce and fetch gas prices | | Bundler URL | string | The Bundler URL. It is used to fetch the gas limits | | Overrides | CreateUserOperationV9Overrides, optional objectkey type descriptionnonce string Anti-replay parameter (see “Semi-abstracted Nonce Support” ) callData string The data to pass to the sender during the main execution call callGasLimit bigint The amount of gas to allocate the main execution call verificationGasLimit bigint The amount of gas to allocate for the verification step preVerificationGas bigint The amount of gas to pay for to compensate the bundler for pre-verification execution and calldata maxFeePerGas bigint Maximum fee per gas (similar to EIP-1559 max\_fee\_per\_gas) maxPriorityFeePerGas bigint Maximum priority fee per gas (similar to EIP-1559 max\_priority\_fee\_per\_gas) callGasLimitPercentageMultiplier number Set the callGasLimitPercentageMultiplier instead of estimating gas using the bundler verificationGasLimitPercentageMultiplier number Set the verificationGasLimitPercentageMultiplier instead of estimating gas using the bundler preVerificationGasPercentageMultiplier number Set the preVerificationGasPercentageMultiplier instead of estimating gas using the bundler maxFeePerGasPercentageMultiplier number Set the maxFeePerGasPercentageMultiplier instead of querying the current gas price from the RPC node maxPriorityFeePerGasPercentageMultiplier number Set the maxPriorityFeePerGasPercentageMultiplier instead of querying the current gas price from the RPC node state\_override\_set? object Pass state overrides for gas estimation state\_override\_set?.\[address: string] object Overrides for a specific address state\_override\_set?.\[address: string].balance bigint Override the balance of the address state\_override\_set?.\[address: string].nonce bigint Override the nonce of the address state\_override\_set?.\[address: string].code string Override the code of the address state\_override\_set?.\[address: string].state Dictionary\ Override the storage slots of the address state\_override\_set?.\[address: string].stateDiff Dictionary\ Apply state differences to the storage slots of the address dummySignerSignaturePairs\[] object Provide dummy signatures for the operation dummySignerSignaturePairs\[].SignerSignaturePair\[] object Signature Pair dummySignerSignaturePairs\[].SignerSignaturePair\[].Signer ECDSAPublicAddress \| WebauthnPublicKey Signer type which can be either an ECDSA public address or a Webauthn public key dummySignerSignaturePairs\[].SignerSignaturePair\[].signature string signature dummySignerSignaturePairs\[].SignerSignaturePair\[].isContractSignature boolean isContractSignature expectedSigners\[] object A array of expected signers that will sign over the transaction. This improves the gas estimates. expectedSigners\[].Signer ECDSAPublicAddress \| WebauthnPublicKey Signer type which can be either an ECDSA public address or a Webauthn public key webAuthnSharedSigner string Specify the WebAuthn shared signer webAuthnSignerFactory string Specify the WebAuthn signer factory webAuthnSignerSingleton string Specify the WebAuthn signer singleton eip7212WebAuthnPrecompileVerifier string Specify the EIP-7212 WebAuthn precompile verifier eip7212WebAuthnContractVerifier string Specify the EIP-7212 WebAuthn contract verifier safeModuleExecutorFunctionSelector SafeModuleExecutorFunctionSelector Specify the function selector for the safe module executor multisendContractAddress string Specify the multisend contract address gasLevel object Multiplier to determine the gas price for the user operation gasLevel.Slow 1 Default Slow Gas gasLevel.Medium 1.2 Medium Gas with a 20% increase gasLevel.Fast 1.5 Medium Gas with a 50% increase polygonGasStation object To specify the polygon network polygonGasStation.Mainnet v2 Polygon PoS Mainnet polygonGasStation.ZkMainnet zkevm Polygon zkEVM Mainnet polygonGasStation.Amoy amoy Polygon Amoy PoS Testnet polygonGasStation.Cardona cardona Polygon Cardona zkEVM Testnet isMultiChainSignature? boolean Whether this is a multi-chain signature using Merkle proofs parallelPaymasterInitValues? ParallelPaymasterInitValues Paymaster fields for parallel signing (EntryPoint v0.9) skipGasEstimation? boolean When true, skip the bundler's eth\_estimateUserOperationGas call. Gas limits fall back to any overrides or 0n. The returned UserOperation is always populated with a dummy signature so it stays valid for downstream paymaster sponsorship calls that require a placeholder signature. factory string Set the factory address instead of using the calculated value factoryData string Set the factory data instead of using the calculated value | CreateUserOperationV9Overrides allows you to override any of the default parameters for the user operation. It has the same fields as CreateUserOperationV7Overrides. | | Param Name | Param Type | Description | | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------- | | UserOperation | Promise\key type descriptionsender string The account making the operation nonce bigint Anti-replay parameter (see Semi-abstracted Nonce Support) factory string \| null Account factory address, only for new accounts (null if account already exists) factoryData string \| null Data for account factory (null if account already exists) callData string The data to pass to the sender during the main execution call callGasLimit bigint The amount of gas to allocate the main execution call verificationGasLimit bigint The amount of gas to allocate for the verification step preVerificationGas bigint The amount of gas to pay for to compensate the bundler for pre-verification execution and calldata maxFeePerGas bigint Maximum fee per gas (similar to EIP-1559 max\_fee\_per\_gas) maxPriorityFeePerGas bigint Maximum priority fee per gas (similar to EIP-1559 max\_priority\_fee\_per\_gas) paymaster string \| null Address of paymaster contract (null if account pays for itself) paymasterVerificationGasLimit bigint \| null The amount of gas to allocate for the paymaster verification step (null if no paymaster) paymasterPostOpGasLimit bigint \| null The amount of gas to allocate for the paymaster post-operation code (null if no paymaster) paymasterData string \| null Data for paymaster (null if no paymaster) eip7702Auth Authorization7702Hex \| null EIP-7702 authorization data for EOA delegation (null if not using EIP-7702) signature string Data passed into the account to verify authorization. Resolves to '0x' when the user did not provide their signature yet | Returns an unsigned UserOperation for EntryPoint v0.9. | #### Source code[​](#source-code-1 "Direct link to Source code") [createUserOperation](https://github.com/candidelabs/abstractionkit/blob/v0.4.0/src/account/Safe/SafeMultiChainSigAccount.ts#L385) ### estimateUserOperationGas[​](#estimateuseroperationgas "Direct link to estimateUserOperationGas") Estimates gas limits for a multichain-signature UserOperation against a bundler, matching the estimation surface available on the other account classes. Returns a tuple of `[preVerificationGas, verificationGasLimit, callGasLimit]`. #### Usage[​](#usage "Direct link to Usage") ``` import { SafeMultiChainSigAccountV1 as SafeAccount, MetaTransaction, } from "abstractionkit"; const bundlerRpc = "https://api.candide.dev/public/v3/11155111"; const nodeRpcUrl = "https://rpc-node-url"; const smartAccount = SafeAccount.initializeNewAccount([ownerPublicAddress]); const transaction: MetaTransaction = { to: "0xTargetAddress", value: 0n, data: "0x", }; const userOperation = await smartAccount.createUserOperation( [transaction], nodeRpcUrl, bundlerRpc, ); const [preVerificationGas, verificationGasLimit, callGasLimit] = await smartAccount.estimateUserOperationGas(userOperation, bundlerRpc); ``` * Param Types * Return Types | key | type | description | | :-------------------------------------- | :------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- | | `userOperation` | `UserOperationV9` | The UserOperation to estimate gas for. | | `bundlerRpc` | `string \| Transport \| Bundler` | The bundler RPC URL used to run eth\_estimateUserOperationGas. | | `overrides?` | `object` | Optional overrides for the estimation, such as bundler state overrides and the dummy signatures used while estimating. | | `overrides?.stateOverrideSet?` | `StateOverrideSet` | State overrides passed to the bundler during estimation. | | `overrides?.dummySignerSignaturePairs?` | `SignerSignaturePair[]` | Dummy signer/signature pairs used as placeholders during estimation. | | `overrides?.expectedSigners?` | `Signer[]` | The signers whose signatures will be produced at sign time. Used to build dummy signatures when dummySignerSignaturePairs is not provided. | | key | type | description | | :--------------------------------------------------------- | :---------------------------------- | :----------------------------------------------------------------------------------------------- | | `[preVerificationGas, verificationGasLimit, callGasLimit]` | `Promise<[bigint, bigint, bigint]>` | Resolves to a tuple of the estimated preVerificationGas, verificationGasLimit, and callGasLimit. | #### Source code[​](#source-code-2 "Direct link to Source code") [estimateUserOperationGas](https://github.com/candidelabs/abstractionkit/blob/v0.4.0/src/account/Safe/SafeMultiChainSigAccount.ts#L461) ### signUserOperation[​](#signuseroperation "Direct link to signUserOperation") Signs a single UserOperation with one or more private keys. This overrides the base method to always encode the signature with the multichain scheme (`isMultiChainSignature: true`), which is how this account validates even single-chain UserOperations. ``` signUserOperation( userOperation: UserOperationV9, privateKeys: string[], chainId: bigint, options?: SafeSignatureOptions, ): string ``` Pass one private key per owner required by the threshold. `options` accepts the usual `SafeSignatureOptions` timing fields (`validAfter`, `validUntil`) and module address override; `multiChainMerkleProof` is rejected here, use [`signUserOperations`](#signuseroperations) for multi-op Merkle signatures. example.ts ``` userOperation.signature = smartAccount.signUserOperation( userOperation, [ownerPrivateKey], 11155111n, // chainId ); ``` #### Source code[​](#source-code-3 "Direct link to Source code") [signUserOperation](https://github.com/candidelabs/abstractionkit/blob/v0.4.0/src/account/Safe/SafeMultiChainSigAccount.ts#L585) ### signUserOperations[​](#signuseroperations "Direct link to signUserOperations") Signs multiple UserOperations across different chains with a single signing session. Builds a Merkle tree from the UserOperation hashes, signs the Merkle root, and returns an array of signatures (one per UserOperation) each containing the Merkle proof for its chain. If only one UserOperation is provided, falls back to single-chain signing. In AbstractionKit `v0.3.5`, `UserOperationToSignWithOverrides` split the previous catch-all `overrides` field into `options` for normal signing options and `webAuthnSignatureOverrides` for WebAuthn-specific signature encoding values. * example.ts * Param Types * Return Type example.ts ``` import { SafeMultiChainSigAccountV1 as SafeAccount } from "abstractionkit"; const smartAccount = SafeAccount.initializeNewAccount([ownerPublicAddress]); // Create UserOperations for each chain const userOp1 = await smartAccount.createUserOperation([tx], nodeUrl1, bundlerUrl1); const userOp2 = await smartAccount.createUserOperation([tx], nodeUrl2, bundlerUrl2); // Sign all UserOperations with one signing session const signatures = smartAccount.signUserOperations( [ { userOperation: userOp1, chainId: 11155111n }, { userOperation: userOp2, chainId: 11155420n }, ], [ownerPrivateKey], ); // Attach signatures userOp1.signature = signatures[0]; userOp2.signature = signatures[1]; ``` | key | type | description | | :--------------------- | :---------------------- | :-------------------------------------------------------------------------------- | | `userOperationsToSign` | `UserOperationToSign[]` | Array of UserOperations with their target chain IDs and optional validity windows | | `privateKeys` | `string[]` | Private keys of the Safe owners to sign with | UserOperationToSign | key | type | description | | :---------------------------- | :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `chainId` | `bigint` | Target chain ID for this UserOperation | | `userOperation` | `UserOperationV9` | The UserOperation to sign | | `validAfter?` | `bigint` | Timestamp the signature will be valid after | | `validUntil?` | `bigint` | Timestamp the signature will be valid until | | `options?` | `MultiChainSigningOptions` | Per-operation signing options such as the Safe 4337 module address. In v0.3.5 this replaced the generic overrides field for non-WebAuthn options. | | `webAuthnSignatureOverrides?` | `WebAuthnSignatureOverrides` | Per-operation WebAuthn signature encoding overrides, such as isInit or WebAuthn verifier addresses. In v0.3.5 this replaced the WebAuthn-specific values previously carried in overrides. | | key | type | description | | :----------- | :--------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `signatures` | `string[]` | Array of signatures, one per UserOperation. Each contains the Merkle proof for its respective chain. If only one UserOperation is provided, falls back to single-chain signing. | #### Source code[​](#source-code-4 "Direct link to Source code") [signUserOperations](https://github.com/candidelabs/abstractionkit/blob/v0.4.0/src/account/Safe/SafeMultiChainSigAccount.ts#L672) ### signUserOperationsWithSigners[​](#signuseroperationswithsigners "Direct link to signUserOperationsWithSigners") Multi-op variant that signs a Merkle-rooted bundle of UserOperations using one or more [`ExternalSigner`s](https://docs.candide.dev/wallet/abstractionkit/external-signers.md) instead of raw private keys. One signing session covers every chain in the bundle. Since `v0.3.8`, this path accepts typed-data-only signers such as `fromViemWalletClient` as well as raw-hash signers. Pass `chainId` inside each `UserOperationToSign` item so the SDK can build the per-chain typed-data payloads. ``` signUserOperationsWithSigners( userOperationsToSign: UserOperationToSign[], signers: ExternalSigner[], ): Promise ``` * example.ts * Param Types * Return Type example.ts ``` import { SafeMultiChainSigAccountV1 as SafeAccount, fromViem } from "abstractionkit"; import { privateKeyToAccount } from "viem/accounts"; const smartAccount = SafeAccount.initializeNewAccount([ownerPublicAddress]); const viemAccount = privateKeyToAccount("0x..."); const signatures = await smartAccount.signUserOperationsWithSigners( [ { userOperation: userOp1, chainId: 11155111n }, { userOperation: userOp2, chainId: 11155420n }, ], [fromViem(viemAccount)], ); userOp1.signature = signatures[0]; userOp2.signature = signatures[1]; ``` | Param Name | Param Type | Description | | :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | userOperationsToSign | UserOperationToSign\[]key type descriptionchainId bigint Target chain ID for this UserOperation userOperation UserOperationV9 The UserOperation to sign validAfter? bigint Timestamp the signature will be valid after validUntil? bigint Timestamp the signature will be valid until options? MultiChainSigningOptions Per-operation signing options such as the Safe 4337 module address. In v0.3.5 this replaced the generic overrides field for non-WebAuthn options. webAuthnSignatureOverrides? WebAuthnSignatureOverrides Per-operation WebAuthn signature encoding overrides, such as isInit or WebAuthn verifier addresses. In v0.3.5 this replaced the WebAuthn-specific values previously carried in overrides. | UserOperations with their chain IDs and optional validity windows. | | signers | ExternalSigner\[] | One signer per owner required by the threshold, in any order. The built-in adapters `fromPrivateKey`, `fromViem`, `fromEthersWallet`, and `fromViemWalletClient` all work here. | | Param Name | Param Type | Description | | :--------- | :------------------ | :------------------------------------------------------------------ | | signatures | Promise\ | One formatted signature per input UserOperation, in the same order. | See [External Signers](https://docs.candide.dev/wallet/abstractionkit/external-signers.md) for the full list of adapters, and the [multi-chain add-owner example](https://github.com/candidelabs/abstractionkit-examples/blob/main/chain-abstraction/add-owner-with-external-signer.ts) for a full end-to-end flow. #### Source code[​](#source-code-5 "Direct link to Source code") [signUserOperationsWithSigners](https://github.com/candidelabs/abstractionkit/blob/v0.4.0/src/account/Safe/SafeMultiChainSigAccount.ts#L768) ### getMultiChainSingleSignatureUserOperationsEip712Hash[​](#getmultichainsinglesignatureuseroperationseip712hash "Direct link to getMultiChainSingleSignatureUserOperationsEip712Hash") Static method. Computes the EIP-712 hash of the Merkle tree root for a set of UserOperations. This is the hash that wallet signers (browser extensions, hardware wallets) sign to approve multiple cross-chain operations at once. * example.ts * Param Types * Return Type example.ts ``` import { SafeMultiChainSigAccountV1 as SafeAccount } from "abstractionkit"; const hash = SafeAccount.getMultiChainSingleSignatureUserOperationsEip712Hash([ { userOperation: userOp1, chainId: 11155111n }, { userOperation: userOp2, chainId: 11155420n }, ]); ``` | key | type | description | | :--------------------- | :---------------------- | :-------------------------------------------------- | | `userOperationsToSign` | `UserOperationToSign[]` | Array of UserOperations with their target chain IDs | | `overrides?` | `object` | Optional overrides for the Safe 4337 module address | UserOperationToSign | key | type | description | | :---------------------------- | :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `chainId` | `bigint` | Target chain ID for this UserOperation | | `userOperation` | `UserOperationV9` | The UserOperation to sign | | `validAfter?` | `bigint` | Timestamp the signature will be valid after | | `validUntil?` | `bigint` | Timestamp the signature will be valid until | | `options?` | `MultiChainSigningOptions` | Per-operation signing options such as the Safe 4337 module address. In v0.3.5 this replaced the generic overrides field for non-WebAuthn options. | | `webAuthnSignatureOverrides?` | `WebAuthnSignatureOverrides` | Per-operation WebAuthn signature encoding overrides, such as isInit or WebAuthn verifier addresses. In v0.3.5 this replaced the WebAuthn-specific values previously carried in overrides. | | key | type | description | | :----- | :------- | :--------------------------------------------------------------------- | | `hash` | `string` | The EIP-712 hash of the Merkle tree root, ready for signing by wallets | #### Source code[​](#source-code-6 "Direct link to Source code") [getMultiChainSingleSignatureUserOperationsEip712Hash](https://github.com/candidelabs/abstractionkit/blob/v0.4.0/src/account/Safe/SafeMultiChainSigAccount.ts#L902) ### getMultiChainSingleSignatureUserOperationsEip712Data[​](#getmultichainsinglesignatureuseroperationseip712data "Direct link to getMultiChainSingleSignatureUserOperationsEip712Data") Static method. Returns the EIP-712 typed data components (domain, types, message value) for a multi-chain Merkle tree root. Use this for wallet-compatible signing via `eth_signTypedData_v4`. * example.ts * Param Types * Return Type example.ts ``` import { SafeMultiChainSigAccountV1 as SafeAccount } from "abstractionkit"; const { domain, types, messageValue } = SafeAccount.getMultiChainSingleSignatureUserOperationsEip712Data([ { userOperation: userOp1, chainId: 11155111n }, { userOperation: userOp2, chainId: 11155420n }, ]); // Use with a wallet provider const signature = await wallet.signTypedData(domain, types, messageValue); ``` | key | type | description | | :--------------------- | :---------------------- | :----------------------------------------------------- | | `userOperationsToSign` | `UserOperationToSign[]` | Array of UserOperations with their target chain IDs | | `overrides?` | `object` | Optional overrides for module and entrypoint addresses | UserOperationToSign | key | type | description | | :---------------------------- | :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `chainId` | `bigint` | Target chain ID for this UserOperation | | `userOperation` | `UserOperationV9` | The UserOperation to sign | | `validAfter?` | `bigint` | Timestamp the signature will be valid after | | `validUntil?` | `bigint` | Timestamp the signature will be valid until | | `options?` | `MultiChainSigningOptions` | Per-operation signing options such as the Safe 4337 module address. In v0.3.5 this replaced the generic overrides field for non-WebAuthn options. | | `webAuthnSignatureOverrides?` | `WebAuthnSignatureOverrides` | Per-operation WebAuthn signature encoding overrides, such as isInit or WebAuthn verifier addresses. In v0.3.5 this replaced the WebAuthn-specific values previously carried in overrides. | | key | type | description | | :------------- | :------------------------------------------------- | :---------------------------------------------------------------------- | | `domain` | `{ verifyingContract: string }` | The EIP-712 domain with the Safe 4337 module as verifying contract | | `types` | `Record` | The EIP-712 type definitions for multi-chain operations | | `messageValue` | `{ merkleTreeRoot: string }` | The message containing the Merkle tree root of all UserOperation hashes | #### Source code[​](#source-code-7 "Direct link to Source code") [getMultiChainSingleSignatureUserOperationsEip712Data](https://github.com/candidelabs/abstractionkit/blob/v0.4.0/src/account/Safe/SafeMultiChainSigAccount.ts#L936) ### formatSignaturesToUseroperationsSignatures[​](#formatsignaturestouseroperationssignatures "Direct link to formatSignaturesToUseroperationsSignatures") Static method. Formats EIP-712 signatures (from wallet signing) into UserOperation signatures with Merkle proofs. Use this after signing with `getMultiChainSingleSignatureUserOperationsEip712Hash` or `getMultiChainSingleSignatureUserOperationsEip712Data`. * example.ts * Param Types * Return Type example.ts ``` import { SafeMultiChainSigAccountV1 as SafeAccount } from "abstractionkit"; const userOpsToSign = [ { userOperation: userOp1, chainId: 11155111n }, // Since v0.3.5, generic signing options and WebAuthn signature overrides // use separate fields instead of the previous catch-all `overrides` field. { userOperation: userOp2, chainId: 11155420n, options: { safe4337ModuleAddress: "0x..." }, webAuthnSignatureOverrides: { isInit: userOp2.nonce === 0n }, }, ]; const signerSignaturePairs = [ { signer: ownerAddress, signature: eip712Signature }, ]; const signatures = SafeAccount.formatSignaturesToUseroperationsSignatures( userOpsToSign, signerSignaturePairs, ); userOp1.signature = signatures[0]; userOp2.signature = signatures[1]; ``` | key | type | description | | :--------------------- | :----------------------------------- | :-------------------------------------------------------------------------------------------------------------------- | | `userOperationsToSign` | `UserOperationToSignWithOverrides[]` | Array of UserOperations with their target chain IDs and optional per-operation options / WebAuthn signature overrides | | `signerSignaturePairs` | `SignerSignaturePair[]` | Array of signer address and signature pairs from EIP-712 signing | UserOperationToSign | key | type | description | | :---------------------------- | :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `chainId` | `bigint` | Target chain ID for this UserOperation | | `userOperation` | `UserOperationV9` | The UserOperation to sign | | `validAfter?` | `bigint` | Timestamp the signature will be valid after | | `validUntil?` | `bigint` | Timestamp the signature will be valid until | | `options?` | `MultiChainSigningOptions` | Per-operation signing options such as the Safe 4337 module address. In v0.3.5 this replaced the generic overrides field for non-WebAuthn options. | | `webAuthnSignatureOverrides?` | `WebAuthnSignatureOverrides` | Per-operation WebAuthn signature encoding overrides, such as isInit or WebAuthn verifier addresses. In v0.3.5 this replaced the WebAuthn-specific values previously carried in overrides. | | key | type | description | | :----------- | :--------- | :---------------------------------------------------------------------- | | `signatures` | `string[]` | Array of formatted signatures with Merkle proofs, one per UserOperation | #### Source code[​](#source-code-8 "Direct link to Source code") [formatSignaturesToUseroperationsSignatures](https://github.com/candidelabs/abstractionkit/blob/v0.4.0/src/account/Safe/SafeMultiChainSigAccount.ts#L1015) ### Manual EIP-712 signing for a single UserOperation[​](#manual-eip-712-signing-for-a-single-useroperation "Direct link to Manual EIP-712 signing for a single UserOperation") `SafeMultiChainSigAccountV1` also validates single-chain UserOperations through its multichain signature scheme. If you drive `signTypedData` yourself instead of using `signUserOperationWithSigners`, format the raw wallet signature with `isMultiChainSignature: true`. example.ts ``` import { EIP712_SAFE_OPERATION_PRIMARY_TYPE, SafeMultiChainSigAccountV1 as SafeAccount, } from "abstractionkit"; const eip712Data = SafeAccount.getUserOperationEip712Data( userOperation, chainId, ); const signature = await walletClient.signTypedData({ domain: eip712Data.domain, types: eip712Data.types, primaryType: EIP712_SAFE_OPERATION_PRIMARY_TYPE, message: eip712Data.messageValue, }); userOperation.signature = SafeAccount.formatSignaturesToUseroperationSignature( [{ signer: ownerAddress, signature }], { isMultiChainSignature: true }, ); ``` Full example: [`eip-712-signing.ts`](https://github.com/candidelabs/abstractionkit-examples/blob/main/eip-712-signing/eip-712-signing.ts). ### sendUserOperation[​](#senduseroperation "Direct link to sendUserOperation") Inherited from [Safe Account](https://docs.candide.dev/wallet/abstractionkit/safe-account.md). Sends a signed UserOperation to the bundler. example.ts ``` const account = new SafeAccount(userOperation.sender); const response = await account.sendUserOperation(userOperation, bundlerUrl); const receipt = await response.included(); ``` ## Owner Management[​](#owner-management "Direct link to Owner Management") `SafeMultiChainSigAccountV1` inherits the Safe owner-management helpers from the base `SafeAccount` class. The two add-owner methods below are the ones used in the guides; the remaining helpers (swap owner, remove owner, module management) are documented on [Safe Account V3](https://docs.candide.dev/wallet/abstractionkit/safe-account-v3.md). ### createAddOwnerWithThresholdMetaTransactions[​](#createaddownerwiththresholdmetatransactions "Direct link to createAddOwnerWithThresholdMetaTransactions") Builds the MetaTransactions needed to add a new owner (an ECDSA address or a WebAuthn public key) and set a new threshold. If the new owner is a WebAuthn signer whose verifier contract is not yet deployed, the returned list also contains a MetaTransaction that deploys the verifier, so it resolves to one or two MetaTransactions. ``` createAddOwnerWithThresholdMetaTransactions( newOwner: Signer, threshold: number, overrides?: { nodeRpcUrl?: string; eip7212WebAuthnPrecompileVerifier?: string; eip7212WebAuthnContractVerifier?: string; webAuthnSignerFactory?: string; webAuthnSignerSingleton?: string; webAuthnSignerProxyCreationCode?: string; }, ): Promise ``` `overrides.nodeRpcUrl` is required when adding a WebAuthn owner, so the SDK can check whether the new owner's verifier is already deployed. * example.ts * Param Types * Return Type example.ts ``` const newOwnerPublicAddress = "0xNewOwnerAddress"; const addOwnerMetaTransactions = await smartAccount.createAddOwnerWithThresholdMetaTransactions( newOwnerPublicAddress, 2, // new threshold ); const userOperation = await smartAccount.createUserOperation( addOwnerMetaTransactions, nodeRpcUrl, bundlerUrl, ); ``` | key | type | description | | :-------------------------------------------- | :---------------------------------------- | :----------------------------------------------------------------------------------------------- | | `newOwner` | `object` | The public address of the new owner to be added | | `newOwner.Signer` | `ECDSAPublicAddress \| WebauthnPublicKey` | Signer type which can be either an ECDSA public address or a Webauthn public key | | `threshold` | `number` | The new threshold value for owner confirmations. | | `overrides` | `object` | Optional Overrides for the default values used in the transaction. | | `overrides.nodeRpcUrl` | `string?` | The JSON-RPC API url for the target chain, to check if the new webauthn owner is deployed or not | | `overrides.eip7212WebAuthnPrecompileVerifier` | `string?` | Address for the EIP-7212 WebAuthn precompile verifier. | | `overrides.eip7212WebAuthnContractVerifier` | `string?` | Address for the EIP-7212 WebAuthn contract verifier. | | `overrides.webAuthnSignerFactory` | `string?` | Address for the WebAuthn signer factory. | | `overrides.webAuthnSignerSingleton` | `string?` | Address for the WebAuthn signer singleton. | | key | type | description | | :--------------------------------- | :------- | :------------------------------------------------------------------------------- | | `Promise` | `object` | The meta-transaction object for adding a new owner with the specified threshold. | | `Promise.to` | `string` | The target address for the meta-transaction (Safe account address). | | `Promise.data` | `string` | The encoded function call data for adding an owner. | | `Promise.value` | `bigint` | The value to be sent with the meta-transaction, set to zero for this function. | #### Source code[​](#source-code-9 "Direct link to Source code") [createAddOwnerWithThresholdMetaTransactions](https://github.com/candidelabs/abstractionkit/blob/v0.4.0/src/account/Safe/SafeAccount.ts#L2475) ### createStandardAddOwnerWithThresholdMetaTransaction[​](#createstandardaddownerwiththresholdmetatransaction "Direct link to createStandardAddOwnerWithThresholdMetaTransaction") Builds the single standard `addOwnerWithThreshold` MetaTransaction for an owner public address. Unlike the plural variant above, it takes a plain address, performs no WebAuthn verifier handling, and returns synchronously. ``` createStandardAddOwnerWithThresholdMetaTransaction( newOwner: string, threshold: number, ): MetaTransaction ``` example.ts ``` const addOwnerMetaTransaction = smartAccount.createStandardAddOwnerWithThresholdMetaTransaction( "0xNewOwnerAddress", 2, // new threshold ); ``` #### Source code[​](#source-code-10 "Direct link to Source code") [createStandardAddOwnerWithThresholdMetaTransaction](https://github.com/candidelabs/abstractionkit/blob/v0.4.0/src/account/Safe/SafeAccount.ts#L2536) ## Gas Sponsorship[​](#gas-sponsorship "Direct link to Gas Sponsorship") Use `CandidePaymaster` for gas sponsorship with multichain operations. The paymaster uses a two-phase flow: **commit** (before signing) and **finalize** (after signing). example.ts ``` import { CandidePaymaster } from "abstractionkit"; // One paymaster instance per chain const paymaster1 = new CandidePaymaster("https://api.candide.dev/public/v3/11155111"); const paymaster2 = new CandidePaymaster("https://api.candide.dev/public/v3/11155420"); // Phase 1: Commit (before signing) const commitContext = { signingPhase: "commit" as const }; const commitOverrides = { preVerificationGasPercentageMultiplier: 20 }; const [{ userOperation: commitOp1 }, { userOperation: commitOp2 }] = await Promise.all([ paymaster1.createSponsorPaymasterUserOperation( smartAccount, userOperation1, bundlerUrl1, undefined, commitContext, commitOverrides ), paymaster2.createSponsorPaymasterUserOperation( smartAccount, userOperation2, bundlerUrl2, undefined, commitContext, commitOverrides ), ]); userOperation1 = commitOp1; userOperation2 = commitOp2; // Sign here with signUserOperations... // Phase 2: Finalize (after signing) const finalizeContext = { signingPhase: "finalize" as const }; const [{ userOperation: finalOp1 }, { userOperation: finalOp2 }] = await Promise.all([ paymaster1.createSponsorPaymasterUserOperation( smartAccount, userOperation1, bundlerUrl1, undefined, finalizeContext ), paymaster2.createSponsorPaymasterUserOperation( smartAccount, userOperation2, bundlerUrl2, undefined, finalizeContext ), ]); userOperation1 = finalOp1; userOperation2 = finalOp2; ```