From 118ae5915f26cb3de51b5f08a8dff2d05d6068b6 Mon Sep 17 00:00:00 2001 From: sednaoui Date: Tue, 28 Jul 2026 09:41:52 +0200 Subject: [PATCH 1/2] docs: split migration out of the address-change caveat The migration note was folded into the "account address changes" bullet, which framed it as an addressing detail. For a Safe already deployed through SafeAccountV0_3_0 it is a prerequisite: the v0.9 module must be enabled and installed as the fallback handler before the account works on EntryPoint v0.9, and the migration batch has to be sent from the v0.7 account itself. Give deployed accounts their own bullet, and say so on the Safe Account index too. Co-Authored-By: Claude Opus 5 (1M context) --- docs/wallet/abstractionkit/13-safe-unified-account.mdx | 3 ++- docs/wallet/abstractionkit/6-safe-account.mdx | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/wallet/abstractionkit/13-safe-unified-account.mdx b/docs/wallet/abstractionkit/13-safe-unified-account.mdx index 963b669..a905330 100644 --- a/docs/wallet/abstractionkit/13-safe-unified-account.mdx +++ b/docs/wallet/abstractionkit/13-safe-unified-account.mdx @@ -79,7 +79,8 @@ The multichain APIs — `signUserOperations`, `signUserOperationsWithSigners`, t A few differences to be aware of when migrating: -- **The account address changes.** A different Safe module and EntryPoint derive a different counterfactual address for the same owner. Existing v0.7 accounts stay on `SafeAccountV0_3_0`; use `SafeMultiChainSigAccountV1` for new accounts, or migrate a deployed one with [`createMigrateToSafeMultiChainSigAccountV1MetaTransactions`](/wallet/abstractionkit/safe-account-v3#createmigratetosafemultichainsigaccountv1metatransactions). +- **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 — the v0.9 module has to be enabled and installed as the fallback handler before the account can be used on EntryPoint v0.9, and UserOperations sent before that will fail. Build the batch with [`createMigrateToSafeMultiChainSigAccountV1MetaTransactions`](/wallet/abstractionkit/safe-account-v3#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. diff --git a/docs/wallet/abstractionkit/6-safe-account.mdx b/docs/wallet/abstractionkit/6-safe-account.mdx index b972467..bc7f961 100644 --- a/docs/wallet/abstractionkit/6-safe-account.mdx +++ b/docs/wallet/abstractionkit/6-safe-account.mdx @@ -43,7 +43,7 @@ import { SafeAccountV0_2_0 as SafeAccount } from "abstractionkit"; ## How to Use -AbstractionKit classes are designed to support the same methods across all versions, ensuring compatibility within the essential classes. This allows developers to move between Safe V2, Safe V3 and the Safe Unified Account seamlessly without breaking functionality or requiring significant code changes. Targeting a different EntryPoint is a change of account class rather than a separate integration — see [Compatibility with Safe Account V3](/wallet/abstractionkit/safe-unified-account#compatibility-with-safe-account-v3). Note that each version derives a different account address for the same owner. +AbstractionKit classes are designed to support the same methods across all versions, ensuring compatibility within the essential classes. This allows developers to move between Safe V2, Safe V3 and the Safe Unified Account seamlessly without breaking functionality or requiring significant code changes. Targeting a different EntryPoint is a change of account class rather than a separate integration — see [Compatibility with Safe Account V3](/wallet/abstractionkit/safe-unified-account#compatibility-with-safe-account-v3). Each version derives a different account address for the same owner, and an already-deployed Safe needs a module migration before another version's class can operate on it. To initialize a new Safe Account and calculate its address: From 9c3c08824c1c034f4146cc673d39e74b69d82aa0 Mon Sep 17 00:00:00 2001 From: sednaoui Date: Tue, 28 Jul 2026 09:53:22 +0200 Subject: [PATCH 2/2] docs: separate the two migration steps, keep deployed addresses stable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Enabling the v0.9 module and updating the Safe's fallback handler are two distinct configuration changes; the previous wording ran them together. Also scope the differing-address claim to counterfactual derivation. An already-deployed Safe keeps its address across a migration — all three migration MetaTransactions target the existing account address — so the unqualified statement wrongly implied the address moves. Co-Authored-By: Claude Opus 5 (1M context) --- docs/wallet/abstractionkit/13-safe-unified-account.mdx | 2 +- docs/wallet/abstractionkit/6-safe-account.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/wallet/abstractionkit/13-safe-unified-account.mdx b/docs/wallet/abstractionkit/13-safe-unified-account.mdx index a905330..b212a81 100644 --- a/docs/wallet/abstractionkit/13-safe-unified-account.mdx +++ b/docs/wallet/abstractionkit/13-safe-unified-account.mdx @@ -80,7 +80,7 @@ The multichain APIs — `signUserOperations`, `signUserOperationsWithSigners`, t 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 — the v0.9 module has to be enabled and installed as the fallback handler before the account can be used on EntryPoint v0.9, and UserOperations sent before that will fail. Build the batch with [`createMigrateToSafeMultiChainSigAccountV1MetaTransactions`](/wallet/abstractionkit/safe-account-v3#createmigratetosafemultichainsigaccountv1metatransactions) and send it as a UserOperation from the v0.7 account itself; once it lands, attach the same address to `SafeMultiChainSigAccountV1`. +- **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`](/wallet/abstractionkit/safe-account-v3#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. diff --git a/docs/wallet/abstractionkit/6-safe-account.mdx b/docs/wallet/abstractionkit/6-safe-account.mdx index bc7f961..7192941 100644 --- a/docs/wallet/abstractionkit/6-safe-account.mdx +++ b/docs/wallet/abstractionkit/6-safe-account.mdx @@ -43,7 +43,7 @@ import { SafeAccountV0_2_0 as SafeAccount } from "abstractionkit"; ## How to Use -AbstractionKit classes are designed to support the same methods across all versions, ensuring compatibility within the essential classes. This allows developers to move between Safe V2, Safe V3 and the Safe Unified Account seamlessly without breaking functionality or requiring significant code changes. Targeting a different EntryPoint is a change of account class rather than a separate integration — see [Compatibility with Safe Account V3](/wallet/abstractionkit/safe-unified-account#compatibility-with-safe-account-v3). Each version derives a different account address for the same owner, and an already-deployed Safe needs a module migration before another version's class can operate on it. +AbstractionKit classes are designed to support the same methods across all versions, ensuring compatibility within the essential classes. This allows developers to move between Safe V2, Safe V3 and the Safe Unified Account seamlessly without breaking functionality or requiring significant code changes. Targeting a different EntryPoint is a change of account class rather than a separate integration — see [Compatibility with Safe Account V3](/wallet/abstractionkit/safe-unified-account#compatibility-with-safe-account-v3). Each version derives a different counterfactual address for the same owner, so a new account is a different account under each class. An already-deployed Safe keeps the address it has; it needs only its module and fallback handler migrated before another version's class can operate on it. To initialize a new Safe Account and calculate its address: