cardano_clusterlib package

Submodules

cardano_clusterlib.clusterlib module

Wrapper for cardano-cli for working with cardano cluster.

class cardano_clusterlib.clusterlib.AddressInfo(address, era, encoding, type, base16)[source]

Bases: tuple

address: str[source]

Alias for field number 0

base16: str[source]

Alias for field number 4

encoding: str[source]

Alias for field number 2

era: str[source]

Alias for field number 1

type: str[source]

Alias for field number 3

class cardano_clusterlib.clusterlib.AddressRecord(address, vkey_file, skey_file)[source]

Bases: tuple

address: str[source]

Alias for field number 0

skey_file: pathlib.Path[source]

Alias for field number 2

vkey_file: pathlib.Path[source]

Alias for field number 1

exception cardano_clusterlib.clusterlib.CLIError[source]

Bases: Exception

class cardano_clusterlib.clusterlib.CLIOut(stdout, stderr)[source]

Bases: tuple

stderr: bytes[source]

Alias for field number 1

stdout: bytes[source]

Alias for field number 0

class cardano_clusterlib.clusterlib.ClusterLib(state_dir: Union[str, pathlib.Path], protocol: str = 'cardano', tx_era: str = '', slots_offset: int = 0)[source]

Bases: object

Methods for working with cardano cluster using cardano-cli..

state_dir[source]

A directory with cluster state files (keys, config files, logs, …).

protocol[source]

A cluster protocol - full cardano mode by default.

tx_era[source]

An era used for transactions, by default same as network Era.

slots_offset[source]

Difference in slots between cluster’s start era and current era (e.g. Byron->Mary)

address_info(address: str)cardano_clusterlib.clusterlib.AddressInfo[source]

View a transaction.

Parameters

address – A Cardano address.

Returns

A tuple containing address info.

Return type

AddressInfo

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.clusterlib.UTXOData], Tuple[()]] = (), txouts: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), tx_files: Optional[cardano_clusterlib.clusterlib.TxFiles] = None, fee: int = 0, ttl: Optional[int] = None, withdrawals: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), deposit: Optional[int] = None, invalid_hereafter: Optional[int] = None, invalid_before: Optional[int] = None, mint: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), join_txouts: bool = True, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.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 UTXOData, specifying input UTxOs (optional).

  • txouts – A list (iterable) of TxOuts, specifying transaction outputs (optional).

  • tx_files – A 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).

  • withdrawals – A list (iterable) of TxOuts, specifying reward withdrawals (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).

  • mint – A list (iterable) of TxOuts, specifying minted tokens (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

TxRawOutput

build_raw_tx_bare(out_file: Union[str, pathlib.Path], txouts: List[cardano_clusterlib.clusterlib.TxOut], tx_files: cardano_clusterlib.clusterlib.TxFiles, fee: int, txins: Union[List[cardano_clusterlib.clusterlib.UTXOData], Tuple[()]] = (), plutus_txins: Union[List[cardano_clusterlib.clusterlib.PlutusTxIn], Tuple[()]] = (), plutus_mint: Union[List[cardano_clusterlib.clusterlib.PlutusMint], Tuple[()]] = (), ttl: Optional[int] = None, withdrawals: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), invalid_hereafter: Optional[int] = None, invalid_before: Optional[int] = None, mint: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), script_valid: bool = True, join_txouts: bool = True)cardano_clusterlib.clusterlib.TxRawOutput[source]

Build a raw transaction.

Parameters
  • out_file – An output file.

  • txouts – A list (iterable) of TxOuts, specifying transaction outputs.

  • tx_files – A TxFiles tuple containing files needed for the transaction.

  • fee – A fee amount.

  • txins – An iterable of UTXOData, specifying input UTxOs (optional).

  • plutus_txins – An iterable of PlutusTxIn, specifying input Plutus UTxOs (optional).

  • plutus_mint – An iterable of PlutusMint, specifying Plutus minting data (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).

  • invalid_hereafter – A last block when the transaction is still valid (optional).

  • invalid_before – A first block when the transaction is valid (optional).

  • mint – A list (iterable) of TxOuts, specifying minted tokens (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

TxRawOutput

build_tx(src_address: str, tx_name: str, tx_files: cardano_clusterlib.clusterlib.TxFiles, txins: Union[List[cardano_clusterlib.clusterlib.UTXOData], Tuple[()]] = (), txouts: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), change_address: str = '', fee_buffer: Optional[int] = None, plutus_txins: Union[List[cardano_clusterlib.clusterlib.PlutusTxIn], Tuple[()]] = (), plutus_mint: Union[List[cardano_clusterlib.clusterlib.PlutusMint], Tuple[()]] = (), withdrawals: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), deposit: Optional[int] = None, invalid_hereafter: Optional[int] = None, invalid_before: Optional[int] = None, mint: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), witness_override: Optional[int] = None, script_valid: bool = True, join_txouts: bool = True, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.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.

  • tx_files – A TxFiles tuple containing files needed for the transaction.

  • txins – An iterable of UTXOData, specifying input UTxOs (optional).

  • txouts – A list (iterable) of TxOuts, specifying transaction outputs (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).

  • plutus_txins – An iterable of PlutusTxIn, specifying input Plutus UTxOs (optional).

  • plutus_mint – An iterable of PlutusMint, specifying Plutus minting data (optional).

  • withdrawals – A list (iterable) of TxOuts, specifying reward withdrawals (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).

  • mint – A list (iterable) of TxOuts, specifying minted tokens (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).

  • destination_dir – A path to directory for storing artifacts (optional).

Returns

A tuple with transaction output details.

Return type

TxRawOutput

calculate_min_req_utxo(txouts: List[cardano_clusterlib.clusterlib.TxOut])cardano_clusterlib.clusterlib.Value[source]

Calculate the minimum required UTxO for a transaction output.

Parameters

txouts – A list of TxOuts for given address.

Returns

A tuple describing the value.

Return type

Value

calculate_min_value(multi_assets: List[cardano_clusterlib.clusterlib.TxOut])cardano_clusterlib.clusterlib.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

Value

calculate_tx_fee(src_address: str, tx_name: str, dst_addresses: Optional[List[str]] = None, txins: Union[List[cardano_clusterlib.clusterlib.UTXOData], Tuple[()]] = (), txouts: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), tx_files: Optional[cardano_clusterlib.clusterlib.TxFiles] = None, ttl: Optional[int] = None, withdrawals: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), invalid_hereafter: Optional[int] = None, mint: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), witness_count_add: int = 0, join_txouts: bool = True, destination_dir: Union[str, pathlib.Path] = '.') → int[source]

Build “dummy” transaction and calculate (estimate) it’s 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 UTXOData, specifying input UTxOs (optional).

  • txouts – A list (iterable) of TxOuts, specifying transaction outputs (optional).

  • tx_files – A TxFiles tuple containing files needed for the transaction (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).

  • invalid_hereafter – A last block when the transaction is still valid (optional).

  • mint – A list (iterable) of TxOuts, specifying minted tokens (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

calculate_tx_ttl() → int[source]

Calculate ttl for a transaction.

cli(cli_args: List[str])cardano_clusterlib.clusterlib.CLIOut[source]

Run the cardano-cli command.

Parameters

cli_args – A list of arguments for cardano-cli.

Returns

A tuple containing command stdout and stderr.

Return type

CLIOut

cli_base(cli_args: List[str])cardano_clusterlib.clusterlib.CLIOut[source]

Run a command.

Parameters

cli_args – A list consisting of command and it’s arguments.

Returns

A tuple containing command stdout and stderr.

Return type

CLIOut

create_stake_pool(pool_data: cardano_clusterlib.clusterlib.PoolData, pool_owners: List[cardano_clusterlib.clusterlib.PoolUser], tx_name: str, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.PoolCreationOutput[source]

Create and register a stake pool.

Parameters
  • pool_data – A PoolData tuple cointaining info about the stake pool.

  • pool_owners – A list of 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

PoolCreationOutput

deregister_stake_pool(pool_owners: List[cardano_clusterlib.clusterlib.PoolUser], cold_key_pair: cardano_clusterlib.clusterlib.ColdKeyPair, epoch: int, pool_name: str, tx_name: str, destination_dir: Union[str, pathlib.Path] = '.') → Tuple[pathlib.Path, cardano_clusterlib.clusterlib.TxRawOutput][source]

Deregister a stake pool.

Parameters
  • pool_owners – A list of PoolUser structures containing pool user addresses and keys.

  • cold_key_pair – A 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, TxRawOutput]

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

gen_cold_key_pair_and_counter(node_name: str, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.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

ColdKeyPair

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

gen_kes_key_pair(node_name: str, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.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

KeyPair

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_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_payment_addr(addr_name: str, payment_vkey_file: Union[str, pathlib.Path], stake_vkey_file: Optional[Union[str, pathlib.Path]] = 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_file – A path to corresponding vkey file.

  • stake_vkey_file – A path to corresponding stake vkey file (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, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.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).

  • destination_dir – A path to directory for storing artifacts (optional).

Returns

A tuple containing the address and key pair.

Return type

AddressRecord

gen_payment_key_pair(key_name: str, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.KeyPair[source]

Generate an 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

KeyPair

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.clusterlib.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 PoolData tuple cointaining 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 acount vkey file (optional).

  • destination_dir – A path to directory for storing artifacts (optional).

Returns

A path to the generated certificate.

Return type

Path

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

gen_stake_addr(addr_name: str, stake_vkey_file: Union[str, pathlib.Path], 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.

  • 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.clusterlib.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.

Return type

AddressRecord

gen_stake_addr_delegation_cert(addr_name: str, stake_vkey_file: Union[str, pathlib.Path], cold_vkey_file: Optional[Union[str, pathlib.Path]] = None, stake_pool_id: Optional[str] = None, 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.

  • 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: Union[str, pathlib.Path], 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.

  • 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: Union[str, pathlib.Path], 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.

  • 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.clusterlib.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

KeyPair

gen_update_proposal(cli_args: Union[list, tuple, set], 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

gen_vrf_key_pair(node_name: str, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.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

KeyPair

property genesis_keys[source]

Return tuple with genesis-related keys.

property genesis_utxo_addr[source]

Produce a genesis UTxO address.

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.

Returns

A total balance.

Return type

int

get_address_deposit() → int[source]

Return stake address deposit amount.

get_block_no() → int[source]

Return block number of last block that was successfully applied to the ledger.

get_epoch() → int[source]

Return epoch of last block that was successfully applied to the ledger.

get_era() → str[source]

Return network era.

get_hash_script_data(script_data_file: Union[str, pathlib.Path] = '', script_data_value: str = '') → str[source]

Return the hash of script data.

Parameters
  • script_data_file – A path to the 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_kes_period() → int[source]

Return last block KES period.

get_ledger_state() → dict[source]

Return the current ledger state info.

get_payment_vkey_hash(payment_vkey_file: Union[str, pathlib.Path]) → str[source]

Return the hash of an address key.

Parameters

payment_vkey_file – A path to payment vkey file.

Returns

A generated hash.

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_pool_deposit() → int[source]

Return stake pool deposit amount.

get_pool_params(stake_pool_id: str)cardano_clusterlib.clusterlib.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_protocol_params() → dict[source]

Return the current protocol parameters.

get_protocol_state() → dict[source]

Return the current protocol state info.

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.clusterlib.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

StakeAddrInfo

get_stake_distribution() → Dict[str, float][source]

Return current aggregated stake distribution per stake pool.

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

get_stake_snapshot(stake_pool_id: str) → Dict[str, int][source]

Return the three stake snapshots for a pool, plus the total active stake.

Parameters

stake_pool_id – An ID of the stake pool (Bech32-encoded or hex-encoded).

Returns

A stake snapshot data.

Return type

Dict

get_tip() → dict[source]

Return current tip - last block successfully applied to the ledger.

get_tx_deposit(tx_files: cardano_clusterlib.clusterlib.TxFiles) → int[source]

Get deposit amount for a transaction (based on certificates used for the TX).

Parameters

tx_files – A TxFiles tuple containing files needed for the transaction.

Returns

A total deposit amount needed for the transaction.

Return type

int

get_tx_ins_outs(src_address: str, tx_files: cardano_clusterlib.clusterlib.TxFiles, txins: Union[List[cardano_clusterlib.clusterlib.UTXOData], Tuple[()]] = (), txouts: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), fee: int = 0, deposit: Optional[int] = None, withdrawals: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), mint: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), lovelace_balanced: bool = False) → Tuple[list, list][source]

Return list of transaction’s inputs and outputs.

Parameters
  • src_address – An address used for fee and inputs (if inputs not specified by txins).

  • tx_files – A TxFiles tuple containing files needed for the transaction.

  • txins – An iterable of UTXOData, specifying input UTxOs (optional).

  • txouts – A list (iterable) of TxOuts, specifying transaction outputs (optional).

  • fee – A fee amount (optional).

  • deposit – A deposit amount needed by the transaction (optional).

  • withdrawals – A list (iterable) of TxOuts, specifying reward withdrawals (optional).

  • mint – A list (iterable) of TxOuts, specifying minted tokens (optional).

Returns

A tuple of list of transaction inputs and list of transaction

outputs.

Return type

Tuple[list, list]

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

get_utxo(address: str = '', txin: str = '', coins: Union[list, tuple, set] = (), decode_names: bool = True) → List[cardano_clusterlib.clusterlib.UTXOData][source]

Return UTxO info for payment address.

Parameters
  • address – A payment address.

  • txin – A transaction input (TxId#TxIx).

  • coins – A list (iterable) of coin names (asset IDs).

  • decode_names – A bool indicating whether to decode asset names (True by default).

Returns

A list of UTxO data.

Return type

List[UTXOData]

get_utxo_with_highest_amount(address: str, coin: str = 'lovelace')cardano_clusterlib.clusterlib.UTXOData[source]

Return data for UTxO with highest amount.

Parameters

address – A payment address string.

Returns

An UTxO record with the highest amount.

Return type

UTXOData

get_withdrawals(withdrawals: List[cardano_clusterlib.clusterlib.TxOut]) → List[cardano_clusterlib.clusterlib.TxOut][source]

Return list of resolved reward withdrawals.

The TxOut.amount can be ‘-1’, meaning all available funds.

Parameters

withdrawals – A list (iterable) of TxOuts, specifying reward withdrawals.

Returns

A list of TxOuts, specifying resolved reward withdrawals.

Return type

List[TxOut]

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).

query_cli(cli_args: Union[list, tuple, set]) → str[source]

Run the cardano-cli query command.

refresh_pparams_file() → None[source]

Refresh protocol parameters file.

register_stake_pool(pool_data: cardano_clusterlib.clusterlib.PoolData, pool_owners: List[cardano_clusterlib.clusterlib.PoolUser], vrf_vkey_file: Union[str, pathlib.Path], cold_key_pair: cardano_clusterlib.clusterlib.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.clusterlib.TxRawOutput][source]

Register a stake pool.

Parameters
  • pool_data – A PoolData tuple cointaining info about the stake pool.

  • pool_owners – A list of PoolUser structures containing pool user addresses and keys.

  • vrf_vkey_file – A path to node VRF vkey file.

  • cold_key_pair – A 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, TxRawOutput]

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

send_funds(src_address: str, destinations: List[cardano_clusterlib.clusterlib.TxOut], tx_name: str, tx_files: Optional[cardano_clusterlib.clusterlib.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.clusterlib.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 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

TxRawOutput

send_tx(src_address: str, tx_name: str, txins: Union[List[cardano_clusterlib.clusterlib.UTXOData], Tuple[()]] = (), txouts: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), tx_files: Optional[cardano_clusterlib.clusterlib.TxFiles] = None, fee: Optional[int] = None, ttl: Optional[int] = None, withdrawals: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), deposit: Optional[int] = None, invalid_hereafter: Optional[int] = None, invalid_before: Optional[int] = None, join_txouts: bool = True, verify_tx: bool = True, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.TxRawOutput[source]

Build, Sign and Submit 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 UTXOData, specifying input UTxOs (optional).

  • txouts – A list (iterable) of TxOuts, specifying transaction outputs (optional).

  • tx_files – A 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).

  • withdrawals – A list (iterable) of TxOuts, specifying reward withdrawals (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).

  • 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

TxRawOutput

sign_tx(tx_body_file: Union[str, pathlib.Path], signing_key_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]

Sign a transaction.

Parameters
  • tx_body_file – A path to file with transaction body.

  • signing_key_files – A list of paths to signing key 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

submit_tx(tx_file: Union[str, pathlib.Path], txins: List[cardano_clusterlib.clusterlib.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 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.

submit_update_proposal(cli_args: Union[list, tuple, set], 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.clusterlib.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

TxRawOutput

time_from_epoch_start() → float[source]

How many seconds passed from start of the current epoch.

time_to_epoch_end() → float[source]

How many seconds to go to start of a new epoch.

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

wait_for_new_block(new_blocks: int = 1) → None[source]

Wait for new block(s) to be created.

Parameters

new_blocks – A number of new blocks to wait for (optional).

wait_for_new_epoch(new_epochs: int = 1, padding_seconds: int = 0) → None[source]

Wait for new epoch(s).

Parameters
  • new_epochs – A number of new epochs to wait for (optional).

  • padding_seconds – A number of additional seconds to wait for (optional).

wait_for_slot(slot: int) → None[source]

Wait for slot number.

Parameters

slot – A slot number to wait for.

withdraw_reward(stake_addr_record: cardano_clusterlib.clusterlib.AddressRecord, dst_addr_record: cardano_clusterlib.clusterlib.AddressRecord, tx_name: str, verify: bool = True, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.TxRawOutput[source]

Withdraw reward to payment address.

Parameters
  • stake_addr_record – An AddressRecord tuple for the stake address with reward.

  • dst_addr_record – An 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).

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

class cardano_clusterlib.clusterlib.ColdKeyPair(vkey_file, skey_file, counter_file)[source]

Bases: tuple

counter_file: pathlib.Path[source]

Alias for field number 2

skey_file: pathlib.Path[source]

Alias for field number 1

vkey_file: pathlib.Path[source]

Alias for field number 0

class cardano_clusterlib.clusterlib.Eras[source]

Bases: object

ALLEGRA = 'allegra'[source]
ALONZO = 'alonzo'[source]
MARY = 'mary'[source]
SHELLEY = 'shelley'[source]
class cardano_clusterlib.clusterlib.GenesisKeys(genesis_utxo_vkey, genesis_utxo_skey, genesis_vkeys, delegate_skeys)[source]

Bases: tuple

delegate_skeys: List[pathlib.Path][source]

Alias for field number 3

genesis_utxo_skey: pathlib.Path[source]

Alias for field number 1

genesis_utxo_vkey: pathlib.Path[source]

Alias for field number 0

genesis_vkeys: List[pathlib.Path][source]

Alias for field number 2

class cardano_clusterlib.clusterlib.KeyPair(vkey_file, skey_file)[source]

Bases: tuple

skey_file: pathlib.Path[source]

Alias for field number 1

vkey_file: pathlib.Path[source]

Alias for field number 0

class cardano_clusterlib.clusterlib.MultiSigTypeArgs[source]

Bases: object

ALL = 'all'[source]
ANY = 'any'[source]
AT_LEAST = 'atLeast'[source]
class cardano_clusterlib.clusterlib.MultiSlotTypeArgs[source]

Bases: object

AFTER = 'after'[source]
BEFORE = 'before'[source]
class cardano_clusterlib.clusterlib.PlutusMint(txins, collaterals, script_file, execution_units, redeemer_file, redeemer_value)[source]

Bases: tuple

collaterals: List[cardano_clusterlib.clusterlib.UTXOData][source]

Alias for field number 1

execution_units: Optional[Tuple[int, int]][source]

Alias for field number 3

redeemer_file: Union[str, pathlib.Path][source]

Alias for field number 4

redeemer_value: str[source]

Alias for field number 5

script_file: Union[str, pathlib.Path][source]

Alias for field number 2

txins: List[cardano_clusterlib.clusterlib.UTXOData][source]

Alias for field number 0

class cardano_clusterlib.clusterlib.PlutusTxIn(txins, collaterals, script_file, execution_units, datum_file, datum_value, redeemer_file, redeemer_value)[source]

Bases: tuple

collaterals: List[cardano_clusterlib.clusterlib.UTXOData][source]

Alias for field number 1

datum_file: Union[str, pathlib.Path][source]

Alias for field number 4

datum_value: str[source]

Alias for field number 5

execution_units: Optional[Tuple[int, int]][source]

Alias for field number 3

redeemer_file: Union[str, pathlib.Path][source]

Alias for field number 6

redeemer_value: str[source]

Alias for field number 7

script_file: Union[str, pathlib.Path][source]

Alias for field number 2

txins: List[cardano_clusterlib.clusterlib.UTXOData][source]

Alias for field number 0

class cardano_clusterlib.clusterlib.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.clusterlib.ColdKeyPair[source]

Alias for field number 2

kes_key_pair: Optional[cardano_clusterlib.clusterlib.KeyPair][source]

Alias for field number 7

pool_data: cardano_clusterlib.clusterlib.PoolData[source]

Alias for field number 4

pool_owners: List[cardano_clusterlib.clusterlib.PoolUser][source]

Alias for field number 5

pool_reg_cert_file: pathlib.Path[source]

Alias for field number 3

stake_pool_id: str[source]

Alias for field number 0

tx_raw_output: cardano_clusterlib.clusterlib.TxRawOutput[source]

Alias for field number 6

vrf_key_pair: cardano_clusterlib.clusterlib.KeyPair[source]

Alias for field number 1

class cardano_clusterlib.clusterlib.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

pool_cost: int[source]

Alias for field number 2

pool_margin: float[source]

Alias for field number 3

pool_metadata_hash: str[source]

Alias for field number 5

pool_metadata_url: str[source]

Alias for field number 4

pool_name: str[source]

Alias for field number 0

pool_pledge: int[source]

Alias for field number 1

pool_relay_dns: str[source]

Alias for field number 6

pool_relay_ipv4: str[source]

Alias for field number 7

pool_relay_port: int[source]

Alias for field number 8

class cardano_clusterlib.clusterlib.PoolParamsTop(pool_params, future_pool_params, retiring)[source]

Bases: tuple

future_pool_params: dict[source]

Alias for field number 1

pool_params: dict[source]

Alias for field number 0

retiring: Optional[int][source]

Alias for field number 2

class cardano_clusterlib.clusterlib.PoolUser(payment, stake)[source]

Bases: tuple

payment: cardano_clusterlib.clusterlib.AddressRecord[source]

Alias for field number 0

stake: cardano_clusterlib.clusterlib.AddressRecord[source]

Alias for field number 1

class cardano_clusterlib.clusterlib.Protocols[source]

Bases: object

CARDANO = 'cardano'[source]
SHELLEY = 'shelley'[source]
class cardano_clusterlib.clusterlib.ScriptFiles(txin_scripts, minting_scripts, certificate_scripts, withdrawal_scripts, auxiliary_scripts)[source]

Bases: tuple

auxiliary_scripts: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]][source]

Alias for field number 4

certificate_scripts: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]][source]

Alias for field number 2

minting_scripts: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]][source]

Alias for field number 1

txin_scripts: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]][source]

Alias for field number 0

withdrawal_scripts: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]][source]

Alias for field number 3

class cardano_clusterlib.clusterlib.StakeAddrInfo(address, delegation, reward_account_balance)[source]

Bases: tuple

address: str[source]

Alias for field number 0

delegation: str[source]

Alias for field number 1

reward_account_balance: int[source]

Alias for field number 2

class cardano_clusterlib.clusterlib.TxFiles(certificate_files, proposal_files, metadata_json_files, metadata_cbor_files, script_files, signing_key_files)[source]

Bases: tuple

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

proposal_files: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]][source]

Alias for field number 1

script_files: Union[cardano_clusterlib.clusterlib.ScriptFiles, Tuple[()]][source]

Alias for field number 4

signing_key_files: Union[List[str], List[pathlib.Path], Set[str], Set[pathlib.Path], Tuple[()]][source]

Alias for field number 5

class cardano_clusterlib.clusterlib.TxOut(address, amount, coin, datum_hash)[source]

Bases: tuple

address: str[source]

Alias for field number 0

amount: int[source]

Alias for field number 1

coin: str[source]

Alias for field number 2

datum_hash: str[source]

Alias for field number 3

class cardano_clusterlib.clusterlib.TxRawOutput(txins, txouts, tx_files, out_file, fee, plutus_txins, plutus_mint, invalid_hereafter, invalid_before, withdrawals, mint, change_address)[source]

Bases: tuple

change_address: str[source]

Alias for field number 11

fee: int[source]

Alias for field number 4

invalid_before: Optional[int][source]

Alias for field number 8

invalid_hereafter: Optional[int][source]

Alias for field number 7

mint: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]][source]

Alias for field number 10

out_file: pathlib.Path[source]

Alias for field number 3

plutus_mint: Union[List[cardano_clusterlib.clusterlib.PlutusMint], Tuple[()]][source]

Alias for field number 6

plutus_txins: Union[List[cardano_clusterlib.clusterlib.PlutusTxIn], Tuple[()]][source]

Alias for field number 5

tx_files: cardano_clusterlib.clusterlib.TxFiles[source]

Alias for field number 2

txins: List[cardano_clusterlib.clusterlib.UTXOData][source]

Alias for field number 0

txouts: List[cardano_clusterlib.clusterlib.TxOut][source]

Alias for field number 1

withdrawals: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]][source]

Alias for field number 9

class cardano_clusterlib.clusterlib.UTXOData(utxo_hash, utxo_ix, amount, address, coin, datum_hash)[source]

Bases: tuple

address: str[source]

Alias for field number 3

amount: int[source]

Alias for field number 2

coin: str[source]

Alias for field number 4

datum_hash: str[source]

Alias for field number 5

utxo_hash: str[source]

Alias for field number 0

utxo_ix: int[source]

Alias for field number 1

class cardano_clusterlib.clusterlib.Value(value, coin)[source]

Bases: tuple

coin: str[source]

Alias for field number 1

value: int[source]

Alias for field number 0

cardano_clusterlib.clusterlib.get_rand_str(length: int = 8) → str[source]

Return random ASCII lowercase string.

cardano_clusterlib.clusterlib.read_address_from_file(addr_file: Union[str, pathlib.Path]) → str[source]

Read address stored in file.

cardano_clusterlib.clusterlib.record_cli_coverage(cli_args: List[str], coverage_dict: dict) → None[source]

Record coverage info for CLI commands.

Parameters
  • cli_args – A list of command and it’s arguments.

  • coverage_dict – A dictionary with coverage info.

cardano_clusterlib.types module

Module contents

Imports.

exception cardano_clusterlib.CLIError[source]

Bases: Exception

class cardano_clusterlib.ClusterLib(state_dir: Union[str, pathlib.Path], protocol: str = 'cardano', tx_era: str = '', slots_offset: int = 0)[source]

Bases: object

Methods for working with cardano cluster using cardano-cli..

state_dir[source]

A directory with cluster state files (keys, config files, logs, …).

protocol[source]

A cluster protocol - full cardano mode by default.

tx_era[source]

An era used for transactions, by default same as network Era.

slots_offset[source]

Difference in slots between cluster’s start era and current era (e.g. Byron->Mary)

address_info(address: str)cardano_clusterlib.clusterlib.AddressInfo[source]

View a transaction.

Parameters

address – A Cardano address.

Returns

A tuple containing address info.

Return type

AddressInfo

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.clusterlib.UTXOData], Tuple[()]] = (), txouts: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), tx_files: Optional[cardano_clusterlib.clusterlib.TxFiles] = None, fee: int = 0, ttl: Optional[int] = None, withdrawals: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), deposit: Optional[int] = None, invalid_hereafter: Optional[int] = None, invalid_before: Optional[int] = None, mint: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), join_txouts: bool = True, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.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 UTXOData, specifying input UTxOs (optional).

  • txouts – A list (iterable) of TxOuts, specifying transaction outputs (optional).

  • tx_files – A 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).

  • withdrawals – A list (iterable) of TxOuts, specifying reward withdrawals (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).

  • mint – A list (iterable) of TxOuts, specifying minted tokens (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

TxRawOutput

build_raw_tx_bare(out_file: Union[str, pathlib.Path], txouts: List[cardano_clusterlib.clusterlib.TxOut], tx_files: cardano_clusterlib.clusterlib.TxFiles, fee: int, txins: Union[List[cardano_clusterlib.clusterlib.UTXOData], Tuple[()]] = (), plutus_txins: Union[List[cardano_clusterlib.clusterlib.PlutusTxIn], Tuple[()]] = (), plutus_mint: Union[List[cardano_clusterlib.clusterlib.PlutusMint], Tuple[()]] = (), ttl: Optional[int] = None, withdrawals: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), invalid_hereafter: Optional[int] = None, invalid_before: Optional[int] = None, mint: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), script_valid: bool = True, join_txouts: bool = True)cardano_clusterlib.clusterlib.TxRawOutput[source]

Build a raw transaction.

Parameters
  • out_file – An output file.

  • txouts – A list (iterable) of TxOuts, specifying transaction outputs.

  • tx_files – A TxFiles tuple containing files needed for the transaction.

  • fee – A fee amount.

  • txins – An iterable of UTXOData, specifying input UTxOs (optional).

  • plutus_txins – An iterable of PlutusTxIn, specifying input Plutus UTxOs (optional).

  • plutus_mint – An iterable of PlutusMint, specifying Plutus minting data (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).

  • invalid_hereafter – A last block when the transaction is still valid (optional).

  • invalid_before – A first block when the transaction is valid (optional).

  • mint – A list (iterable) of TxOuts, specifying minted tokens (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

TxRawOutput

build_tx(src_address: str, tx_name: str, tx_files: cardano_clusterlib.clusterlib.TxFiles, txins: Union[List[cardano_clusterlib.clusterlib.UTXOData], Tuple[()]] = (), txouts: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), change_address: str = '', fee_buffer: Optional[int] = None, plutus_txins: Union[List[cardano_clusterlib.clusterlib.PlutusTxIn], Tuple[()]] = (), plutus_mint: Union[List[cardano_clusterlib.clusterlib.PlutusMint], Tuple[()]] = (), withdrawals: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), deposit: Optional[int] = None, invalid_hereafter: Optional[int] = None, invalid_before: Optional[int] = None, mint: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), witness_override: Optional[int] = None, script_valid: bool = True, join_txouts: bool = True, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.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.

  • tx_files – A TxFiles tuple containing files needed for the transaction.

  • txins – An iterable of UTXOData, specifying input UTxOs (optional).

  • txouts – A list (iterable) of TxOuts, specifying transaction outputs (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).

  • plutus_txins – An iterable of PlutusTxIn, specifying input Plutus UTxOs (optional).

  • plutus_mint – An iterable of PlutusMint, specifying Plutus minting data (optional).

  • withdrawals – A list (iterable) of TxOuts, specifying reward withdrawals (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).

  • mint – A list (iterable) of TxOuts, specifying minted tokens (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).

  • destination_dir – A path to directory for storing artifacts (optional).

Returns

A tuple with transaction output details.

Return type

TxRawOutput

calculate_min_req_utxo(txouts: List[cardano_clusterlib.clusterlib.TxOut])cardano_clusterlib.clusterlib.Value[source]

Calculate the minimum required UTxO for a transaction output.

Parameters

txouts – A list of TxOuts for given address.

Returns

A tuple describing the value.

Return type

Value

calculate_min_value(multi_assets: List[cardano_clusterlib.clusterlib.TxOut])cardano_clusterlib.clusterlib.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

Value

calculate_tx_fee(src_address: str, tx_name: str, dst_addresses: Optional[List[str]] = None, txins: Union[List[cardano_clusterlib.clusterlib.UTXOData], Tuple[()]] = (), txouts: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), tx_files: Optional[cardano_clusterlib.clusterlib.TxFiles] = None, ttl: Optional[int] = None, withdrawals: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), invalid_hereafter: Optional[int] = None, mint: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), witness_count_add: int = 0, join_txouts: bool = True, destination_dir: Union[str, pathlib.Path] = '.') → int[source]

Build “dummy” transaction and calculate (estimate) it’s 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 UTXOData, specifying input UTxOs (optional).

  • txouts – A list (iterable) of TxOuts, specifying transaction outputs (optional).

  • tx_files – A TxFiles tuple containing files needed for the transaction (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).

  • invalid_hereafter – A last block when the transaction is still valid (optional).

  • mint – A list (iterable) of TxOuts, specifying minted tokens (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

calculate_tx_ttl() → int[source]

Calculate ttl for a transaction.

cli(cli_args: List[str])cardano_clusterlib.clusterlib.CLIOut[source]

Run the cardano-cli command.

Parameters

cli_args – A list of arguments for cardano-cli.

Returns

A tuple containing command stdout and stderr.

Return type

CLIOut

cli_base(cli_args: List[str])cardano_clusterlib.clusterlib.CLIOut[source]

Run a command.

Parameters

cli_args – A list consisting of command and it’s arguments.

Returns

A tuple containing command stdout and stderr.

Return type

CLIOut

create_stake_pool(pool_data: cardano_clusterlib.clusterlib.PoolData, pool_owners: List[cardano_clusterlib.clusterlib.PoolUser], tx_name: str, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.PoolCreationOutput[source]

Create and register a stake pool.

Parameters
  • pool_data – A PoolData tuple cointaining info about the stake pool.

  • pool_owners – A list of 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

PoolCreationOutput

deregister_stake_pool(pool_owners: List[cardano_clusterlib.clusterlib.PoolUser], cold_key_pair: cardano_clusterlib.clusterlib.ColdKeyPair, epoch: int, pool_name: str, tx_name: str, destination_dir: Union[str, pathlib.Path] = '.') → Tuple[pathlib.Path, cardano_clusterlib.clusterlib.TxRawOutput][source]

Deregister a stake pool.

Parameters
  • pool_owners – A list of PoolUser structures containing pool user addresses and keys.

  • cold_key_pair – A 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, TxRawOutput]

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

gen_cold_key_pair_and_counter(node_name: str, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.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

ColdKeyPair

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

gen_kes_key_pair(node_name: str, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.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

KeyPair

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_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_payment_addr(addr_name: str, payment_vkey_file: Union[str, pathlib.Path], stake_vkey_file: Optional[Union[str, pathlib.Path]] = 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_file – A path to corresponding vkey file.

  • stake_vkey_file – A path to corresponding stake vkey file (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, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.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).

  • destination_dir – A path to directory for storing artifacts (optional).

Returns

A tuple containing the address and key pair.

Return type

AddressRecord

gen_payment_key_pair(key_name: str, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.KeyPair[source]

Generate an 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

KeyPair

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.clusterlib.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 PoolData tuple cointaining 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 acount vkey file (optional).

  • destination_dir – A path to directory for storing artifacts (optional).

Returns

A path to the generated certificate.

Return type

Path

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

gen_stake_addr(addr_name: str, stake_vkey_file: Union[str, pathlib.Path], 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.

  • 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.clusterlib.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.

Return type

AddressRecord

gen_stake_addr_delegation_cert(addr_name: str, stake_vkey_file: Union[str, pathlib.Path], cold_vkey_file: Optional[Union[str, pathlib.Path]] = None, stake_pool_id: Optional[str] = None, 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.

  • 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: Union[str, pathlib.Path], 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.

  • 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: Union[str, pathlib.Path], 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.

  • 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.clusterlib.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

KeyPair

gen_update_proposal(cli_args: Union[list, tuple, set], 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

gen_vrf_key_pair(node_name: str, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.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

KeyPair

property genesis_keys[source]

Return tuple with genesis-related keys.

property genesis_utxo_addr[source]

Produce a genesis UTxO address.

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.

Returns

A total balance.

Return type

int

get_address_deposit() → int[source]

Return stake address deposit amount.

get_block_no() → int[source]

Return block number of last block that was successfully applied to the ledger.

get_epoch() → int[source]

Return epoch of last block that was successfully applied to the ledger.

get_era() → str[source]

Return network era.

get_hash_script_data(script_data_file: Union[str, pathlib.Path] = '', script_data_value: str = '') → str[source]

Return the hash of script data.

Parameters
  • script_data_file – A path to the 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_kes_period() → int[source]

Return last block KES period.

get_ledger_state() → dict[source]

Return the current ledger state info.

get_payment_vkey_hash(payment_vkey_file: Union[str, pathlib.Path]) → str[source]

Return the hash of an address key.

Parameters

payment_vkey_file – A path to payment vkey file.

Returns

A generated hash.

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_pool_deposit() → int[source]

Return stake pool deposit amount.

get_pool_params(stake_pool_id: str)cardano_clusterlib.clusterlib.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_protocol_params() → dict[source]

Return the current protocol parameters.

get_protocol_state() → dict[source]

Return the current protocol state info.

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.clusterlib.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

StakeAddrInfo

get_stake_distribution() → Dict[str, float][source]

Return current aggregated stake distribution per stake pool.

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

get_stake_snapshot(stake_pool_id: str) → Dict[str, int][source]

Return the three stake snapshots for a pool, plus the total active stake.

Parameters

stake_pool_id – An ID of the stake pool (Bech32-encoded or hex-encoded).

Returns

A stake snapshot data.

Return type

Dict

get_tip() → dict[source]

Return current tip - last block successfully applied to the ledger.

get_tx_deposit(tx_files: cardano_clusterlib.clusterlib.TxFiles) → int[source]

Get deposit amount for a transaction (based on certificates used for the TX).

Parameters

tx_files – A TxFiles tuple containing files needed for the transaction.

Returns

A total deposit amount needed for the transaction.

Return type

int

get_tx_ins_outs(src_address: str, tx_files: cardano_clusterlib.clusterlib.TxFiles, txins: Union[List[cardano_clusterlib.clusterlib.UTXOData], Tuple[()]] = (), txouts: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), fee: int = 0, deposit: Optional[int] = None, withdrawals: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), mint: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), lovelace_balanced: bool = False) → Tuple[list, list][source]

Return list of transaction’s inputs and outputs.

Parameters
  • src_address – An address used for fee and inputs (if inputs not specified by txins).

  • tx_files – A TxFiles tuple containing files needed for the transaction.

  • txins – An iterable of UTXOData, specifying input UTxOs (optional).

  • txouts – A list (iterable) of TxOuts, specifying transaction outputs (optional).

  • fee – A fee amount (optional).

  • deposit – A deposit amount needed by the transaction (optional).

  • withdrawals – A list (iterable) of TxOuts, specifying reward withdrawals (optional).

  • mint – A list (iterable) of TxOuts, specifying minted tokens (optional).

Returns

A tuple of list of transaction inputs and list of transaction

outputs.

Return type

Tuple[list, list]

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

get_utxo(address: str = '', txin: str = '', coins: Union[list, tuple, set] = (), decode_names: bool = True) → List[cardano_clusterlib.clusterlib.UTXOData][source]

Return UTxO info for payment address.

Parameters
  • address – A payment address.

  • txin – A transaction input (TxId#TxIx).

  • coins – A list (iterable) of coin names (asset IDs).

  • decode_names – A bool indicating whether to decode asset names (True by default).

Returns

A list of UTxO data.

Return type

List[UTXOData]

get_utxo_with_highest_amount(address: str, coin: str = 'lovelace')cardano_clusterlib.clusterlib.UTXOData[source]

Return data for UTxO with highest amount.

Parameters

address – A payment address string.

Returns

An UTxO record with the highest amount.

Return type

UTXOData

get_withdrawals(withdrawals: List[cardano_clusterlib.clusterlib.TxOut]) → List[cardano_clusterlib.clusterlib.TxOut][source]

Return list of resolved reward withdrawals.

The TxOut.amount can be ‘-1’, meaning all available funds.

Parameters

withdrawals – A list (iterable) of TxOuts, specifying reward withdrawals.

Returns

A list of TxOuts, specifying resolved reward withdrawals.

Return type

List[TxOut]

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).

query_cli(cli_args: Union[list, tuple, set]) → str[source]

Run the cardano-cli query command.

refresh_pparams_file() → None[source]

Refresh protocol parameters file.

register_stake_pool(pool_data: cardano_clusterlib.clusterlib.PoolData, pool_owners: List[cardano_clusterlib.clusterlib.PoolUser], vrf_vkey_file: Union[str, pathlib.Path], cold_key_pair: cardano_clusterlib.clusterlib.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.clusterlib.TxRawOutput][source]

Register a stake pool.

Parameters
  • pool_data – A PoolData tuple cointaining info about the stake pool.

  • pool_owners – A list of PoolUser structures containing pool user addresses and keys.

  • vrf_vkey_file – A path to node VRF vkey file.

  • cold_key_pair – A 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, TxRawOutput]

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

send_funds(src_address: str, destinations: List[cardano_clusterlib.clusterlib.TxOut], tx_name: str, tx_files: Optional[cardano_clusterlib.clusterlib.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.clusterlib.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 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

TxRawOutput

send_tx(src_address: str, tx_name: str, txins: Union[List[cardano_clusterlib.clusterlib.UTXOData], Tuple[()]] = (), txouts: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), tx_files: Optional[cardano_clusterlib.clusterlib.TxFiles] = None, fee: Optional[int] = None, ttl: Optional[int] = None, withdrawals: Union[List[cardano_clusterlib.clusterlib.TxOut], Tuple[()]] = (), deposit: Optional[int] = None, invalid_hereafter: Optional[int] = None, invalid_before: Optional[int] = None, join_txouts: bool = True, verify_tx: bool = True, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.TxRawOutput[source]

Build, Sign and Submit 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 UTXOData, specifying input UTxOs (optional).

  • txouts – A list (iterable) of TxOuts, specifying transaction outputs (optional).

  • tx_files – A 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).

  • withdrawals – A list (iterable) of TxOuts, specifying reward withdrawals (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).

  • 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

TxRawOutput

sign_tx(tx_body_file: Union[str, pathlib.Path], signing_key_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]

Sign a transaction.

Parameters
  • tx_body_file – A path to file with transaction body.

  • signing_key_files – A list of paths to signing key 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

submit_tx(tx_file: Union[str, pathlib.Path], txins: List[cardano_clusterlib.clusterlib.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 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.

submit_update_proposal(cli_args: Union[list, tuple, set], 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.clusterlib.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

TxRawOutput

time_from_epoch_start() → float[source]

How many seconds passed from start of the current epoch.

time_to_epoch_end() → float[source]

How many seconds to go to start of a new epoch.

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

wait_for_new_block(new_blocks: int = 1) → None[source]

Wait for new block(s) to be created.

Parameters

new_blocks – A number of new blocks to wait for (optional).

wait_for_new_epoch(new_epochs: int = 1, padding_seconds: int = 0) → None[source]

Wait for new epoch(s).

Parameters
  • new_epochs – A number of new epochs to wait for (optional).

  • padding_seconds – A number of additional seconds to wait for (optional).

wait_for_slot(slot: int) → None[source]

Wait for slot number.

Parameters

slot – A slot number to wait for.

withdraw_reward(stake_addr_record: cardano_clusterlib.clusterlib.AddressRecord, dst_addr_record: cardano_clusterlib.clusterlib.AddressRecord, tx_name: str, verify: bool = True, destination_dir: Union[str, pathlib.Path] = '.')cardano_clusterlib.clusterlib.TxRawOutput[source]

Withdraw reward to payment address.

Parameters
  • stake_addr_record – An AddressRecord tuple for the stake address with reward.

  • dst_addr_record – An 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).

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