Skip to main content

Resharing

Keys can be manually migrated between Treasury clusters using the normal backup/restore tooling. However, if the cluster size has changed, then keys will need to be manually reshared. For example, if you're changing from a 2-of-2 Treasury to a 3-of-4, then the "2" key shares each need to be reshared to "4" key shares.

warning

The API's used for importing keys and deriving addresses are not yet stable, and subject to future changes.

To follow this guide, you must be on >=25.1.1.

Overview​

Following our example of migration from 2-of-2 to 3-of-4, each of the 2 old signer databases will each export 4 sub-shares for the respective new signer databases to import.

  • Old node 1: Split key-share x1 into sub-shares x11, x12, x13, x14
  • Old node 2: Split key-share x2 into sub-shares x21, x22, x23, x24

Then each of our 4 new node will need to each import two sub-shares each.

  • New node 1: Import x11, x21 to construct a 3-of-4 key-share for x
  • New node 2: Import x12, x22 to construct a 3-of-4 key-share for x
  • New node 3: Import x13, x23 to construct a 3-of-4 key-share for x
  • New node 4: Import x14, x24 to construct a 3-of-4 key-share for x

Example

Now let's run the commands for real, assuming we are resharing from 2-of-2 to 3-of-4.

Signer​

Generate encryption keys on new nodes​

On each of your new nodes, generate a unique encryption key. This will be used only for importing subshares from the old nodes. It's important to use a unique key for each node to protect from accidentally exposing shares to the wrong node.

signer backup-keygen

Prepare the list of public keys in order of the participants (1, 2, 3, 4).

export BAKS="age11...,age12...,age13...,age14..."

Export subshares from on old nodes​

Export subshares for all key-shares on each node.

signer backup reshare --db ${TREASURY_HOME}/signer.db \
    --threshold 3 --cluster 4 \
    --baks ${BAKS} \
    --output-dir ./subshares

This will result in exporting a structure like:

./subshares/1/subshare_1_from_1_keys-x.json
# ...
./subshares/2/subshare_2_from_1_keys-x.json
# ...
./subshares/3/subshare_3_from_1_keys-x.json
# ...
./subshares/4/subshare_4_from_1_keys-x.json

Note to import, we will need to merge the resulting ./subshares directories from all of the old nodes. All subshares are encrypted to the backup keys we originally generated for this.

Import subshares on new nodes​

Now each node can import the subshares, using the merged ./subshares directories. Nodes should be stopped prior to any import.

 export SIGNER_BAK_PHRASE="..."
signer backup import --import-dir subshares/1 --db ${TREASURY_HOME}/signer.db

You can list the keys locally to confirm that they are imported.

signer list-keys --db ${TREASURY_HOME}/signer.db

Treasury​

Linking Key resources​

If you manually import keys using signer, it's important that you also import them into the policy engine on Treasury. Otherwise, you won't be able to reference them or use them at all in Treasury.

At the very least, for all keys you've imported locally, you need to call treasury keys load <key-name> each time. This will create a Key resource in Treasury that is linked to the signer key of the same name. This command will fail if the Key already exists in Treasury, or if there is no key found in signer.db.

# assuming there's a keys/10 from the import, as seen from `signer list-keys --db $jTREASURY_HOME/signer.db`
treasury keys load keys/10 --shared

Use --shared to be able to create Address's off of the key.

When restoring only a single node

Importing state from existing cluster​

If you're only trying to restore a single node (already have an existing Treasury cluster), you could alternatively restore the engine state directly from snapshot.

cord backup restore --snapshot  "snapshot.tar" --home ${TREASURY_HOME} --no-secrets --no-configs

Deriving Address resources​

You can derive Address resources from Key resources.

# create a Bitcoin address
treasury addresses create --shared --key keys/10 BTC

# create a Solana address
treasury addresses create --shared --key keys/11 SOL

Note that not all key algorithms are compatible with all chains.