Migration Guide

Migration Guide: Upgrading to Nexus

Table of Contents

• Introduction
• General Upgrade Process
  • Overview
  • Steps for Upgrading
  • Testing the Upgrade
• Upgrading from Biconomy Smart Account V2
  • Specific Steps for V2 Users
  • Initialization Data
  • Additional Considerations
  • Utilizing the Nexus SDK
• Conclusion

Introduction

This guide provides instructions for upgrading to the Nexus protocol from any upgradable smart contract. It includes general steps for the upgrade process and specific guidance for users migrating from Biconomy Smart Account V2 to Nexus.

General Upgrade Process

Overview

Upgrading to Nexus involves replacing the current smart contract implementation with the Nexus implementation. This ensures that your smart contract benefits from Nexus's enhanced functionality, security, and modular architecture.

Steps for Upgrading

1. Prepare the Upgrade:

   • New Implementation Address: Obtain the address of the Nexus implementation contract.
   • Initialization Data: Prepare any initialization data required by the new implementation.

2. Call the Upgrade Function:

   • Function to Use: Use a function like upgradeToAndCall to initiate the upgrade process.
   • Parameters: Provide the new implementation address and any initialization data.

3. Verify the Upgrade:

   • Ensure the upgrade was successful by verifying the new implementation address and testing critical functionalities.

Important

Always verify the new implementation address and initialization data to prevent any security risks or functionality issues.

Testing the Upgrade

It’s essential to perform thorough testing to ensure the new implementation functions correctly. Testing should include:

• Functionality Tests: Verify that all critical functions work as expected.
• Security Tests: Ensure no new vulnerabilities have been introduced.
• Performance Tests: Confirm that performance metrics meet expectations.

Tip

Use automated test scripts to streamline the testing process and ensure consistency.

Warning

When upgrading from a non-ERC7579 compatible smart account, you will lose access to the modules already installed. You will need to install them manually or through the migration process when calling the upgradeToAndCall function.

Important

At all times, a validation module should be present in the Nexus smart account.

Upgrading from Biconomy Smart Account V2

For users migrating from Biconomy Smart Account V2, additional steps and specific guidance are provided.

Specific Steps for V2 Users

1. Retrieve the New Implementation Address:

   • Obtain the Nexus implementation contract address from the official Nexus repository or documentation.

2. Upgrade Function:

   • Use the updateImplementation function on your Biconomy Smart Account V2 contract.
   • Example call: updateImplementation(newImplementation)

3. Initialization:

   • Ensure that the new implementation is initialized with the necessary data.
   • Call initializeAccount with appropriate initialization data.

Tip

You can find an example in our Foundry test here: ArbitrumSmartAccountUpgradeTest.t.sol and here: UpgradeSmartAccountTest.t.sol.

Initialization Data

When upgrading from Biconomy Smart Account V2 to Nexus, the initialization data should include the following:

• Validators: Addresses and initialization data for validator modules.
  • Example: Use BootstrapLib.createArrayConfig to prepare the validators configuration.
• Hook: Configuration for the hook module.
  • Example: Use BootstrapLib.createSingleConfig for the hook module.

The initialization data is prepared using the BOOTSTRAPPER utility, ensuring the new Nexus account is correctly configured with the required modules and validators.

Additional Considerations

• Backward Compatibility: Ensure that the new implementation maintains compatibility with existing data and functionality.
• Data Migration: Migrate any necessary data to the new implementation if required.

Caution

Ensure you test the upgrade process in a controlled environment before applying it to production to avoid any potential disruptions.

Utilizing the Nexus SDK

The Nexus SDK simplifies the upgrade process with streamlined methods for direct upgrades and validation tools. The SDK supports:

• Direct Upgrade: Simplified methods to call upgrade functions with the required parameters.
• Validation Tools: Tools to verify the successful upgrade and initialization.

Note

The Nexus SDK is still under development. Always perform upgrades in a controlled environment and thoroughly test all functionalities before deploying to production.

Conclusion

Upgrading to Nexus enhances your smart contract with improved security, modularity, and functionality. Follow the outlined steps and utilize the Nexus SDK for a smooth and secure migration process. For further information and access to the SDK, please refer to the Nexus GitHub repository.