Docs
chromia.com

Python client

On this page

A Python client library for interacting with Postchain nodes on Chromia blockchain networks. This library provides an interface for creating, signing, and sending transactions, as well as querying the blockchain, with full async support.

Features

  • Full asynchronous API support using aiohttp.
  • Secure transaction creation and signing.
  • Comprehensive blockchain querying capabilities.

Prerequisites

  • Python 3.7 or higher.
  • A running Postchain node (for actual usage).

Installation

Terminal
pip install postchain-client-py

Configuration

To use the library, you’ll need to set up a .env file in your project root with the following variables:

Text
POSTCHAIN_TEST_NODE=http://localhost:7740
BLOCKCHAIN_TEST_RID=your_blockchain_rid
PRIV_KEY=your_private_key
  • POSTCHAIN_TEST_NODE: The URL of the Postchain node you want to interact with.
  • BLOCKCHAIN_TEST_RID: The unique identifier (RID) of the blockchain you’re connecting to.
  • PRIV_KEY: Your private key in hexadecimal format, used for signing transactions.

Generating a Private Key

If you don’t have a private key, you can generate one using the following Python code:

Python
from coincurve import PrivateKey

private_key = PrivateKey()
print(private_key.to_hex())  # Use this value for PRIV_KEY in your .env file

Quick Start

Here’s a simple example to get started:

Python
import asyncio
from postchain_client_py import BlockchainClient
from postchain_client_py.blockchain_client.types import NetworkSettings

async def main():
    # Initialize network settings
    settings = NetworkSettings(
        node_url_pool=["http://localhost:7740"],
        blockchain_rid="YOUR_BLOCKCHAIN_RID",
    )

    # Create client and execute query
    client = await BlockchainClient.create(settings)
    result = await client.query("get_collections")
    print(f"Collections: {result}")

    # Clean up
    await client.rest_client.close()

if __name__ == "__main__":
    asyncio.run(main())

Queries

Here’s an example of querying the blockchain:

Python
async def query_example(client: BlockchainClient):
    # Simple query without arguments
    books = await client.query("get_all_books")
    print(f"Books: {books}")

    # Query with arguments
    reviews = await client.query(
        "get_all_reviews_for_book",
        {"isbn": "ISBN123"}
    )
    print(f"Reviews: {reviews}")

Transactions

Here’s an example of creating and sending a transaction:

Python
import os
import asyncio
from coincurve import PrivateKey
from postchain_client_py import BlockchainClient
from postchain_client_py.blockchain_client.types import Operation, Transaction

async def transaction_example(client: BlockchainClient):
    # Load private key from environment variable
    private_bytes = bytes.fromhex(os.getenv("PRIV_KEY"))
    private_key = PrivateKey(private_bytes, raw=True)
    public_key = private_key.pubkey.serialize()

    # Create operation
    operation = Operation(
        op_name="create_book",
        args=["ISBN123", "Python Mastery", "Jane Doe"]
    )

    # Build transaction
    transaction = Transaction(
        operations=[operation],
        signers=[public_key],
        signatures=None,
        blockchain_rid=client.config.blockchain_rid
    )

    # Sign and send
    signed_tx = await client.sign_transaction(transaction, private_bytes)
    receipt = await client.send_transaction(signed_tx, do_status_polling=True)

    if receipt.status == "CONFIRMED":
        print("Transaction confirmed!")

Development

Running Tests

  1. Install development dependencies:

    Terminal
    pip install -e ".[dev]"
  2. Run tests:

    Output
    pytest tests/