Transaction
Definitions of transaction-related data types.
- class pycardano.transaction.TransactionInput(transaction_id: 'TransactionId', index: 'int')
Bases:
pycardano.serialization.ArrayCBORSerializable
- transaction_id: pycardano.hash.TransactionId
- index: int
- class pycardano.transaction.AssetName(payload: bytes)
Bases:
pycardano.hash.ConstrainedBytes
- MAX_SIZE = 32
- class pycardano.transaction.Asset(*args, **kwargs)
Bases:
pycardano.serialization.DictCBORSerializable
- KEY_TYPE
alias of
pycardano.transaction.AssetName
- VALUE_TYPE
alias of
int
- union(other: pycardano.transaction.Asset) pycardano.transaction.Asset
- class pycardano.transaction.MultiAsset(*args, **kwargs)
Bases:
pycardano.serialization.DictCBORSerializable
- KEY_TYPE
alias of
pycardano.hash.ScriptHash
- VALUE_TYPE
alias of
pycardano.transaction.Asset
- filter(criteria=typing.Callable[[pycardano.hash.ScriptHash, pycardano.transaction.AssetName, int], bool]) pycardano.transaction.MultiAsset
Filter items by criteria.
- Parameters
criteria – A function that takes in three input arguments (policy_id, asset_name, amount) and returns a bool. If returned value is True, then the asset will be kept, otherwise discarded.
- Returns
A new filtered MultiAsset object.
- count(criteria=typing.Callable[[pycardano.hash.ScriptHash, pycardano.transaction.AssetName, int], bool]) int
Count number of distinct assets that satisfy a certain criteria.
- Parameters
criteria – A function that takes in three input arguments (policy_id, asset_name, amount) and returns a bool.
- Returns
Total number of distinct assets that satisfy the criteria.
- Return type
int
- class pycardano.transaction.Value(coin: 'int' = 0, multi_asset: 'MultiAsset' = <factory>)
Bases:
pycardano.serialization.ArrayCBORSerializable
- coin: int = 0
Amount of ADA
- multi_asset: pycardano.transaction.MultiAsset
Multi-assets associated with the UTxO
- union(other: Union[pycardano.transaction.Value, int]) pycardano.transaction.Value
- to_shallow_primitive()
- Returns
A CBOR primitive.
- Return type
Primitive
- Raises
SerializeException – When the object could not be converted to CBOR primitive types.
- class pycardano.transaction.TransactionOutput(address: 'Address', amount: 'Union[Value]', datum_hash: 'Optional[DatumHash]' = None, datum: 'Optional[Datum]' = None, script: 'Optional[Union[NativeScript, PlutusV1Script, PlutusV2Script]]' = None, post_alonzo: 'Optional[bool]' = False)
Bases:
pycardano.serialization.CBORSerializable
- address: pycardano.address.Address
- amount: pycardano.transaction.Value
- datum_hash: Optional[pycardano.hash.DatumHash] = None
- datum: Optional[Union[pycardano.plutus.PlutusData, dict, pycardano.serialization.IndefiniteList, int, bytes, pycardano.serialization.RawCBOR, pycardano.plutus.RawPlutusData]] = None
- script: Optional[Union[pycardano.nativescript.NativeScript, pycardano.plutus.PlutusV1Script, pycardano.plutus.PlutusV2Script]] = None
- post_alonzo: Optional[bool] = False
- validate()
Validate the data stored in the current instance. Defaults to always pass.
- Raises
InvalidDataException – When the data is invalid.
- property lovelace: int
- to_primitive() Union[bytes, bytearray, str, int, float, decimal.Decimal, bool, None, tuple, list, pycardano.serialization.IndefiniteList, dict, collections.defaultdict, collections.OrderedDict, undefined_type, datetime.datetime, re.Pattern, CBORSimpleValue, _cbor2.CBORTag, set, frozenset]
Convert the instance and its elements to CBOR primitives recursively.
- Returns
A CBOR primitive.
- Return type
Primitive
- Raises
SerializeException – When the object or its elements could not be converted to CBOR primitive types.
- classmethod from_primitive(value: Union[bytes, bytearray, str, int, float, decimal.Decimal, bool, None, tuple, list, pycardano.serialization.IndefiniteList, dict, collections.defaultdict, collections.OrderedDict, undefined_type, datetime.datetime, re.Pattern, CBORSimpleValue, _cbor2.CBORTag, set, frozenset]) pycardano.transaction.TransactionOutput
Turn a CBOR primitive to its original class type.
- Parameters
cls (CBORBase) – The original class type.
value (
Primitive
) – A CBOR primitive.
- Returns
A CBOR serializable object.
- Return type
CBORBase
- Raises
DeserializeException – When the object could not be restored from primitives.
- class pycardano.transaction.UTxO(input: 'TransactionInput', output: 'TransactionOutput')
- class pycardano.transaction.TransactionBody(inputs: 'List[TransactionInput]' = <factory>, outputs: 'List[TransactionOutput]' = <factory>, fee: 'int' = 0, ttl: 'Optional[int]' = None, certificates: 'Optional[List[Certificate]]' = None, withdraws: 'Optional[Withdrawals]' = None, update: 'Any' = None, auxiliary_data_hash: 'Optional[AuxiliaryDataHash]' = None, validity_start: 'Optional[int]' = None, mint: 'Optional[MultiAsset]' = None, script_data_hash: 'Optional[ScriptDataHash]' = None, collateral: 'Optional[List[TransactionInput]]' = None, required_signers: 'Optional[List[VerificationKeyHash]]' = None, network_id: 'Optional[Network]' = None, collateral_return: 'Optional[TransactionOutput]' = None, total_collateral: 'Optional[int]' = None, reference_inputs: 'Optional[List[TransactionInput]]' = None)
Bases:
pycardano.serialization.MapCBORSerializable
- inputs: List[pycardano.transaction.TransactionInput]
- outputs: List[pycardano.transaction.TransactionOutput]
- fee: int = 0
- ttl: Optional[int] = None
- certificates: Optional[List[Union[pycardano.certificate.StakeRegistration, pycardano.certificate.StakeDeregistration, pycardano.certificate.StakeDelegation]]] = None
- withdraws: Optional[pycardano.transaction.Withdrawals] = None
- update: Any = None
- auxiliary_data_hash: Optional[pycardano.hash.AuxiliaryDataHash] = None
- validity_start: Optional[int] = None
- mint: Optional[pycardano.transaction.MultiAsset] = None
- script_data_hash: Optional[pycardano.hash.ScriptDataHash] = None
- collateral: Optional[List[pycardano.transaction.TransactionInput]] = None
- required_signers: Optional[List[pycardano.hash.VerificationKeyHash]] = None
- network_id: Optional[pycardano.network.Network] = None
- collateral_return: Optional[pycardano.transaction.TransactionOutput] = None
- total_collateral: Optional[int] = None
- reference_inputs: Optional[List[pycardano.transaction.TransactionInput]] = None
- hash() bytes
- property id: pycardano.hash.TransactionId
- class pycardano.transaction.Transaction(transaction_body: 'TransactionBody', transaction_witness_set: 'TransactionWitnessSet', valid: 'bool' = True, auxiliary_data: 'Optional[AuxiliaryData]' = None)
Bases:
pycardano.serialization.ArrayCBORSerializable
- transaction_body: pycardano.transaction.TransactionBody
- transaction_witness_set: pycardano.witness.TransactionWitnessSet
- valid: bool = True
- auxiliary_data: Optional[pycardano.metadata.AuxiliaryData] = None
- property id: pycardano.hash.TransactionId
- class pycardano.transaction.Withdrawals(*args, **kwargs)
Bases:
pycardano.serialization.DictCBORSerializable
A disctionary of reward addresses to reward withdrawal amount.
Key is address bytes, value is an integer.
Examples
>>> address = Address.from_primitive("stake_test1upyz3gk6mw5he20apnwfn96cn9rscgvmmsxc9r86dh0k66gswf59n") >>> Withdrawals({bytes(address): 1000000}) {b'\xe0H(\xa2\xda\xdb\xa9|\xa9\xfd\x0c\xdc\x99\x97X\x99G\x0c!\x9b\xdc\r\x82\x8c\xfam\xdfmi': 1000000}
- KEY_TYPE
alias of
bytes
- VALUE_TYPE
alias of
int
- class pycardano.txbuilder.TransactionBuilder(context: pycardano.backend.base.ChainContext, utxo_selectors: List[pycardano.coinselection.UTxOSelector] = <factory>, execution_memory_buffer: float = 0.2, execution_step_buffer: float = 0.2, ttl: Optional[int] = None, validity_start: Optional[int] = None, auxiliary_data: Optional[pycardano.metadata.AuxiliaryData] = None, native_scripts: Optional[List[pycardano.nativescript.NativeScript]] = None, mint: Optional[pycardano.transaction.MultiAsset] = None, required_signers: Optional[List[pycardano.hash.VerificationKeyHash]] = None, collaterals: List[pycardano.transaction.UTxO] = <factory>, certificates: Optional[List[Union[pycardano.certificate.StakeRegistration, pycardano.certificate.StakeDeregistration, pycardano.certificate.StakeDelegation]]] = None, withdrawals: Optional[pycardano.transaction.Withdrawals] = None)
Bases:
object
A class builder that makes it easy to build a transaction.
- context: pycardano.backend.base.ChainContext
- utxo_selectors: List[pycardano.coinselection.UTxOSelector]
- execution_memory_buffer: float = 0.2
Additional amount of execution memory (in ratio) that will be on top of estimation
- execution_step_buffer: float = 0.2
Additional amount of execution step (in ratio) that will be added on top of estimation
- ttl: Optional[int] = None
- validity_start: Optional[int] = None
- auxiliary_data: Optional[pycardano.metadata.AuxiliaryData] = None
- native_scripts: Optional[List[pycardano.nativescript.NativeScript]] = None
- mint: Optional[pycardano.transaction.MultiAsset] = None
- required_signers: Optional[List[pycardano.hash.VerificationKeyHash]] = None
- collaterals: List[pycardano.transaction.UTxO]
- certificates: Optional[List[Union[pycardano.certificate.StakeRegistration, pycardano.certificate.StakeDeregistration, pycardano.certificate.StakeDelegation]]] = None
- withdrawals: Optional[pycardano.transaction.Withdrawals] = None
- reference_inputs: Set[Union[pycardano.transaction.UTxO, pycardano.transaction.TransactionInput]]
- add_input(utxo: pycardano.transaction.UTxO) pycardano.txbuilder.TransactionBuilder
Add a specific UTxO to transaction’s inputs.
- Parameters
utxo (UTxO) – UTxO to be added.
- Returns
Current transaction builder.
- Return type
- add_script_input(utxo: pycardano.transaction.UTxO, script: Optional[Union[pycardano.transaction.UTxO, pycardano.nativescript.NativeScript, pycardano.plutus.PlutusV1Script, pycardano.plutus.PlutusV2Script]] = None, datum: Optional[Union[pycardano.plutus.PlutusData, dict, pycardano.serialization.IndefiniteList, int, bytes, pycardano.serialization.RawCBOR, pycardano.plutus.RawPlutusData]] = None, redeemer: Optional[pycardano.plutus.Redeemer] = None) pycardano.txbuilder.TransactionBuilder
Add a script UTxO to transaction’s inputs.
- Parameters
utxo (UTxO) – Script UTxO to be added.
script (Optional[Union[UTxO, NativeScript, PlutusV1Script, PlutusV2Script]]) – A plutus script. If not provided, the script will be inferred from the input UTxO (first arg of this method). The script can also be a specific UTxO whose output contains an inline script.
datum (Optional[Datum]) – A plutus datum to unlock the UTxO.
redeemer (Optional[Redeemer]) – A plutus redeemer to unlock the UTxO.
- Returns
Current transaction builder.
- Return type
- add_minting_script(script: Union[pycardano.transaction.UTxO, pycardano.nativescript.NativeScript, pycardano.plutus.PlutusV1Script, pycardano.plutus.PlutusV2Script], redeemer: Optional[pycardano.plutus.Redeemer] = None) pycardano.txbuilder.TransactionBuilder
Add a minting script along with its datum and redeemer to this transaction.
- Parameters
script (Union[UTxO, PlutusV1Script, PlutusV2Script]) – A plutus script.
redeemer (Optional[Redeemer]) – A plutus redeemer to unlock the UTxO.
- Returns
Current transaction builder.
- Return type
- add_input_address(address: Union[pycardano.address.Address, str]) pycardano.txbuilder.TransactionBuilder
Add an address to transaction’s input address. Unlike
add_input()
, which deterministically adds a UTxO to the transaction’s inputs, add_input_address will not immediately select any UTxO when called. Instead, it will delegate UTxO selection toUTxOSelector`s of the builder when :meth:`build
is called.- Parameters
address (Union[Address, str]) – Address to be added.
- Returns
The current transaction builder.
- Return type
- add_output(tx_out: pycardano.transaction.TransactionOutput, datum: Optional[Union[pycardano.plutus.PlutusData, dict, pycardano.serialization.IndefiniteList, int, bytes, pycardano.serialization.RawCBOR, pycardano.plutus.RawPlutusData]] = None, add_datum_to_witness: bool = False) pycardano.txbuilder.TransactionBuilder
Add a transaction output.
- Parameters
tx_out (TransactionOutput) – The transaction output to be added.
datum (Datum) – Attach a datum hash to this transaction output.
add_datum_to_witness (bool) – Optionally add the actual datum to transaction witness set. Defaults to False.
- Returns
Current transaction builder.
- Return type
- property inputs: List[pycardano.transaction.UTxO]
- property excluded_inputs: List[pycardano.transaction.UTxO]
- property input_addresses: List[Union[pycardano.address.Address, str]]
- property outputs: List[pycardano.transaction.TransactionOutput]
- property fee: int
- property all_scripts: List[Union[bytes, pycardano.nativescript.NativeScript, pycardano.plutus.PlutusV1Script, pycardano.plutus.PlutusV2Script]]
- property scripts: List[Union[bytes, pycardano.nativescript.NativeScript, pycardano.plutus.PlutusV1Script, pycardano.plutus.PlutusV2Script]]
- property datums: Dict[pycardano.hash.DatumHash, Union[pycardano.plutus.PlutusData, dict, pycardano.serialization.IndefiniteList, int, bytes, pycardano.serialization.RawCBOR, pycardano.plutus.RawPlutusData]]
- property redeemers: List[pycardano.plutus.Redeemer]
- property script_data_hash: Optional[pycardano.hash.ScriptDataHash]
- build_witness_set() pycardano.witness.TransactionWitnessSet
Build a transaction witness set, excluding verification key witnesses. This function is especially useful when the transaction involves Plutus scripts.
- Returns
A transaction witness set without verification key witnesses.
- Return type
- build(change_address: Optional[pycardano.address.Address] = None, merge_change: Optional[bool] = False, collateral_change_address: Optional[pycardano.address.Address] = None, auto_validity_start_offset: Optional[int] = None, auto_ttl_offset: Optional[int] = None, auto_required_signers: Optional[bool] = None) pycardano.transaction.TransactionBody
Build a transaction body from all constraints set through the builder.
- Parameters
change_address (Optional[Address]) – Address to which changes will be returned. If not provided, the transaction body will likely be unbalanced (sum of inputs is greater than the sum of outputs).
merge_change (Optional[bool]) – If the change address match one of the transaction output, the change amount will be directly added to that transaction output, instead of being added as a separate output.
collateral_change_address (Optional[Address]) – Address to which collateral changes will be returned.
auto_validity_start_offset (Optional[int]) – Automatically set the validity start interval of the transaction to the current slot number + the given offset (default -1000). A manually set validity start will always take precedence.
auto_ttl_offset (Optional[int]) – Automatically set the validity end interval (ttl) of the transaction to the current slot number + the given offset (default 10_000). A manually set ttl will always take precedence.
auto_required_signers (Optional[bool]) – Automatically add all pubkeyhashes of transaction inputs to required signatories (default only for Smart Contract transactions). Manually set required signers will always take precedence.
- Returns
A transaction body.
- Return type
- build_and_sign(signing_keys: List[Union[pycardano.key.SigningKey, pycardano.key.ExtendedSigningKey]], change_address: Optional[pycardano.address.Address] = None, merge_change: Optional[bool] = False, collateral_change_address: Optional[pycardano.address.Address] = None, auto_validity_start_offset: Optional[int] = None, auto_ttl_offset: Optional[int] = None, auto_required_signers: Optional[bool] = None) pycardano.transaction.Transaction
Build a transaction body from all constraints set through the builder and sign the transaction with provided signing keys.
- Parameters
signing_keys (List[Union[SigningKey, ExtendedSigningKey]]) – A list of signing keys that will be used to sign the transaction.
change_address (Optional[Address]) – Address to which changes will be returned. If not provided, the transaction body will likely be unbalanced (sum of inputs is greater than the sum of outputs).
merge_change (Optional[bool]) – If the change address match one of the transaction output, the change amount will be directly added to that transaction output, instead of being added as a separate output.
collateral_change_address (Optional[Address]) – Address to which collateral changes will be returned.
auto_validity_start_offset (Optional[int]) – Automatically set the validity start interval of the transaction to the current slot number + the given offset (default -1000). A manually set validity start will always take precedence.
auto_ttl_offset (Optional[int]) – Automatically set the validity end interval (ttl) of the transaction to the current slot number + the given offset (default 10_000). A manually set ttl will always take precedence.
auto_required_signers (Optional[bool]) – Automatically add all pubkeyhashes of transaction inputs to required signatories (default only for Smart Contract transactions). Manually set required signers will always take precedence.
- Returns
A signed transaction.
- Return type