GDK Overview and Examples

Liquid Blockstream's Green Development Kit (GDK) is a rapidly evolving, open source Bitcoin and Liquid wallet software solution that allows people to build server, desktop and mobile applications.

GDK allows you to build applications that can interact with our Green server's "2of2" multi-signature shield technology and also create and manage single signature Bitcoin and Liquid wallets. The GDK repository has examples of how to implement solutions on Bitcoin and Liquid using the code base.

See the GDK API documentation for a full list of features available to you.

GDK Liquid example in Python

The GDK Liquid and AMP example shows how to do the following in Python.

  1. Generate a mnemonic or validate and use an existing mnemonic.
  2. Optionally set a PIN to encrypt the sign in data.
  3. Initialize GDK.
  4. Sign into a Green session (production or testnet) using a mnemonic or a PIN that has encrypted the mnemonic.
  5. Enable Two Factor Authentication (2FA) for a wallet.
  6. Perform function calls against GDK such as get balance, get new address, send L-BTC or a Liquid asset, retrieve all transactions related to the wallet.
  7. Receive Liquid network notifications from Green, for example; new block notifications.

Installing GDK

Using the Python wheel release

To install GDK, download the GDK python wheel from https://github.com/Blockstream/gdk/releases.

The cp number refers to the python version you have. So if you are using Linux and have Python 3.9.* installed you would install the relevant GDK .whl using pip.

pip install greenaddress-0.0.57-cp39-cp39-linux_x86_64.whl

Building the Python wheel from source code

You can follow the step-by-step instructions for building the GDK wheel from source on Ubuntu here. The GDK repository has more instructions for other operating systems, such as Mac OS, and other language wrappers.

Initializing GDK

The example uses the Testnet Liquid network. To test it on mainnet, change the following line's value to 'liquid':

NETWORK = 'testnet-liquid'

The example's call to gdk.init only needs to be called once during your code otherwise an exception will be thrown.

Mnemonic and PIN encryption

To create a wallet with an account that works with Blockstream AMP you need to create a Managed Assets account. You can generate a 24 word mnemonic yourself or have GDK generate it for you. You can choose to create a wallet that's covered by 2FA or not. 2FA can be activated or deactivated at any point in time.

To login to an existing wallet you can either use the mnemonic or PIN and then you can perform calls against the session, such as get balance for the logged in Blockstream AMP Managed Assets account.

To use a pin to encrypt the mnemonic you need to set the pin for the wallet, which returns encrypted data that is saved to file. When you login with the pin, the server will give you the key to decrypt the mnemonic which it uses to login. If the pin is entered incorrectly 3 times the server will delete the key and you must use the mnemonic to login.

You can add Two Factor Authentication (2FA) to a wallet when you create it or enable or disable 2FA at a later date.

When you get a new address the address returned will be confidential, whereas GDK returned transactions will show the unconfidential address. For this reason, use the address "pointer" to identify it in transactions. 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 as shown below.

address_info = wallet.get_new_address()  
print(f'Address 1: {address_info["address"]}') 
print(f'Address 1 pointer: {address_info["pointer"]}')

Each call creates a new address/pointer pair for the user.

address_info = wallet.get_new_address()  
print(f'Address 2: {address_info["address"]}') 
print(f'Address 2 pointer: {address_info["pointer"]}')

Sending Liquid assets

Please be aware that 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" for more details and examples.

If the asset is registered with the Liquid Assets Registry you can check the precision using the Blockstream Explorer, or check with the asset's issuer.

Retrieving a list of transactions

When you retrieve a list of transactions from Green using GDK it will return a default number of transactions, which you can override if you want. Note that transactions are returned in the order of most recently seen transaction first. It is possible for a transaction seen less recently to be unconfimred while a more recent transaction is confirmed. You can use the notification queue to get the current block height and derive the confirmation status from that.

Using the notification queue

You can access the Green server's notification queue using GDK to get things like the current block height, new block notifications and the like. These helps your application be dynamic and alert the user to new events affecting their wallet etc.

Developer References

  1. Green Development Kit (GDK) GitHub repository.
    1. Bitcoin use example (in Python).
    2. Liquid & AMP example (in Python).
  2. GDK API Specification.
  3. Green-cli GDK command line interface.
  4. The HTTP GDK API wrapper allows languages that do not have GDK build wrappers (as Python and Java do) to call GDK. This allows any language that can make HTTP API calls (such as JavaScript or Node.js) to use GDK.
  5. GDK has a test network for Liquid and also Bitcoin for developers to experiment on.