Skip to main content

Python Client for interacting with a CasperLabs Node

Project description

CasperLabs Python Client API library and command line tool

casperlabs-client is a Python package consisting of

  • a client library casperlabs_client that can be used to interact with a CasperLabs node via its gRPC API and
  • a command line interface (CLI) script with the same name: casperlabs_client.

Note, the name of the package available on PyPi is casperlabs-client (with hyphen), but the name of the library as well as the CLI is written with underscore: casperlabs_client. The name of the CLI is written with underscore to make it different from the Scala client, which is written with hyphen.


casperlabs-client is a Python 3.6+ module, it does not support Python 2.7.


You can install the casperlabs_client package with

pip3 install casperlabs-client

or, if you have only Python 3 installed (Python 3 installed as python, rather than python3):

pip install casperlabs-client

Mac OS X

Install Python 3 with brew:

Next, type the following commands in the Terminal:

brew update
brew upgrade
pip install casperlabs-client

Windows 10

To install casperlabs-client on Windows 10 you need to install latest Python 3.7, it is curently not possible to install it on Python 3.8 due to

It is recommended to install Python from the website:

If you install Python from the Windows Store you will need to manually add the Scripts folder of your Python installation to your Path in order to have the casperlabs_client command line tool available on the command line without providing full path to it. This will be located in a path similar to this:


You also need to install free Microsoft Visual Studio C++ 14.0. Get it with "Build Tools for Visual Studio 2019": (All downloads -> Tools for Visual Studio 2019 -> Build tools for Visual Studio 2019). This is required by the pyblake2 extension module.

After installing the above prerequisites you can install the casperlabs-client package by typing the following on the command line:

C:\Users\alice>pip install casperlabs-client

Getting started

After installing casperlabs-client you can start interacting with CasperLabs devnet.

import casperlabs_client
client = casperlabs_client.CasperLabsClient('', 40401)
blockInfo = next(client.showBlocks(1, full_view=False))
for bond in blockInfo.summary.header.state.bonds:
    print(f'{bond.validator_public_key.hex()}: {bond.stake.value}')

When executed the script should print a list of bonded validators' public keys and their stake:

89e744783c2d70902a5f2ef78e82e1f44102b5eb08ca6234241d95e50f615a6b: 5000000000
1f66ea6321a48a935f66e97d4f7e60ee2d7fc9ccc62dfbe310f33b4839fc62eb: 8000000000
569b41d574c46390212d698660b5326269ddb0a761d1294258897ac717b4958b: 4000000000
d286526663ca3766c80781543a148c635f2388bfe128981c3e4ac69cea88dc35: 3000000000

Note, you will also see a warning:

WARNING:root:Creating insecure connection to (<class 'casperlabs_client.casper_pb2_grpc.CasperServiceStub'>)

Currently it is possible to connect from client to node without SSL encryption, which is what the above example code does. In the future encryption will become obligatory and you will have to pass a certificate_path to the CasperLabsClient constructor. The warning about insecure connection is meant to remind about this.

Graph visualization

casperlabs_client has vdag command that can be used to visualize DAG. If you want to use it you need to first install Graphviz, the free graph visuallization software.

For example:

casperlabs_client --host vdag --depth 10 --out dag.png

will produce an image file simillar to the one below:

DAG visualization example

Small boxes represent blocks, labeled with short prefixes of their block hashes. Blocks are aligned in "lanes" representing validators that created them. Bold arrows point to main parents of blocks.

Deploying smart contracts

To deploy a smart contract to CasperLabs devnet you have to first:

  1. Create an account using CasperLabs Explorer and transfer (free) tokens to the account from the faucet.

    An account address is a public key in hex format such as:

  2. Compile a contract to the WASM format, see CasperLabs contract examples to see example contracts and instructions on how to compile them.

To deploy a compiled contract from your account address:

response = client.deploy(from_addr="f2cbd19d054bd2b2c06ea26714275271663a5e4503d5d059de159c3b60d81ab7",

Return values

Return values of the API functions defined in the CasperLabsClient are generally deserialized gRPC response objects of the corresponding requests defined in the node's gRPC service, see casper.proto.

Response to requests like showBlocks or showDeploys is a stream of objects. Corresponding Python API functions return generator objects:

for block in client.showBlocks(depth=10):
    print (block.blockHash)

Error handling

Some requests' response objects (see their definitions in casper.proto ) have fields indicating success.

InternalError is the only exception that user code can expect to be thrown by the API.

Learn more about CasperLabs blockchain

See Usage of the CasperLabs system.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for casperlabs-client, version 0.7.0
Filename, size File type Python version Upload date Hashes
Filename, size casperlabs_client-0.7.0.tar.gz (878.7 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page