Hard Key Recovery

Use cases

In the unlikely event that Cobo MPC Co-Managed Custody is no longer in service, with the assistance of your entrusted third party, you (i.e. the client) can reconstruct the MPC root extended private key that corresponds to the MPC wallet. All child private keys that correspond to the wallet addresses in this MPC wallet can then be derived from this MPC root extended private key.

The hard key recovery requires pre-preparation. If you follow the prerequisite steps on a regular basis, the hard key recovery will only involve the two MPC key shares managed by you and your entrusted third party. Cobo’s participation is not needed.

Requirements

The secrets.db database files and passwords that associate with the two MPC key shares managed by you and your entrusted third party must be accessible.

Pre-Preparation

  • Acquire the hard key recovery kit via the open-source repository: https://github.com/CoboCustody/cobo-mpc-recovery-kits (project name: cobo-mpc-recovery-kits); read through the README.md file before compiling cobo-mpc-recovery-tool; alternatively, the latest version of cobo-mpc-recovery-tool can be downloaded directly at https://github.com/CoboCustody/cobo-mpc-recovery-kits/releases

  • Record the MPC root extended public key after all three parties have jointly generated a set of three MPC key shares; the MPC root extended public key will remain the same once it has been generated

  • Save all wallet addresses under the MPC wallet; the address information can be queried using the following three methods:

  1. Retrieve AddressDetail via the generate_addresses API interface during key generation; the HD path that corresponds to each address will be included in the response

  2. Retrieve AddressDetail via the list_addresses API interface on a regular basis; the HD path that corresponds to each address will be included in the response

  3. Click on the “Export” icon on Cobo Custody Web to manually download all address information under the selected MPC wallet

Recovery Process

  • Prepare the recovery environment

The server where your TSS Node is hosted must be offline or in a secure environment. Please make sure that your TSS Node package and the database file are readily available. The directory of your TSS Node package is as follows:

cobo-tss-node-generic
├── configs
│   └── cobo-tss-node-config.yaml.template
├── db
│   └── secrets.db
├── recovery  (default folder where the exported MPC key shares will be stored)
└── tss-node.sh
  • Confirm the accuracy of MPC key shares

Enter the cobo-tss-node-generic directory to retrieve the group information:

sudo ./tss-node.sh info group

Output example:

$ sudo ./tss-node.sh info group
Container started: bc5e54bc4675a46b3edc9bbabc76ebb7d3918260fe8aeb09bbd60375ae26438c
Wait a few seconds ..................
INFO[2022-12-14T09:51:28+08:00] Total number of groups: 1, from db/secrets.db
INFO[2023-01-16T09:04:12+08:00] Group info: 
    Group ID: OoQGkknsPdPjLCmSuuSf
    Created Time: 2023-01-09 17:42:21.391854 +0800 HKT
    Root Extended Public Key: xpub661MyMwAqRbcGNFddDqGveSvN9jr1n1GMGFypyhqn34oKyMw9bvrych636CDwgBbLjdLgQRoQtmqPucPb1pZQVBZq3tuXXTQX8wP3JMWAak
    ChainCode: 0xb74087d551e44ef8d3a1270accb1977fd373c29fe6e235bc681c59a2137e1334
    Share ID: 914259450665435839517029445012417071559
    Share Public Key: 0x023633989378b01c2e66d5fd70666101546a310aaab2c08c7b5813be371d438c0d
    Type: 1
    Curve: secp256k1
    Threshold: 2
    Local Node ID: cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs
    Other Node IDs: [coboBP97RpWKD2WGKhUUtZ1iu6uyWL7MjY4S8MpTUHDiwvRni cobok1nJ4P8DL1mU5SDEzh8QDA5FzdSg7gdkAZKUWK4NuviS4]
    Participants: 3
      (1) Node ID: coboBP97RpWKD2WGKhUUtZ1iu6uyWL7MjY4S8MpTUHDiwvRni
          Share ID: 751341643106997665517612415491881522730
          Share Public Key: 0x02ad8728dce88aa210645cff8dea474114376796d81e4b4df76bfa3ea847131b57
      (2) Node ID: cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs
          Share ID: 914259450665435839517029445012417071559
          Share Public Key: 0x023633989378b01c2e66d5fd70666101546a310aaab2c08c7b5813be371d438c0d
      (3) Node ID: cobok1nJ4P8DL1mU5SDEzh8QDA5FzdSg7gdkAZKUWK4NuviS4
          Share ID: 997493310528521058725882883276549657588
          Share Public Key: 0x02a233d2d37297bcfc3092ea65997a29b72931b5ca343db5cd608c85a306be5994
  • Share with your entrusted third party the group ID and MPC root extended public key associated with the MPC key share you’d like to export; your entrusted third party will use the information to verify the key share information

  • Export the MPC key share

In an offline or a secure network environment, execute the following command in the root directory of your TSS Node to export the MPC key share. Please note that <Group ID> should be replaced with the group ID you’ve retrieved in the previous step:

./tss-node.sh export-share --group-id <GROUP_ID>

Output example:

./tss-node.sh export-share --group-id OoQGkknsPdPjLCmSuuSf
INFO[2023-01-16T16:57:10+08:00] Init from default config file configs/cobo-tss-node-config.yaml 
Type password: 
Please type new password to encrypt export share
Type password (at least 8 characters): 
Retype password: 
INFO[2023-01-16T16:57:20+08:00] Export group info: 
    Group ID: OoQGkknsPdPjLCmSuuSf
    Created Time: 2023-01-09 17:42:21.391854 +0800 HKT
    Root Extended Public Key: xpub661MyMwAqRbcGNFddDqGveSvN9jr1n1GMGFypyhqn34oKyMw9bvrych636CDwgBbLjdLgQRoQtmqPucPb1pZQVBZq3tuXXTQX8wP3JMWAak
    ChainCode: 0xb74087d551e44ef8d3a1270accb1977fd373c29fe6e235bc681c59a2137e1334
    Share ID: 914259450665435839517029445012417071559
    Share Public Key: 0x023633989378b01c2e66d5fd70666101546a310aaab2c08c7b5813be371d438c0d
    Type: 1
    Curve: secp256k1
    Threshold: 2
    Local Node ID: cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs
    Other Node IDs: [coboBP97RpWKD2WGKhUUtZ1iu6uyWL7MjY4S8MpTUHDiwvRni cobok1nJ4P8DL1mU5SDEzh8QDA5FzdSg7gdkAZKUWK4NuviS4]
    Participants: 3
      (1) Node ID: coboBP97RpWKD2WGKhUUtZ1iu6uyWL7MjY4S8MpTUHDiwvRni
          Share ID: 751341643106997665517612415491881522730
          Share Public Key: 0x02ad8728dce88aa210645cff8dea474114376796d81e4b4df76bfa3ea847131b57
      (2) Node ID: cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs
          Share ID: 914259450665435839517029445012417071559
          Share Public Key: 0x023633989378b01c2e66d5fd70666101546a310aaab2c08c7b5813be371d438c0d
      (3) Node ID: cobok1nJ4P8DL1mU5SDEzh8QDA5FzdSg7gdkAZKUWK4NuviS4
          Share ID: 997493310528521058725882883276549657588
          Share Public Key: 0x02a233d2d37297bcfc3092ea65997a29b72931b5ca343db5cd608c85a306be5994 
INFO[2023-01-16T16:57:20+08:00] Export TSS group OoQGkknsPdPjLCmSuuSf to file: recovery/tss-group-OoQGkknsPdPjLCmSuuSf-node-cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs-recovery-20230116-165720 

Your MPC key share file (JSON format) will be as shown below:

{
   "version": 1,
   "group_info": {
       "id": "OoQGkknsPdPjLCmSuuSf",
       "created_time": "2023-01-09 17:42:21.391854 +0800 HKT",
       "type": 1,
       "root_extended_public_key": "xpub661MyMwAqRbcGNFddDqGveSvN9jr1n1GMGFypyhqn34oKyMw9bvrych636CDwgBbLjdLgQRoQtmqPucPb1pZQVBZq3tuXXTQX8wP3JMWAak",
       "chaincode": "0xb74087d551e44ef8d3a1270accb1977fd373c29fe6e235bc681c59a2137e1334",
       "curve": "secp256k1",
       "threshold": 2,
       "participants": [
           {
               "node_id": "coboBP97RpWKD2WGKhUUtZ1iu6uyWL7MjY4S8MpTUHDiwvRni",
               "share_id": "751341643106997665517612415491881522730",
               "share_public_key": "0x02ad8728dce88aa210645cff8dea474114376796d81e4b4df76bfa3ea847131b57"
           },
           {
               "node_id": "cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs",
               "share_id": "914259450665435839517029445012417071559",
               "share_public_key": "0x023633989378b01c2e66d5fd70666101546a310aaab2c08c7b5813be371d438c0d"
           },
           {
               "node_id": "cobok1nJ4P8DL1mU5SDEzh8QDA5FzdSg7gdkAZKUWK4NuviS4",
               "share_id": "997493310528521058725882883276549657588",
               "share_public_key": "0x02a233d2d37297bcfc3092ea65997a29b72931b5ca343db5cd608c85a306be5994"
           }
       ]
   },
   "share_info": {
       "node_id": "cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs",
       "share_id": "914259450665435839517029445012417071559",
       "share_public_key": "0x023633989378b01c2e66d5fd70666101546a310aaab2c08c7b5813be371d438c0d",
       "encrypted_share": "7Ej7pjpYN7QuZ8U0j7bBpsXWfmcQ8fS3jt7gyAgpvjH8nMBZyO8q3MGwcDkkaqzq6FdkG55KqhMXLTR6",
       "kdf": {
           "length": 32,
           "iterations": 100000,
           "salt": "0x36cba7fe220aae67e748a2fb8bb5c99d20da34321c3485f3a017ee7e73e81517",
           "hash_type": 5,
           "hash_name": "SHA-256"
       }
   }
}



  • Acquire MPC key share exported by your entrusted third party, and verify all MPC key shares

The MPC key share exported by your entrusted third party will also be a JSON file. Please make sure that the group ID and the MPC root extended public key in the files exported by you and your entrusted third party are the same. Create a new recovery folder in the same directory level as cobo-mpc-recovery-tool, and paste the two exported MPC key share files under the recovery folder, as shown below:

├── cobo-mpc-recovery-tool
└── recovery
    ├── tss-group-<GROUP_ID>-node-<NODE_ID1>-recovery-<TIME1>
    └── tss-group-<GROUP_ID>-node-<NODE_ID2>-recovery-<TIME2>

Execute the following commands (please use the actual group ID and MPC key share files):

./cobo-mpc-recovery-tool verify \
    --group-recovery-files recovery/tss-group-<GROUP_ID>-node-<NODE_ID1>-recovery-<TIME1>,recovery/tss-group-<GROUP_ID>-node-<NODE_ID2>-recovery-<TIME2> \
    --group-id <GROUP_ID>

Output example:

./cobo-mpc-recovery-tool verify \
    --group-recovery-files recovery/tss-group-OoQGkknsPdPjLCmSuuSf-node-cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs-recovery-20230116-165720,recovery/tss-group-OoQGkknsPdPjLCmSuuSf-node-cobok1nJ4P8DL1mU5SDEzh8QDA5FzdSg7gdkAZKUWK4NuviS4-recovery-20230109-174349 \
    --group-id OoQGkknsPdPjLCmSuuSf
INFO[2023-01-16T22:01:30+08:00] Start to verify group recovery file recovery/tss-group-OoQGkknsPdPjLCmSuuSf-node-cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs-recovery-20230116-165720 
INFO[2023-01-16T22:01:30+08:00] Verify all group parameters passed!          
INFO[2023-01-16T22:01:30+08:00] Start to reconstruct root public key ...     
INFO[2023-01-16T22:01:30+08:00] Use participants (no.1) (no.2)  to reconstruct root extended public key ... 
INFO[2023-01-16T22:01:30+08:00] Reconstructed root extended public key: xpub661MyMwAqRbcGNFddDqGveSvN9jr1n1GMGFypyhqn34oKyMw9bvrych636CDwgBbLjdLgQRoQtmqPucPb1pZQVBZq3tuXXTQX8wP3JMWAak 
INFO[2023-01-16T22:01:30+08:00] Use participants (no.1) (no.3)  to reconstruct root extended public key ... 
INFO[2023-01-16T22:01:30+08:00] Reconstructed root extended public key: xpub661MyMwAqRbcGNFddDqGveSvN9jr1n1GMGFypyhqn34oKyMw9bvrych636CDwgBbLjdLgQRoQtmqPucPb1pZQVBZq3tuXXTQX8wP3JMWAak 
INFO[2023-01-16T22:01:30+08:00] Verify to reconstruct root public key passed! 
INFO[2023-01-16T22:01:30+08:00] Start to derive share public key from share secret ... 
Enter password to decrypt share secret from recovery/tss-group-OoQGkknsPdPjLCmSuuSf-node-cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs-recovery-20230116-165720
Password:
INFO[2023-01-16T22:01:34+08:00] Derived share public key: 0x043633989378b01c2e66d5fd70666101546a310aaab2c08c7b5813be371d438c0d724e32e537b78ddd1cba1c38aa088aa997e4f3a47d45ac422b54518a138cb732 
INFO[2023-01-16T22:01:34+08:00] Verify to derive share public key from share secret passed! 
INFO[2023-01-16T22:01:34+08:00] Verify group recovery file recovery/tss-group-OoQGkknsPdPjLCmSuuSf-node-cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs-recovery-20230116-165720 passed! 
INFO[2023-01-16T22:01:34+08:00] =======================================      
INFO[2023-01-16T22:01:34+08:00] Start to verify group recovery file recovery/tss-group-OoQGkknsPdPjLCmSuuSf-node-cobok1nJ4P8DL1mU5SDEzh8QDA5FzdSg7gdkAZKUWK4NuviS4-recovery-20230109-174349 
INFO[2023-01-16T22:01:34+08:00] Verify all group parameters passed!          
INFO[2023-01-16T22:01:34+08:00] Start to compare with group (no.1) parameters ... 
INFO[2023-01-16T22:01:34+08:00] Compare with group (no.1) parameters passed! 
INFO[2023-01-16T22:01:34+08:00] Start to reconstruct root public key ...     
INFO[2023-01-16T22:01:34+08:00] Use participants (no.1) (no.2)  to reconstruct root extended public key ... 
INFO[2023-01-16T22:01:34+08:00] Reconstructed root extended public key: xpub661MyMwAqRbcGNFddDqGveSvN9jr1n1GMGFypyhqn34oKyMw9bvrych636CDwgBbLjdLgQRoQtmqPucPb1pZQVBZq3tuXXTQX8wP3JMWAak 
INFO[2023-01-16T22:01:34+08:00] Use participants (no.1) (no.3)  to reconstruct root extended public key ... 
INFO[2023-01-16T22:01:34+08:00] Reconstructed root extended public key: xpub661MyMwAqRbcGNFddDqGveSvN9jr1n1GMGFypyhqn34oKyMw9bvrych636CDwgBbLjdLgQRoQtmqPucPb1pZQVBZq3tuXXTQX8wP3JMWAak 
INFO[2023-01-16T22:01:34+08:00] Verify to reconstruct root public key passed! 
INFO[2023-01-16T22:01:34+08:00] Start to derive share public key from share secret ... 
Enter password to decrypt share secret from recovery/tss-group-OoQGkknsPdPjLCmSuuSf-node-cobok1nJ4P8DL1mU5SDEzh8QDA5FzdSg7gdkAZKUWK4NuviS4-recovery-20230109-174349
Password:
INFO[2023-01-16T22:01:37+08:00] Derived share public key: 0x04a233d2d37297bcfc3092ea65997a29b72931b5ca343db5cd608c85a306be59944e8ba3e10a2dea4f4682c2076f9ed7cc1b1a8261b6a7b4abab7a941e60f172f2 
INFO[2023-01-16T22:01:37+08:00] Verify to derive share public key from share secret passed! 
INFO[2023-01-16T22:01:37+08:00] Verify group recovery file recovery/tss-group-OoQGkknsPdPjLCmSuuSf-node-cobok1nJ4P8DL1mU5SDEzh8QDA5FzdSg7gdkAZKUWK4NuviS4-recovery-20230109-174349 passed! 
INFO[2023-01-16T22:01:37+08:00] =======================================      
INFO[2023-01-16T22:01:37+08:00] Verify all group recovery files passed!  

  • Reconstruct all MPC key shares, and derive the child private keys of all wallet addresses under the MPC wallet

There are three methods to export the address information, as outlined in step 3 of the "Pre-Preparation" section. The following guide uses the third method (i.e. Cobo Custody Web) as an example. If you’d like to use the other two methods, please save the exported address information as CSV files.

You can locate the address.csv file after manually exporting the address information from Cobo Custody Web. Please paste address.csv under the recovery folder, as shown below:

├── cobo-mpc-recovery-tool
└── recovery
    ├── address.csv
    ├── tss-group-<GROUP_ID>-node-<NODE_ID1>-recovery-<TIME1>
    └── tss-group-<GROUP_ID>-node-<NODE_ID2>-recovery-<TIME2>

Execute the following commands (please use the actual group ID and MPC key share files):

./cobo-mpc-recovery-tool \
    --group-recovery-files recovery/tss-group-<GROUP_ID>-node-<NODE_ID1>-recovery-<TIME1>,recovery/tss-group-<GROUP_ID>-node-<NODE_ID2>-recovery-<TIME2> \
    --group-id <GROUP_ID> \
    --csv-file recovery/address.csv \
    --show-root-private-key

Output example:

 ./cobo-mpc-recovery-tool verify \
    --group-recovery-files recovery/tss-group-OoQGkknsPdPjLCmSuuSf-node-cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs-recovery-20230116-165720,recovery/tss-group-OoQGkknsPdPjLCmSuuSf-node-cobok1nJ4P8DL1mU5SDEzh8QDA5FzdSg7gdkAZKUWK4NuviS4-recovery-20230109-174349 \
    --group-id OoQGkknsPdPjLCmSuuSf
INFO[2023-01-16T22:01:30+08:00] Start to verify group recovery file recovery/tss-group-OoQGkknsPdPjLCmSuuSf-node-cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs-recovery-20230116-165720 
INFO[2023-01-16T22:01:30+08:00] Verify all group parameters passed!          
INFO[2023-01-16T22:01:30+08:00] Start to reconstruct root public key ...     
INFO[2023-01-16T22:01:30+08:00] Use participants (no.1) (no.2)  to reconstruct root extended public key ... 
INFO[2023-01-16T22:01:30+08:00] Reconstructed root extended public key: xpub661MyMwAqRbcGNFddDqGveSvN9jr1n1GMGFypyhqn34oKyMw9bvrych636CDwgBbLjdLgQRoQtmqPucPb1pZQVBZq3tuXXTQX8wP3JMWAak 
INFO[2023-01-16T22:01:30+08:00] Use participants (no.1) (no.3)  to reconstruct root extended public key ... 
INFO[2023-01-16T22:01:30+08:00] Reconstructed root extended public key: xpub661MyMwAqRbcGNFddDqGveSvN9jr1n1GMGFypyhqn34oKyMw9bvrych636CDwgBbLjdLgQRoQtmqPucPb1pZQVBZq3tuXXTQX8wP3JMWAak 
INFO[2023-01-16T22:01:30+08:00] Verify to reconstruct root public key passed! 
INFO[2023-01-16T22:01:30+08:00] Start to derive share public key from share secret ... 
Enter password to decrypt share secret from recovery/tss-group-OoQGkknsPdPjLCmSuuSf-node-cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs-recovery-20230116-165720
Password:
INFO[2023-01-16T22:01:34+08:00] Derived share public key: 0x043633989378b01c2e66d5fd70666101546a310aaab2c08c7b5813be371d438c0d724e32e537b78ddd1cba1c38aa088aa997e4f3a47d45ac422b54518a138cb732 
INFO[2023-01-16T22:01:34+08:00] Verify to derive share public key from share secret passed! 
INFO[2023-01-16T22:01:34+08:00] Verify group recovery file recovery/tss-group-OoQGkknsPdPjLCmSuuSf-node-cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs-recovery-20230116-165720 passed! 
INFO[2023-01-16T22:01:34+08:00] =======================================      
INFO[2023-01-16T22:01:34+08:00] Start to verify group recovery file recovery/tss-group-OoQGkknsPdPjLCmSuuSf-node-cobok1nJ4P8DL1mU5SDEzh8QDA5FzdSg7gdkAZKUWK4NuviS4-recovery-20230109-174349 
INFO[2023-01-16T22:01:34+08:00] Verify all group parameters passed!          
INFO[2023-01-16T22:01:34+08:00] Start to compare with group (no.1) parameters ... 
INFO[2023-01-16T22:01:34+08:00] Compare with group (no.1) parameters passed! 
INFO[2023-01-16T22:01:34+08:00] Start to reconstruct root public key ...     
INFO[2023-01-16T22:01:34+08:00] Use participants (no.1) (no.2)  to reconstruct root extended public key ... 
INFO[2023-01-16T22:01:34+08:00] Reconstructed root extended public key: xpub661MyMwAqRbcGNFddDqGveSvN9jr1n1GMGFypyhqn34oKyMw9bvrych636CDwgBbLjdLgQRoQtmqPucPb1pZQVBZq3tuXXTQX8wP3JMWAak 
INFO[2023-01-16T22:01:34+08:00] Use participants (no.1) (no.3)  to reconstruct root extended public key ... 
INFO[2023-01-16T22:01:34+08:00] Reconstructed root extended public key: xpub661MyMwAqRbcGNFddDqGveSvN9jr1n1GMGFypyhqn34oKyMw9bvrych636CDwgBbLjdLgQRoQtmqPucPb1pZQVBZq3tuXXTQX8wP3JMWAak 
INFO[2023-01-16T22:01:34+08:00] Verify to reconstruct root public key passed! 
INFO[2023-01-16T22:01:34+08:00] Start to derive share public key from share secret ... 
Enter password to decrypt share secret from recovery/tss-group-OoQGkknsPdPjLCmSuuSf-node-cobok1nJ4P8DL1mU5SDEzh8QDA5FzdSg7gdkAZKUWK4NuviS4-recovery-20230109-174349
Password:
INFO[2023-01-16T22:01:37+08:00] Derived share public key: 0x04a233d2d37297bcfc3092ea65997a29b72931b5ca343db5cd608c85a306be59944e8ba3e10a2dea4f4682c2076f9ed7cc1b1a8261b6a7b4abab7a941e60f172f2 
INFO[2023-01-16T22:01:37+08:00] Verify to derive share public key from share secret passed! 
INFO[2023-01-16T22:01:37+08:00] Verify group recovery file recovery/tss-group-OoQGkknsPdPjLCmSuuSf-node-cobok1nJ4P8DL1mU5SDEzh8QDA5FzdSg7gdkAZKUWK4NuviS4-recovery-20230109-174349 passed! 
INFO[2023-01-16T22:01:37+08:00] =======================================      
INFO[2023-01-16T22:01:37+08:00] Verify all group recovery files passed! 

Once the execution is complete, all child private keys will be saved under the recovery/address-recovery-<TIME>.csv file in plain text. Please make sure that all data is stored securely.

Last updated