> ## Documentation Index
> Fetch the complete documentation index at: https://docs.biconomy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Account Migration Guide

> Complete guide to migrate between different versions of Biconomy smart accounts while preserving addresses and assets

# Account Migration Guide

> Complete guide to migrate between different versions of Biconomy smart accounts while preserving addresses and assets

<Callout type="info">
  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.
</Callout>

## Key Migration Concepts

<CardGroup cols={1}>
  <Card title="Address Preservation" icon="shield">
    The most important concept in any smart account migration is **address preservation**. When you migrate a smart account:

    <Steps>
      <Step title="Address Remains Unchanged">
        The account's address remains unchanged
      </Step>

      <Step title="Assets Stay with Account">
        All assets and tokens stay with the account
      </Step>

      <Step title="External Contracts Continue Working">
        External contracts and services that interact with the account continue to work
      </Step>

      <Step title="Seamless User Experience">
        User experience remains seamless with no visible interruption
      </Step>
    </Steps>
  </Card>
</CardGroup>

<CardGroup cols={1}>
  <Card title="Migration Types" icon="list">
    AbstractJS supports the following migration paths:

    <Steps>
      <Step title="V2 to Nexus Migration">
        [**V2 to Nexus Migration**](/upgrade-migrate/v2-to-nexus): Migrate from Biconomy Smart Account v2 to Nexus accounts
      </Step>

      <Step title="Nexus to Nexus Migration">
        [**Nexus to Nexus Migration**](/upgrade-migrate/upgrade-mee-suite): Upgrade between different versions of Nexus accounts
      </Step>
    </Steps>
  </Card>
</CardGroup>

## Why User Address Persistence Is Critical

<Callout type="warning">
  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:
</Callout>

<CardGroup cols={1}>
  <Card title="Critical Reasons for Address Preservation" icon="alert-triangle">
    <Tabs>
      <Tab title="Asset Preservation">
        All user assets (tokens, NFTs, etc.) are associated with their account address. If this address changes or access is lost:

        <Steps>
          <Step title="Loss of Access">
            Users lose access to all their funds and digital assets
          </Step>

          <Step title="Permanent Loss Risk">
            Recovery may be impossible, resulting in permanent loss
          </Step>
        </Steps>

        **To avoid that, the address should be kept unchanged after the upgrade**
      </Tab>

      <Tab title="External Relationship Preservation">
        Smart account addresses establish relationships with other contracts and services:

        <Steps>
          <Step title="Token Allowances">
            Token allowances and approvals are tied to specific addresses
          </Step>

          <Step title="DAO Memberships">
            DAO memberships, governance rights, and voting power
          </Step>

          <Step title="Access Control">
            Access control in permissioned systems
          </Step>
        </Steps>
      </Tab>
    </Tabs>
  </Card>
</CardGroup>

## Best Practices for Migration

<CardGroup cols={1}>
  <Card title="Migration Best Practices" icon="check-circle">
    <Tabs>
      <Tab title="Account address overriding">
        After migration, you **must always** use the `accountAddress` parameter when recreating the account instance:

        ```typescript theme={null} theme={null}
        // 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)
          },
        });
        ```
      </Tab>

      <Tab title="Store Account Addresses Persistently">
        Always store user account addresses in a persistent database or storage:

        <Steps>
          <Step title="Backend Applications">
            Server-side database for backend applications
          </Step>

          <Step title="Frontend Applications">
            Local storage or secure storage for frontend applications
          </Step>

          <Step title="Critical Applications">
            Consider multiple backup locations for critical applications
          </Step>
        </Steps>
      </Tab>

      <Tab title="Test Before Full Deployment">
        <Steps>
          <Step title="Testnet Testing">
            Run the migration on testnets first
          </Step>

          <Step title="Test Transactions">
            Perform small test transactions after migration
          </Step>

          <Step title="Functionality Verification">
            Verify all functionality works as expected with the migrated account
          </Step>
        </Steps>
      </Tab>

      <Tab title="Provide User Guidance">
        If your application has end users:

        <Steps>
          <Step title="Communication">
            Communicate the migration timeline in advance
          </Step>

          <Step title="Asset Preservation Explanation">
            Explain that the migration preserves all assets and functionality
          </Step>

          <Step title="Clear Instructions">
            Provide clear instructions for any user-initiated steps
          </Step>
        </Steps>
      </Tab>

      <Tab title="Maintain Version Records">
        Keep records of:

        <Steps>
          <Step title="Pre-Migration Version">
            The account version before migration
          </Step>

          <Step title="Post-Migration Version">
            The account version after migration
          </Step>

          <Step title="Migration Timestamps">
            Timestamps of when migrations occurred
          </Step>
        </Steps>
      </Tab>
    </Tabs>
  </Card>
</CardGroup>

## Framework Support

<CardGroup cols={1}>
  <Card title="AbstractJS Migration Support" icon="gear">
    AbstractJS provides comprehensive migration support with automatic handling of:

    <Steps>
      <Step title="Implementation Upgrades">
        Account implementation upgrades
      </Step>

      <Step title="Parameter Initialization">
        Initialization with the correct parameters
      </Step>

      <Step title="Module Installation">
        Module installation and configuration
      </Step>

      <Step title="Validator Setup">
        Compatible validator setup
      </Step>
    </Steps>
  </Card>
</CardGroup>

## Migration Links

<CardGroup cols={1}>
  <Card title="Choose Your Migration Path" icon="arrow-right">
    Choose the appropriate migration path based on your current account type:

    <Steps>
      <Step title="Upgrade from V2 to Nexus">
        [Migrate from V2 to Nexus](/upgrade-migrate/v2-to-nexus)
      </Step>

      <Step title="Upgrade to a newer MEE suite">
        [Upgrade Nexus Accounts](/upgrade-migrate/upgrade-mee-suite)
      </Step>
    </Steps>
  </Card>
</CardGroup>

<Callout type="info">
  For additional support with migrations, please refer to the [AbstractJS GitHub repository](https://github.com/bcnmy/abstractjs) or join our [Discord community](https://discord.gg/biconomy).
</Callout>