README for cardano-clusterlib
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")
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")
# 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 Ruff (through pre-commit command).
2 maintainers
Metadata
2 maintainers
Release files for cardano-clusterlib 0.10.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| cardano_clusterlib-0.10.8.tar.gz | 82.7 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cardano_clusterlib-0.10.8-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 162.5 kB
Release files / cardano_clusterlib-0.10.8.tar.gz
| Download URL | cardano_clusterlib-0.10.8.tar.gz |
|---|---|
| Size | 82.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2d0ca9f7b264d72536b29c2a2ff8bf30a9828be30e4539e1d7d82e1adc50c932
|
|
BLAKE2b-256 checksum How to use checksums |
68caed6dad9458833543cfe51099ba4425980f292ebe1740a7195bfb7c22cd79
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Release files / cardano_clusterlib-0.10.8-py3-none-any.whl
| Download URL | cardano_clusterlib-0.10.8-py3-none-any.whl |
|---|---|
| Size | 79.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
35b6826db73cde9a03e066e33ae8435b7f07597576f2142064024eee3e0a9512
|
|
BLAKE2b-256 checksum How to use checksums |
94c80c4768a46334531b1d44c7a0b44a007470c016d9acc8aeae80dc4bd7ef5b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Security for cardano-clusterlib 0.10.8
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
