cardano_clusterlib package
Submodules
cardano_clusterlib.address_group module
Group of methods for working with payment addresses.
- class cardano_clusterlib.address_group.AddressGroup(clusterlib_obj: types.ClusterLib)[source]
Bases:
object- gen_payment_addr(addr_name: str, payment_vkey: Optional[str] = None, payment_vkey_file: Optional[Union[str, pathlib.Path]] = None, payment_script_file: Optional[Union[str, pathlib.Path]] = None, stake_vkey: Optional[str] = None, stake_vkey_file: Optional[Union[str, pathlib.Path]] = None, stake_script_file: Optional[Union[str, pathlib.Path]] = None, stake_address: Optional[str] = None, destination_dir: Union[str, pathlib.Path] = '.') str[source]
Generate a payment address, with optional delegation to a stake address.
- Parameters
addr_name – A name of payment address.
payment_vkey – A vkey file (Bech32, optional).
payment_vkey_file – A path to corresponding vkey file (optional).
payment_script_file – A path to corresponding payment script file (optional).
stake_vkey – A stake vkey file (optional).
stake_vkey_file – A path to corresponding stake vkey file (optional).
stake_script_file – A path to corresponding stake script file (optional).
stake_address – A stake address (Bech32, optional).
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A generated payment address.
- Return type
str
- gen_payment_addr_and_keys(name: str, stake_vkey_file: Optional[Union[str, pathlib.Path]] = None, stake_script_file: Optional[Union[str, pathlib.Path]] = None, destination_dir: Union[str, pathlib.Path] = '.') cardano_clusterlib.structs.AddressRecord[source]
Generate payment address and key pair.
- Parameters
name – A name of the address and key pair.
stake_vkey_file – A path to corresponding stake vkey file (optional).
stake_script_file – A path to corresponding payment script file (optional).
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A tuple containing the address and key pair / script file.
- Return type
- gen_payment_key_pair(key_name: str, extended: bool = False, destination_dir: Union[str, pathlib.Path] = '.') cardano_clusterlib.structs.KeyPair[source]
Generate an address key pair.
- Parameters
key_name – A name of the key pair.
extended – A bool indicating whether to generate extended ed25519 Shelley-era key (False by default).
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A tuple containing the key pair.
- Return type
- gen_script_addr(addr_name: str, script_file: Union[str, pathlib.Path], destination_dir: Union[str, pathlib.Path] = '.') str[source]
Generate a script address.
- Parameters
addr_name – A name of payment address.
script_file – A path to corresponding script file.
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A generated script address.
- Return type
str
- get_address_info(address: str) cardano_clusterlib.structs.AddressInfo[source]
Get information about an address.
- Parameters
address – A Cardano address.
- Returns
A tuple containing address info.
- Return type
- get_payment_vkey_hash(payment_vkey_file: Optional[Union[str, pathlib.Path]] = None, payment_vkey: Optional[str] = None) str[source]
Return the hash of an address key.
- Parameters
payment_vkey_file – A path to payment vkey file (optional).
payment_vkey – A payment vkey, (Bech32, optional).
- Returns
A generated hash.
- Return type
str
cardano_clusterlib.clusterlib module
Legacy top-level module.
Import everything that used to be available here for backwards compatibility.
cardano_clusterlib.clusterlib_helpers module
Helper functions for ClusterLib.
- class cardano_clusterlib.clusterlib_helpers.EpochInfo(epoch, first_slot, last_slot)[source]
Bases:
tuple
- cardano_clusterlib.clusterlib_helpers.get_epoch_for_slot(cluster_obj: types.ClusterLib, slot_no: int) cardano_clusterlib.clusterlib_helpers.EpochInfo[source]
Given slot number, return corresponding epoch number and first and last slot of the epoch.
- cardano_clusterlib.clusterlib_helpers.wait_for_block(clusterlib_obj: types.ClusterLib, tip: Dict[str, Any], block_no: int) int[source]
Wait for block number.
- Parameters
clusterlib_obj – An instance of ClusterLib.
tip – Current tip - last block successfully applied to the ledger.
block_no – A block number to wait for.
- Returns
A block number of last added block.
- Return type
int
cardano_clusterlib.clusterlib_klass module
Wrapper for cardano-cli for working with cardano cluster.
- class cardano_clusterlib.clusterlib_klass.ClusterLib(state_dir: Union[str, pathlib.Path], protocol: str = 'cardano', tx_era: str = '', slots_offset: int = 0, socket_path: Union[str, pathlib.Path] = '')[source]
Bases:
objectMethods for working with cardano cluster using cardano-cli..
- slots_offset[source]
Difference in slots between cluster’s start era and current era (e.g. Byron->Mary)
- socket_path[source]
A path to socket file for communication with the node. This overrides the CARDANO_NODE_SOCKET_PATH environment variable.
- cli(cli_args: List[str], timeout: Optional[float] = None) cardano_clusterlib.structs.CLIOut[source]
Run the cardano-cli command.
- Parameters
cli_args – A list of arguments for cardano-cli.
timeout – A timeout for the command, in seconds (optional).
- Returns
A tuple containing command stdout and stderr.
- Return type
- property g_address: cardano_clusterlib.address_group.AddressGroup[source]
Address group.
- property g_genesis: cardano_clusterlib.genesis_group.GenesisGroup[source]
Genesis group.
- property g_governance: cardano_clusterlib.governance_group.GovernanceGroup[source]
Governance group.
- property g_key: cardano_clusterlib.key_group.KeyGroup[source]
Key group.
- property g_node: cardano_clusterlib.node_group.NodeGroup[source]
Node group.
- property g_query: cardano_clusterlib.query_group.QueryGroup[source]
Query group.
- property g_stake_address: cardano_clusterlib.stake_address_group.StakeAddressGroup[source]
Stake address group.
- property g_stake_pool: cardano_clusterlib.stake_pool_group.StakePoolGroup[source]
Stake pool group.
- property g_transaction: cardano_clusterlib.transaction_group.TransactionGroup[source]
Transaction group.
- poll_new_epoch(exp_epoch: int, padding_seconds: int = 0) None[source]
Wait for new epoch(s) by polling current epoch every 3 sec.
Can be used only for waiting up to 3000 sec + padding seconds.
- Parameters
exp_epoch – An epoch number to wait for.
padding_seconds – A number of additional seconds to wait for (optional).
- set_socket_path(socket_path: Optional[Union[str, pathlib.Path]]) None[source]
Set a path to socket file for communication with the node.
- time_from_epoch_start(tip: Optional[dict] = None) float[source]
How many seconds passed from start of the current epoch.
- time_to_epoch_end(tip: Optional[dict] = None) float[source]
How many seconds to go to start of a new epoch.
- wait_for_block(block: int) int[source]
Wait for block number.
- Parameters
block – A block number to wait for.
- Returns
A block number of last added block.
- Return type
int
- wait_for_new_block(new_blocks: int = 1) int[source]
Wait for new block(s) to be created.
- Parameters
new_blocks – A number of new blocks to wait for (optional).
- Returns
A block number of last added block.
- Return type
int
cardano_clusterlib.consts module
cardano_clusterlib.coverage module
cardano_clusterlib.exceptions module
cardano_clusterlib.genesis_group module
Group of methods related to genesis block.
- class cardano_clusterlib.genesis_group.GenesisGroup(clusterlib_obj: types.ClusterLib)[source]
Bases:
object- gen_genesis_addr(addr_name: str, vkey_file: Union[str, pathlib.Path], destination_dir: Union[str, pathlib.Path] = '.') str[source]
Generate the address for an initial UTxO based on the verification key.
- Parameters
addr_name – A name of genesis address.
vkey_file – A path to corresponding vkey file.
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A generated genesis address.
- Return type
str
- property genesis_keys: cardano_clusterlib.structs.GenesisKeys[source]
Return tuple with genesis-related keys.
cardano_clusterlib.governance_group module
Group of methods for governance.
- class cardano_clusterlib.governance_group.GovernanceGroup(clusterlib_obj: types.ClusterLib)[source]
Bases:
object- gen_mir_cert_stake_addr(stake_addr: str, reward: int, tx_name: str, use_treasury: bool = False, destination_dir: Union[str, pathlib.Path] = '.') pathlib.Path[source]
Create an MIR certificate to pay stake addresses.
- Parameters
stake_addr – A stake address string.
reward – An amount of Lovelace to transfer.
tx_name – A name of the transaction.
use_treasury – A bool indicating whether to use treasury or reserves (default).
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A path to the MIR certificate file.
- Return type
Path
- gen_mir_cert_to_rewards(transfer: int, tx_name: str, destination_dir: Union[str, pathlib.Path] = '.') pathlib.Path[source]
Create an MIR certificate to transfer from the treasury pot to the reserves pot.
- Parameters
transfer – An amount of Lovelace to transfer.
tx_name – A name of the transaction.
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A path to the MIR certificate file.
- Return type
Path
- gen_mir_cert_to_treasury(transfer: int, tx_name: str, destination_dir: Union[str, pathlib.Path] = '.') pathlib.Path[source]
Create an MIR certificate to transfer from the reserves pot to the treasury pot.
- Parameters
transfer – An amount of Lovelace to transfer.
tx_name – A name of the transaction.
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A path to the MIR certificate file.
- Return type
Path
- gen_update_proposal(cli_args: Union[list, tuple, set, frozenset], epoch: int, tx_name: str, destination_dir: Union[str, pathlib.Path] = '.') pathlib.Path[source]
Create an update proposal.
- Parameters
cli_args – A list (iterable) of CLI arguments.
epoch – An epoch where the update proposal will take effect.
tx_name – A name of the transaction.
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A path to the update proposal file.
- Return type
Path
- submit_update_proposal(cli_args: Union[list, tuple, set, frozenset], src_address: str, src_skey_file: Union[str, pathlib.Path], tx_name: str, epoch: Optional[int] = None, destination_dir: Union[str, pathlib.Path] = '.') cardano_clusterlib.structs.TxRawOutput[source]
Submit an update proposal.
- Parameters
cli_args – A list (iterable) of CLI arguments.
src_address – An address used for fee and inputs.
src_skey_file – A path to skey file corresponding to the src_address.
tx_name – A name of the transaction.
epoch – An epoch where the update proposal will take effect (optional).
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A tuple with transaction output details.
- Return type
cardano_clusterlib.helpers module
cardano_clusterlib.key_group module
Group of methods for working with key commands.
- class cardano_clusterlib.key_group.KeyGroup(clusterlib_obj: types.ClusterLib)[source]
Bases:
object- gen_non_extended_verification_key(key_name: str, extended_verification_key_file: Union[str, pathlib.Path], destination_dir: Union[str, pathlib.Path] = '.') pathlib.Path[source]
Generate a non-extended key from a verification key.
- Parameters
key_name – A name of the key.
extended_verification_key_file – A path to the extended verification key file.
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A path to the generated non-extended verification key file.
- Return type
Path
- gen_verification_key(key_name: str, signing_key_file: Union[str, pathlib.Path], destination_dir: Union[str, pathlib.Path] = '.') pathlib.Path[source]
Generate a verification file from a signing key.
- Parameters
key_name – A name of the key.
signing_key_file – A path to signing key file.
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A path to the generated verification key file.
- Return type
Path
cardano_clusterlib.node_group module
Group of methods for node operation.
- class cardano_clusterlib.node_group.NodeGroup(clusterlib_obj: types.ClusterLib)[source]
Bases:
object- gen_cold_key_pair_and_counter(node_name: str, destination_dir: Union[str, pathlib.Path] = '.') cardano_clusterlib.structs.ColdKeyPair[source]
Generate a key pair for operator’s offline key and a new certificate issue counter.
- Parameters
node_name – A name of the node the key pair and the counter is generated for.
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A tuple containing the key pair and the counter.
- Return type
- gen_kes_key_pair(node_name: str, destination_dir: Union[str, pathlib.Path] = '.') cardano_clusterlib.structs.KeyPair[source]
Generate a key pair for a node KES operational key.
- Parameters
node_name – A name of the node the key pair is generated for.
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A tuple containing the key pair.
- Return type
- gen_node_operational_cert(node_name: str, kes_vkey_file: Union[str, pathlib.Path], cold_skey_file: Union[str, pathlib.Path], cold_counter_file: Union[str, pathlib.Path], kes_period: Optional[int] = None, destination_dir: Union[str, pathlib.Path] = '.') pathlib.Path[source]
Generate a node operational certificate.
This certificate is used when starting the node and not submitted through a transaction.
- Parameters
node_name – A name of the node the certificate is generated for.
kes_vkey_file – A path to pool KES vkey file.
cold_skey_file – A path to pool cold skey file.
cold_counter_file – A path to pool cold counter file.
kes_period – A start KES period. The current KES period is used when not specified.
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A path to the generated certificate.
- Return type
Path
- gen_vrf_key_pair(node_name: str, destination_dir: Union[str, pathlib.Path] = '.') cardano_clusterlib.structs.KeyPair[source]
Generate a key pair for a node VRF operational key.
- Parameters
node_name – A name of the node the key pair is generated for.
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A tuple containing the key pair.
- Return type
cardano_clusterlib.query_group module
Wrapper for cardano-cli for working with cardano cluster.
- class cardano_clusterlib.query_group.QueryGroup(clusterlib_obj: types.ClusterLib)[source]
Bases:
object- get_address_balance(address: str, coin: str = 'lovelace') int[source]
Get total balance of an address (sum of all UTxO balances).
- Parameters
address – A payment address string.
coin – A coin name (asset IDs).
- Returns
A total balance.
- Return type
int
- get_block_no() int[source]
Return block number of last block that was successfully applied to the ledger.
- get_epoch_slot_no() int[source]
Return slot number within a given epoch.
(of last block successfully applied to the ledger)
- get_kes_period_info(opcert_file: Union[str, pathlib.Path]) Dict[str, Any][source]
Get information about the current KES period and node’s operational certificate.
- Parameters
opcert_file – A path to operational certificate.
- Returns
A dictionary containing KES period information.
- Return type
dict
- get_leadership_schedule(vrf_skey_file: Union[str, pathlib.Path], stake_pool_vkey: str = '', cold_vkey_file: Optional[Union[str, pathlib.Path]] = None, stake_pool_id: str = '', for_next: bool = False) List[cardano_clusterlib.structs.LeadershipSchedule][source]
Get the slots the node is expected to mint a block in.
- Parameters
vrf_skey_file – A path to node VRF skey file.
stake_pool_vkey – A pool cold vkey (Bech32 or hex-encoded, optional)
cold_vkey_file – A path to pool cold vkey file (optional).
stake_pool_id – An ID of the stake pool (Bech32 or hex-encoded, optional).
for_next – A bool indicating whether to get the leadership schedule for the following epoch (current epoch by default)
- Returns
- A list of structs.LeadershipSchedule, specifying
slot and time.
- Return type
- get_mempool_info() Dict[str, Any][source]
Return info about the current mempool’s capacity and sizes.
- Returns
A dictionary containing mempool information.
- Return type
dict
- get_mempool_next_tx() Dict[str, Any][source]
Return info about the next transaction in the mempool’s current list.
- Returns
A dictionary containing mempool information.
- Return type
dict
- get_mempool_tx_exists(txid: str) Dict[str, Any][source]
Query if a particular transaction exists in the mempool.
- Parameters
txid – A transaction ID.
- Returns
A dictionary containing mempool information.
- Return type
dict
- get_pool_params(stake_pool_id: str) cardano_clusterlib.structs.PoolParamsTop[source]
Return a pool parameters.
- Parameters
stake_pool_id – An ID of the stake pool (Bech32-encoded or hex-encoded).
- Returns
A pool parameters.
- Return type
dict
- get_pool_state(stake_pool_id: str) cardano_clusterlib.structs.PoolParamsTop[source]
Return a pool state.
- Parameters
stake_pool_id – An ID of the stake pool (Bech32-encoded or hex-encoded).
- Returns
A pool parameters.
- Return type
dict
- get_registered_stake_pools_ledger_state() dict[source]
Return ledger state info for registered stake pools.
- get_slot_no() int[source]
Return slot number of last block that was successfully applied to the ledger.
- get_stake_addr_info(stake_addr: str) cardano_clusterlib.structs.StakeAddrInfo[source]
Return the current delegations and reward accounts filtered by stake address.
- Parameters
stake_addr – A stake address string.
- Returns
A tuple containing stake address info.
- Return type
- get_stake_distribution() Dict[str, float][source]
Return current aggregated stake distribution per stake pool.
- get_stake_snapshot(stake_pool_ids: Optional[List[str]] = None, all_stake_pools: bool = False) Dict[str, Any][source]
Return the three stake snapshots, plus the total active stake.
- Parameters
stake_pool_ids – A list of stake pool IDs, Bech32-encoded or hex-encoded (optional).
all_stake_pools – A bool indicating whether to query for all stake pools (optional).
- Returns
A stake snapshot data.
- Return type
Dict
- get_tip() Dict[str, Any][source]
Return current tip - last block successfully applied to the ledger.
- get_utxo(address: Union[str, List[str]] = '', txin: Union[str, List[str]] = '', utxo: Union[cardano_clusterlib.structs.UTXOData, List[cardano_clusterlib.structs.UTXOData], Tuple[()]] = (), tx_raw_output: Optional[cardano_clusterlib.structs.TxRawOutput] = None, coins: Union[list, tuple, set, frozenset] = ()) List[cardano_clusterlib.structs.UTXOData][source]
Return UTxO info for payment address.
- Parameters
address – Payment address(es).
txin – Transaction input(s) (TxId#TxIx).
utxo – Representation of UTxO data (structs.UTXOData).
tx_raw_output – A data used when building a transaction (structs.TxRawOutput).
coins – A list (iterable) of coin names (asset IDs, optional).
- Returns
A list of UTxO data.
- Return type
List[structs.UTXOData]
- get_utxo_with_highest_amount(address: str, coin: str = 'lovelace') cardano_clusterlib.structs.UTXOData[source]
Return data for UTxO with the highest amount.
- Parameters
address – A payment address string.
coin – A coin name (asset IDs).
- Returns
An UTxO record with the highest amount.
- Return type
- query_cli(cli_args: Union[list, tuple, set, frozenset], cli_sub_args: Union[list, tuple, set, frozenset] = ()) str[source]
Run the cardano-cli query command.
- save_ledger_state(state_name: str, destination_dir: Union[str, pathlib.Path] = '.') pathlib.Path[source]
Save ledger state to file.
- Parameters
state_name – A name of the ledger state (can be epoch number, etc.).
destination_dir – A path to directory for storing the state JSON file (optional).
- Returns
A path to the generated state JSON file.
- Return type
Path
cardano_clusterlib.stake_address_group module
Group of methods for working with stake addresses.
- class cardano_clusterlib.stake_address_group.StakeAddressGroup(clusterlib_obj: types.ClusterLib)[source]
Bases:
object- gen_stake_addr(addr_name: str, stake_vkey_file: Optional[Union[str, pathlib.Path]] = None, stake_script_file: Optional[Union[str, pathlib.Path]] = None, destination_dir: Union[str, pathlib.Path] = '.') str[source]
Generate a stake address.
- Parameters
addr_name – A name of payment address.
stake_vkey_file – A path to corresponding stake vkey file (optional).
stake_script_file – A path to corresponding payment script file (optional).
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A generated stake address.
- Return type
str
- gen_stake_addr_and_keys(name: str, destination_dir: Union[str, pathlib.Path] = '.') cardano_clusterlib.structs.AddressRecord[source]
Generate stake address and key pair.
- Parameters
name – A name of the address and key pair.
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A tuple containing the address and key pair / script file.
- Return type
- gen_stake_addr_delegation_cert(addr_name: str, stake_vkey_file: Optional[Union[str, pathlib.Path]] = None, stake_script_file: Optional[Union[str, pathlib.Path]] = None, stake_address: Optional[str] = None, cold_vkey_file: Optional[Union[str, pathlib.Path]] = None, stake_pool_id: str = '', destination_dir: Union[str, pathlib.Path] = '.') pathlib.Path[source]
Generate a stake address delegation certificate.
- Parameters
addr_name – A name of stake address.
stake_vkey_file – A path to corresponding stake vkey file (optional).
stake_script_file – A path to corresponding stake script file (optional).
stake_address – Stake address key, bech32 or hex-encoded (optional).
cold_vkey_file – A path to pool cold vkey file (optional).
stake_pool_id – An ID of the stake pool (optional).
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A path to the generated certificate.
- Return type
Path
- gen_stake_addr_deregistration_cert(addr_name: str, stake_vkey_file: Optional[Union[str, pathlib.Path]] = None, stake_script_file: Optional[Union[str, pathlib.Path]] = None, stake_address: Optional[str] = None, destination_dir: Union[str, pathlib.Path] = '.') pathlib.Path[source]
Generate a stake address deregistration certificate.
- Parameters
addr_name – A name of stake address.
stake_vkey_file – A path to corresponding stake vkey file (optional).
stake_script_file – A path to corresponding stake script file (optional).
stake_address – Stake address key, bech32 or hex-encoded (optional).
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A path to the generated certificate.
- Return type
Path
- gen_stake_addr_registration_cert(addr_name: str, stake_vkey_file: Optional[Union[str, pathlib.Path]] = None, stake_script_file: Optional[Union[str, pathlib.Path]] = None, stake_address: Optional[str] = None, destination_dir: Union[str, pathlib.Path] = '.') pathlib.Path[source]
Generate a stake address registration certificate.
- Parameters
addr_name – A name of stake address.
stake_vkey_file – A path to corresponding stake vkey file (optional).
stake_script_file – A path to corresponding stake script file (optional).
stake_address – Stake address key, bech32 or hex-encoded (optional).
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A path to the generated certificate.
- Return type
Path
- gen_stake_key_pair(key_name: str, destination_dir: Union[str, pathlib.Path] = '.') cardano_clusterlib.structs.KeyPair[source]
Generate a stake address key pair.
- Parameters
key_name – A name of the key pair.
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A tuple containing the key pair.
- Return type
- get_stake_vkey_hash(stake_vkey_file: Optional[Union[str, pathlib.Path]] = None, stake_vkey: Optional[str] = None) str[source]
Return the hash of a stake address key.
- Parameters
stake_vkey_file – A path to stake vkey file (optional).
stake_vkey – A stake vkey (Bech32, optional).
- Returns
A generated hash.
- Return type
str
- withdraw_reward(stake_addr_record: cardano_clusterlib.structs.AddressRecord, dst_addr_record: cardano_clusterlib.structs.AddressRecord, tx_name: str, verify: bool = True, destination_dir: Union[str, pathlib.Path] = '.') cardano_clusterlib.structs.TxRawOutput[source]
Withdraw reward to payment address.
- Parameters
stake_addr_record – An structs.AddressRecord tuple for the stake address with reward.
dst_addr_record – An structs.AddressRecord tuple for the destination payment address.
tx_name – A name of the transaction.
verify – A bool indicating whether to verify that the reward was transferred correctly.
destination_dir – A path to directory for storing artifacts (optional).
cardano_clusterlib.stake_pool_group module
Group of methods for working with stake pools.
- class cardano_clusterlib.stake_pool_group.StakePoolGroup(clusterlib_obj: types.ClusterLib)[source]
Bases:
object- create_stake_pool(pool_data: cardano_clusterlib.structs.PoolData, pool_owners: List[cardano_clusterlib.structs.PoolUser], tx_name: str, destination_dir: Union[str, pathlib.Path] = '.') cardano_clusterlib.structs.PoolCreationOutput[source]
Create and register a stake pool.
- Parameters
pool_data – A structs.PoolData tuple containing info about the stake pool.
pool_owners – A list of structs.PoolUser structures containing pool user addresses and keys.
tx_name – A name of the transaction.
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A tuple containing pool creation output.
- Return type
- deregister_stake_pool(pool_owners: List[cardano_clusterlib.structs.PoolUser], cold_key_pair: cardano_clusterlib.structs.ColdKeyPair, epoch: int, pool_name: str, tx_name: str, destination_dir: Union[str, pathlib.Path] = '.') Tuple[pathlib.Path, cardano_clusterlib.structs.TxRawOutput][source]
Deregister a stake pool.
- Parameters
pool_owners – A list of structs.PoolUser structures containing pool user addresses and keys.
cold_key_pair – A structs.ColdKeyPair tuple containing the key pair and the counter.
epoch – An epoch where the update proposal will take effect (optional).
pool_name – A name of the stake pool.
tx_name – A name of the transaction.
destination_dir – A path to directory for storing artifacts (optional).
- Returns
- A tuple with pool registration cert file and
transaction output details.
- Return type
Tuple[Path, structs.TxRawOutput]
- gen_pool_deregistration_cert(pool_name: str, cold_vkey_file: Union[str, pathlib.Path], epoch: int, destination_dir: Union[str, pathlib.Path] = '.') pathlib.Path[source]
Generate a stake pool deregistration certificate.
- Parameters
pool_name – A name of the stake pool.
cold_vkey_file – A path to pool cold vkey file.
epoch – An epoch where the pool will be deregistered.
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A path to the generated certificate.
- Return type
Path
- gen_pool_metadata_hash(pool_metadata_file: Union[str, pathlib.Path]) str[source]
Generate the hash of pool metadata.
- Parameters
pool_metadata_file – A path to the pool metadata file.
- Returns
A metadata hash.
- Return type
str
- gen_pool_registration_cert(pool_data: cardano_clusterlib.structs.PoolData, vrf_vkey_file: Union[str, pathlib.Path], cold_vkey_file: Union[str, pathlib.Path], owner_stake_vkey_files: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path]], reward_account_vkey_file: Optional[Union[str, pathlib.Path]] = None, destination_dir: Union[str, pathlib.Path] = '.') pathlib.Path[source]
Generate a stake pool registration certificate.
- Parameters
pool_data – A structs.PoolData tuple containing info about the stake pool.
vrf_vkey_file – A path to node VRF vkey file.
cold_vkey_file – A path to pool cold vkey file.
owner_stake_vkey_files – A list of paths to pool owner stake vkey files.
reward_account_vkey_file – A path to pool reward account vkey file (optional).
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A path to the generated certificate.
- Return type
Path
- get_stake_pool_id(cold_vkey_file: Union[str, pathlib.Path]) str[source]
Return pool ID from the offline key.
- Parameters
cold_vkey_file – A path to pool cold vkey file.
- Returns
A pool ID.
- Return type
str
- register_stake_pool(pool_data: cardano_clusterlib.structs.PoolData, pool_owners: List[cardano_clusterlib.structs.PoolUser], vrf_vkey_file: Union[str, pathlib.Path], cold_key_pair: cardano_clusterlib.structs.ColdKeyPair, tx_name: str, reward_account_vkey_file: Optional[Union[str, pathlib.Path]] = None, deposit: Optional[int] = None, destination_dir: Union[str, pathlib.Path] = '.') Tuple[pathlib.Path, cardano_clusterlib.structs.TxRawOutput][source]
Register a stake pool.
- Parameters
pool_data – A structs.PoolData tuple containing info about the stake pool.
pool_owners – A list of structs.PoolUser structures containing pool user addresses and keys.
vrf_vkey_file – A path to node VRF vkey file.
cold_key_pair – A structs.ColdKeyPair tuple containing the key pair and the counter.
tx_name – A name of the transaction.
reward_account_vkey_file – A path to reward account vkey file (optional).
deposit – A deposit amount needed by the transaction (optional).
destination_dir – A path to directory for storing artifacts (optional).
- Returns
- A tuple with pool registration cert file and
transaction output details.
- Return type
Tuple[Path, structs.TxRawOutput]
cardano_clusterlib.structs module
- class cardano_clusterlib.structs.AddressInfo(address, era, encoding, type, base16)[source]
Bases:
tuple
- class cardano_clusterlib.structs.ColdKeyPair(vkey_file, skey_file, counter_file)[source]
Bases:
tuple
- class cardano_clusterlib.structs.ComplexCert(certificate_file: Union[str, pathlib.Path], script_file: Union[str, pathlib.Path] = '', reference_txin: Optional[cardano_clusterlib.structs.UTXOData] = None, reference_type: str = '', collaterals: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]] = (), execution_units: Optional[Tuple[int, int]] = None, redeemer_file: Union[str, pathlib.Path] = '', redeemer_cbor_file: Union[str, pathlib.Path] = '', redeemer_value: str = '')[source]
Bases:
tupleData structure for certificates with optional data for Plutus scripts.
If used for one certificate, it needs to be used for all the other certificates in a given transaction (instead of TxFiles.certificate_files). Otherwise, order of certificates cannot be guaranteed.
- collaterals: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]][source]
Alias for field number 4
- reference_txin: Optional[cardano_clusterlib.structs.UTXOData][source]
Alias for field number 2
- class cardano_clusterlib.structs.DataForBuild(txins, txouts, withdrawals, script_withdrawals)[source]
Bases:
tuple- script_withdrawals: Union[List[cardano_clusterlib.structs.ScriptWithdrawal], Tuple[()]][source]
Alias for field number 3
- txins: List[cardano_clusterlib.structs.UTXOData][source]
Alias for field number 0
- txouts: List[cardano_clusterlib.structs.TxOut][source]
Alias for field number 1
- withdrawals: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]][source]
Alias for field number 2
- class cardano_clusterlib.structs.GenesisKeys(genesis_utxo_vkey, genesis_utxo_skey, genesis_vkeys, delegate_skeys)[source]
Bases:
tuple
- class cardano_clusterlib.structs.Mint(txouts, script_file, reference_txin, reference_type, policyid, collaterals, execution_units, redeemer_file, redeemer_cbor_file, redeemer_value)[source]
Bases:
tuple- collaterals: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]][source]
Alias for field number 5
- reference_txin: Optional[cardano_clusterlib.structs.UTXOData][source]
Alias for field number 2
- txouts: List[cardano_clusterlib.structs.TxOut][source]
Alias for field number 0
- class cardano_clusterlib.structs.PoolCreationOutput(stake_pool_id, vrf_key_pair, cold_key_pair, pool_reg_cert_file, pool_data, pool_owners, tx_raw_output, kes_key_pair)[source]
Bases:
tuple- cold_key_pair: cardano_clusterlib.structs.ColdKeyPair[source]
Alias for field number 2
- kes_key_pair: Optional[cardano_clusterlib.structs.KeyPair][source]
Alias for field number 7
- pool_data: cardano_clusterlib.structs.PoolData[source]
Alias for field number 4
- pool_owners: List[cardano_clusterlib.structs.PoolUser][source]
Alias for field number 5
- tx_raw_output: cardano_clusterlib.structs.TxRawOutput[source]
Alias for field number 6
- vrf_key_pair: cardano_clusterlib.structs.KeyPair[source]
Alias for field number 1
- class cardano_clusterlib.structs.PoolData(pool_name, pool_pledge, pool_cost, pool_margin, pool_metadata_url, pool_metadata_hash, pool_relay_dns, pool_relay_ipv4, pool_relay_port)[source]
Bases:
tuple
- class cardano_clusterlib.structs.PoolParamsTop(pool_params, future_pool_params, retiring)[source]
Bases:
tuple
- class cardano_clusterlib.structs.PoolUser(payment, stake)[source]
Bases:
tuple- payment: cardano_clusterlib.structs.AddressRecord[source]
Alias for field number 0
- stake: cardano_clusterlib.structs.AddressRecord[source]
Alias for field number 1
- class cardano_clusterlib.structs.ScriptTxIn(txins: List[cardano_clusterlib.structs.UTXOData], script_file: Union[str, pathlib.Path] = '', reference_txin: Optional[cardano_clusterlib.structs.UTXOData] = None, reference_type: str = '', collaterals: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]] = (), execution_units: Optional[Tuple[int, int]] = None, datum_file: Union[str, pathlib.Path] = '', datum_cbor_file: Union[str, pathlib.Path] = '', datum_value: str = '', inline_datum_present: bool = False, redeemer_file: Union[str, pathlib.Path] = '', redeemer_cbor_file: Union[str, pathlib.Path] = '', redeemer_value: str = '')[source]
Bases:
tupleData structure for Tx inputs that are combined with scripts (simple or Plutus).
- collaterals: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]][source]
Alias for field number 4
- reference_txin: Optional[cardano_clusterlib.structs.UTXOData][source]
Alias for field number 2
- txins: List[cardano_clusterlib.structs.UTXOData][source]
Alias for field number 0
- class cardano_clusterlib.structs.ScriptWithdrawal(txout: cardano_clusterlib.structs.TxOut, script_file: Union[str, pathlib.Path] = '', reference_txin: Optional[cardano_clusterlib.structs.UTXOData] = None, reference_type: str = '', collaterals: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]] = (), execution_units: Optional[Tuple[int, int]] = None, redeemer_file: Union[str, pathlib.Path] = '', redeemer_cbor_file: Union[str, pathlib.Path] = '', redeemer_value: str = '')[source]
Bases:
tupleData structure for withdrawals that are combined with Plutus scripts.
- collaterals: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]][source]
Alias for field number 4
- reference_txin: Optional[cardano_clusterlib.structs.UTXOData][source]
Alias for field number 2
- txout: cardano_clusterlib.structs.TxOut[source]
Alias for field number 0
- class cardano_clusterlib.structs.StakeAddrInfo(address, delegation, reward_account_balance)[source]
Bases:
tuple
- class cardano_clusterlib.structs.TxFiles(certificate_files, proposal_files, metadata_json_files, metadata_cbor_files, signing_key_files, auxiliary_script_files, metadata_json_detailed_schema)[source]
Bases:
tuple- auxiliary_script_files: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]][source]
Alias for field number 5
- certificate_files: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]][source]
Alias for field number 0
- metadata_cbor_files: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]][source]
Alias for field number 3
- metadata_json_files: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]][source]
Alias for field number 2
- class cardano_clusterlib.structs.TxOut(address, amount, coin, datum_hash, datum_hash_file, datum_hash_cbor_file, datum_hash_value, datum_embed_file, datum_embed_cbor_file, datum_embed_value, inline_datum_file, inline_datum_cbor_file, inline_datum_value, reference_script_file)[source]
Bases:
tuple
- class cardano_clusterlib.structs.TxRawOutput(txins, txouts, txouts_count, tx_files, out_file, fee, build_args, era, script_txins, script_withdrawals, complex_certs, mint, invalid_hereafter, invalid_before, withdrawals, change_address, return_collateral_txouts, total_collateral_amount, readonly_reference_txins, script_valid, required_signers, required_signer_hashes, combined_reference_txins)[source]
Bases:
tuple- combined_reference_txins: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]][source]
Alias for field number 22
- complex_certs: Union[List[cardano_clusterlib.structs.ComplexCert], Tuple[()]][source]
Alias for field number 10
- mint: Union[List[cardano_clusterlib.structs.Mint], Tuple[()]][source]
Alias for field number 11
- readonly_reference_txins: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]][source]
Alias for field number 18
- required_signers: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]][source]
Alias for field number 20
- return_collateral_txouts: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]][source]
Alias for field number 16
- script_txins: Union[List[cardano_clusterlib.structs.ScriptTxIn], Tuple[()]][source]
Alias for field number 8
- script_withdrawals: Union[List[cardano_clusterlib.structs.ScriptWithdrawal], Tuple[()]][source]
Alias for field number 9
- tx_files: cardano_clusterlib.structs.TxFiles[source]
Alias for field number 3
- txins: List[cardano_clusterlib.structs.UTXOData][source]
Alias for field number 0
- txouts: List[cardano_clusterlib.structs.TxOut][source]
Alias for field number 1
- withdrawals: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]][source]
Alias for field number 14
cardano_clusterlib.transaction_group module
Group of methods for working with transactions.
- class cardano_clusterlib.transaction_group.TransactionGroup(clusterlib_obj: types.ClusterLib)[source]
Bases:
object- assemble_tx(tx_body_file: Union[str, pathlib.Path], witness_files: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]], tx_name: str, destination_dir: Union[str, pathlib.Path] = '.') pathlib.Path[source]
Assemble a tx body and witness(es) to form a signed transaction.
- Parameters
tx_body_file – A path to file with transaction body.
witness_files – A list of paths to transaction witness files.
tx_name – A name of the transaction.
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A path to signed transaction file.
- Return type
Path
- build_multisig_script(script_name: str, script_type_arg: str, payment_vkey_files: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]], required: int = 0, slot: int = 0, slot_type_arg: str = '', destination_dir: Union[str, pathlib.Path] = '.') pathlib.Path[source]
Build a multi-signature script.
- Parameters
script_name – A name of the script.
script_type_arg – A script type, see MultiSigTypeArgs.
payment_vkey_files – A list of paths to payment vkey files.
required – A number of required keys for the “atLeast” script type (optional).
slot – A slot that sets script validity, depending on value of slot_type_arg (optional).
slot_type_arg – A slot validity type, see MultiSlotTypeArgs (optional).
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A path to the script file.
- Return type
Path
- build_raw_tx(src_address: str, tx_name: str, txins: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]] = (), txouts: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]] = (), readonly_reference_txins: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]] = (), script_txins: Union[List[cardano_clusterlib.structs.ScriptTxIn], Tuple[()]] = (), return_collateral_txouts: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]] = (), total_collateral_amount: Optional[int] = None, mint: Union[List[cardano_clusterlib.structs.Mint], Tuple[()]] = (), tx_files: Optional[cardano_clusterlib.structs.TxFiles] = None, complex_certs: Union[List[cardano_clusterlib.structs.ComplexCert], Tuple[()]] = (), fee: int = 0, required_signers: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]] = (), required_signer_hashes: Optional[List[str]] = None, ttl: Optional[int] = None, withdrawals: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]] = (), script_withdrawals: Union[List[cardano_clusterlib.structs.ScriptWithdrawal], Tuple[()]] = (), deposit: Optional[int] = None, invalid_hereafter: Optional[int] = None, invalid_before: Optional[int] = None, join_txouts: bool = True, destination_dir: Union[str, pathlib.Path] = '.') cardano_clusterlib.structs.TxRawOutput[source]
Balance inputs and outputs and build a raw transaction.
- Parameters
src_address – An address used for fee and inputs (if inputs not specified by txins).
tx_name – A name of the transaction.
txins – An iterable of structs.UTXOData, specifying input UTxOs (optional).
txouts – A list (iterable) of TxOuts, specifying transaction outputs (optional).
readonly_reference_txins – An iterable of structs.UTXOData, specifying input UTxOs to be referenced and used as readonly (optional).
script_txins – An iterable of ScriptTxIn, specifying input script UTxOs (optional).
return_collateral_txouts – A list (iterable) of TxOuts, specifying transaction outputs for excess collateral (optional).
total_collateral_amount – An integer indicating the total amount of collateral (optional).
mint – An iterable of Mint, specifying script minting data (optional).
tx_files – A structs.TxFiles tuple containing files needed for the transaction (optional).
complex_certs – An iterable of ComplexCert, specifying certificates script data (optional).
fee – A fee amount (optional).
required_signers – An iterable of filepaths of the signing keys whose signatures are required (optional).
required_signer_hashes – A list of hashes of the signing keys whose signatures are required (optional).
ttl – A last block when the transaction is still valid (deprecated in favor of invalid_hereafter, optional).
withdrawals – A list (iterable) of TxOuts, specifying reward withdrawals (optional).
script_withdrawals – An iterable of ScriptWithdrawal, specifying withdrawal script data (optional).
deposit – A deposit amount needed by the transaction (optional).
invalid_hereafter – A last block when the transaction is still valid (optional).
invalid_before – A first block when the transaction is valid (optional).
join_txouts – A bool indicating whether to aggregate transaction outputs by payment address (True by default).
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A tuple with transaction output details.
- Return type
- build_raw_tx_bare(out_file: Union[str, pathlib.Path], txouts: List[cardano_clusterlib.structs.TxOut], tx_files: cardano_clusterlib.structs.TxFiles, fee: int, txins: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]] = (), readonly_reference_txins: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]] = (), script_txins: Union[List[cardano_clusterlib.structs.ScriptTxIn], Tuple[()]] = (), return_collateral_txouts: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]] = (), total_collateral_amount: Optional[int] = None, mint: Union[List[cardano_clusterlib.structs.Mint], Tuple[()]] = (), complex_certs: Union[List[cardano_clusterlib.structs.ComplexCert], Tuple[()]] = (), required_signers: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]] = (), required_signer_hashes: Optional[List[str]] = None, ttl: Optional[int] = None, withdrawals: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]] = (), script_withdrawals: Union[List[cardano_clusterlib.structs.ScriptWithdrawal], Tuple[()]] = (), invalid_hereafter: Optional[int] = None, invalid_before: Optional[int] = None, script_valid: bool = True, join_txouts: bool = True) cardano_clusterlib.structs.TxRawOutput[source]
Build a raw transaction.
- Parameters
out_file – An output file.
txouts – A list (iterable) of TxOuts, specifying transaction outputs.
tx_files – A structs.TxFiles tuple containing files needed for the transaction.
fee – A fee amount.
txins – An iterable of structs.UTXOData, specifying input UTxOs (optional).
readonly_reference_txins – An iterable of structs.UTXOData, specifying input UTxOs to be referenced and used as readonly (optional).
script_txins – An iterable of ScriptTxIn, specifying input script UTxOs (optional).
return_collateral_txouts – A list (iterable) of TxOuts, specifying transaction outputs for excess collateral (optional).
total_collateral_amount – An integer indicating the total amount of collateral (optional).
mint – An iterable of Mint, specifying script minting data (optional).
complex_certs – An iterable of ComplexCert, specifying certificates script data (optional).
required_signers – An iterable of filepaths of the signing keys whose signatures are required (optional).
required_signer_hashes – A list of hashes of the signing keys whose signatures are required (optional).
ttl – A last block when the transaction is still valid (deprecated in favor of invalid_hereafter, optional).
withdrawals – A list (iterable) of TxOuts, specifying reward withdrawals (optional).
script_withdrawals – An iterable of ScriptWithdrawal, specifying withdrawal script data (optional).
invalid_hereafter – A last block when the transaction is still valid (optional).
invalid_before – A first block when the transaction is valid (optional).
script_valid – A bool indicating that the script is valid (True by default).
join_txouts – A bool indicating whether to aggregate transaction outputs by payment address (True by default).
- Returns
A tuple with transaction output details.
- Return type
- build_tx(src_address: str, tx_name: str, txins: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]] = (), txouts: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]] = (), readonly_reference_txins: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]] = (), script_txins: Union[List[cardano_clusterlib.structs.ScriptTxIn], Tuple[()]] = (), return_collateral_txouts: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]] = (), total_collateral_amount: Optional[int] = None, mint: Union[List[cardano_clusterlib.structs.Mint], Tuple[()]] = (), tx_files: Optional[cardano_clusterlib.structs.TxFiles] = None, complex_certs: Union[List[cardano_clusterlib.structs.ComplexCert], Tuple[()]] = (), change_address: str = '', fee_buffer: Optional[int] = None, required_signers: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]] = (), required_signer_hashes: Optional[List[str]] = None, withdrawals: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]] = (), script_withdrawals: Union[List[cardano_clusterlib.structs.ScriptWithdrawal], Tuple[()]] = (), deposit: Optional[int] = None, invalid_hereafter: Optional[int] = None, invalid_before: Optional[int] = None, witness_override: Optional[int] = None, script_valid: bool = True, calc_script_cost_file: Optional[Union[str, pathlib.Path]] = None, join_txouts: bool = True, destination_dir: Union[str, pathlib.Path] = '.', skip_asset_balancing: bool = False) cardano_clusterlib.structs.TxRawOutput[source]
Build a transaction.
- Parameters
src_address – An address used for fee and inputs (if inputs not specified by txins).
tx_name – A name of the transaction.
txins – An iterable of structs.UTXOData, specifying input UTxOs (optional).
txouts – A list (iterable) of TxOuts, specifying transaction outputs (optional).
readonly_reference_txins – An iterable of structs.UTXOData, specifying input UTxOs to be referenced and used as readonly (optional).
script_txins – An iterable of ScriptTxIn, specifying input script UTxOs (optional).
return_collateral_txouts – A list (iterable) of TxOuts, specifying transaction outputs for excess collateral (optional).
total_collateral_amount – An integer indicating the total amount of collateral (optional).
mint – An iterable of Mint, specifying script minting data (optional).
tx_files – A structs.TxFiles tuple containing files needed for the transaction (optional).
complex_certs – An iterable of ComplexCert, specifying certificates script data (optional).
change_address – A string with address where ADA in excess of the transaction fee will go to (src_address by default).
fee_buffer – A buffer for fee amount (optional).
required_signers – An iterable of filepaths of the signing keys whose signatures are required (optional).
required_signer_hashes – A list of hashes of the signing keys whose signatures are required (optional).
withdrawals – A list (iterable) of TxOuts, specifying reward withdrawals (optional).
script_withdrawals – An iterable of ScriptWithdrawal, specifying withdrawal script data (optional).
deposit – A deposit amount needed by the transaction (optional).
invalid_hereafter – A last block when the transaction is still valid (optional).
invalid_before – A first block when the transaction is valid (optional).
witness_override – An integer indicating real number of witnesses. Can be used to fix fee calculation (optional).
script_valid – A bool indicating that the script is valid (True by default).
calc_script_cost_file – A path for output of the Plutus script cost information (optional).
join_txouts – A bool indicating whether to aggregate transaction outputs by payment address (True by default).
destination_dir – A path to directory for storing artifacts (optional).
skip_asset_balancing – A bool indicating if assets balancing should be skipped (build command balance the assets automatically in newer versions).
- Returns
A tuple with transaction output details.
- Return type
- calculate_min_req_utxo(txouts: List[cardano_clusterlib.structs.TxOut]) cardano_clusterlib.structs.Value[source]
Calculate the minimum required UTxO for a single transaction output.
- Parameters
txouts – A list of TxOut records that correspond to a single transaction output (UTxO).
- Returns
A tuple describing the value.
- Return type
- calculate_min_value(multi_assets: List[cardano_clusterlib.structs.TxOut]) cardano_clusterlib.structs.Value[source]
Calculate the minimum value in for a transaction.
This was replaced by calculate_min_req_utxo for node 1.29.0+.
- Parameters
multi_assets – A list of TxOuts, specifying multi-assets.
- Returns
A tuple describing the value.
- Return type
- calculate_plutus_script_cost(src_address: str, tx_name: str, txins: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]] = (), txouts: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]] = (), readonly_reference_txins: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]] = (), script_txins: Union[List[cardano_clusterlib.structs.ScriptTxIn], Tuple[()]] = (), return_collateral_txouts: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]] = (), total_collateral_amount: Optional[int] = None, mint: Union[List[cardano_clusterlib.structs.Mint], Tuple[()]] = (), tx_files: Optional[cardano_clusterlib.structs.TxFiles] = None, complex_certs: Union[List[cardano_clusterlib.structs.ComplexCert], Tuple[()]] = (), change_address: str = '', fee_buffer: Optional[int] = None, required_signers: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]] = (), required_signer_hashes: Optional[List[str]] = None, withdrawals: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]] = (), script_withdrawals: Union[List[cardano_clusterlib.structs.ScriptWithdrawal], Tuple[()]] = (), deposit: Optional[int] = None, invalid_hereafter: Optional[int] = None, invalid_before: Optional[int] = None, witness_override: Optional[int] = None, script_valid: bool = True, calc_script_cost_file: Optional[Union[str, pathlib.Path]] = None, join_txouts: bool = True, destination_dir: Union[str, pathlib.Path] = '.') List[dict][source]
Calculate cost of Plutus scripts. Accepts the same arguments as build_tx.
- Parameters
src_address – An address used for fee and inputs (if inputs not specified by txins).
tx_name – A name of the transaction.
txins – An iterable of structs.UTXOData, specifying input UTxOs (optional).
txouts – A list (iterable) of TxOuts, specifying transaction outputs (optional).
readonly_reference_txins – An iterable of structs.UTXOData, specifying input UTxOs to be referenced and used as readonly (optional).
script_txins – An iterable of ScriptTxIn, specifying input script UTxOs (optional).
return_collateral_txouts – A list (iterable) of TxOuts, specifying transaction outputs for excess collateral (optional).
total_collateral_amount – An integer indicating the total amount of collateral (optional).
mint – An iterable of Mint, specifying script minting data (optional).
tx_files – A structs.TxFiles tuple containing files needed for the transaction (optional).
complex_certs – An iterable of ComplexCert, specifying certificates script data (optional).
change_address – A string with address where ADA in excess of the transaction fee will go to (src_address by default).
fee_buffer – A buffer for fee amount (optional).
required_signers – An iterable of filepaths of the signing keys whose signatures are required (optional).
required_signer_hashes – A list of hashes of the signing keys whose signatures are required (optional).
withdrawals – A list (iterable) of TxOuts, specifying reward withdrawals (optional).
script_withdrawals – An iterable of ScriptWithdrawal, specifying withdrawal script data (optional).
deposit – A deposit amount needed by the transaction (optional).
invalid_hereafter – A last block when the transaction is still valid (optional).
invalid_before – A first block when the transaction is valid (optional).
witness_override – An integer indicating real number of witnesses. Can be used to fix fee calculation (optional).
script_valid – A bool indicating that the script is valid (True by default).
calc_script_cost_file – A path for output of the Plutus script cost information (optional).
join_txouts – A bool indicating whether to aggregate transaction outputs by payment address (True by default).
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A Plutus scripts cost data.
- Return type
List[dict]
- calculate_tx_fee(src_address: str, tx_name: str, dst_addresses: Optional[List[str]] = None, txins: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]] = (), txouts: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]] = (), readonly_reference_txins: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]] = (), script_txins: Union[List[cardano_clusterlib.structs.ScriptTxIn], Tuple[()]] = (), return_collateral_txouts: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]] = (), total_collateral_amount: Optional[int] = None, mint: Union[List[cardano_clusterlib.structs.Mint], Tuple[()]] = (), tx_files: Optional[cardano_clusterlib.structs.TxFiles] = None, complex_certs: Union[List[cardano_clusterlib.structs.ComplexCert], Tuple[()]] = (), required_signers: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]] = (), required_signer_hashes: Optional[List[str]] = None, ttl: Optional[int] = None, withdrawals: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]] = (), script_withdrawals: Union[List[cardano_clusterlib.structs.ScriptWithdrawal], Tuple[()]] = (), invalid_hereafter: Optional[int] = None, invalid_before: Optional[int] = None, witness_count_add: int = 0, join_txouts: bool = True, destination_dir: Union[str, pathlib.Path] = '.') int[source]
Build “dummy” transaction and calculate (estimate) its fee.
- Parameters
src_address – An address used for fee and inputs (if inputs not specified by txins).
tx_name – A name of the transaction.
dst_addresses – A list of destination addresses (optional)
txins – An iterable of structs.UTXOData, specifying input UTxOs (optional).
txouts – A list (iterable) of TxOuts, specifying transaction outputs (optional).
readonly_reference_txins – An iterable of structs.UTXOData, specifying input UTxOs to be referenced and used as readonly (optional).
script_txins – An iterable of ScriptTxIn, specifying input script UTxOs (optional).
return_collateral_txouts – A list (iterable) of TxOuts, specifying transaction outputs for excess collateral (optional).
total_collateral_amount – An integer indicating the total amount of collateral (optional).
mint – An iterable of Mint, specifying script minting data (optional).
tx_files – A structs.TxFiles tuple containing files needed for the transaction (optional).
complex_certs – An iterable of ComplexCert, specifying certificates script data (optional).
required_signers – An iterable of filepaths of the signing keys whose signatures are required (optional).
required_signer_hashes – A list of hashes of the signing keys whose signatures are required (optional).
ttl – A last block when the transaction is still valid (deprecated in favor of invalid_hereafter, optional).
withdrawals – A list (iterable) of TxOuts, specifying reward withdrawals (optional).
script_withdrawals – An iterable of ScriptWithdrawal, specifying withdrawal script data (optional).
invalid_hereafter – A last block when the transaction is still valid (optional).
invalid_before – A first block when the transaction is valid (optional).
witness_count_add – A number of witnesses to add - workaround to make the fee calculation more precise.
join_txouts – A bool indicating whether to aggregate transaction outputs by payment address (True by default).
destination_dir – A path to directory for storing artifacts (optional).
- Returns
An estimated fee.
- Return type
int
- estimate_fee(txbody_file: Union[str, pathlib.Path], txin_count: int, txout_count: int, witness_count: int = 1, byron_witness_count: int = 0) int[source]
Estimate the minimum fee for a transaction.
- Parameters
txbody_file – A path to file with transaction body.
txin_count – A number of transaction inputs.
txout_count – A number of transaction outputs.
witness_count – A number of witnesses (optional).
byron_witness_count – A number of Byron witnesses (optional).
- Returns
An estimated fee.
- Return type
int
- get_hash_script_data(script_data_file: Optional[Union[str, pathlib.Path]] = None, script_data_cbor_file: Optional[Union[str, pathlib.Path]] = None, script_data_value: str = '') str[source]
Return the hash of script data.
- Parameters
script_data_file – A path to the JSON file containing the script data (optional).
script_data_cbor_file – A path to the CBOR file containing the script data (optional).
script_data_value – A value (in JSON syntax) for the script data (optional).
- Returns
A hash of script data.
- Return type
str
- get_policyid(script_file: Union[str, pathlib.Path]) str[source]
Calculate the PolicyId from the monetary policy script.
- Parameters
script_file – A path to the script file.
- Returns
A script policyId.
- Return type
str
- get_tx_deposit(tx_files: cardano_clusterlib.structs.TxFiles) int[source]
Get deposit amount for a transaction (based on certificates used for the TX).
- Parameters
tx_files – A structs.TxFiles tuple containing files needed for the transaction.
- Returns
A total deposit amount needed for the transaction.
- Return type
int
- get_txid(tx_body_file: Union[str, pathlib.Path] = '', tx_file: Union[str, pathlib.Path] = '') str[source]
Return the transaction identifier.
- Parameters
tx_body_file – A path to the transaction body file (JSON TxBody - optional).
tx_file – A path to the signed transaction file (JSON Tx - optional).
- Returns
A transaction ID.
- Return type
str
- send_funds(src_address: str, destinations: List[cardano_clusterlib.structs.TxOut], tx_name: str, tx_files: Optional[cardano_clusterlib.structs.TxFiles] = None, fee: Optional[int] = None, ttl: Optional[int] = None, deposit: Optional[int] = None, invalid_hereafter: Optional[int] = None, verify_tx: bool = True, destination_dir: Union[str, pathlib.Path] = '.') cardano_clusterlib.structs.TxRawOutput[source]
Send funds - convenience function for send_tx.
- Parameters
src_address – An address used for fee and inputs.
destinations – A list (iterable) of TxOuts, specifying transaction outputs.
tx_name – A name of the transaction.
tx_files – A structs.TxFiles tuple containing files needed for the transaction (optional).
fee – A fee amount (optional).
ttl – A last block when the transaction is still valid (deprecated in favor of invalid_hereafter, optional).
deposit – A deposit amount needed by the transaction (optional).
invalid_hereafter – A last block when the transaction is still valid (optional).
verify_tx – A bool indicating whether to verify the transaction made it to chain and resubmit the transaction if not (True by default).
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A tuple with transaction output details.
- Return type
- send_tx(src_address: str, tx_name: str, txins: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]] = (), txouts: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]] = (), readonly_reference_txins: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]] = (), script_txins: Union[List[cardano_clusterlib.structs.ScriptTxIn], Tuple[()]] = (), return_collateral_txouts: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]] = (), total_collateral_amount: Optional[int] = None, mint: Union[List[cardano_clusterlib.structs.Mint], Tuple[()]] = (), tx_files: Optional[cardano_clusterlib.structs.TxFiles] = None, complex_certs: Union[List[cardano_clusterlib.structs.ComplexCert], Tuple[()]] = (), fee: Optional[int] = None, required_signers: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]] = (), required_signer_hashes: Optional[List[str]] = None, ttl: Optional[int] = None, withdrawals: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]] = (), script_withdrawals: Union[List[cardano_clusterlib.structs.ScriptWithdrawal], Tuple[()]] = (), deposit: Optional[int] = None, invalid_hereafter: Optional[int] = None, invalid_before: Optional[int] = None, witness_count_add: int = 0, join_txouts: bool = True, verify_tx: bool = True, destination_dir: Union[str, pathlib.Path] = '.') cardano_clusterlib.structs.TxRawOutput[source]
Build, Sign and Submit a transaction.
Not recommended for complex transactions that involve Plutus scripts!
This function uses cardano-cli transaction build-raw to build the transaction. For more complex transactions that involve Plutus scripts, consider using build_tx. The build_tx uses cardano-cli transaction build and handles execution units and collateral return automatically.
- Parameters
src_address – An address used for fee and inputs (if inputs not specified by txins).
tx_name – A name of the transaction.
txins – An iterable of structs.UTXOData, specifying input UTxOs (optional).
txouts – A list (iterable) of TxOuts, specifying transaction outputs (optional).
readonly_reference_txins – An iterable of structs.UTXOData, specifying input UTxOs to be referenced and used as readonly (optional).
script_txins – An iterable of ScriptTxIn, specifying input script UTxOs (optional).
return_collateral_txouts – A list (iterable) of TxOuts, specifying transaction outputs for excess collateral (optional).
total_collateral_amount – An integer indicating the total amount of collateral (optional).
mint – An iterable of Mint, specifying script minting data (optional).
tx_files – A structs.TxFiles tuple containing files needed for the transaction (optional).
complex_certs – An iterable of ComplexCert, specifying certificates script data (optional).
fee – A fee amount (optional).
required_signers – An iterable of filepaths of the signing keys whose signatures are required (optional).
required_signer_hashes – A list of hashes of the signing keys whose signatures are required (optional).
ttl – A last block when the transaction is still valid (deprecated in favor of invalid_hereafter, optional).
withdrawals – A list (iterable) of TxOuts, specifying reward withdrawals (optional).
script_withdrawals – An iterable of ScriptWithdrawal, specifying withdrawal script data (optional).
deposit – A deposit amount needed by the transaction (optional).
invalid_hereafter – A last block when the transaction is still valid (optional).
invalid_before – A first block when the transaction is valid (optional).
witness_count_add – A number of witnesses to add - workaround to make the fee calculation more precise.
join_txouts – A bool indicating whether to aggregate transaction outputs by payment address (True by default).
verify_tx – A bool indicating whether to verify the transaction made it to chain and resubmit the transaction if not (True by default).
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A tuple with transaction output details.
- Return type
- sign_tx(signing_key_files: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]], tx_name: str, tx_body_file: Optional[Union[str, pathlib.Path]] = None, tx_file: Optional[Union[str, pathlib.Path]] = None, destination_dir: Union[str, pathlib.Path] = '.') pathlib.Path[source]
Sign a transaction.
- Parameters
signing_key_files – A list of paths to signing key files.
tx_name – A name of the transaction.
tx_body_file – A path to file with transaction body (optional).
tx_file – A path to file with transaction (for incremental signing, optional).
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A path to signed transaction file.
- Return type
Path
- submit_tx(tx_file: Union[str, pathlib.Path], txins: List[cardano_clusterlib.structs.UTXOData], wait_blocks: int = 2) None[source]
Submit a transaction, resubmit if the transaction didn’t make it to the chain.
- Parameters
tx_file – A path to signed transaction file.
txins – An iterable of structs.UTXOData, specifying input UTxOs.
wait_blocks – A number of new blocks to wait for (default = 2).
- submit_tx_bare(tx_file: Union[str, pathlib.Path]) None[source]
Submit a transaction, don’t do any verification that it made it to the chain.
- Parameters
tx_file – A path to signed transaction file.
- view_tx(tx_body_file: Union[str, pathlib.Path] = '', tx_file: Union[str, pathlib.Path] = '') str[source]
View a transaction.
- Parameters
tx_body_file – A path to the transaction body file (JSON TxBody - optional).
tx_file – A path to the signed transaction file (JSON Tx - optional).
- Returns
A transaction.
- Return type
str
- witness_tx(tx_body_file: Union[str, pathlib.Path], witness_name: str, signing_key_files: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]] = (), destination_dir: Union[str, pathlib.Path] = '.') pathlib.Path[source]
Create a transaction witness.
- Parameters
tx_body_file – A path to file with transaction body.
witness_name – A name of the transaction witness.
signing_key_files – A list of paths to signing key files (optional).
destination_dir – A path to directory for storing artifacts (optional).
- Returns
A path to transaction witness file.
- Return type
Path
cardano_clusterlib.txtools module
Tools used by ClusterLib for constructing transactions.
- cardano_clusterlib.txtools.calculate_utxos_balance(utxos: Union[List[cardano_clusterlib.structs.UTXOData], List[cardano_clusterlib.structs.TxOut]], coin: str = 'lovelace') int[source]
Calculate sum of UTxO balances.
- Parameters
utxos – A list of UTxO data (either structs.UTXOData or structs.TxOut).
coin – A coin name (asset IDs).
- Returns
A total balance.
- Return type
int
- cardano_clusterlib.txtools.collect_data_for_build(clusterlib_obj: types.ClusterLib, src_address: str, txins: Union[List[cardano_clusterlib.structs.UTXOData], Tuple[()]] = (), txouts: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]] = (), script_txins: Union[List[cardano_clusterlib.structs.ScriptTxIn], Tuple[()]] = (), mint: Union[List[cardano_clusterlib.structs.Mint], Tuple[()]] = (), tx_files: Optional[cardano_clusterlib.structs.TxFiles] = None, complex_certs: Union[List[cardano_clusterlib.structs.ComplexCert], Tuple[()]] = (), fee: int = 0, withdrawals: Union[List[cardano_clusterlib.structs.TxOut], Tuple[()]] = (), script_withdrawals: Union[List[cardano_clusterlib.structs.ScriptWithdrawal], Tuple[()]] = (), deposit: Optional[int] = None, lovelace_balanced: bool = False, skip_asset_balancing: bool = False) cardano_clusterlib.structs.DataForBuild[source]
Collect data (txins, txouts, withdrawals) needed for building a transaction.
- Parameters
clusterlib_obj – An instance of ClusterLib.
src_address – An address used for fee and inputs (if inputs not specified by txins).
txins – An iterable of structs.UTXOData, specifying input UTxOs (optional).
txouts – A list (iterable) of TxOuts, specifying transaction outputs (optional).
script_txins – An iterable of ScriptTxIn, specifying input script UTxOs (optional).
mint – An iterable of Mint, specifying script minting data (optional).
tx_files – A structs.TxFiles tuple containing files needed for the transaction (optional).
complex_certs – An iterable of ComplexCert, specifying certificates script data (optional).
fee – A fee amount (optional).
withdrawals – A list (iterable) of TxOuts, specifying reward withdrawals (optional).
script_withdrawals – An iterable of ScriptWithdrawal, specifying withdrawal script data (optional).
deposit – A deposit amount needed by the transaction (optional).
lovelace_balanced – A bool indicating whether Lovelace ins/outs are balanced (by build command).
skip_asset_balancing – A bool indicating if assets balancing should be skipped (build command balance the assets automatically in newer versions).
- Returns
A tuple with data for build(-raw) commands.
- Return type
- cardano_clusterlib.txtools.filter_utxo_with_highest_amount(utxos: List[cardano_clusterlib.structs.UTXOData], coin: str = 'lovelace') cardano_clusterlib.structs.UTXOData[source]
Return data for UTxO with the highest amount.
- Parameters
utxos – A list of UTxO data.
coin – A coin name (asset IDs).
- Returns
An UTxO record with the highest amount.
- Return type
- cardano_clusterlib.txtools.filter_utxos(utxos: List[cardano_clusterlib.structs.UTXOData], utxo_hash: str = '', utxo_ix: Optional[int] = None, amount: Optional[int] = None, address: str = '', coin: str = '', datum_hash: str = '', inline_datum_hash: str = '') List[cardano_clusterlib.structs.UTXOData][source]
Get UTxO records that match given filtering criteria.
- Parameters
utxos – A list of UTxO data.
utxo_hash – A transaction identifier (optional).
utxo_ix – A UTxO index (optional).
amount – An amount of coin (optional).
address – A payment address (optional).
coin – A coin name (asset ID; optional).
datum_hash – A datum hash (optional).
inline_datum_hash – An inline datum hash (optional).
- Returns
UTxO records that match given filtering criteria.
- Return type
- cardano_clusterlib.txtools.get_joined_txouts(txouts: List[cardano_clusterlib.structs.TxOut]) List[List[cardano_clusterlib.structs.TxOut]][source]
Return list of joined `TxOut`s.
- cardano_clusterlib.txtools.get_utxo(utxo_dict: dict, address: str = '', coins: Union[list, tuple, set, frozenset] = ()) List[cardano_clusterlib.structs.UTXOData][source]
Return UTxO info for payment address.
- Parameters
utxo_dict – A JSON output of query utxo.
address – A payment address.
coins – A list (iterable) of coin names (asset IDs).
- Returns
A list of UTxO data.
- Return type
List[structs.UTXOData]
cardano_clusterlib.types module
Module contents
Imports.
- class cardano_clusterlib.ClusterLib(state_dir: Union[str, pathlib.Path], protocol: str = 'cardano', tx_era: str = '', slots_offset: int = 0, socket_path: Union[str, pathlib.Path] = '')[source]
Bases:
objectMethods for working with cardano cluster using cardano-cli..
- slots_offset[source]
Difference in slots between cluster’s start era and current era (e.g. Byron->Mary)
- socket_path[source]
A path to socket file for communication with the node. This overrides the CARDANO_NODE_SOCKET_PATH environment variable.
- cli(cli_args: List[str], timeout: Optional[float] = None) cardano_clusterlib.structs.CLIOut[source]
Run the cardano-cli command.
- Parameters
cli_args – A list of arguments for cardano-cli.
timeout – A timeout for the command, in seconds (optional).
- Returns
A tuple containing command stdout and stderr.
- Return type
- property g_address: cardano_clusterlib.address_group.AddressGroup[source]
Address group.
- property g_genesis: cardano_clusterlib.genesis_group.GenesisGroup[source]
Genesis group.
- property g_governance: cardano_clusterlib.governance_group.GovernanceGroup[source]
Governance group.
- property g_key: cardano_clusterlib.key_group.KeyGroup[source]
Key group.
- property g_node: cardano_clusterlib.node_group.NodeGroup[source]
Node group.
- property g_query: cardano_clusterlib.query_group.QueryGroup[source]
Query group.
- property g_stake_address: cardano_clusterlib.stake_address_group.StakeAddressGroup[source]
Stake address group.
- property g_stake_pool: cardano_clusterlib.stake_pool_group.StakePoolGroup[source]
Stake pool group.
- property g_transaction: cardano_clusterlib.transaction_group.TransactionGroup[source]
Transaction group.
- poll_new_epoch(exp_epoch: int, padding_seconds: int = 0) None[source]
Wait for new epoch(s) by polling current epoch every 3 sec.
Can be used only for waiting up to 3000 sec + padding seconds.
- Parameters
exp_epoch – An epoch number to wait for.
padding_seconds – A number of additional seconds to wait for (optional).
- set_socket_path(socket_path: Optional[Union[str, pathlib.Path]]) None[source]
Set a path to socket file for communication with the node.
- time_from_epoch_start(tip: Optional[dict] = None) float[source]
How many seconds passed from start of the current epoch.
- time_to_epoch_end(tip: Optional[dict] = None) float[source]
How many seconds to go to start of a new epoch.
- wait_for_block(block: int) int[source]
Wait for block number.
- Parameters
block – A block number to wait for.
- Returns
A block number of last added block.
- Return type
int
- wait_for_new_block(new_blocks: int = 1) int[source]
Wait for new block(s) to be created.
- Parameters
new_blocks – A number of new blocks to wait for (optional).
- Returns
A block number of last added block.
- Return type
int