Migrating from Orion to Tessera
We recommend use of Tessera as a drop-in replacement private transaction manager in place of Orion. As Tessera supports the same endpoints and functionality, nothing needs to be changed in your Besu deployment to migrate. However, as Orion and Tessera can not communicate, you must stop all privacy-enabled Besu nodes in the network to perform the migration. Besu nodes without an associated private transaction manager can remain live during this time.
A utility is included in Tessera which enables migration of an Orion configuration file and database to a Tessera configuration file and database.
A full migration workflow would be as follows:
- Build or download the migration utility.
- Shut down all privacy-enabled Besu nodes and Orion instances in the network (non-privacy-enabled nodes can remain active).
- Perform configuration and database migration.
- Start Tessera instances with the new configuration and database files.
- Restart all privacy-enabled Besu nodes in the network.
Build Migration Utility
The utility can be built from the Tessera repository.
First clone the Tessera repository:
git clone https://github.com/ConsenSys/tessera
Navigate to the project root directory:
Build the migration utility with the Gradle wrapper
./gradlew clean migration:orion-to-tessera:installDist -x test
Download Migration Utility
Or download the migration utility binaries, which are available at the following download links: .zip and .tar.
Verify the installation by running the migration utility with the
Usage: orion-to-tessera/bin/migrate [-h] -f=Orion config file -o=<outputFile>
-f, orionfile, orionconfig=Orion config file
Orion config file
-h, help, --help Print this message
Output Tessera config file
Target Tessera DB password
Target Tessera DB JDBC connection string
Target Tessera DB username
By default Tessera uses an H2 database. However, you can configure alternative databases. Refer to the SQL Data Definition Language files for help with other databases.
If migrating from an SQL database to Tessera, you must add the JDBC driver to the
CLASSPATH environment variable and to the start script at
Password protected keys are migrated to the Tessera format as part of the migration. The original Orion format keys are renamed with a
Verify State and Stop Services
Verify the private state root and private transaction count on your Besu and Orion network using
"params": ["MC4aHjApHsGb0j5glU2iAj5KcR5LId52S0BU9mtdeuY=", "latest"],
After recording the state root and transaction count, stop your Besu and Orion nodes.
Begin the migration by running
migrate with all required options. Substitute
Orion config file,
username with your own values.
To ensure you have the correct database path, run the migration tool from the same directory in which Orion was running. Alternatively, modify the Orion configuration file to add
workdir parameters with absolute paths.
./bin/migrate -f <Orion config file> -o <outputFile> tessera.jdbc.password <password> tessera.jdbc.url <url> tessera.jdbc.user <username>
./bin/migrate -f "orion.conf" -o="tessera-migrated.conf" tessera.jdbc.password "My Secret Pass" tessera.jdbc.url "jdbc:h2:tessera1" tessera.jdbc.user "user1"
=== Migration report ===
Migrated 2156 of 2156 transactions
Migrated 56 of 56 privacy groups
On a successful migration, the count of transactions and privacy groups migrated will match expected values.
Restart Services and Verify State
Start Besu and Tessera using the new Tessera configuration file and database.
Verify the private state root and private transaction count on your Besu and Tessera network using
It should give identical results to those collected earlier.
You must specify the following options in order to run the migration tool:
Orion config file= Orion configuration file location
outputFile= Target Tessera configuration file location
username= Target Tessera database username
password= Target Tessera database password
url= Target Tessera database JDBC connection string
If you require support to undertake this process or any other use of ConsenSys Quorum software, ConsenSys offers support subscriptions for Quorum to accelerate time to market and provide confidence in production networks. Visit the following site to find out more: ConsenSys Quorum Support.