We officially end support for our previous long-term release, Builder Vault v70 LTS, at 2027-03-14. We therefore recommend that you upgrade to our most recent LTS version, Builder Vault v73 LTS. Builder Vault v73 LTS will be officially supported with bug-fixes and other patches until at least 2028-03.

This page guides you through the necessary steps for upgrading Builder Vault from v70 LTS to v73 LTS.

New Features

Builder Vault v73 comes with a number of new features and other improvements, most notably:

• Each MPC node now optionally exposes a new Management API. This is a web API that lets you query information and perform a number of changes to the node's configuration without having to reboot the MPC node.
• It is now possible to run an MPC node in a browser, using WebAssembly (wasm).
• Improved flexibility of MPC node-to-node communication:
  • It is now possible for some MPC nodes to connect using direct TCP or WebSocket while others connect using a message broker.
  • Dynamic Addresses. Player addresses can now be configured dynamically at runtime. Previously, only public keys could be supplied dynamically, effectively limiting dynamic players to message-broker setups. With this release, you can now specify a player’s address at runtime as well—provided that the address and public key are not already defined in the MPC node configuration file. More information here.
• The multi-instance mode can now be configured so the overall load is more evenly distributed among the MPC nodes.
• With the Builder Vault Emergency Emergency Recovery System (ERS) it is now possible to recover the private key and master chain code from recovery data by providing a decryption callback function. Prior to this version, recovery required you to decrypt the recovery data directly. This new feature allows ERS recovery using a recovery key that remains protected by an HSM, another Builder Vault instance, or similar. This feature is currently only available via the Go SDK.
• Support for BLS signatures over the BLS12-381 curve (according to this IETF draft).
• External randomness. There is a new section in the MPC-node configuration file, which can be used to specify an external randomness source.
• Builder Vault now supports the EC-KCDSA signature scheme.
• Experimental support for the Schnorr signature variant used by the Aleo blockchain. Note that this is subject to change in future versions.
• ECDH is now supported with the new SDK
• With the new direct MPC node-to-node configuration, MPC player indices are no longer required to start with index 0.
• Builder Vault now supports any number of players and security thresholds for AES-CTR, AES-CBC, AES-GCM, AES-CMAC, HMAC-SHA256, HMAC-SHA512, RFC5649 and AN10922. Prior versions only allowed these operations for a fixed set of parameters.
• Builder Vault now applies the same high threshold protection to the plaintext input and output of AES-CTR and AES-GCM as is used to protect the encryption keys. Prior versions protected the encryption key but revealed the plaintext to each MPC node.
• Security of key share export/import(formerly known as key share backup/restore) has been strengthened. The exported key share is now encrypted using a provided wrapping key. The MPC node only exports if the provided wrapping key exists in a whitelist in the MPC node's configuration. Imported key shares must be encrypted under the MPC node's own wrapping key.
• The MPC node's own public wrapping key is now automatically part of its wrapping key whitelist. This means that you can now always import key shares that were earlier exported by the node itself, without manually having to add the MPC node's public wrapping key to the whitelist.
• Key share export now optionally includes presignatures. If presignatures are exported, they are removed from the MPC node database to reduce the risk of presignature reuse.
• Running an MPC node with log level set to DEBUG will log many operations together with a duration indicating how long time the operation took.
• In addition to the Debian / GLIBC version, Builder Vault is now also available in an Alpine / musl version. Use e.g. bv.sepior.net/tsm-node:73.1.0-alpine to fetch the Alpine-based version, instead of bv.sepior.net/tsm-node:73.1.0 which is the usual Debian-based build.

Deprecation Notice

🚧
DKLs19 is still supported in v73 LTS, but may not be part of future LTS versions. We recommend upgrading to the DKLs23 protocol (upgrade instructions here). Note keys generated with DKLs19 can automatically be used with the DKLs23 protocol.

Upgrade Instructions

When upgrading from v70 LTS to v73 LTS you need to take the following into account:

• Changes to node-to-node communication. There are breaking changes related to WebSocket communication, hardened BIP32 derivation, and the AES, HMAC, AN10922, RFC5649 operations, as detailed below. If you don't use any of these features, one upgraded MPC node can still operate with other non-upgraded MPC nodes. If you do use these operations, you need to upgrade all your MPC nodes in sync.
• Changes to SDK-to-node communication. There are breaking changes related to backup/restore key share and import/export of key shares, as well as hardened BIP32 derivation and the AES, HMAC, AN10922, RFC5649 operations, as explained below. If you do not use these features, you can upgrade the MPC node and the old v70 SDK will still work. If you do use these features, you must upgrade the MPC node and the SDKs that connect to the MPC node in sync.
• Changes to SDK API. There are breaking changes related to hardened BIP32 derivation and the AES, HMAC, AN10922, RFC5649 operations, as explained below. In addition, there are some breaking changes to the Java SDK, in order to make it consistent with the Golang SDK. These changes are also detailed below. Also, the NewStaticSessionConfigWithTenant has been removed. Finally, the tsm.NewSessionConfig method now takes an extra argument. This is the optional dynamic addresses of. Unless you use actually use this new feature, you can just pass an empty value. In Golang it would look like this: tsm.NewSessionConfig(tsm.GenerateSessionID(), keyGenPlayers, nil, nil). In node.js, it will look like this: const presigSessionConfig = await SessionConfig.newSessionConfig(presigSessionId, new Uint32Array(players), {}, {});. If you use any of these SDK methods, upgrading the SDK will require you to change your code as well.
• Changes to database. There are changes to the database format. Normally, this does not require any action from you, since the database upgrade is performed automatically, the first time an upgraded MPC node connects to the database. But if you use horizontal scaling / multi-instance mode, where many MPC nodes connect to the same database, then you need to upgrade these MPC nodes in sync.
• Changes to metrics and profiling endpoints. These endpoints on the MPC nodes have been moved to the new Management API. If you use the profiling or metrics features, upgrading will require you to switch to the Management API.
• Changes to MPC node configuration. There are breaking changes if you use the BackupKeyShare/RestoreKeyShare methods, the ImportKeyShare/ExportKeyShare. You will have to rename these operations in the MPC node configuration file as explained below. Moreover, the two-party MPC protocol called WRK17 has been removed, as explained below.
• Changes to key data formats. The old WRK17 key format is no longer supported. Contact Blockdaemon support for help with upgrading if you have generated keys using the WRK17 protocol.

We always recommend to backup your data before attempting an upgrade of the system. See our recommendations for upgrading for more on how to upgrade Builder Vault in general.

Required changes and other important recommended changes are described in more detail below.

Backup and Restore Key Share

In v70 LTS the BackupKeyShare exported an unencrypted key share from an MPC node and the key share could later be imported using RestoreKeyShare. In v73 LTS, these methods have been renamed to ExportKeyShare and ImportKeyShare. Moreover, the exported key share is now encrypted using the a wrapping key.

📘
IMPORTANT
The exported key is now encrypted using a provided public wrapping key. If you use the exported key share as a back up, so you can later restore the MPC node, it is important that you either:

1. Make sure that the corresponding private wrapping key is available when you want to restore. You can for example keep the private wrapping key in a protected environment such as an HSM. The benefit of this is that the backup is not sensitive and can be stored and replicated anywhere.
2. Alternatively, you can use a "dummy" wrapping key and unwrap the exported data immediately after you have called ExportKeyShare. This gives you the raw, unencrypted, key share backup similarly to how BackupKeyShare worked in v70 LTS. It is then your responsibility to store the unencrypted key share backup in a secure way.

In v73 LTS, the export can (optionally) include presignatures as well. If presignatures are exported, they are removed from the MPC node to reduce the risk of reusing a presignature.

If you used BackupKeyShare and RestoreKeyShare in v70 LTS you need to:

1. Change your code so it matches the new method names of the SDK.
2. Rename BackupKeyShare and RestoreKeyShare to ExportKeyShare and ImportKeyShare in the MPC node's configuration file.
3. Consider how to handle the new required wrapping key (store the private wrapping key safely, or use a dummy wrapping key, as explained above).

Export and Import Key Shares

In v70 LTS the ExportKeyShares and ImportKeyShares methods exports and imports wrapped and re-randomized key shares of a key, one key share to each MPC node. These methods have been renamed to ExportKey and ImportKey in v73 LTS, but the functionality remains unchanged.

If you use these methods, you need to

1. Change your code so it matches the new method names of the SDK.
2. Rename ExportKeyShares and ImportKeyShares to ExportKey and ImportKey in the MPC node's configuration file.

Direct Node Communication (WebSocket and TCP)

Builder Vault v73 LTS introduces updates to how MPC nodes communicate with each other.

Previously, direct communication was configured using MPCTCPServer and MPCWebSocketServer in the MPC node configuration file. These are now replaced with a new unified communication server:MPCDirectServer.

If you use direct raw TCP connections, you can keep using the old MPCTCPServer, though we recommend switching to the new MPCDirectServer.

If you use direct WebSocket communication between nodes, you are required to switch to the new MPCDirectServer since the old MPCWebSocketServer has been removed.

Switching breaks node-to-node communication, so you will need to do this for all your MPC nodes in sync. See this for more on how to set up the new MPCDirectServer.

The new MPCDirectServer is essentially a drop-in replacement for MPCTCPServer. However, with MPCDirectServer, if an MPC node specifies the address of another node, it means that this node will initiate the communication. So if you used MPCTCPServer and both MPC nodes had the address of each other, you will need to remove it from one of the nodes, or include symmetricConnection=true in the connection string.

General Purpose MPC

Builder Vault v73 LTS contains a number of changes and improvements related to general purpose MPC. This affects the AES, HMAC, AN10922, RFC5642 operations as well as the hardened BIP32 available via the ECDSA protocols DKLs19 and DKLs23.

• A new parameter MinPlayers is now required when generating and importing keys (AES, HMAC, AN10922, RFC5642). MinPlayers is the number of players that must participate in later operations on the key, such as signing or encryption. So, for example, if five players generate an AES key with MinPlayers=3 and Threshold=2 it means that the key remains secure even if up to two of the five players are corrupted, and that to encrypt or decrypt using the key, three players must participate in the encrypt/decrypt session. Any value can be used, as long as 1 ≤ Threshold < MinPlayers ≤ PlayerCount.
• Support for the WRK17 protocol is removed.
• Prior to this release, the MRZ15 protocol only worked with three players and security threshold 2. As of v73 LTS, the MRZ15 protocol works for any number of players and thresholds. Behind the scenes, it now uses different MPC protocols (MRZ15, YWZ20), depending on the number of players, the MinPlayers, and the specified security threshold.
• The hardened BIP32 derivation available for DKLs19 and DKLs23 is changed: Like symmetric keys, it now requires a MinPlayers parameter when importing or generating a BIP32 seed. Currently, it is only supported for three players, MinPlayers=3 and Threshold=1, but future versions of Builder Vault may support additional parameters.
• The internal key format for AES and HMAC keys, as well as hardened BIP32 seeds and keys, have changed. As a consequence, AES and HMAC keys from prior versions generated by the WRK17 protocol for two players, as well as any hardened BIP32 seeds and keys, are no longer supported. Contact Builder Vault support if you need assistance with migrating of such keys. AES and HMAC keys generated with three players and threshold one can still be used. This includes any AN10922 and RFC5649 keys.
• Builder Vault now provides additional privacy for sensitive input and output to the MPC computation. Examples of sensitive input and output are AES GCM plaintexts and AES CTR key streams. The additional privacy means that no single MPC node sees the sensitive values. This requires you to split this input into secret shares and pass one share to each SDK. Splitting the input into shares can be done using the static method SplitInput provided in the TSMUtils section of the SDK. Non-sensitive input, such as AES GCM tags and AES ciphertexts are still just input to each SDK in the clear. Builder Vault still protects the integrity of these values, even if up to threshold of the MPC nodes are corrupted.
• The sensitive input to AN10922 and RFC5649 methods were also split prior to this release. But these methods now requires you to split the input into shares in the same way as for AES above, using the SplitInput helper function in the TSM Utils section of the SDK.
• Imported AN10922 and RFC5649 imported key sharings are now re-randomized similarly to AES and HMAC key import.

Changes to the Java SDK

• The generateEcdsaKey method has been renamed to generateEcdsaKeyPair.
• Some time ago the SDK started returning JSON public keys instead of PKIX keys. This change was not reflected in the naming of some methods in the Java SDK. The methods returning JSON keys but referenced Pkix have been rename to Json instead of Pkix, so a simple replacement of this should fix any compile problems. If migrating from an older version where PKIX were used, please see the conversion methods in TsmUtils that can convert between JSON and PKIX for keys where such a conversion is possible.