Skip to main content

Python wrapper for cardano-cli for working with cardano cluster

Project description

README for cardano-clusterlib

Documentation Status PyPi Version Code style: black

Python wrapper for cardano-cli for working with cardano cluster. It supports all cardano-cli commands (except parts of genesis and governance).

The library is used for development of cardano-node system tests.

Installation

# create and activate virtual env
$ python3 -m venv .env
$ . .env/bin/activate
# install cardano-clusterlib from PyPI
$ pip install cardano-clusterlib
# - OR - install cardano-clusterlib in development mode together with dev requirements
$ make install

Usage

The library needs working cardano-cli (the command is available on PATH, cardano-node is running, CARDANO_NODE_SOCKET_PATH is set). In state_dir it expects "shelley/genesis.json".

# instantiate `ClusterLib`
cluster = clusterlib.ClusterLib(state_dir="path/to/cluster/state_dir")

On custom testnets that were started in Byron era, you might need to specify a slots offset between Byron epochs and Shelley epochs. The "slots_offset" is a difference between number of slots in Byron epochs and in the same number of Shelley epochs.

E.g. for a testnet with parameters

  • 100 slots per epoch in Byron era
  • 1000 slots per epoch in Shelley era
  • two epochs in Byron era before forking to Shelley

The offset will be 2 * (1000 - 100) = 1800.

cluster = clusterlib.ClusterLib(state_dir="path/to/cluster/state_dir", slots_offset=1800)

Transfer funds

from cardano_clusterlib import clusterlib

# instantiate `ClusterLib`
cluster = clusterlib.ClusterLib(state_dir="path/to/cluster/state_dir")

src_address = "addr_test1vpst87uzwafqkxumyf446zr2jsyn44cfpu9fe8yqanyuh6glj2hkl"
src_skey_file = "/path/to/skey"

dst_addr = cluster.g_address.gen_payment_addr_and_keys(name="destination_address")
amount_lovelace = 10_000_000  # 10 ADA

# specify where to send funds and amounts to send
txouts = [clusterlib.TxOut(address=dst_addr.address, amount=amount_lovelace)]

# provide keys needed for signing the transaction
tx_files = clusterlib.TxFiles(signing_key_files=[src_skey_file])

# build, sign and submit the transaction
tx_raw_output = cluster.g_transaction.send_tx(
    src_address=src_address,
    tx_name="send_funds",
    txouts=txouts,
    tx_files=tx_files,
)

# check that the funds were received
cluster.g_query.get_utxo(dst_addr.address)

Lock and redeem funds with Plutus script

from cardano_clusterlib import clusterlib

# instantiate `ClusterLib`
cluster = clusterlib.ClusterLib(state_dir="path/to/cluster/state_dir", tx_era="babbage")

# source address - for funding
src_address = "addr_test1vpst87uzwafqkxumyf446zr2jsyn44cfpu9fe8yqanyuh6glj2hkl"
src_skey_file = "/path/to/skey"

# destination address - for redeeming
dst_addr = cluster.g_address.gen_payment_addr_and_keys(name="destination_address")

amount_fund = 10_000_000  # 10 ADA
amount_redeem = 5_000_000  # 5 ADA

# get address of the Plutus script
script_address = cluster.g_address.gen_payment_addr(
    addr_name="script_address", payment_script_file="path/to/script.plutus"
)

# create a Tx output with a datum hash at the script address

# provide keys needed for signing the transaction
tx_files_fund = clusterlib.TxFiles(signing_key_files=[src_skey_file])

# get datum hash
datum_hash = cluster.g_transaction.get_hash_script_data(script_data_file="path/to/file.datum")

# specify Tx outputs for script address and collateral
txouts_fund = [
    clusterlib.TxOut(address=script_address, amount=amount_fund, datum_hash=datum_hash),
    # for collateral
    clusterlib.TxOut(address=dst_addr.address, amount=2_000_000),
]

# build and submit the Tx
tx_output_fund = cluster.g_transaction.build_tx(
    src_address=src_address,
    tx_name="fund_script_address",
    tx_files=tx_files_fund,
    txouts=txouts_fund,
    fee_buffer=2_000_000,
)
tx_signed_fund = cluster.g_transaction.sign_tx(
    tx_body_file=tx_output_fund.out_file,
    signing_key_files=tx_files_fund.signing_key_files,
    tx_name="fund_script_address",
)
cluster.g_transaction.submit_tx(tx_file=tx_signed_fund, txins=tx_output_fund.txins)

# get newly created UTxOs
fund_utxos = cluster.g_query.get_utxo(tx_raw_output=tx_output_fund)
script_utxos = clusterlib.filter_utxos(utxos=fund_utxos, address=script_address)
collateral_utxos = clusterlib.filter_utxos(utxos=fund_utxos, address=dst_addr.address)

# redeem the locked UTxO

plutus_txins = [
    clusterlib.ScriptTxIn(
        txins=script_utxos,
        script_file="path/to/script.plutus",
        collaterals=collateral_utxos,
        datum_file="path/to/file.datum",
        redeemer_file="path/to/file.redeemer",
    )
]

tx_files_redeem = clusterlib.TxFiles(signing_key_files=[dst_addr.skey_file])

txouts_redeem = [
    clusterlib.TxOut(address=dst_addr.address, amount=amount_redeem),
]

# The entire locked UTxO will be spent and fees will be covered from the locked UTxO.
# One UTxO with "amount_redeem" amount will be created on "destination address".
# Second UTxO with change will be created on "destination address".
tx_output_redeem = cluster.g_transaction.build_tx(
    src_address=src_address,  # this will not be used, because txins (`script_txins`) are specified explicitly
    tx_name="redeem_funds",
    tx_files=tx_files_redeem,
    txouts=txouts_redeem,
    script_txins=plutus_txins,
    change_address=dst_addr.address,
)
tx_signed_redeem = cluster.g_transaction.sign_tx(
    tx_body_file=tx_output_redeem.out_file,
    signing_key_files=tx_files_redeem.signing_key_files,
    tx_name="redeem_funds",
)
cluster.g_transaction.submit_tx(tx_file=tx_signed_redeem, txins=tx_output_fund.txins)

More examples

See cardano-node-tests for more examples, e.g. minting new tokens or minting new tokens with Plutus

Source Documentation

https://cardano-clusterlib-py.readthedocs.io/en/latest/cardano_clusterlib.html

Contributing

Install this package and its dependencies as described above.

Run pre-commit install to set up the git hook scripts that will check you changes before every commit. Alternatively run make lint manually before pushing your changes.

Follow the Google Python Style Guide, with the exception that formatting is handled automatically by Black (through pre-commit command).

Project details


Release history Release notifications | RSS feed

Download files

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

Source Distribution

cardano_clusterlib-0.6.0a20.tar.gz (65.9 kB view details)

Uploaded Source

Built Distribution

cardano_clusterlib-0.6.0a20-py3-none-any.whl (67.8 kB view details)

Uploaded Python 3

File details

Details for the file cardano_clusterlib-0.6.0a20.tar.gz.

File metadata

  • Download URL: cardano_clusterlib-0.6.0a20.tar.gz
  • Upload date:
  • Size: 65.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.3

File hashes

Hashes for cardano_clusterlib-0.6.0a20.tar.gz
Algorithm Hash digest
SHA256 3c603197965f475592acada1d890f2a2dff95f16e2f4720cfa2b7d7333bd4462
MD5 1a6e61b216b74a20b3e9657383ddacba
BLAKE2b-256 d4fbc1d11be95efd3bce30806560e8b7249ce9658feb110c16f70767c838fb3e

See more details on using hashes here.

File details

Details for the file cardano_clusterlib-0.6.0a20-py3-none-any.whl.

File metadata

File hashes

Hashes for cardano_clusterlib-0.6.0a20-py3-none-any.whl
Algorithm Hash digest
SHA256 0f1c9734240878afb95d82a1161863a0eb26a81d512e11adda3fd74141ac69b9
MD5 4e7d775ee9e0db77b4c2baad160dc0cd
BLAKE2b-256 8f358ab77233cd20719a85823984ea24ae1d286d187ff931b6833a0f0339440b

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page