Recover coins from GreenAddress wallets
Build status:
For more information on the GreenAddress service, subaccount types and recovery, please read the GreenAddress FAQ
$ sudo apt-get update -qq
$ sudo apt-get install python3-pip python3-dev build-essential python3-virtualenv -yqq
$ virtualenv -p python3 venv
$ source venv/bin/activate
$ pip install --require-hashes -r tools/requirements.txt
$ pip install .
The GreenAddress Recovery Tool allows you to recover coins from your GreenAddress account(s) if you cannot use the normal mechanisms for making payments. This could be due to one of the following scenarios:
- You lose access to your two factor authentication (2FA) mechanism
- The GreenAddress service becomes unavailable
There are two recovery scenarios depending on whether the coins are in a GreenAddress 2of2 or a 2of3 subaccount. If you have an nlocktimes.zip recovery file that was emailed to you by the service, then the 2of2 proceedure should be followed.
The recovery tool supports recovering from both types of subaccounts.
Coins received into your Blockstream Green wallet after January 25 2021 are
recoverable after a configurable period without the Green server and without
requiring an nlocktimes.zip file. The default 2FA expiry period is 360 days and
can be changed in your wallet settings. To recover these coins refer to the
CSV (Check Sequence Verify)
section.
All funds received in 2of2 accounts prior to January 25 2021 need to be signed
by both you and Blockstream Green (also known with the previous name Greenaddress).
In order to recover such older coins you need to have nLocktime emails enabled in
your settings. The service automatically generates special "nLockTime" transactions,
pre-signed by Blockstream Green but not spendable until some time in the future (the
nLockTime). To recover these coins, refer to the nLocktime
section.
Note that, in some cases, it may be needed to follow both procedures to recover all coins.
To recover coins from a 2of2 account you simply wait until each nLockTime transaction becomes spendable (90 days by default), then countersign using the recovery tool and broadcast. The coins are sent to a key derived from your login mnemonics which you can then sweep into any wallet.
You will need:
- The latest nlocktimes.zip file sent to your email address from GreenAddress
- Your GreenAddress mnemonic
- The recovery tool
To run the recovery tool in 2of2 mode:
$ garecovery-cli 2of2 --nlocktime-file /path/to/downloaded/nlocktimes.zip -o garecovery.csv
Enter your mnemonic when prompted. The recovery tool will print a summary of the
recovery transactions and also write them to a file garecovery.csv.
WARNING
garecovery.csv contains the private keys to which the coins will
be sent. Be sure to perform the recovery on a device you trust and take care
to delete the recovery csv file securely when you are finished with it.
A sample of the printed summary output is:
mnemonic: <your mnemonic here...>
tx id lock time total out destination address coin value
--------- --------- -------------- ---------------------------------- --------------
7a00ab... 1139186 830673.85 bits 19G11T26M6xYwbq5UpJPtGrXbsdQyzpCsx 830673.85 bits
total value = 830673.85 bits in 1 utxo
Here you can see the file contains a transaction worth 830673.85 bits, with locktime = 1139186. The locktime indicates the block number that the bitcoin blockchain must reach before the coins are available for recovery. You can find the current block number (also known as the block height) using your local full node or many available online tools, for example https://blockstream.info
Once the transactions are spendable they can be broadcast onto the network. The raw transactions are in the csv file, along with the private key for the address they send their coins to. You can broadcast these raw transactions using your full node via RPC or online tools such as:
https://blockstream.info/tx/push https://www.smartbit.com.au/txs/pushtx
Unspent coins locked by CSV scripts (OP_CHECK_SEQUENCE_VERIFY, not to be
confused with the file extension .csv) in 2of2 subaccounts are discoverable
by scanning the blockchain to look for them. The recovery tool connects to your
Bitcoin Core full node in order to perform this scanning for you when
recovering.
You will need:
- A Bitcoin Core full node configured for local RPC access; the node wallet functionality must not be disabled, indeed the coins will be sent to addresses owned obtained from the node.
- The recovery tool
- Your Blockstream Green/GreenAddress mnemonic
To run the recovery tool in 2of2-csv mode:
$ garecovery-cli 2of2-csv -o garecovery.csv
Enter your mnemonic when prompted. The recovery tool will print a summary of the
recovery transactions and also write them to a file garecovery.csv.
If any recoverable coins were found the tool will display a summary of them on the console and write the details to the output csv file ready for broadcasting using the same steps as detailed above for 2of2 nLocktime.
Note for 0.17 users: it is now possible to specify --ignore-mempool,
which makes the procedure much faster (by using scantxoutset).
However, as the flag suggests, it does not consider the transactions
that are still in the mempool.
In the case of 2of3 subaccounts you hold the mnemonics for 2 keys: the default key used for day to day spending and a backup key used for recovery. Coins held in a 2of3 account can be spent either by signing with your default key and the GreenAddress key under normal circumstances, or by signing with both your default and backup keys for recovery.
Unlike 2of2 where GreenAddress sends nLocktime transactions to you for recovery, unspent coins in 2of3 subaccounts are only discoverable by scanning the blockchain to look for them. The recovery tool connects to your bitcoin core full node in order to perform this scanning for you when recovering.
You will need:
- A bitcoin core full node configured for local RPC access
- The recovery tool
- Your GreenAddress mnemonic
- The GreenAddress mnemonic for your 2of3 account
- The GreenAddress extended public key (xpub) for your 2of3 account
- A destination bitcoin address to send the recovered coins to
Setting up and running a bitcoin node is beyond the scope of this document but instructions are readily available online. Ensure your node is running, fully synced and you are able to connect to the RPC interface. You can verify this using a command like:
/path/to/bitcoin-core/bin/bitcoin-cli getblockchaininfo
Also note that wallet functionality must not be disabled on your node.
Run the recovery tool in 2of3 mode:
$ garecovery-cli 2of3 --destination-address=XXXX -o garecovery.csv --ga-xpub=YYYY
The tool will prompt you for your mnemonic, recovery mnemonic and xpub. You should have noted these details down when you created the 2of3 subaccount.
The tool will then connect to your node to scan for the 2of3 transactions. This may take quite a long time. You can check the scan progress either by looking in the bitcoind log file or in the bitcoin GUI.
If any recoverable coins were found the tool will display a summary of them on the console and write the details to the output csv file ready for broadcasting using the same steps as detailed above for 2of2 subaccounts.
In the case of Liquid subaccounts the outputs are locked by CSV (OP_CHECK_SEQUENCE_VERIFY) scripts. Which means that coins can be spent either by signing with your default key and the Green/GreenAddress key under normal circumstances, or by signing with your default key only after a certain amount of blocks.
Unspent coins in Liquid subaccounts are only discoverable by scanning the blockchain to look for them. The recovery tool connects to your Liquid/Elements core full node in order to perform this scanning for you when recovering.
You will need:
- A Liquid/Elements core full node configured for local RPC access
- The recovery tool
- Your Green/GreenAddress Liquid mnemonic
Instructions to run a Liquid node can be found here. Ensure your node is running, fully synced and you are able to connect to the RPC interface. You can verify this using a command like:
$ /path/to/elements-core/bin/elements-cli getblockchaininfo
Run the recovery tool in CSV mode:
$ garecovery-liquid-cli csv --network=liquid
The tool will prompt you for your mnemonic.
Unlike 2of3, wallet functionality must be available on your node. Indeed the tool will create transactions sending the recovered funds to addresses obtained from the node.
If you find any bugs, or have suggestions or patches, please raise them on the garecovery github project.