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

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

❗️

Note

The Builder Vault SDKv1 has entered maintenance mode. It will still be available in v70 and will as such receive patch updates until 2027-03-14. But it will no longer receive any feature upgrades, and it will no longer be part Builder Vault versions following v70. If you use SDKv1, we recommend that you upgrade to SDKv2. In the following, we use “SDK” to refer to SDKv2 and we use “legacy SDK” to refer to SDKv1.

New Features

Upgrading Builder Vault from v62 to v70 brings a number of bug fixes, enhancements and new features. Some highlights are listed here.

• Support for AWS Secrets Manager
• Support for dynamic IAM RDS authentication
• New curve for ECDSA signatures as used by Starknet
• New Schnorr signature schemes supporting Mina, Zilliqa and Polkadot (sr25519)
• Support for OCSP validation, including OCSP stapling of client certificates
• A re-worked PKCS#11 integration that lets you use use Builder Vault as a PKCS#11 module
• Node-to-node communication via Redis and enhanced load-balancing using AMQP and Redis
• New flexible KeyCopy operation (useful for changing the threshold or number of players of a key sharing)
• Our new SDK is now also available in Web Assembly (WASM)
• The MPC nodes now support the DKLS23 MPC protocol for ECDSA signatures. DKLS23 computes ECDSA signatures in a more efficient way than DKLS19.
• Ability to choose hashing algorithms for API keys: MD5, SHA256, SHA512, bcrypt, Argon2i, Argon2id
• RSA, AES and HMAC operations now available in our SDK (previously only available in the legacy SDK). The methods are available in both Go, Java, Node.js, WASM, as well as on the mobile SDK (iOS/Android) and our native SDK library.
• A new demo repository with a collection of Builder Vault configurations and code examples for our different SDKs
• More flexible ways to authenticate clients using fields from the client certificate
• Reduced size of mobile library (iOS, android)
• Ability to toggle individual operations on or off for each algorithm
• Passing a negative UID or GID value to the Builder Vault container will now disable privilege dropping
• Typescript definitions for our node.js SDK
• Ability to specify individual session timeout for each MPC session

📘

Info

• You can find more information in our release changelog.
• Additional information about the new SDK features is available in our API reference documentation.
• Examples of the new features of the MPC node configuration and API calls can also be found in our demo repository.

Upgrading Builder Vault

Builder Vault (BV) has several APIs that are versioned separately as described here. The table below shows each of these for BV v62 and BV v70, respectively. In the following we will go through each of these APIs and cover the changes to that API and the relevant actions you need to take in order to upgrade.

Upgrading the MPC Nodes

Upgrading brings the node communication protocol from v31 to v34. This includes breaking changes. The only parts of the MPC node communication that breaks, however, are related to the AES, HMAC, AN10922 and RFC5649 protocols. If you use any of these operations, you will have to upgrade all your MPC nodes at the same time.

If you do not use any of the above, e.g. if you only use ECDSA or Schnorr (Ed25519 or Ed448) keys, you can upgrade one MPC node at the time. In this case, Builder Vault remains operational even if some MPC nodes are running v62 while others have been upgraded to v70. Some of the new features will of course only be available once you have upgraded all MPC nodes. It will for example only be possible to switch from the DKLS19 protocol to the DKLS23 protocol once all MPC nodes are running v70.

Database

The MPC node database version will go from v7.8 to v7.12 so database upgrading is needed. However, the upgrade happens automatically. The first time an MPC node v70 is started, it will automatically perform the necessary upgrade on its own database.

We recommend that you backup the MPC node database before upgrading. In some cases, e.g., for mobile MPC nodes that only handle a single key, it may be enough to export the key share or take a backup of the key share.

Node Configuration

When you upgrade an MPC node, the Node Configuration API goes from v18.1 to v21.4. This includes some breaking changes that may require you to modify the MPC node configuration file as part of the upgrade. The specific breaking changes are listed below. You can learn more about the new configuration format in the online documentation, and from the example configurations in the demo repository.

• All MPC protocol methods can be toggled on and off, and are disabled by default. You must explicitly enable the ones you need. Consult the protocol sections you are using here or in the example configuration file to see how this works.
• The RSA protocol has been renamed from SEPH20RSA to ADN06.
• The KeySize has been removed from the MRZ15 protocol configuration.

🚧

Note

DKLS19 is still supported in v70 LTS, but will not be part of future LTS versions. If you want to upgrade to the faster DKLS23 protocol, you can follow the instructions here.

However, that it's not possible to use DKLS23 with the v62 LTS version of the SDK, so if you switch to DKLS23, you will have to upgrade the SDK as well. In addition, DKLS23 doesn't work with our legacy SDK (SDKv1), so if you use this, you will need to upgrade to our recent SDK (SDKv2) as explained below.

Upgrading the SDK

Do I Need to Upgrade the SDK?

When upgrading Builder Vault from V62 to v70, the Client Communication API in the table above goes from v27 to v29. This is a major upgrade with breaking changes. The breaking changes, however, only affect users of the RSA, AES, HMAC, AN10922, and RFC5649 operations.

If you use any of these operations, you will therefore need to upgrade BV SDK to v70 at the same time as you upgrade the MPC node to v70. See next section for info about upgrading the SDK.

If not, e.g., if you only use ECDSA or Schnorr signatures (Ed25519, Ed448), you can upgrade an MPC node to v70 and keep using SDK v62. This may make the upgrade process easier. We still recommend upgrading the SDK to v70 as well, in order to get access to the new SDK features.

Upgrading from SDK v62

This section assumes that you already use our new SDK (SDKv2). See next section if you are using our legacy SDK (SDKv1) and want to upgrade to the new SDK.

When upgrading Builder Vault from v62 to v70, the Client API in the table above goes from v51 to v60.2. This is a major upgrade with breaking changes to the SDK API. Breaking changes to the SDK usually only requires small changes, but if you are affected by the breaking changes, you need to modify, recompile, and re-deploy the parts of your application that uses the BV SDK.

The following breaking changes were made between Builder Vault v62 and v70:

• The Go SDK now uses proper Go versioning. This means that you must include the version number in the import statement at the top of your go files. I.e., you need to use gitlab.com/Blockdaemon/go-tsm-sdkv2/v70/tsm instead of gitlab.com/Blockdaemon/go-tsm-sdkv2/tsm. An example of the new import path is available here.
• Previously, when generating and using Schnorr signatures (for example Ed25519) you had to specify the curve name. You now have to instead specify a Schnorr variant and the curve name is then derived from that variant. The previous Ed25519 and Ed448 signatures now requires you to specify the Schnorr variants tsm.SchnorrEd25519 tsm.SchnorrEd448. The new schemes are available by specifying the variants: tsm.SchnorrBIP340, tsm.SchnorrMina, tsm.SchnorrZilliqa, and tsm.SchnorrSr25519.
• A few of the static methods on the Go SDK have had their names changed. Consult the SDK API reference for more information.
• The SDK now returns public keys in a new JSON format instead of PKIX. A public key now has the following
  format:
  JSON

  {  
      "scheme": "...",  
      "curve": "...",  
      "point": "..."  
  }
  

  The scheme is either ECDSA or one of the Schnorr schemes. The curve is the name of the elliptic curve, but can be empty if it is uniquely defined by the scheme. The point is a compressed or uncompressed point representing the public key.
  The SDK comes utility methods that lets you easily convert between the JSON format and other formats, for example tsmutils.ConvertPKIXPublicKeyToJSONPublicKey(). Consult the SDK API reference for more information.
• SDK (Go, Node.js, Java, native): The public key pinning feature was removed from the mTLS authenticator. Public key pinning is now done using its own method, e.g., config := config.WithPublicKeyPinning(serverPKIXPublicKey). See this for more information.
• Duplicate sign method was removed from the node.js SDK.

The following changes apply to our legacy SDK:

• Changes to AES and RFC5649 operations for legacy SDK (SDKv1) (Go, Node.js, Java, native):
• A new max of 16384 bytes in introduced for plaintexts and ciphertexts in the AES-CTR, AES-CBC, and AES-GCM encrypt/decrypt methods
• A new max of 16384 bytes for the AES-GCM additional data is introduced
• The AES GCMEncrypt/GCMDecrypt methods now require a nonce of 12 bytes (previously, any nonce length of 1-16 bytes was accepted)
• The RFC5649 Blob length is now limited to 8192 bytes.
• The PRF method is no longer supported.

If you want to test that your application works with the new SDK, our advice is to deploy an internal test version of Builder Vault v70 (e.g., with all MPC nodes running in local Docker containers, as shown here). Then, in a separate branch of your application, you can upgrade to Builder Vault SDK v70 and make the necessary updates to your application, such that it works with the internal Builder Vault SDK v70.

Upgrading from the Legacy SDK

Our new SDK was introduced in BV v55 so you may already use this. But if you still use the BV legacy SDK (SDKv1) you may want to switch to our new SDK (SDKv2) as part of the upgrade process. As noted, the legacy SDK has entered maintenance mode and will not receive further feature upgrades.

The main differences between the legacy SDK and our new SDK are:

• With the legacy SDK you could in some cases control more than one MPC node with a single SDK. Our new SDK has a more uniform structure where you always need a separate SDK to control each of the MPC nodes. If you used a single SDK for multiple MPC nodes, you will now have to instantiate separate SDKs for each node, and invoke these concurrently in your application. Each SDK will return a partial result and you will then have to combine the partial results in order to get the final result. See the online documentation and the demo repository for examples of how to use the new SDK.
• The user/password authentication in the legacy SDK has been replaced with API key authentication. See more about this here and here. To migrate existing password-authenticated users to the new SDK, you can set the ApplicationID of an API key in the MPC node configuration file to match the existing user name.

In addition, if you use AES or RFC5649 operations, you also need to take into account the changes to these operations described in the previous section.

Builder Vault Integrations

The following is only relevant if you use one of the Builder Vault integrations (PKCS#11 or JCE):

• We have re-worked our PKCS#11 integration. The previous PKCS#11 integration was based on our legacy SDK and is now in maintenance mode and will not receive further feature upgrades. We instead recommend that you use our new PKCS#11 integration.
• The custom “SEPPRF” encryption mode in our JCE integration is no longer available.