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:
- 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:
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.
- Command
- Result
./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
tessera.jdbc.password=<password>
Target Tessera DB password
tessera.jdbc.url=<url>
Target Tessera DB JDBC connection string
tessera.jdbc.user=<username>
Target Tessera DB username
Migrate
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
- Request
- Result
{
"jsonrpc": "2.0",
"method": "priv_debugGetStateRoot",
"params": ["MC4aHjApHsGb0j5glU2iAj5KcR5LId52S0BU9mtdeuY=", "latest"],
"id": 1
}
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x69904cc3945ada15579fa6f7f1c95e31555210ac017646b4a1373412281dce82"
}
and then priv_getTransactionCount
.
- Request
- Result
{
"jsonrpc": "2.0",
"method": "priv_getTransactionCount",
"params": [
"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73",
"67NmE7/94nuomQiZv/g19BzyhhX84kwJo3lr5+n43xI="
],
"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.
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 storage
and workdir
parameters with absolute paths.
- Request
- Example
- Result
./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 priv_debugGetStateRoot
and priv_getTransactionCount
.
It should give identical results to those collected earlier.
Options
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.