Provide detailed instructions for recovery-CLI

[RowboTony]

Hello, requesting documentation improvement and clarity for laypersons to recover/combine their vaults to a seed phrase.

I tried using the Web Recovery UI without success (#27). I also tried the CLI recovery without success.

The docs page: https://docs.vultisig.com/threshold-signature-scheme/emergency-recovery#option-2-cli-version says:

Follow the instructions displayed in the terminal to proceed with the recovery process.

The only output I saw was general esoteric help usage.

[local-pc]-(/mnt/d/vultisig-EMT/mobile-tss-lib/cmd/cli)-[git://main ✔]-
└> go run main.go
NAME:
   tss-test - tss-test is a tool for testing tss library.

USAGE:
   tss-test [global options] command [command options]

COMMANDS:
   keygen
   reshare
   signECDSA
   signEDDSA
   help, h    Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --server value, -s value                                 server address (default: "http://127.0.0.1:9090")
   --key value, -k value                                    something to uniquely identify local party
   --parties value, -p value [ --parties value, -p value ]  comma separated list of party keys, need to have all the keys of the keygen committee
   --session value                                          current communication session
   --leader                                                 leader will make sure all parties present , and kick off the process(keygen/reshare/keysign) (default: false)
   --help, -h                                               show help
panic: Required flags "key, parties, session" not set

goroutine 1 [running]:
main.main()
        /mnt/d/vultisig-EMT/mobile-tss-lib/cmd/cli/main.go:166 +0xe59
exit status 2

I was expecting a prompt to walk me through such as; "please add file1, please add file2", or "path to .vult shares" etc.

VultiSig is a giant leap forward in secure self-custody. I'm excited to use and improve it, but I'll sleep better at night knowing the "in case of emergency" backup actually works for real humans, such as my family in the case of my untimely demise 😕.

Thank you! --Tony

[Mansarde]

I tried this myself a while ago, and this is how it works:

1. Go into mobile-tss-lib/cmd/recovery-cli (not cli)
2. go run main.go recover --files <VULT-SHARE 1> --files <VULT-SHARE 2>

The --files makes it seem as if you can add multiple files after only this one flag, but you actually have to provide the flag per file.

Also, it could be that in the current state the execution might error because of some coins not working. I haven't looked into it closely yet, but you can just manually remove those coins from the main.go file and try again. To do that, look for the getKeys function and then inside that look for supportedCoins. It will show a list of coins, a block of name, derivePath and action for each. Remove the one for which the error occurs and rerun the command.

If you successfully removed the erroneous ones, you will get an output of the public and private keys. The first private key will be the one for the vault itself from which all other keys are derived. After that you'll see the private keys for the individual coins.

[RowboTony]

Thank you for the detailed response. I tried as suggested, on non-password protected .vult files within the run directory, and recevied the following errors:

┌[wintel]-(/mnt/d/vultisig-EMT/mobile-tss-lib/cmd/recovery-cli)-[git://main ✗]-
└> go run main.go recover \                                                                                             
> --files toSeedTwo2-f5b2-part2of3.vult\
> --files toSeedTwo2-f5b2-part3of3.vult\
> --files toSeedTwo2-windows-988-2of3.vult
# command-line-arguments
./main.go:297:17: undefined: showBitcoinCashKey
./main.go:302:17: undefined: showLitecoinKey
./main.go:307:17: undefined: showDogecoinKey

I removed the lines of coins with errors as suggested, and recevied further errors:

┌[wintel]-(/mnt/d/vultisig-EMT/mobile-tss-lib/cmd/recovery-cli)-[git://main ✗]-
└> go run main.go recover \
--files toSeedTwo2-f5b2-part2of3.vult\
--files toSeedTwo2-f5b2-part3of3.vult\
--files toSeedTwo2-windows-988-2of3.vult
panic: runtime error: slice bounds out of range [:1] with capacity 0

goroutine 1 [running]:
main.getKeys(0x1, {0xc000012240, 0x0, 0xf259d77700000000?}, 0x0)
        /mnt/d/vultisig-EMT/mobile-tss-lib/cmd/recovery-cli/main.go:263 +0xe85
main.recoverAction(0xc000149280)
        /mnt/d/vultisig-EMT/mobile-tss-lib/cmd/recovery-cli/main.go:232 +0x553
github.com/urfave/cli/v2.(*Command).Run(0xc0004466e0, 0xc000149280, {0xc0003da1e0, 0x5, 0x5})
        /home/tgroff/go/pkg/mod/github.com/urfave/cli/v2@v2.27.1/command.go:279 +0x7e2
github.com/urfave/cli/v2.(*Command).Run(0xc0004469a0, 0xc000149140, {0xc00014a120, 0x6, 0x6})
        /home/tgroff/go/pkg/mod/github.com/urfave/cli/v2@v2.27.1/command.go:272 +0xa65
github.com/urfave/cli/v2.(*App).RunContext(0xc0000caa00, {0x13d36e8, 0x1ce8360}, {0xc00014a120, 0x6, 0x6})
        /home/tgroff/go/pkg/mod/github.com/urfave/cli/v2@v2.27.1/app.go:337 +0x58b
github.com/urfave/cli/v2.(*App).Run(...)
        /home/tgroff/go/pkg/mod/github.com/urfave/cli/v2@v2.27.1/app.go:311
main.main()
        /mnt/d/vultisig-EMT/mobile-tss-lib/cmd/recovery-cli/main.go:68 +0x29b
exit status 2

Thanks again, but this seems to have a bit further to go in order to be normie friendly.

Thank you, --Tony

[RowboTony]

I was experimenting, and was able to perform the following with success! So it does appear to work properly when exetued with *.vult wildcard: go run main.go recover --files *.vult!

┌[wintel]-(/mnt/d/vultisig-EMT/mobile-tss-lib/cmd/recovery-cli)-[git://main ✗]-
└> go run main.go recover --files *.vult
hex encoded root pubkey(ECDSA):xxxxxXXXXXXxxxxxxxETC
hex encoded root privkey(ECDSA):xxxxxXXXXXXxxxxxxxETC
chaincode: xxxxxXXXXXXxxxxxxxETC
extended private key full: xxxxxXXXXXXxxxxxxxETC
Recovering bitcoin key....
private key for  bitcoin : xxxxxXXXXXXxxxxxxxETC
non-hardened extended private key for bitcoin: xxxxxXXXXXXxxxxxxxETC
hex encoded non-hardened public key for bitcoin: xxxxxXXXXXXxxxxxxxETC
...snip...
...etc...

For now, I tested this on an empty throw-away Vault with apparent success, though I didn't try a password protectded .vult file. I'm getting there, but I had some Solana assets in another test Vault, which the recovery-cli doesn't support SOL yet. Hopefully soon I can test it with some real Bitcoin or low-gas ETH assets.

I created a request clarifying some documentation.

https://github.com/vultisig/docs/pull/46

Thanks! --Tony

...update....upon further testing I'm not sure how this really works. I deleted 2 of the 3 .vult files, and it doesn't matter if I run the command with all three, or any combination of two, or even each individual .vult file, the output provides the same key. So, are all files not neccessary for creating/recovering/combining to a private key? Did the very first run of command combine this as the documentatoin states:

Before the user does this, the private key never existed. This is a one-way function; once the private key is created, the vault is no longer a TSS vault, but a single-signature wallet.

So that each subsequent time I run the command on any of the .vult files it shows the single-sig key that was created? I ran this on the single jp-honeypot.vult backup, and it gave me some keys, but loading the keys to a wallet showed zero balance, so is this just generating a new empty single-sig wallet? Apparently I have more documentation to find and read to understand this. 👀. Thanks to anyone who reads this. --Tony

[Mansarde]

Oh nice, I never tried with wildcard, but that's good to know, thx! When you try it with password encrypted shares, then it should ask you for one password after another (i.e. per file).

When I first tried it with only one flag and all the files afterwards, it only asked for the password of the first file and calculated keys based on the first share. So if you pass multiple files with a wildcard, make sure it's asking you for a password for every file and then compare the addresses it outputs with the ones the vault shows within the Vultisig app. Just to be safe.

[SxMShaDoW]

I commented on your other post but feel free to try it from this repo:

https://github.com/SxMShaDoW/Vultisig-Share-Decoder/

I put some instructions on it as well and a share of backups that generate the private keys you can test with

[RowboTony]

I've been experimenting more with this, with my new understanding - all .vult shares will show output of keys and addresses. The *wildcard `.vult, while initially appearing to work, didn't actually decode all shares to a recoverable key.** It is required to add--files` for each .vult share. (see the detailed explanation of .vult shares in this thread - https://github.com/vultisig/mobile-tss-lib/issues/27#issuecomment-2455883467)

[Mansarde]

That's what I initially noticed when using multiple filenames for one --files flag and after looking at the code I thought that you had to use a flag for each file. But when you mentioned the wildcard working with just one flag I never verified that. My bad. 😅

So thanks for clearing things up, good to know! At least this way the use of the flag is consistent.

[SxMShaDoW]

@RowboTony - maybe edit your original comment so people won't be confused when they come to find this thread.