Python client

note

We are currently updating this documentation. While it offers a general overview, some details may be outdated. Please check back soon for the latest version. For the most up-to-date information, refer to the postchain-client-py repository.

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

1. Clone the repository:

   git clone git@bitbucket.org:chromawallet/postchain-client-py.git
   cd postchain-client-py

2. Install the package and its dependencies:

   pip install -e .

3. For development (includes testing tools):

   pip install -e ".[dev]"

Configuration

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

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:

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:

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

Querying the Blockchain

Here’s an example of querying the blockchain:

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

Creating and Sending Transactions

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

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:

   pip install -e ".[dev]"

2. Run tests:

   pytest tests/