pccontext

PyCardano Chain Contexts

This library contains the various Chain Contexts to use with the PyCardano library as well as a few helper functions for working with and building certain types of transactions.

Documentation

Full documentation is at https://pccontext.readthedocs.io. It covers how each chain context is configured, the staking and governance transaction helpers, a full API reference, and — if you are coming from PyCardano's built-in chain contexts — a page on what differs between them.

To build it locally:

poetry install --with docs
make docs

Chain Context Usage

The library supports multiple blockchain data providers and local node interfaces. Choose the appropriate chain context based on your setup and requirements.

Blockfrost

from pccontext import BlockFrostChainContext, Network

chain_context = BlockFrostChainContext(
    project_id="your_project_id",
    network=Network.MAINNET,
)

Cardano-CLI

from pccontext import CardanoCliChainContext, Network
from pathlib import Path

chain_context = CardanoCliChainContext(
    binary=Path("cardano-cli"),
    socket=Path("node.socket"),
    config_file=Path("config.json"),
    network=Network.MAINNET,
)

Koios

from pccontext import KoiosChainContext

chain_context = KoiosChainContext(api_key="api_key")

Ogmios

from pccontext import OgmiosChainContext

chain_context = OgmiosChainContext(host="localhost", port=1337)

Kupo

from pccontext import OgmiosChainContext, KupoChainContextExtension

ogmios_chain_context = OgmiosChainContext(host="localhost", port=1337)
chain_context = KupoChainContextExtension(wrapped_backend=ogmios_chain_context)

Offline Transfer File

from pathlib import Path
from pccontext import OfflineTransferFileContext

chain_context = OfflineTransferFileContext(offline_transfer_file=Path("offline-transfer.json"))

Yaci Devkit

from pccontext import YaciDevkitChainContext

chain_context = YaciDevkitChainContext(api_url="http://localhost:8080")

Transactions Usage

The library provides various transaction helper functions for common Cardano operations. All transaction functions can optionally sign the transaction if signing keys are provided.

Common Setup for Transaction Examples

from pycardano import (
    Address,
    DRepKind,
    StakeSigningKey,
    StakeVerificationKey,
    PaymentSigningKey,
    PaymentVerificationKey,
)

from pccontext import BlockFrostChainContext, Network
import os

# Setup chain context
network = Network.PREPROD
blockfrost_api_key = os.getenv("BLOCKFROST_API_KEY_PREPROD")
chain_context = BlockFrostChainContext(
    project_id=blockfrost_api_key, network=network
)

# Generate keys
payment_signing_key = PaymentSigningKey.generate()
payment_verification_key = PaymentVerificationKey.from_signing_key(
    payment_signing_key
)

stake_signing_key = StakeSigningKey.generate()
stake_verification_key = StakeVerificationKey.from_signing_key(stake_signing_key)

address = Address(
    payment_part=payment_verification_key.hash(),
    staking_part=stake_verification_key.hash(),
    network=network.get_network(),
)

Transaction Assembly and Signing Utilities

assemble_transaction

from pccontext.transactions import assemble_transaction
from pycardano import Transaction, VerificationKeyWitness

# Create an unsigned transaction (example using stake registration)
from pccontext.transactions import stake_address_registration

unsigned_transaction = stake_address_registration(
    context=chain_context,
    stake_vkey=stake_verification_key,
    send_from_addr=address,
    signing_keys=None  # Don't sign yet
)

# Create verification key witnesses manually
verification_key_witnesses = [
    VerificationKeyWitness(
        vkey=payment_verification_key,
        signature=payment_signing_key.sign(unsigned_transaction.transaction_body.hash())
    ),
    VerificationKeyWitness(
        vkey=stake_verification_key,
        signature=stake_signing_key.sign(unsigned_transaction.transaction_body.hash())
    )
]

# Assemble a transaction with witnesses
assembled_tx = assemble_transaction(
    transaction=unsigned_transaction,
    vkey_witnesses=verification_key_witnesses
)

sign_transaction

from pccontext.transactions import sign_transaction, stake_address_registration

# Create an unsigned transaction
unsigned_transaction = stake_address_registration(
    context=chain_context,
    stake_vkey=stake_verification_key,
    send_from_addr=address,
    signing_keys=None  # Don't sign yet
)

# Sign a transaction with provided keys
signed_tx = sign_transaction(
    transaction=unsigned_transaction,
    keys=[payment_signing_key, stake_signing_key],
)

witness

from pccontext.transactions import witness, stake_address_registration

# Create an unsigned transaction
transaction = stake_address_registration(
    context=chain_context,
    stake_vkey=stake_verification_key,
    send_from_addr=address,
    signing_keys=None  # Don't sign yet
)

# Generate verification key witnesses for a transaction
witnesses = witness(
    transaction=transaction,
    keys=[payment_signing_key, stake_signing_key],
)

Stake Address Registration

from pccontext.transactions import stake_address_registration

# Register a stake address
signed_stake_address_registration_tx = stake_address_registration(
    context=chain_context,
    stake_vkey=stake_verification_key,
    send_from_addr=address,
    signing_keys=[payment_signing_key, stake_signing_key],
)

print(f"Transaction ID: {signed_stake_address_registration_tx.id}")
chain_context.submit_tx(signed_stake_address_registration_tx)

Stake Address Deregistration

from pccontext.transactions import stake_address_deregistration

# Deregister a stake address
signed_stake_address_deregistration_tx = stake_address_deregistration(
    context=chain_context,
    stake_vkey=stake_verification_key,
    send_from_addr=address,
    signing_keys=[payment_signing_key, stake_signing_key],
)

print(f"Transaction ID: {signed_stake_address_deregistration_tx.id}")
chain_context.submit_tx(signed_stake_address_deregistration_tx)

Stake Delegation

from pccontext.transactions import stake_delegation

# Delegate stake to a pool (requires already registered stake address)
pool_id = "abcd1234567890abcdef1234567890abcdef123456789012345678901234"

signed_stake_delegation_tx = stake_delegation(
    context=chain_context,
    stake_vkey=stake_verification_key,
    pool_id=pool_id,
    send_from_addr=address,
    signing_keys=[payment_signing_key, stake_signing_key],
)

print(f"Transaction ID: {signed_stake_delegation_tx.id}")
chain_context.submit_tx(signed_stake_delegation_tx)

Stake Address Registration and Delegation

from pccontext.transactions import stake_address_registration_and_delegation

# Register stake address and delegate in one transaction
pool_id = "abcd1234567890abcdef1234567890abcdef123456789012345678901234"

signed_registration_and_delegation_tx = stake_address_registration_and_delegation(
    context=chain_context,
    stake_vkey=stake_verification_key,
    pool_id=pool_id,
    send_from_addr=address,
    signing_keys=[payment_signing_key, stake_signing_key],
)

print(f"Transaction ID: {signed_registration_and_delegation_tx.id}")
chain_context.submit_tx(signed_registration_and_delegation_tx)

Vote Delegation

from pccontext.transactions import vote_delegation
from pycardano import DRepKind

# Delegate voting power to a DRep
drep_id = "drep1abcd1234567890abcdef1234567890abcdef123456789012345678"

signed_vote_delegation_tx = vote_delegation(
    context=chain_context,
    stake_vkey=stake_verification_key,
    send_from_addr=address,
    drep_kind=DRepKind.KEY_HASH,
    drep_id=drep_id,
    signing_keys=[payment_signing_key, stake_signing_key],
)

print(f"Transaction ID: {signed_vote_delegation_tx.id}")
chain_context.submit_tx(signed_vote_delegation_tx)

# Delegate to "Always Abstain"
signed_vote_abstain_tx = vote_delegation(
    context=chain_context,
    stake_vkey=stake_verification_key,
    send_from_addr=address,
    drep_kind=DRepKind.ALWAYS_ABSTAIN,
    drep_id=None,
    signing_keys=[payment_signing_key, stake_signing_key],
)

# Delegate to "Always No Confidence"
signed_vote_no_confidence_tx = vote_delegation(
    context=chain_context,
    stake_vkey=stake_verification_key,
    send_from_addr=address,
    drep_kind=DRepKind.ALWAYS_NO_CONFIDENCE,
    drep_id=None,
    signing_keys=[payment_signing_key, stake_signing_key],
)

Stake Address Registration and Vote Delegation

from pccontext.transactions import stake_address_registration_and_vote_delegation
from pycardano import DRepKind

# Register stake address and delegate voting power in one transaction
drep_id = "drep1abcd1234567890abcdef1234567890abcdef123456789012345678"

signed_registration_and_vote_delegation_tx = stake_address_registration_and_vote_delegation(
    context=chain_context,
    stake_vkey=stake_verification_key,
    send_from_addr=address,
    drep_kind=DRepKind.KEY_HASH,
    drep_id=drep_id,
    signing_keys=[payment_signing_key, stake_signing_key],
)

print(f"Transaction ID: {signed_registration_and_vote_delegation_tx.id}")
chain_context.submit_tx(signed_registration_and_vote_delegation_tx)

Stake and Vote Delegation

from pccontext.transactions import stake_and_vote_delegation
from pycardano import DRepKind

# Delegate both stake and voting power (requires already registered stake address)
pool_id = "abcd1234567890abcdef1234567890abcdef123456789012345678901234"
drep_id = "drep1abcd1234567890abcdef1234567890abcdef123456789012345678"

signed_stake_and_vote_delegation_tx = stake_and_vote_delegation(
    context=chain_context,
    stake_vkey=stake_verification_key,
    pool_id=pool_id,
    send_from_addr=address,
    drep_kind=DRepKind.KEY_HASH,
    drep_id=drep_id,
    signing_keys=[payment_signing_key, stake_signing_key],
)

print(f"Transaction ID: {signed_stake_and_vote_delegation_tx.id}")
chain_context.submit_tx(signed_stake_and_vote_delegation_tx)

Stake Address Registration, Delegation and Vote Delegation

from pccontext.transactions import stake_address_registration_delegation_and_vote_delegation
from pycardano import DRepKind

# Register stake address, delegate to pool, and delegate voting power in one transaction
pool_id = "abcd1234567890abcdef1234567890abcdef123456789012345678901234"
drep_id = "drep1abcd1234567890abcdef1234567890abcdef123456789012345678"

signed_full_registration_tx = stake_address_registration_delegation_and_vote_delegation(
    context=chain_context,
    stake_vkey=stake_verification_key,
    pool_id=pool_id,
    send_from_addr=address,
    drep_kind=DRepKind.KEY_HASH,
    drep_id=drep_id,
    signing_keys=[payment_signing_key, stake_signing_key],
)

print(f"Transaction ID: {signed_full_registration_tx.id}")
chain_context.submit_tx(signed_full_registration_tx)

Withdraw Rewards

from pccontext.transactions import withdraw_rewards

# Withdraw rewards from a stake address
signed_withdraw_rewards_tx = withdraw_rewards(
    context=chain_context,
    stake_vkey=stake_verification_key,
    send_from_addr=address,
    signing_keys=[payment_signing_key, stake_signing_key],
)

print(f"Transaction ID: {signed_withdraw_rewards_tx.id}")
chain_context.submit_tx(signed_withdraw_rewards_tx)

Notes

All transaction functions return a Transaction object
When signing_keys are provided, the transaction is automatically signed
When signing_keys are not provided, you get an unsigned transaction that needs to be signed separately
Pool IDs should be provided as hex strings without the "pool" prefix
DRep IDs should be provided as hex strings or you can use the special DRep kinds (ALWAYS_ABSTAIN, ALWAYS_NO_CONFIDENCE)

Metadata

Release files for pccontext 0.8.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pccontext 0.8.1
File	Size	Uploaded
pccontext-0.8.1.tar.gz	109.8 kB	Sep 13, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pccontext 0.8.1
File	Interpreter	ABI	Platform	Reset
pccontext-0.8.1-py3-none-any.whl 135.5 kB Sep 13, 2026	Python 3	none	any	Details

Total release size: 245.3 kB

Release files / pccontext-0.8.1.tar.gz

Download URL	pccontext-0.8.1.tar.gz
Size	109.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`844f2f6aeaf4609897ee1a33ead957828b33a50d6d4dc7ef9158649b28448991`
BLAKE2b-256 checksum How to use checksums	`fae71c1186359100a9a831399b03e0cce9e35aa88a1cefd966e1648ca0ab2139`
Upload date	Sep 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.1.3 CPython/3.10.10 Darwin/25.6.0`

Release files / pccontext-0.8.1-py3-none-any.whl

Download URL	pccontext-0.8.1-py3-none-any.whl
Size	135.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`3b418559a4132bee62d1b812553d1cf9e8071d620d1e48f1d024362baf13739c`
BLAKE2b-256 checksum How to use checksums	`281491190719c50c88c83561c5d671b20bbf877d38a6b7fd423ecee621db9507`
Upload date	Sep 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.1.3 CPython/3.10.10 Darwin/25.6.0`