As an alternative to creating your own code that uses Python to call GDK, you can use an existing tool, such as the the green-cli command line interface for GDK. Written in Python, green-cli wraps many GDK functions and exposes them via the command line. Installing green-cli also enables you to call
green-liquid-cli, its Liquid network counterpart, which is what we’ll be using in this example.
The example covers:
- Installing green-cli.
- Logging in with an existing 24 word mnemonic or generating a new mnemonic.
- Storing the mnemonic to file and using a pin to encrypt the contents.
- Getting a new address and understanding address pointers.
- Checking wallet asset balances.
- Enabling and using Two Factor Authentication (2FA).
- Sending assets and checking inbound and outbound transactions.
- Viewing events in the Green notification queue, such as new blocks.
- Changing the wallet’s configuration.
We’ll be installing green-cli and making calls to green-liquid-cli (green-cli configured to connect to GDK’s Liquid network back end).
First, clone the green-cli repository using a terminal session:
git clone https://github.com/Blockstream/green_cli.git
Move into the newly created directory:
It is recommended that you create a virtual environment within which to install the requirements and green-cli:
virtualenv -p python3 venv
Activate the virtual environment:
Now install the base requirements:
pip install -r requirements.txt
Now you can build and install green-cli (and also green-liquid-cli, which is green-cli running in its Liquid configuration mode):
pip install .
If you make any changes yourself to the green-cli code, remember to run
pip install . afterwards to re-install your updated green-cli.
Optionally, you can enable bash completion in your terminal for green-liquid-cli:
eval "$(\_GREEN_LIQUID_CLI_COMPLETE=source green-liquid-cli)"
With green-liquid-cli installed, you can now start using it from the command line.
To initialize a wallet, you can either have green-liquid-cli generate a 24 word mnemonic for you, or enter one you’ve generated yourself.
Whichever method you use to create the wallet, please be careful to back up the mnemonic as it will be used to recover, and can also be used to access, any funds that the wallet receives. You may also want to use a PIN to encrypt the mnemonic file. The
--expertflag indicates that you understand that the wallet will hold funds on the live Liquid network and that you will manage your wallet mnemonic backup appropriately. Without the flag, the wallet creation call will fail.
To have green-liquid-cli create a Liquid wallet mnemonic for you:
green-liquid-cli --expert --network liquid create
If you would rather use a mnemonic you have generated yourself, you just need to put the mnemonic as plain text within a new file and then call set mnemonic:
green-liquid-cli --network liquid set mnemonic -f $HOME/path_to_file/file_with_mnemonic_in
The format of the 24 word mnemonic is words separated by a single space. E.g.:
small decide absurd fresh lesson valid mushroom [etc...]
Both methods create a new file named
$HOME/.green-cli/liquid which green-liquid-cli will use in subsequent calls to login. You should back up this file and note that the mnemonic is saved within it as plaintext. If you do not call
set mnemonic then each call you make that requires login will prompt you to enter the mnemonic. You may also want to see the use of
setpin later in this guide.
After setting the mnemonic with
set mnemonic, you must then register the wallet with the Green server (this isn’t needed if you called
create instead as it does if for you):
green-liquid-cli --network liquid register
Then we need to create a sub account that works with Blockstream AMP. You can name it whatever you want, we’ve used ‘Managed Assets’ below because it is the same name that Green mobile and desktop use. Account type and name are used to retrieve the correct account and should be unique per wallet.
2of2_no_recovery is the account type used by Blockstream AMP assets, do not change this value.
green-liquid-cli --network liquid createsubaccount 'Managed Assets' 2of2_no_recovery
Checking the sub accounts:
green-liquid-cli --network liquid getsubaccounts
Please note that the subaccount contains a
receiving_id, which is the Green Account ID (GAID) required for user registration with Transfer-Restricted assets.
Note the pointer of the account that you just created. This value is what you need to pass in as the
--subaccount in subsequent calls to the wallet. The account pointer allows GDK to know which account to action requests against. We will use
1 in the rest of the example, but this is not guaranteed to be the value you will need to use, so please check using
green-liquid-cli --network liquid getsubaccounts first.
Instead of storing the mnemonic as plaintext in the
mnemonic file, you can have green-liquid-cli encrypt it by setting a pin:
green-liquid-cli --network liquid setpin 123456 1
In the above example 123456 is the new pin and 1 is the device id.
Setting a pin will delete the locally stored plaintext mnemonic file mnemonic and create a new encrypted file named pin_data, therefore it is advised to ensure you have a back up the mnemonic before calling setpin.
Any subsequent calls to green-liquid-cli will require pin entry. When you login with the pin, the server will pass green-liquid-cli the key to decrypt the mnemonic which it then uses to login.
If the pin is entered incorrectly 3 times the server will delete the key and you must then use the mnemonic to login and set another pin.
To get a new address that can receive Blockstream AMP assets we must also specify the relevant sub account.
green-liquid-cli --network liquid getsubaccountsto check what pointer value to use if you are unsure. It is not guaranteed to always be
1which the examples here use.
green-liquid-cli --network liquid getreceiveaddress --subaccount 1
The above will return a new confidential address, along with other data relating to the address. An example of the returned data is shown below.
Any calls that return transaction data for the wallet (shown later) will return the unconfidential address. For this reason, you must use the address ‘pointer’ returned above to identify the address within transaction data. The pointer plus sub account index maps to a derivation path so you can use pointers within each sub account to link confidential and unconfidential addresses. Be sure to note that you must consider which sub account you are using when using the pointer as an identifier like this.
To test the receiving of a Blockstream AMP asset you can use the Blockstream AMP demo website to receive an amount of the ‘Issuer-Tracked’ Blockstream AMP issued asset. This won’t require any L-BTC in your wallet as the sending wallet will cover the fees. You can then check the balance of your wallet using the following.
green-liquid-cli --network liquid getbalance --subaccount 1
An example of the returned balance data is shown below.
You can check the current 2FA status of the wallet using:
green-liquid-cli --network liquid 2fa getconfig
To enable 2FA (using email in this example):
green-liquid-cli --network liquid 2fa enable email [email protected]
You will be asked for the 2FA code sent to the provided email address. Entering the code activates the 2FA.
You can check 2FA was enabled by getting the 2FA config again:
green-liquid-cli --network liquid 2fa getconfig
If enabled, 2FA will wrap calls that require it, such as
In order to send assets that are not ‘btc’ over the live Liquid network we need to use the
--expert flag. This will let green-cli know that we understand how precision affects issued assets. Please read the following note carefully before using
Please be aware that Blockstream AMP issued assets are issued with a precision that affects how the number of sats sent are converted to the number of units of the asset itself. Please refer to the examples under ‘precision’ on the issuing an asset example. If the asset is registered with the Liquid Assets Registry you can check the precision there, or check with the asset’s issuer, and set the amount appropriately, based on the precision used for the asset.
green-liquid-cli --expert --network liquid sendtoaddress --subaccount 1 VJLCK7n7W3zCs6GpnpjuQd7xEeKPboa8fMmv1d5D6co6GFp5qxR7DoUw8niX9Yya9diQqWnFyYR2yheg f266a3f15e78b71481adfedff9aefe47c69501a181ffc68527bb5fb26da6a4b2 0.00000001
To check transactions (inbound and outbound) for a wallet:
green-liquid-cli --network liquid gettransactions --subaccount 1
Remember that the
getreceiveaddress function used previously returns a confidential address, whereas transaction data contains the unconfidential address and that you can use the address ‘pointer’ returned by both to map the two. See the notes on pointers above for more details.
To get the last Liquid block height, along with other network events from the Blockstream Green server, call:
green-liquid-cli --network liquid listen
This returns network notification events as they occur, such as new blocks. Use
Ctrl+C to quit listening. Calls to listen will always return the last block height initially, then update as new blocks are found.
To change wallet settings, first get the settings json:
green-liquid-cli --network liquid getsettings
An example of the settings returned:
To change settings, save the settings returned above to file, alter the setting you want to change and pass the file path to changesettings:
green-liquid-cli --network liquid changesettings $HOME/.green-cli/liquid/new_settings
Using the above example you can set up a GDK wallet and transact Blockstream AMP assets from the command line.
If you would rather use GDK with Python directly, refer to the Python GDK example instead.
Updated about 1 year ago