# README for cardano-clusterlib
[](https://cardano-clusterlib-py.readthedocs.io/en/latest/?badge=latest)
[](https://pypi.org/project/cardano-clusterlib/)
[](https://github.com/ambv/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](https://github.com/input-output-hk/cardano-node-tests).
## Installation
```sh
# 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".
```python
# 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`.
```python
cluster = clusterlib.ClusterLib(state_dir="path/to/cluster/state_dir", slots_offset=1800)
```
### Transfer funds
```python
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
```python
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](https://github.com/input-output-hk/cardano-node-tests) for more examples, e.g. [minting new tokens](https://github.com/input-output-hk/cardano-node-tests/blob/4b50e8069f5294aaba14140ef0509e2857bec35d/cardano_node_tests/utils/clusterlib_utils.py#L491) or [minting new tokens with Plutus](https://github.com/input-output-hk/cardano-node-tests/blob/4b50e8069f5294aaba14140ef0509e2857bec35d/cardano_node_tests/tests/tests_plutus/test_mint_build.py#L151-L195)
## 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](https://google.github.io/styleguide/pyguide.html), with the exception that formatting is handled automatically by [Black](https://github.com/psf/black) (through `pre-commit` command).
Raw data
{
"_id": null,
"home_page": "https://github.com/input-output-hk/cardano-clusterlib-py",
"name": "cardano-clusterlib",
"maintainer": "Martin Kourim",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "martin.kourim@iohk.io",
"keywords": "cardano,cardano-node,cardano-cli,cardano-node-tests",
"author": "",
"author_email": "Martin Kourim <martin.kourim@iohk.io>",
"download_url": "https://files.pythonhosted.org/packages/f8/bb/cf0e0c6152b02dc7a97588ceb6088a28065d47e4e0f82e19f82bb8fa6b70/cardano-clusterlib-0.5.0.tar.gz",
"platform": null,
"description": "# README for cardano-clusterlib\n\n[](https://cardano-clusterlib-py.readthedocs.io/en/latest/?badge=latest)\n[](https://pypi.org/project/cardano-clusterlib/)\n[](https://github.com/ambv/black)\n\nPython wrapper for cardano-cli for working with cardano cluster. It supports all cardano-cli commands (except parts of `genesis` and `governance`).\n\nThe library is used for development of [cardano-node system tests](https://github.com/input-output-hk/cardano-node-tests).\n\n## Installation\n\n```sh\n# create and activate virtual env\n$ python3 -m venv .env\n$ . .env/bin/activate\n# install cardano-clusterlib from PyPI\n$ pip install cardano-clusterlib\n# - OR - install cardano-clusterlib in development mode together with dev requirements\n$ make install\n```\n\n## Usage\n\nThe 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\".\n\n```python\n# instantiate `ClusterLib`\ncluster = clusterlib.ClusterLib(state_dir=\"path/to/cluster/state_dir\")\n```\n\nOn custom testnets that were started in Byron era, you might need to specify a slots offset between Byron epochs and Shelley epochs.\nThe \"slots_offset\" is a difference between number of slots in Byron epochs and in the same number of Shelley epochs.\n\nE.g. for a testnet with parameters\n\n* 100 slots per epoch in Byron era\n* 1000 slots per epoch in Shelley era\n* two epochs in Byron era before forking to Shelley\n\nThe offset will be `2 * (1000 - 100) = 1800`.\n\n```python\ncluster = clusterlib.ClusterLib(state_dir=\"path/to/cluster/state_dir\", slots_offset=1800)\n```\n\n### Transfer funds\n\n```python\nfrom cardano_clusterlib import clusterlib\n\n# instantiate `ClusterLib`\ncluster = clusterlib.ClusterLib(state_dir=\"path/to/cluster/state_dir\")\n\nsrc_address = \"addr_test1vpst87uzwafqkxumyf446zr2jsyn44cfpu9fe8yqanyuh6glj2hkl\"\nsrc_skey_file = \"/path/to/skey\"\n\ndst_addr = cluster.g_address.gen_payment_addr_and_keys(name=\"destination_address\")\namount_lovelace = 10_000_000 # 10 ADA\n\n# specify where to send funds and amounts to send\ntxouts = [clusterlib.TxOut(address=dst_addr.address, amount=amount_lovelace)]\n\n# provide keys needed for signing the transaction\ntx_files = clusterlib.TxFiles(signing_key_files=[src_skey_file])\n\n# build, sign and submit the transaction\ntx_raw_output = cluster.g_transaction.send_tx(\n src_address=src_address,\n tx_name=\"send_funds\",\n txouts=txouts,\n tx_files=tx_files,\n)\n\n# check that the funds were received\ncluster.g_query.get_utxo(dst_addr.address)\n```\n\n### Lock and redeem funds with Plutus script\n\n```python\nfrom cardano_clusterlib import clusterlib\n\n# instantiate `ClusterLib`\ncluster = clusterlib.ClusterLib(state_dir=\"path/to/cluster/state_dir\", tx_era=\"babbage\")\n\n# source address - for funding\nsrc_address = \"addr_test1vpst87uzwafqkxumyf446zr2jsyn44cfpu9fe8yqanyuh6glj2hkl\"\nsrc_skey_file = \"/path/to/skey\"\n\n# destination address - for redeeming\ndst_addr = cluster.g_address.gen_payment_addr_and_keys(name=\"destination_address\")\n\namount_fund = 10_000_000 # 10 ADA\namount_redeem = 5_000_000 # 5 ADA\n\n# get address of the Plutus script\nscript_address = cluster.g_address.gen_payment_addr(\n addr_name=\"script_address\", payment_script_file=\"path/to/script.plutus\"\n)\n\n# create a Tx output with a datum hash at the script address\n\n# provide keys needed for signing the transaction\ntx_files_fund = clusterlib.TxFiles(signing_key_files=[src_skey_file])\n\n# get datum hash\ndatum_hash = cluster.g_transaction.get_hash_script_data(script_data_file=\"path/to/file.datum\")\n\n# specify Tx outputs for script address and collateral\ntxouts_fund = [\n clusterlib.TxOut(address=script_address, amount=amount_fund, datum_hash=datum_hash),\n # for collateral\n clusterlib.TxOut(address=dst_addr.address, amount=2_000_000),\n]\n\n# build and submit the Tx\ntx_output_fund = cluster.g_transaction.build_tx(\n src_address=src_address,\n tx_name=\"fund_script_address\",\n tx_files=tx_files_fund,\n txouts=txouts_fund,\n fee_buffer=2_000_000,\n)\ntx_signed_fund = cluster.g_transaction.sign_tx(\n tx_body_file=tx_output_fund.out_file,\n signing_key_files=tx_files_fund.signing_key_files,\n tx_name=\"fund_script_address\",\n)\ncluster.g_transaction.submit_tx(tx_file=tx_signed_fund, txins=tx_output_fund.txins)\n\n# get newly created UTxOs\nfund_utxos = cluster.g_query.get_utxo(tx_raw_output=tx_output_fund)\nscript_utxos = clusterlib.filter_utxos(utxos=fund_utxos, address=script_address)\ncollateral_utxos = clusterlib.filter_utxos(utxos=fund_utxos, address=dst_addr.address)\n\n# redeem the locked UTxO\n\nplutus_txins = [\n clusterlib.ScriptTxIn(\n txins=script_utxos,\n script_file=\"path/to/script.plutus\",\n collaterals=collateral_utxos,\n datum_file=\"path/to/file.datum\",\n redeemer_file=\"path/to/file.redeemer\",\n )\n]\n\ntx_files_redeem = clusterlib.TxFiles(signing_key_files=[dst_addr.skey_file])\n\ntxouts_redeem = [\n clusterlib.TxOut(address=dst_addr.address, amount=amount_redeem),\n]\n\n# The entire locked UTxO will be spent and fees will be covered from the locked UTxO.\n# One UTxO with \"amount_redeem\" amount will be created on \"destination address\".\n# Second UTxO with change will be created on \"destination address\".\ntx_output_redeem = cluster.g_transaction.build_tx(\n src_address=src_address, # this will not be used, because txins (`script_txins`) are specified explicitly\n tx_name=\"redeem_funds\",\n tx_files=tx_files_redeem,\n txouts=txouts_redeem,\n script_txins=plutus_txins,\n change_address=dst_addr.address,\n)\ntx_signed_redeem = cluster.g_transaction.sign_tx(\n tx_body_file=tx_output_redeem.out_file,\n signing_key_files=tx_files_redeem.signing_key_files,\n tx_name=\"redeem_funds\",\n)\ncluster.g_transaction.submit_tx(tx_file=tx_signed_redeem, txins=tx_output_fund.txins)\n```\n\n### More examples\n\nSee [cardano-node-tests](https://github.com/input-output-hk/cardano-node-tests) for more examples, e.g. [minting new tokens](https://github.com/input-output-hk/cardano-node-tests/blob/4b50e8069f5294aaba14140ef0509e2857bec35d/cardano_node_tests/utils/clusterlib_utils.py#L491) or [minting new tokens with Plutus](https://github.com/input-output-hk/cardano-node-tests/blob/4b50e8069f5294aaba14140ef0509e2857bec35d/cardano_node_tests/tests/tests_plutus/test_mint_build.py#L151-L195)\n\n\n## Source Documentation\n\n<https://cardano-clusterlib-py.readthedocs.io/en/latest/cardano_clusterlib.html>\n\n\n## Contributing\n\nInstall this package and its dependencies as described above.\n\nRun `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.\n\nFollow the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html), with the exception that formatting is handled automatically by [Black](https://github.com/psf/black) (through `pre-commit` command).\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Python wrapper for cardano-cli for working with cardano cluster",
"version": "0.5.0",
"project_urls": {
"Homepage": "https://github.com/input-output-hk/cardano-clusterlib-py",
"documentation": "https://cardano-clusterlib-py.readthedocs.io/",
"repository": "https://github.com/input-output-hk/cardano-clusterlib-py"
},
"split_keywords": [
"cardano",
"cardano-node",
"cardano-cli",
"cardano-node-tests"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2ac79826bc23d1c8431e9daaa17a06f3755a0f25bcd24107f20f97440d892f91",
"md5": "2ad1732551a2d7b1d2ae3d0ab4ba6313",
"sha256": "aac845d44fb856dd37a1b45aacd87f7770c3767c53d3a6b4b18c34bfb12940b8"
},
"downloads": -1,
"filename": "cardano_clusterlib-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2ad1732551a2d7b1d2ae3d0ab4ba6313",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 54960,
"upload_time": "2023-06-22T11:55:50",
"upload_time_iso_8601": "2023-06-22T11:55:50.010058Z",
"url": "https://files.pythonhosted.org/packages/2a/c7/9826bc23d1c8431e9daaa17a06f3755a0f25bcd24107f20f97440d892f91/cardano_clusterlib-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f8bbcf0e0c6152b02dc7a97588ceb6088a28065d47e4e0f82e19f82bb8fa6b70",
"md5": "cdd98e72bb7a6671bb54250d4db7f6b2",
"sha256": "986109b165749ab1bce2d6681be1ab10e1466901b46522de8b1075573ac5ef4b"
},
"downloads": -1,
"filename": "cardano-clusterlib-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "cdd98e72bb7a6671bb54250d4db7f6b2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 57288,
"upload_time": "2023-06-22T11:55:53",
"upload_time_iso_8601": "2023-06-22T11:55:53.105848Z",
"url": "https://files.pythonhosted.org/packages/f8/bb/cf0e0c6152b02dc7a97588ceb6088a28065d47e4e0f82e19f82bb8fa6b70/cardano-clusterlib-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-22 11:55:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "input-output-hk",
"github_project": "cardano-clusterlib-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cardano-clusterlib"
}
JSON
