Getting Started with the Hyperledger Fabric Python SDK

How do you go about deploying the tools needed for developing a Hyperledger-based blockchain with Python?

Hyperledger Fabric is one of the most popular blockchain frameworks. It is used by enterprises and medium-sized companies to build data applications on top of a cryptographically secure distributed ledger. In previous articles in this series we have looked at the basics of blockchain and analyzed the fundamentals of how Hyperledger Fabric works. In this article, we will take the next step on how blockchain can be implemented through the use of Fabric's Python SDK.

Python is a popular programming language with a concise syntax that is often used for working with data or building machine-learning models. Because of its place in the data ecosystem and the speed at which it can be used for prototyping, it is often utilized for building block chain systems. We use it here because it is poised to play an important role within Hyperledger Fabric. Hyperledger Fabric also supports SDKs for Node and Java. At the time of this writing (November 2019), the Python Application SDK is under heavy development and is an emerging technology.

In this article we will:

Configure the tools required to deploy a Hyperledger based blockchain
Build a sample network
Install and configure the Fabric Python SDK
Test the resulting endpoints to ensure the network is available

Requirements

The Hyperledger Fabric Python SDK requires a number of components. Prior to the deployment of your network, you will need to download and configure the items below. This tutorial was tested and designed to run on the Ubuntu 18.04 LTS distribution of Linux. Likewise, we assume some prior programming knowledge and proficiency with Python, BASH, and Docker.

cURL

cURL (curl) is a command-line interface (CLI) tool that is vital in testing endpoints. cURL download links for all operating systems can be found here.

Docker

Docker is a tool that allows you to package parts of software into containers that can be deployed nearly anywhere. Docker is available within the Ubuntu 18.04 repositories. For instructions on how to download and install in Ubuntu, see How to install Docker on Ubuntu 18+. For other platforms such as Windows, see the instructions here.

Docker Compose

Docker Compose is a tool that allows for the definition and instantiation of multi-container Docker applications. These applications are defined in a pre-configured source file (Docker compose uses YAML). How to install Docker Compose on Ubuntu 18+. You may find instructions for installation on different operating systems here.

Node.js

Node is one of Fabric's primary runtimes and is often used for production deployments. You can find a download link for Node.js here. A guide for installing via the binary for Linux is available here.

You can install both Node.js and NPM via the command line for Ubuntu by following this guide.

NPM

NPM is the package installer and manager for Node.js. It comes bundled with Node.js and will be automatically installed with Node.js. It's important to ensure that it is installed successfully after installing Node.js with npm -v.

NPM Packages

There are a few modules we need to use for Python SDK from NPM. Note that these modules may only be necessary when running certain tests. These are not needed for just testing endpoints using Python.

gRPC (Remote Procedure Calls) is a protocol where a program may request a service from another program on a separate network. Install gRPC simply with npm install grpc in Bash.
HFC is a client API that we can use to interact with a Fabric network - while it was designed for the Node.js SDK, the Python SDK relies on it as well. Install an updated version with npm install hfc@0.6.x.

Python

To utilize the Python SDK, you need to have a recent version of Python 3 installed. The SDK is not compatible with Python 2. If using Ubuntu 18.04, this will be Python 3.6. For Ubuntu 19.10 or newer, it will be Python 3.7.

You can check your version of Python by running $ python3 --version in Bash.

You will also need to install virtualenv (a module for Python that creates isolated environments into which we can install dependencies and set up testing environments). It can be installed via pip3 (Python3's package installer). virtualenv is also available as an Ubuntu package. You can find additional information about virtualenv here.

libssl, a package for working with SSL, is also required for the SDK. It can be installed from the Ubuntu packages.

# Check for pip (the Python package manager)
$ pip3 --version
$ sudo apt install python3-pip # if not installed

# Check for virtualenv and install
$ pip3 freeze | grep virtualenv
$ pip3 install virtualenv

# Install other required Python components
$ sudo apt-get install python-dev python3-dev libssl-dev

You also need to install the tox package for Python. You can do that by running pip3 install tox or sudo apt install tox. You can wait to do this inside of the virtual environment we will set up if you do not want it on your root system.

Git

Git is the version control system for Hyperledger with which repositories may be downloaded. An installation guide for Git can be found here.

Go Programming Language

Fabric is primarily written in Go and a Go runtime is required for you to install it.

Given that we will be writing chaincode programs in Go, there are two environment variables you will need to set properly. You can make these variables permanent by placing them in the appropriate startup file, such as your personal ~/.bashrc file if you are using the bash shell under Linux.

Example: ~/.bashrc:

...
# GO PATH and System PATH additions required for GO
export GOPATH=$HOME/GO
export PATH=$PATH:$GOPATH/bin

Setting up a Sample Network

The Hyperledger Network is the set of resources where your application will run. Hyperledger includes a sample network packaged as a Docker container (the container image also comes with the rest of the Fabric binaries) and can be used for development

Note: If you've gone through this tutorial before, or would like to start from a clean slate, you may kill any dead containers in Docker with docker rm $(docker ps -a -q), and you can remove any and all images on your system with docker rmi $(docker images -q) -f. It is very important to use it with caution though, as this force removes any images with dependencies.

Configure SDK and Runtime

The network is deployed from the Hyperledger Fabric repository. To begin the tutorial, create a working folder and clone the Hyperledger source code as shown below:

# Create project folder
$ cd $HOME
$ mkdir fabric-tutorial && cd fabric-tutorial

# Clone Fabric source code
$ git clone https://github.com/hyperledger/fabric -b release-1.4

We will be using Fabric version 1.4.

Rather than cloning the source code, you could also download the source code for Fabric from the project's website.

Once the source has been cloned, you will then need to add configtxgen to the $PATH for the environment within your terminal.

$ export PATH="$PATH:~/GO/fabric-tutorial/fabric-sdk-py/fabric-bin/bin/"

configtxgen requires a config file to be set within the variable FABRIC_CFG_PATH. This path needs to be set as the configtx.yaml configuration file within the Python SDK.

$ export FABRIC_CFG_PATH="$HOME/GO/fabric-tutorial/fabric-sdk-py/fabric-bin/bin/"

For development environments, it might be worthwhile to create a postactivate script that can be included in the virtualenv that will be triggered when the environment is activated.

Download and Deploy Docker Images

You are now able to navigate to the sample network folder and install the Docker images for the development network. A shell script that does this for you is included within the sample network folder.

Before you can do that though, you need to run the bootstrap.sh command that comes with Fabric to download the actual sample binaries.

# Bootstrap the environment, download binaries
$ cd fabric
$ sudo ./scripts/bootstrap.sh # download binaries

# Start Fabric
$ cd fabric-samples/fabcar/
$ sudo ./startFabric.sh

This command will download a few images to your system on which we can create a network. If you check with the command docker ps -a, you'll find that you are now running a network of three members/organizations, represented by two peer nodes each and one organization as an orderer node.

With all of this set up, you can then run a shell script that comes with the SDK to ensure that you've configured everything correctly in order to actually be able to use the SDK. This shell script can be run with the command sudo ./scripts/check-env.sh.

Setting up the Fabric Python SDK

Now that we've got the basic requirements covered to run the SDK, you need to actually clone the project itself so that you may start up its network. You'll want to create a new folder/directory where you'd like to store this repository. Navigate to that folder and run the following Git command:

$ cd ~/GO/fabric-tutorial/

$ git clone https://github.com/hyperledger/fabric-sdk-py.git

Next, we'll navigate inside the folder where the repository we've just cloned resides. It should be named fabric-sdk-py.

You will be installing dependencies, testing the SDK, and interacting with our sample network within a virtual environment that we can create using the Python package venv. Most of these commands are managed through the makefile distributed with the SDK. To prevent collisions with other software installed on the system, it's a good idea to create a virtual environment.

# Navigate to the Python Fabric SDK Folder
$ cd fabric-sdk-py

# Create and activate a virtual environment for dependencies
$ python3 -m venv env 
$ source env/bin/activate

With the environment active, we can install the dependencies via make install.

When that completes, we'll want to check our environment to ensure we have everything we need to use the SDK. Hyperledger Fabric includes a handy utility called make check that will ensure we have all of our dependencies installed and run tests for the environment to validate that the toolchain is sane.

# Install all Hyperledger Fabric dependencies
$ sudo make install

# Ensure the environment is sane
$ sudo make check

Once that's complete you should see a message saying that all dependencies have been processed.

Testing Endpoints

The network.json file within test/fixtures/ provides the necessary information to connect and interact with a running fabric network. While it is only a sample, it's enough to let you bootstrap a working networking.

To begin testing endpoints within your network via Python SDK, ensure that you are in the top folder of the SDK and then enter Python in Bash with sudo python3. We can now begin testing the client using our network profile.

>>> from hfc.fabric import Client
>>> cli = Client(net_profile="test/fixtures/network.json")
>>> print(cli.organizations)

Depending on your workstation, running these python commands can cause permission errors. You may need to create a root terminal as a workaround.

# Create root terminal (will need to enter root password)
$ sudo -i

# Navigate to the fabric-sdk folder
/# cd /home/<user>/GO/fabric-tutorial/fabric-sdk-py

# Run python commands
/# python3

>>> from hfc.fabric import Client

>>> cli = Client(net_profile="test/fixtures/network.json")

>>> print(cli.organizations)

In response to this query, you should see three organizations returned, including one orderer.

Example: {'orderer.example.com': <hfc.fabric.organization.Organization object at 0x7f6ac832cac8>, 'org1.example.com': <hfc.fabric.organization.Organization object at 0x7f6acc100978>, 'org2.example.com': <hfc.fabric.organization.Organization object at 0x7f6ac7dde5f8>}

You can then print your peers, orderers, and even CAs within your network with that command, substituting the organizations of course with (print(cli.orderers), print(cli.peers), etc).

Conclusion

In this article, we've shown how to download the required dependencies in order to run a local instance of Fabric Hyperleder for development. We were then able install necessary binaries for the Python SDK and test the endpoints to the nodes running within the local network.

With a running network, the next step is to start writing data to the blockchain and reading data from it.