Upgrading

📘

Upgrading the Builder Vault

Before upgrading a production installation of the Builder Vault to a new version, make sure you understand the different interfaces described here. In particular, you need to be aware of any consequences in the case where your upgrade involves a bump in the major version of any of these interfaces.

If you are upgrading to a new version of the database, make sure to follow the instructions in this section.

In some cases, depending on which features of the Builder Vault you use, an upgrade to a new major version may not affect your installation. Consult the changelog or contact the Builder Vault support team if you want more information about the impact of upgrading to specific major versions.

The following may require special care when upgrading:

Major Changes to Client Communication

If your upgrade includes a major bump in the client communication version, but not in the node communication version, it means that you can upgrade each node individually. But you may have to upgrade a node and its SDK in sync.

If your node is a static node running on a server, and it's accessed only by a few SDKs that also run on the server side, then you can usually upgrade a node and its SDK(s) in one go. It's also easy if you have many clients, but each client holds an SDK with an embedded node, say, on its mobile device. In this case you can simply upgrade the client SDKs gradually, since the upgrade automatically also upgrades the embedded node.

The only case where you need to take extra care is the the case where you have many clients that each holds its own SDK and where the client SDKs all connects to a single server node. To ensure a smooth upgrade in this case, we recommend you follow this procedure:

1. First update your application such that no new keys are generated on the server node.
2. Make a copy of the server node and its database. The copy node should have the same config.toml file, containing the same PlayerIndex and point to the same set of peer nodes as the original. The only exception is that it should point to the copy database. So now you will have two identical copies of the node, using two identical copies of the database.
3. Now upgrade the node copy. This will automatically upgrade the database copy as well. We will refer to this as the new node.
4. If you have any presignatures in your database, then make sure to delete these in the new database. This is important for security, since a presignature must only be used once.
5. Update your application so that the new node is accessible on a new different URL. It is ok to allow creation of new keys on the new node.
6. Now you can gradually upgrade the client SDKs. Once a client is upgraded, you configure its SDK to point to the new server node instead of the old server node.
7. Finally, when all clients have switched to the new SDK, you can take down the old node.

Disabling key generation in the old database essentially makes it read-only. If this is not possible, you may end up with new keys in both the old and the new database, and you will have to manually move key shares from the old to the new using the ExportKeyShare and ImportKeyShare methods. This is possible, but quickly gets complicated if the two databases diverge a lot.

Major Changes to Node Communication

A major bump in the node communication version, but not in client communication means that the SDKs can be upgraded gradually, but you may need to upgrade all your nodes in sync.

If your setup only consists of just a few static server nodes, then this is usually easy to handle. But if you run many nodes, e.g. embedded on client mobile devices, this might not be as easy. To ensure a smooth upgrade in this case, we recommend the following approach. Assume for instance that you have two static server nodes and a number of (embedded) client nodes.

1. First update your application such that no new keys are generated on the server nodes.
2. Make a copy of the static nodes and their databases. The copies node should have the same config.toml files as the originals, containing the same PlayerIndex. The only exception is that the config.toml file on each of the new server nodes should be modified so that it connects to the copied database, and its MPC server should be exposed on a different port. Also make sure the new config.toml makes the server node connect to the other server node on the new port. After this step, the static server nodes and their databases should exist in two identical versions.
3. Now upgrade the two server nodes in one of the versions. We will refer to this as the new server nodes. Note that this will automatically upgrade the database copies on the new server nodes, as well.
4. If you have any presignatures in your server node databases, then make sure to delete these in the new database. This is important for security, since a presignature must only be used once.
5. Update your application so that the new nodes are accessible on a new different URL. It is ok to generate keys on the new server nodes.
6. Now you can gradually upgrade the client nodes. Once a client is upgraded, you configure its embedded node to point to the new server nodes instead of the old server nodes.
7. Finally, when all clients have switched to the new server node, you can take down the old node.

Major Bump in both Client and Node Communication

If you migrate to a new version that involves a major bump in both client communication and node communication, a smooth upgrade process may require a duplication of nodes as described above.

Upgrading with Node Replication and Database Changes

If your setup involves node replication, you need to consider the following. Suppose that you use replication for Player 1, such that you have two nodes, Node 1A, Node1B, that both connect to the same Player 1 database. If the upgrade does not involve any changes to the database, then you can upgrade Node 1A and Node 1B separately. (You may need to upgrade their SDK's and the other nodes as well, depending on whether there are breaking changes to node communication and client communication, as mentioned above.)

But if the upgrade involves a database change, then when you upgrade Node 1A, it will automatically upgrade the database. All our database upgrades are "breaking" in the sense that older nodes cannot work on database with more recent versions. This means that you will have to upgrade node 1A and node 1B in one go.