Skip to content
You are reading Orion development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.
Orion features have been merged into Tessera! Read our Orion to Tessera migration guide and about all the new Tessera features.

Updated on June 2, 2021

Migrating from Orion to Tessera

Migration Process

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:

  1. Build or download the migration utility.
  2. Shut down all privacy-enabled Besu nodes and Orion instances in the network (non-privacy-enabled nodes can remain active).
  3. Perform configuration and database migration.
  4. Start Tessera instances with the new configuration and database files.
  5. 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

Navigate to the project root directory:

cd tessera

Build the migration utility with the Gradle wrapper gradlew:

./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 Installation

Verify the installation by running the migration utility with the --help flag.

./bin/migrate --help
./bin/migrate --help
Usage: orion-to-tessera/bin/migrate [-h] -f=Orion config file -o=<outputFile>
                                tessera.jdbc.password=<password> tessera.
                                jdbc.url=<url> tessera.jdbc.user=<username>
-f, orionfile, orionconfig=Orion config file
                   Orion config file
-h, help, --help   Print this message
-o, outputfile=<outputFile>
                   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 ./bin/migrate.


Password protected keys are migrated to the Tessera format as part of the migration. The original Orion format keys are renamed with a .orion suffix.

Verify State and Stop Services

Verify the private state root and private transaction count on your Besu and Orion network using priv_debugGetStateRoot

    "jsonrpc": "2.0",
    "method": "priv_debugGetStateRoot",
    "params": [
    "id": 1
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0x69904cc3945ada15579fa6f7f1c95e31555210ac017646b4a1373412281dce82"

and then priv_getTransactionCount.

    "jsonrpc": "2.0",
    "method": "priv_getTransactionCount",
    "params": [
    "id": 1
    "jsonrpc": "2.0",
    "id": 1,
    "result": "0xb4"

After recording the state root and transaction count, stop your Besu and Orion nodes.

Run Migration

Begin the migration by running migrate with all required options. Substitute Orion config file, outputFile, password, url and username with your own values.

=== "Request"

./bin/migrate -f <Orion config file> -o <outputFile> tessera.jdbc.password <password> tessera.jdbc.url <url> tessera.jdbc.user <username>

=== "Example"

./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"

=== "Result"

=== 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 priv_debugGetStateRoot and priv_getTransactionCount.

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

Enterprise support

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.

ConsenSys has acquired Quorum from J.P. Morgan. Please read the FAQ.
Questions or feedback? You can discuss issues and obtain free support on Orion Discord channel.
For paid professional support by Consensys, contact us at