Developer Documentation Portal

GDK Command Line Example

Suggest Edits

Using the green-liquid-cli command line interface with Blockstream AMP assets

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.

Configuring and installing green-cli

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:

cd green-cli

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:

source venv/bin/activate

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

Wallet creation

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.

📘

Note

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 --expert flag 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 mnemonic in $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.

Using a PIN to login

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.

📘

Note

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.

📘

Note

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.

Getting a new address and understanding pointers

To get a new address that can receive Blockstream AMP assets we must also specify the relevant sub account.

📘

Note

Use green-liquid-cli --network liquid getsubaccounts to check what pointer value to use if you are unsure. It is not guaranteed to always be 1 which 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.

{  
  "address": "VJLENssvSNHH2sG3h18CSWSws43Wvt2XKkqkJrYB62nwhp88EbconWAxeJr6TUacYunssqrvYbCRcVwV",  
  "address_type": "p2wsh",  
  "blinding_script_hash": "a914dff5c10aa2db1bf15df3860fd203b33aa65bd70d87",  
  "branch": 1,  
  "pointer": 33,  
  "script": "522103cc8c8849064d824f21edfb2e5111f2a816c0acd63a3c0ca753fef4594fea5f432103685bb2c3859d3c057030a74b4dda3a09f09cf33fcb57ae8bbcd7a49c67591dff52ae",  
  "script_type": 14,  
  "subaccount": 1,  
  "subtype": null  
}

📘

Note

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.

Checking asset balances

green-liquid-cli --network liquid getbalance --subaccount 1

An example of the returned balance data is shown below.

{  
  "btc": 0,  
  "f266a3f15e78b71481adfedff9aefe47c69501a181ffc68527bb5fb26da6a4b2": 5  
}

Enabling and using Two Factor Authentication (2FA)

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

Sending assets and checking inbound and outbound transactions

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

📘

Note

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.

Viewing new blocks and other network events

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.

Changing wallet settings

To change wallet settings, first get the settings json:

green-liquid-cli --network liquid getsettings

An example of the settings returned:

{  
  "altimeout": 5,  
  "nlocktime": 12960,  
  "notifications": {  
    "email_incoming": false,  
    "email_outgoing": false  
  },  
  "pricing": {  
    "currency": "USD",  
    "exchange": "BITSTAMP"  
  },  
  "required_num_blocks": 12,  
  "sound": true,  
  "unit": "BTC"  
}

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

Other things to consider

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 over 1 year ago