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:

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
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
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

Make sure that the MPC root extended public key in the above example is the same as the MPC root extended public key you’ve saved in step 2 during the “Pre-Preparation” stage
Find the group with the correct MPC root extended public key and the latest update time in the event that multiple MPC key shares are managed by the TSS Node; note down the group ID (e.g. OoQGkknsPdPjLCmSuuSf in the example above)

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 <groupID> should be replaced with the group ID you’ve retrieved in the previous step:

./tss-node.sh export-share --group-ids <groupID>

Output example:

./tss-node.sh export-share --group-ids 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 16 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/recovery-secrets-cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs-2023-01-16T16:57:20Z

Enter the password you’ve set to encrypt the database file when initializing your TSS Node
Enter a new password; this password is used to encrypt the MPC key share in the exported file and will be used during hard key recovery to access data associated with your MPC key share; this password cannot be modified once it has been set; in the event that this password is lost, your exported MPC key share file will no longer be accessible and must be exported again; you're recommended to set a complex password between 16-32 characters using a password manager (e.g. 1Password) and store the password on a secure device
Re-enter the new password
The program will generate private key share files automatically, following this naming convention: recovery/recovery-secrets-<nodeID>-<time>. Each private key shard file is in JSON format, as shown in this example from the log entry: recovery/recovery-secrets-cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs-2023-01-16T16:57:20Z.
Verify the accuracy of the group ID and the MPC root extended public key in the exported file (i.e. group_info and root_extended_public_key)

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


{
    "recovery_groups": [
        {
           "version": 4,
           "group_info": {
               "id": "OoQGkknsPdPjLCmSuuSf",
               "canonical_group_id": "",
               "protocol_group_id": "",
               "protocol_type": "",
               "created_time": "2023-01-09T17:42:21+08:00",
               "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
    ├── recovery-secrets-<nodeID1>-<time1>
    └── recovery-secrets-<nodeID2>-<time2>

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

./cobo-mpc-recovery-tool verify \
    --recovery-group-files recovery/recovery-secrets-<nodeID1>-<time1>,recovery/recovery-secrets-<nodeID2>-<time2> \
    --group-id <groupID>

Output example:

./cobo-mpc-recovery-tool verify \
    --recovery-group-files recovery/recovery-secrets-cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs-2023-01-16T16:57:20Z,recovery/recovery-secrets-cobok1nJ4P8DL1mU5SDEzh8QDA5FzdSg7gdkAZKUWK4NuviS4-2023-01-09T17:43:49Z \
    --group-id OoQGkknsPdPjLCmSuuSf
INFO[2023-01-16T22:01:30+08:00] Start to verify recovery group file recovery/recovery-secrets-cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs-2023-01-16T16:57:20Z 
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/recovery-secrets-cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs-2023-01-16T16:57:20Z
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 recovery group file recovery/recovery-secrets-cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs-2023-01-16T16:57:20Z passed! 
INFO[2023-01-16T22:01:34+08:00] =======================================      
INFO[2023-01-16T22:01:34+08:00] Start to verify recovery group file recovery/recovery-secrets-cobok1nJ4P8DL1mU5SDEzh8QDA5FzdSg7gdkAZKUWK4NuviS4-2023-01-09T17:43:49Z
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/recovery-secrets-cobok1nJ4P8DL1mU5SDEzh8QDA5FzdSg7gdkAZKUWK4NuviS4-2023-01-09T17:43:49Z
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 recovery group file recovery/recovery-secrets-cobok1nJ4P8DL1mU5SDEzh8QDA5FzdSg7gdkAZKUWK4NuviS4-2023-01-09T17:43:49Z passed! 
INFO[2023-01-16T22:01:37+08:00] =======================================      
INFO[2023-01-16T22:01:37+08:00] Verify all recovery group files passed!

The tool will automatically verify the keys/values associated with the first MPC key share file
The tool will automatically derive and verify the MPC root extended public key using the “participants” information in the first MPC key share file
You need to manually enter the password associated with the first MPC key share file to decrypt it; the tool will automatically derive and verify the corresponding share public key
The tool will automatically verify the keys/values associated with the second MPC key share file
The tool will automatically verify whether the keys/values in the first MPC key share file are consistent with that in the second MPC key share file
The tool will automatically derive and verify the MPC root extended public key using the “participants” information in the second MPC key share file
You need to manually enter the password associated with the second MPC key share file to decrypt it; the tool will automatically derive and verify the corresponding share public key

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
    ├── recovery-secrets-<nodeID1>-<time1>
    └── recovery-secrets-<nodeID2>-<time2>

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

./cobo-mpc-recovery-tool \
    --recovery-group-files recovery/recovery-secrets-<nodeID1>-<time1>,recovery/recovery-secrets-<nodeID2>-<time2> \
    --group-id <groupID> \
    --csv-file recovery/address.csv \
    --show-root-private-key

Output example:

 ./cobo-mpc-recovery-tool \
    --recovery-group-files recovery/recovery-secrets-cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs-2023-01-16T16:57:20Z,recovery/recovery-secrets-cobok1nJ4P8DL1mU5SDEzh8QDA5FzdSg7gdkAZKUWK4NuviS4-2023-01-09T17:43:49Z \
    --group-id OoQGkknsPdPjLCmSuuSf \
    --csv-file recovery/address.csv \
    --show-root-private-key
Enter password to decrypt share secret from recovery/recovery-secrets-cobo2Jitd83uNFZmGnvs8c4Bs1TUNjVVeBQmc82a4KpLFqdbLs-2023-01-16T16:57:20Z
Password:
Enter password to decrypt share secret from recovery/recovery-secrets-cobok1nJ4P8DL1mU5SDEzh8QDA5FzdSg7gdkAZKUWK4NuviS4-2023-01-09T17:43:49Z
Password:
INFO[2023-01-16T22:54:17+08:00] Derive keys from recovery/address.csv to recovery/address-recovery-20230116-225417.csv: 
INFO[2023-01-16T22:54:17+08:00] Path: 44/1/2/0/15 derived child private key: [child-hex-private-key-display] 
INFO[2023-01-16T22:54:17+08:00] Path: 44/1/2/0/15 derived child extended private key: [child-extended-private-key-display]
INFO[2023-01-16T22:54:17+08:00] Path: 44/1/2/0/15 derived child extended public key: xpub6GQqSwqQCEJ7uB2XnbrWGrRTQckfhPH1B9UoyBaHVT4cJikeQFTnUk94b9s13JfcdYY4VzQMhiDtBtVtvAQAbaqeUikAbnYzyFKpxdudyRZ 
INFO[2023-01-16T22:54:17+08:00] Path: 44/1/2/0/14 derived child private key: [child-hex-private-key-display]
INFO[2023-01-16T22:54:17+08:00] Path: 44/1/2/0/14 derived child extended private key: [child-extended-private-key-display]
INFO[2023-01-16T22:54:17+08:00] Path: 44/1/2/0/14 derived child extended public key: xpub6GQqSwqQCEJ7rRKt8CLveYenF4LgKLtpy8EpUiJ95bdF6hWMHuW4pZksFE3Am9SDrsccbDxBi4P7gEHAfXbdJGJCQhqZz3dMyEYoz5vgLeh 
INFO[2023-01-16T22:54:17+08:00] Path: 44/1/2/0/13 derived child private key: [child-hex-private-key-display] 
INFO[2023-01-16T22:54:17+08:00] Path: 44/1/2/0/13 derived child extended private key: [child-extended-private-key-display]
INFO[2023-01-16T22:54:17+08:00] Path: 44/1/2/0/13 derived child extended public key: xpub6GQqSwqQCEJ7p3Q6AZa5KRfj5xBKCPzv4nvkPLDs7N9HoN5FwzruzFGy2qfxjSagJXvkxVahST4oFFnkbPUd6sm3UcoSoXxMHGYEZMFNsLU 
INFO[2023-01-16T22:54:17+08:00] Derive keys from recovery/address.csv to recovery/address-recovery-20230116-225417.csv completed 
INFO[2023-01-16T22:54:17+08:00] Reconstructed root private key: 0x61272be72bf74d3b9320d8019aab0fe2add5e75fcb23efde2d899ec2d3f78959 
INFO[2023-01-16T22:54:17+08:00] Reconstructed root extended private key: [root-extended-private-key-display]
INFO[2023-01-16T22:54:17+08:00] Reconstructed root extended public key: xpub661MyMwAqRbcGNFddDqGveSvN9jr1n1GMGFypyhqn34oKyMw9bvrych636CDwgBbLjdLgQRoQtmqPucPb1pZQVBZq3tuXXTQX8wP3JMWAak

Enter the passwords to decrypt the two MPC key share files
The MPC root extended private key and the MPC root extended public key will be reconstructed
Make sure that the MPC root extended public key in the above example is the same as the MPC root extended public key you’ve saved in step 2 during the “Pre-Preparation” stage
The address.csv file will be automatically imported; the system will then generate the recovery/address-recovery-<time>.csv file based on the HD paths in the address.csv file (e.g. recovery/address-recovery-20230116-225417.csv in the example above)

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.

PreviousSoft Key Recovery NextThird Party Key Recovery

Last updated 5 months ago