Account Migration Guide
Complete guide to migrate between different versions of Biconomy smart accounts while preserving addresses and assets
This section covers how to migrate between different versions of Biconomy smart accounts. AbstractJS provides migration paths that preserve your users’ account addresses, balances, and transaction history while upgrading to newer implementations.
Start here
MEE2.2.3 is the current contract suite and the version to use for newly created accounts. What you need to do depends on the state of the accounts you already have.
Undeployed accounts holding balances
A classic smart account address can be computed before the account exists on chain, and can receive funds while it is still undeployed. If you hold balances at addresses in that state, deploy them.1
Deploy the account
Any operation deploys the account, including one with empty calldata. You do not need to move the funds, and deploying is permanent for that account.
2
Use the version that derived the address
Deploy at the address you already have, with the version that created it. This does not require upgrading the SDK or switching MEE versions. In AbstractJS
v2.0.0 and later, resolve that version with getLegacyMEEVersion().3
Deploy in bulk if you hold precomputed addresses
If you keep precomputed addresses for your users, deploy them by calling the account factory for each address. This needs no user signature and does not change ownership. Run it against a few accounts first and confirm they are deployed on chain before continuing.
Deploying is the action that matters here. Upgrading an account to
2.2.3 is a separate, optional step, and an account has to be deployed before it can be upgraded at all.Key Migration Concepts
Address Preservation
The most important concept in any smart account migration is address preservation. When you migrate a smart account:
1
Address Remains Unchanged
The account’s address remains unchanged
2
Assets Stay with Account
All assets and tokens stay with the account
3
External Contracts Continue Working
External contracts and services that interact with the account continue to work
4
Seamless User Experience
User experience remains seamless with no visible interruption
Migration Types
AbstractJS supports the following migration paths:
1
V2 to Nexus Migration
V2 to Nexus Migration: Migrate from Biconomy Smart Account v2 to Nexus accounts
2
Nexus to Nexus Migration
Nexus to Nexus Migration: Upgrade between different versions of Nexus accounts
Why User Address Persistence Is Critical
Smart account addresses are the cornerstone of user identity and asset ownership in blockchain applications. It’s absolutely essential to maintain these addresses during and after migration for several key reasons:
Critical Reasons for Address Preservation
- Asset Preservation
- External Relationship Preservation
All user assets (tokens, NFTs, etc.) are associated with their account address. If this address changes or access is lost:To avoid that, the address should be kept unchanged after the upgrade
1
Loss of Access
Users lose access to all their funds and digital assets
2
Permanent Loss Risk
Recovery may be impossible, resulting in permanent loss
Best Practices for Migration
Migration Best Practices
- Account address overriding
- Store Account Addresses Persistently
- Test Before Full Deployment
- Provide User Guidance
- Maintain Version Records
After migration, you must always use the
accountAddress parameter when recreating the account instance:Framework Support
AbstractJS Migration Support
AbstractJS provides comprehensive migration support with automatic handling of:
1
Implementation Upgrades
Account implementation upgrades
2
Parameter Initialization
Initialization with the correct parameters
3
Module Installation
Module installation and configuration
4
Validator Setup
Compatible validator setup
Migration Links
Choose Your Migration Path
Choose the appropriate migration path based on your current account type:
1
Upgrade from V2 to Nexus
2
Upgrade to a newer MEE suite
For additional support with migrations, please refer to the AbstractJS GitHub repository or join our Discord community.