Package: cardano-clusterlib
README for cardano-clusterlibPython wrapper for cardano-cli for working with cardano cluster. It supports all cardano-cli commands (except parts ofgenesisandgovernance).The library is used for development ofcardano-node system tests.Installation# create and activate virtual env$python3-mvenv.env
$..env/bin/activate# install cardano-clusterlib from PyPI$pipinstallcardano-clusterlib# - OR - install cardano-clusterlib in development mode together with dev requirements$makeinstallUsageThe library needs workingcardano-cli(the command is available onPATH,cardano-nodeis running,CARDANO_NODE_SOCKET_PATHis set). Instate_dirit 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 parameters100 slots per epoch in Byron era1000 slots per epoch in Shelley eratwo epochs in Byron era before forking to ShelleyThe offset will be2 * (1000 - 100) = 1800.cluster=clusterlib.ClusterLib(state_dir="path/to/cluster/state_dir",slots_offset=1800)Transfer fundsfromcardano_clusterlibimportclusterlib# 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 sendtxouts=[clusterlib.TxOut(address=dst_addr.address,amount=amount_lovelace)]# provide keys needed for signing the transactiontx_files=clusterlib.TxFiles(signing_key_files=[src_skey_file])# build, sign and submit the transactiontx_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 receivedcluster.g_query.get_utxo(dst_addr.address)Lock and redeem funds with Plutus scriptfromcardano_clusterlibimportclusterlib# instantiate `ClusterLib`cluster=clusterlib.ClusterLib(state_dir="path/to/cluster/state_dir",tx_era="babbage")# source address - for fundingsrc_address="addr_test1vpst87uzwafqkxumyf446zr2jsyn44cfpu9fe8yqanyuh6glj2hkl"src_skey_file="/path/to/skey"# destination address - for redeemingdst_addr=cluster.g_address.gen_payment_addr_and_keys(name="destination_address")amount_fund=10_000_000# 10 ADAamount_redeem=5_000_000# 5 ADA# get address of the Plutus scriptscript_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 transactiontx_files_fund=clusterlib.TxFiles(signing_key_files=[src_skey_file])# get datum hashdatum_hash=cluster.g_transaction.get_hash_script_data(script_data_file="path/to/file.datum")# specify Tx outputs for script address and collateraltxouts_fund=[clusterlib.TxOut(address=script_address,amount=amount_fund,datum_hash=datum_hash),# for collateralclusterlib.TxOut(address=dst_addr.address,amount=2_000_000),]# build and submit the Txtx_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 UTxOsfund_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 UTxOplutus_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 explicitlytx_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 examplesSeecardano-node-testsfor more examples, e.g.minting new tokensorminting new tokens with PlutusSource Documentationhttps://cardano-clusterlib-py.readthedocs.io/en/latest/cardano_clusterlib.htmlContributingInstall this package and its dependencies as described above.Runpre-commit installto set up the git hook scripts that will check you changes before every commit. Alternatively runmake lintmanually before pushing your changes.Follow theGoogle Python Style Guide, with the exception that formatting is handled automatically byBlack(throughpre-commitcommand).