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.

​
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

All user assets (tokens, NFTs, etc.) are associated with their account address. If this address changes or access is lost:
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
To avoid that, the address should be kept unchanged after the upgrade

​
Best Practices for Migration

Migration Best Practices

After migration, you must always use the accountAddress parameter when recreating the account instance:
// CORRECT: Specifying accountAddress preserves access to the existing account
const nexusAccount = await toNexusAccount({
  signer: eoaAccount,
  chainConfiguration: {
    chain: baseChain,
    transport: http(),
    version: getMEEVersion(MEEVersion.V2_1_0)
  },
  accountAddress: "0xUserExistingAccountAddress" // CRITICAL!
});

// INCORRECT: Without accountAddress, a new account is created
// This will result in loss of access to the existing account and its funds!
const newAccount = await toNexusAccount({
  signer: eoaAccount,
  chainConfiguration: {
    chain: baseChain,
    transport: http(),
    version: getMEEVersion(MEEVersion.V2_1_0)
  },
});

​
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

Choose Your Migration Path

Choose the appropriate migration path based on your current account type:
1

Upgrade from V2 to Nexus

Migrate from V2 to Nexus
2

Upgrade to a newer MEE suite

Upgrade Nexus Accounts
For additional support with migrations, please refer to the AbstractJS GitHub repository or join our Discord community.