Transaction
Definitions of transaction-related data types.
- class pycardano.transaction.TransactionInput(transaction_id: 'TransactionId', index: 'int')
Bases:
ArrayCBORSerializable
- transaction_id: TransactionId
- index: int
- class pycardano.transaction.AssetName(payload: bytes)
Bases:
ConstrainedBytes
- MAX_SIZE = 32
- class pycardano.transaction.Asset(*args, **kwargs)
Bases:
DictCBORSerializable
- VALUE_TYPE
alias of
int
- classmethod from_primitive(value: dict) DictBase
Restore a primitive value to its original class type.
- Parameters:
cls (DictBase) – The original class type.
value (
Primitive
) – A CBOR primitive.
- Returns:
Restored object.
- Return type:
DictBase
- Raises:
DeserializeException – When the object could not be restored from primitives.
- to_shallow_primitive() dict
Convert the instance to a CBOR primitive. If the primitive is a container, e.g. list, dict, the type of its elements could be either a Primitive or a CBORSerializable.
- Returns:
A CBOR primitive.
- Return type:
Primitive
- Raises:
SerializeException – When the object could not be converted to CBOR primitive types.
- class pycardano.transaction.MultiAsset(*args, **kwargs)
Bases:
DictCBORSerializable
- KEY_TYPE
alias of
ScriptHash
- union(other: MultiAsset) MultiAsset
- normalize() MultiAsset
Normalize the MultiAsset by removing zero values.
- filter(criteria=typing.Callable[[pycardano.hash.ScriptHash, pycardano.transaction.AssetName, int], bool]) 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
- classmethod from_primitive(value: dict) DictBase
Restore a primitive value to its original class type.
- Parameters:
cls (DictBase) – The original class type.
value (
Primitive
) – A CBOR primitive.
- Returns:
Restored object.
- Return type:
DictBase
- Raises:
DeserializeException – When the object could not be restored from primitives.
- to_shallow_primitive() dict
Convert the instance to a CBOR primitive. If the primitive is a container, e.g. list, dict, the type of its elements could be either a Primitive or a CBORSerializable.
- Returns:
A CBOR primitive.
- Return type:
Primitive
- Raises:
SerializeException – When the object could not be converted to CBOR primitive types.
- class pycardano.transaction.Value(coin: 'int' = 0, multi_asset: 'MultiAsset' = <factory>)
Bases:
ArrayCBORSerializable
- coin: int = 0
Amount of ADA
- multi_asset: MultiAsset
Multi-assets associated with the UTxO
- 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, PlutusV3Script]]' = None, post_alonzo: 'Optional[bool]' = False)
Bases:
CBORSerializable
- datum: Optional[Union[PlutusData, dict, int, bytes, IndefiniteList, RawCBOR, RawPlutusData]] = None
- script: Optional[Union[NativeScript, PlutusV1Script, PlutusV2Script, PlutusV3Script]] = 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, bool, None, tuple, list, IndefiniteList, dict, defaultdict, OrderedDict, datetime, Pattern, CBORSimpleValue, CBORTag, set, frozenset, frozendict, FrozenList, IndefiniteFrozenList, ByteString]
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, bool, None, tuple, list, IndefiniteList, dict, defaultdict, OrderedDict, datetime, Pattern, CBORSimpleValue, CBORTag, set, frozenset, frozendict, FrozenList, IndefiniteFrozenList, ByteString]) 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')
Bases:
ArrayCBORSerializable
- 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:
MapCBORSerializable
- inputs: List[TransactionInput]
- outputs: List[TransactionOutput]
- fee: int = 0
- ttl: Optional[int] = None
- certificates: Optional[List[Union[StakeRegistration, StakeDeregistration, StakeDelegation, PoolRegistration, PoolRetirement]]] = 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
- collateral_return: Optional[TransactionOutput] = None
- total_collateral: Optional[int] = None
- reference_inputs: Optional[List[TransactionInput]] = None
- validate()
Validate the data stored in the current instance. Defaults to always pass.
- Raises:
InvalidDataException – When the data is invalid.
- hash() bytes
- property id: TransactionId
- class pycardano.transaction.Transaction(transaction_body: 'TransactionBody', transaction_witness_set: 'TransactionWitnessSet', valid: 'bool' = True, auxiliary_data: 'Optional[AuxiliaryData]' = None)
Bases:
ArrayCBORSerializable
- transaction_body: TransactionBody
- transaction_witness_set: TransactionWitnessSet
- valid: bool = True
- auxiliary_data: Optional[AuxiliaryData] = None
- property id: TransactionId
- class pycardano.transaction.Withdrawals(*args, **kwargs)
Bases:
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: ~typing.List[~pycardano.coinselection.UTxOSelector] = <factory>, execution_memory_buffer: float = 0.2, execution_step_buffer: float = 0.2, fee_buffer: ~typing.Optional[int] = None, ttl: ~typing.Optional[int] = None, validity_start: ~typing.Optional[int] = None, auxiliary_data: ~typing.Optional[~pycardano.metadata.AuxiliaryData] = None, native_scripts: ~typing.Optional[~typing.List[~pycardano.nativescript.NativeScript]] = None, mint: ~typing.Optional[~pycardano.transaction.MultiAsset] = None, required_signers: ~typing.Optional[~typing.List[~pycardano.hash.VerificationKeyHash]] = None, collaterals: ~typing.List[~pycardano.transaction.UTxO] = <factory>, certificates: ~typing.Optional[~typing.List[~typing.Union[~pycardano.certificate.StakeRegistration, ~pycardano.certificate.StakeDeregistration, ~pycardano.certificate.StakeDelegation, ~pycardano.certificate.PoolRegistration, ~pycardano.certificate.PoolRetirement]]] = None, withdrawals: ~typing.Optional[~pycardano.transaction.Withdrawals] = None, witness_override: ~typing.Optional[int] = None, initial_stake_pool_registration: ~typing.Optional[bool] = False, use_redeemer_map: ~typing.Optional[bool] = True)
Bases:
object
A class builder that makes it easy to build a transaction.
- context: ChainContext
- utxo_selectors: List[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
- fee_buffer: Optional[int] = None
Additional amount of fee (in lovelace) that will be added on top of estimation.
- ttl: Optional[int] = None
- validity_start: Optional[int] = None
- auxiliary_data: Optional[AuxiliaryData] = None
- native_scripts: Optional[List[NativeScript]] = None
- mint: Optional[MultiAsset] = None
- required_signers: Optional[List[VerificationKeyHash]] = None
- certificates: Optional[List[Union[StakeRegistration, StakeDeregistration, StakeDelegation, PoolRegistration, PoolRetirement]]] = None
- withdrawals: Optional[Withdrawals] = None
- reference_inputs: Set[Union[UTxO, TransactionInput]]
- witness_override: Optional[int] = None
- initial_stake_pool_registration: Optional[bool] = False
- use_redeemer_map: Optional[bool] = True
Whether to serialize redeemers as a map or a list. Default is True.
- add_input(utxo: UTxO) 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: UTxO, script: Optional[Union[UTxO, NativeScript, PlutusV1Script, PlutusV2Script, PlutusV3Script]] = None, datum: Optional[Union[PlutusData, dict, int, bytes, IndefiniteList, RawCBOR, RawPlutusData]] = None, redeemer: Optional[Redeemer] = None) TransactionBuilder
Add a script UTxO to transaction’s inputs.
- Parameters:
utxo (UTxO) – Script UTxO to be added.
script (Optional[Union[UTxO, NativeScript, PlutusV1Script, PlutusV2Script, PlutusV3Script]]) – 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[UTxO, NativeScript, PlutusV1Script, PlutusV2Script, PlutusV3Script], redeemer: Optional[Redeemer] = None) TransactionBuilder
Add a minting script along with its datum and redeemer to this transaction.
- Parameters:
script (Union[UTxO, PlutusV1Script, PlutusV2Script, PlutusV3Script]) – A plutus script.
redeemer (Optional[Redeemer]) – A plutus redeemer to unlock the UTxO.
- Returns:
Current transaction builder.
- Return type:
- add_withdrawal_script(script: Union[UTxO, NativeScript, PlutusV1Script, PlutusV2Script, PlutusV3Script], redeemer: Optional[Redeemer] = None) TransactionBuilder
Add a withdrawal script along with its redeemer to this transaction.
- Parameters:
script (Union[UTxO, PlutusV1Script, PlutusV2Script, PlutusV3Script]) – A plutus script.
redeemer (Optional[Redeemer]) – A plutus redeemer to unlock the UTxO.
- Returns:
Current transaction builder.
- Return type:
- add_certificate_script(script: Union[UTxO, NativeScript, PlutusV1Script, PlutusV2Script, PlutusV3Script], redeemer: Optional[Redeemer] = None) TransactionBuilder
Add a certificate script along with its redeemer to this transaction. WARNING: The order of operations matters. The index of the redeemer will be set to the index of the last certificate added.
- Parameters:
script (Union[UTxO, PlutusV1Script, PlutusV2Script, PlutusV3Script]) – A plutus script.
redeemer (Optional[Redeemer]) – A plutus redeemer to unlock the UTxO.
- Returns:
Current transaction builder.
- Return type:
- add_input_address(address: Union[Address, str]) 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: TransactionOutput, datum: Optional[Union[PlutusData, dict, int, bytes, IndefiniteList, RawCBOR, RawPlutusData]] = None, add_datum_to_witness: bool = False) 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 outputs: List[TransactionOutput]
- property fee: int
- property all_scripts: List[Union[bytes, NativeScript, PlutusV1Script, PlutusV2Script]]
- property scripts: List[Union[bytes, NativeScript, PlutusV1Script, PlutusV2Script]]
- property datums: Dict[DatumHash, Union[PlutusData, dict, int, bytes, IndefiniteList, RawCBOR, RawPlutusData]]
- redeemers() Union[List[Redeemer], RedeemerMap]
- property script_data_hash: Optional[ScriptDataHash]
- build_witness_set(remove_dup_script: bool = False) TransactionWitnessSet
Build a transaction witness set, excluding verification key witnesses. This function is especially useful when the transaction involves Plutus scripts.
- Parameters:
remove_dup_script (bool) – Whether to remove scripts, that are already attached to inputs, from the witness set.
- Returns:
A transaction witness set without verification key witnesses.
- Return type:
- build(*args, **kwargs)
- build_and_sign(signing_keys: List[Union[SigningKey, ExtendedSigningKey]], change_address: Optional[Address] = None, merge_change: Optional[bool] = False, collateral_change_address: Optional[Address] = None, auto_validity_start_offset: Optional[int] = None, auto_ttl_offset: Optional[int] = None, auto_required_signers: Optional[bool] = None, force_skeys: Optional[bool] = False) 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 and the given signers to required signatories (default only for Smart Contract transactions). Manually set required signers will always take precedence.
force_skeys (Optional[bool]) – Whether to force the use of signing keys for signing the transaction. Default is False, which means that provided signing keys will only be used to sign the transaction if they are actually required by the transaction. This is useful to reduce tx fees by not including unnecessary signatures. If set to True, all provided signing keys will be used to sign the transaction.
- Returns:
A signed transaction.
- Return type: