Struct TransactionBuilder

pub struct TransactionBuilder { /* private fields */ }

Implementations

impl TransactionBuilder

pub fn add_inputs_from( &mut self, inputs: &TransactionUnspentOutputs, strategy: CoinSelectionStrategyCIP2, ) -> Result<(), JsError>

This automatically selects and adds inputs from {inputs} consisting of just enough to cover the outputs that have already been added. This should be called after adding all certs/outputs/etc and will be an error otherwise. Uses CIP2: https://github.com/cardano-foundation/CIPs/blob/master/CIP-0002/CIP-0002.md Adding a change output must be called after via TransactionBuilder::add_change_if_needed() This function, diverging from CIP2, takes into account fees and will attempt to add additional inputs to cover the minimum fees. This does not, however, set the txbuilder’s fee.

pub fn set_inputs(&mut self, inputs: &TxInputsBuilder)

pub fn set_collateral(&mut self, collateral: &TxInputsBuilder)

pub fn set_collateral_return(&mut self, collateral_return: &TransactionOutput)

pub fn remove_collateral_return(&mut self)

pub fn set_collateral_return_and_total( &mut self, collateral_return: &TransactionOutput, ) -> Result<(), JsError>

This function will set the collateral-return value and then auto-calculate and assign the total collateral coin value. Will raise an error in case no collateral inputs are set or in case the total collateral value will have any assets in it except coin.

pub fn set_total_collateral(&mut self, total_collateral: &Coin)

pub fn remove_total_collateral(&mut self)

pub fn set_total_collateral_and_return( &mut self, total_collateral: &Coin, return_address: &Address, ) -> Result<(), JsError>

This function will set the total-collateral coin and then auto-calculate and assign the collateral return value. Will raise an error in case no collateral inputs are set. The specified address will be the received of the collateral return

pub fn add_reference_input(&mut self, reference_input: &TransactionInput)

pub fn add_script_reference_input( &mut self, reference_input: &TransactionInput, script_size: usize, )

pub fn add_key_input( &mut self, hash: &Ed25519KeyHash, input: &TransactionInput, amount: &Value, )

👎Deprecated since 10.2.0: Use .set_inputs

We have to know what kind of inputs these are to know what kind of mock witnesses to create since

1. mock witnesses have different lengths depending on the type which changes the expecting fee
2. Witnesses are a set so we need to get rid of duplicates to avoid over-estimating the fee

pub fn add_native_script_input( &mut self, script: &NativeScript, input: &TransactionInput, amount: &Value, )

👎Deprecated since 10.2.0: Use .set_inputs

This method will add the input to the builder and also register the required native script witness

pub fn add_plutus_script_input( &mut self, witness: &PlutusWitness, input: &TransactionInput, amount: &Value, )

👎Deprecated since 10.2.0: Use .set_inputs

This method will add the input to the builder and also register the required plutus witness

pub fn add_bootstrap_input( &mut self, hash: &ByronAddress, input: &TransactionInput, amount: &Value, )

👎Deprecated since 10.2.0: Use .set_inputs

pub fn add_regular_input( &mut self, address: &Address, input: &TransactionInput, amount: &Value, ) -> Result<(), JsError>

👎Deprecated since 12.0.0: Use .set_inputs

This function is replace for previous one add_input. The functions adds a non script input, if it is a script input it returns an error. To add script input you need to use add_native_script_input or add_plutus_script_input. Also we recommend to use TxInputsBuilder and .set_inputs, because all add_*_input functions might be removed from transaction builder.

pub fn add_inputs_from_and_change( &mut self, inputs: &TransactionUnspentOutputs, strategy: CoinSelectionStrategyCIP2, change_config: &ChangeConfig, ) -> Result<bool, JsError>

pub fn add_inputs_from_and_change_with_collateral_return( &mut self, inputs: &TransactionUnspentOutputs, strategy: CoinSelectionStrategyCIP2, change_config: &ChangeConfig, collateral_percentage: &BigNum, ) -> Result<(), JsError>

pub fn get_native_input_scripts(&self) -> Option<NativeScripts>

👎Deprecated since 10.2.0: Use .set_inputs

Returns a copy of the current script input witness scripts in the builder

pub fn get_plutus_input_scripts(&self) -> Option<PlutusWitnesses>

👎Deprecated since 10.2.0: Use .set_inputs

Returns a copy of the current plutus input witness scripts in the builder. NOTE: each plutus witness will be cloned with a specific corresponding input index

pub fn fee_for_input( &self, address: &Address, input: &TransactionInput, amount: &Value, ) -> Result<Coin, JsError>

calculates how much the fee would increase if you added a given output

pub fn add_output(&mut self, output: &TransactionOutput) -> Result<(), JsError>

Add explicit output via a TransactionOutput object

pub fn fee_for_output( &self, output: &TransactionOutput, ) -> Result<Coin, JsError>

calculates how much the fee would increase if you added a given output

pub fn set_fee(&mut self, fee: &Coin)

Set exact fee for the transaction. If the real fee will be bigger then the set value, the transaction will not be created on .build_tx()

pub fn set_min_fee(&mut self, fee: &Coin)

Set minimal fee for the transaction. If the real fee will be bigger then the set value, the transaction will be created with the real fee.

pub fn set_ttl(&mut self, ttl: u32)

👎Deprecated since 10.1.0: Underlying value capacity of ttl (BigNum u64) bigger then Slot32. Use set_ttl_bignum instead.

!!! DEPRECATED !!! Set ttl value.

pub fn set_ttl_bignum(&mut self, ttl: &BigNum)

pub fn remove_ttl(&mut self)

pub fn set_validity_start_interval(&mut self, validity_start_interval: u32)

👎Deprecated since 10.1.0: Underlying value capacity of validity_start_interval (BigNum u64) bigger then Slot32. Use set_validity_start_interval_bignum instead.

!!! DEPRECATED !!! Uses outdated slot number format.

pub fn set_validity_start_interval_bignum( &mut self, validity_start_interval: BigNum, )

pub fn remove_validity_start_interval(&mut self)

pub fn set_certs(&mut self, certs: &Certificates) -> Result<(), JsError>

👎Deprecated since 11.4.1: Can emit an error if you add a cert with script credential. Use set_certs_builder instead.

!!! DEPRECATED !!! Can emit error if add a cert with script credential. Use set_certs_builder instead.

pub fn remove_certs(&mut self)

pub fn set_certs_builder(&mut self, certs: &CertificatesBuilder)

pub fn set_withdrawals( &mut self, withdrawals: &Withdrawals, ) -> Result<(), JsError>

👎Deprecated since 11.4.1: Can emit an error if you add a withdrawal with script credential. Use set_withdrawals_builder instead.

!!! DEPRECATED !!! Can emit error if add a withdrawal with script credential. Use set_withdrawals_builder instead.

pub fn set_withdrawals_builder(&mut self, withdrawals: &WithdrawalsBuilder)

pub fn set_voting_builder(&mut self, voting_builder: &VotingBuilder)

pub fn set_voting_proposal_builder( &mut self, voting_proposal_builder: &VotingProposalBuilder, )

pub fn remove_withdrawals(&mut self)

pub fn get_auxiliary_data(&self) -> Option<AuxiliaryData>

pub fn set_auxiliary_data(&mut self, auxiliary_data: &AuxiliaryData)

Set explicit auxiliary data via an AuxiliaryData object It might contain some metadata plus native or Plutus scripts

pub fn remove_auxiliary_data(&mut self)

pub fn set_metadata(&mut self, metadata: &GeneralTransactionMetadata)

Set metadata using a GeneralTransactionMetadata object It will be set to the existing or new auxiliary data in this builder

pub fn add_metadatum( &mut self, key: &TransactionMetadatumLabel, val: &TransactionMetadatum, )

Add a single metadatum using TransactionMetadatumLabel and TransactionMetadatum objects It will be securely added to existing or new metadata in this builder

pub fn add_json_metadatum( &mut self, key: &TransactionMetadatumLabel, val: String, ) -> Result<(), JsError>

Add a single JSON metadatum using a TransactionMetadatumLabel and a String It will be securely added to existing or new metadata in this builder

pub fn add_json_metadatum_with_schema( &mut self, key: &TransactionMetadatumLabel, val: String, schema: MetadataJsonSchema, ) -> Result<(), JsError>

Add a single JSON metadatum using a TransactionMetadatumLabel, a String, and a MetadataJsonSchema object It will be securely added to existing or new metadata in this builder

pub fn set_mint_builder(&mut self, mint_builder: &MintBuilder)

pub fn remove_mint_builder(&mut self)

pub fn get_mint_builder(&self) -> Option<MintBuilder>

pub fn set_mint( &mut self, mint: &Mint, mint_scripts: &NativeScripts, ) -> Result<(), JsError>

👎Deprecated since 11.2.0: Mints are defining by MintBuilder now. Use .set_mint_builder() and MintBuilder instead.

!!! DEPRECATED !!! Mints are defining by MintBuilder now. Use .set_mint_builder() and MintBuilder instead. Set explicit Mint object and the required witnesses to this builder it will replace any previously existing mint and mint scripts NOTE! Error will be returned in case a mint policy does not have a matching script

pub fn get_mint(&self) -> Option<Mint>

👎Deprecated since 11.2.0: Mints are defining by MintBuilder now. Use .get_mint_builder() and .build() instead.

!!! DEPRECATED !!! Mints are defining by MintBuilder now. Use .get_mint_builder() and .build() instead. Returns a copy of the current mint state in the builder

pub fn get_mint_scripts(&self) -> Option<NativeScripts>

Returns a copy of the current mint witness scripts in the builder

pub fn set_mint_asset( &mut self, policy_script: &NativeScript, mint_assets: &MintAssets, ) -> Result<(), JsError>

👎Deprecated since 11.2.0: Mints are defining by MintBuilder now. Use .set_mint_builder() and MintBuilder instead.

!!! DEPRECATED !!! Mints are defining by MintBuilder now. Use .set_mint_builder() and MintBuilder instead. Add a mint entry to this builder using a PolicyID and MintAssets object It will be securely added to existing or new Mint in this builder It will replace any existing mint assets with the same PolicyID

pub fn add_mint_asset( &mut self, policy_script: &NativeScript, asset_name: &AssetName, amount: &Int, ) -> Result<(), JsError>

👎Deprecated since 11.2.0: Mints are defining by MintBuilder now. Use .set_mint_builder() and MintBuilder instead.

!!! DEPRECATED !!! Mints are defining by MintBuilder now. Use .set_mint_builder() and MintBuilder instead. Add a mint entry to this builder using a PolicyID, AssetName, and Int object for amount It will be securely added to existing or new Mint in this builder It will replace any previous existing amount same PolicyID and AssetName

pub fn add_mint_asset_and_output( &mut self, policy_script: &NativeScript, asset_name: &AssetName, amount: &Int, output_builder: &TransactionOutputAmountBuilder, output_coin: &Coin, ) -> Result<(), JsError>

Add a mint entry together with an output to this builder Using a PolicyID, AssetName, Int for amount, Address, and Coin (BigNum) objects The asset will be securely added to existing or new Mint in this builder A new output will be added with the specified Address, the Coin value, and the minted asset

pub fn add_mint_asset_and_output_min_required_coin( &mut self, policy_script: &NativeScript, asset_name: &AssetName, amount: &Int, output_builder: &TransactionOutputAmountBuilder, ) -> Result<(), JsError>

Add a mint entry together with an output to this builder Using a PolicyID, AssetName, Int for amount, and Address objects The asset will be securely added to existing or new Mint in this builder A new output will be added with the specified Address and the minted asset The output will be set to contain the minimum required amount of Coin

pub fn add_extra_witness_datum(&mut self, datum: &PlutusData)

pub fn get_extra_witness_datums(&self) -> Option<PlutusList>

pub fn set_donation(&mut self, donation: &Coin)

pub fn get_donation(&self) -> Option<Coin>

pub fn set_current_treasury_value( &mut self, current_treasury_value: &Coin, ) -> Result<(), JsError>

pub fn get_current_treasury_value(&self) -> Option<Coin>

pub fn new(cfg: &TransactionBuilderConfig) -> Self

pub fn get_reference_inputs(&self) -> TransactionInputs

pub fn get_explicit_input(&self) -> Result<Value, JsError>

does not include refunds or withdrawals

pub fn get_implicit_input(&self) -> Result<Value, JsError>

withdrawals and refunds

pub fn get_total_input(&self) -> Result<Value, JsError>

Return explicit input plus implicit input plus mint

pub fn get_total_output(&self) -> Result<Value, JsError>

Return explicit output plus deposit plus burn

pub fn get_explicit_output(&self) -> Result<Value, JsError>

does not include fee

pub fn get_deposit(&self) -> Result<Coin, JsError>

pub fn get_fee_if_set(&self) -> Option<Coin>

pub fn add_change_if_needed( &mut self, address: &Address, ) -> Result<bool, JsError>

Warning: this function will mutate the /fee/ field Make sure to call this function last after setting all other tx-body properties Editing inputs, outputs, mint, etc. after change been calculated might cause a mismatch in calculated fee versus the required fee

pub fn add_change_if_needed_with_datum( &mut self, address: &Address, plutus_data: &OutputDatum, ) -> Result<bool, JsError>

pub fn calc_script_data_hash( &mut self, cost_models: &Costmdls, ) -> Result<(), JsError>

This method will calculate the script hash data using the plutus datums and redeemers already present in the builder along with the provided cost model, and will register the calculated value in the builder to be used when building the tx body. In case there are no plutus input witnesses present - nothing will change You can set specific hash value using .set_script_data_hash NOTE: this function will check which language versions are used in the present scripts and will assert and require for a corresponding cost-model to be present in the passed map. Only the cost-models for the present language versions will be used in the hash calculation.

pub fn set_script_data_hash(&mut self, hash: &ScriptDataHash)

Sets the specified hash value. Alternatively you can use .calc_script_data_hash to calculate the hash automatically. Or use .remove_script_data_hash to delete the previously set value

pub fn remove_script_data_hash(&mut self)

Deletes any previously set plutus data hash value. Use .set_script_data_hash or .calc_script_data_hash to set it.

pub fn add_required_signer(&mut self, key: &Ed25519KeyHash)

pub fn full_size(&self) -> Result<usize, JsError>

pub fn output_sizes(&self) -> Vec<usize>

pub fn build(&self) -> Result<TransactionBody, JsError>

Returns object the body of the new transaction Auxiliary data itself is not included You can use get_auxiliary_data or build_tx

pub fn build_tx(&self) -> Result<Transaction, JsError>

Returns full Transaction object with the body and the auxiliary data NOTE: witness_set will contain all mint_scripts if any been added or set NOTE: is_valid set to true NOTE: Will fail in case there are any script inputs added with no corresponding witness

pub fn build_tx_unsafe(&self) -> Result<Transaction, JsError>

Similar to .build_tx() but will NOT fail in case there are missing script witnesses

pub fn min_fee(&self) -> Result<Coin, JsError>

warning: sum of all parts of a transaction must equal 0. You cannot just set the fee to the min value and forget about it warning: min_fee may be slightly larger than the actual minimum fee (ex: a few lovelaces) this is done to simplify the library code, but can be fixed later

Trait Implementations

impl Clone for TransactionBuilder

fn clone(&self) -> TransactionBuilder

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TransactionBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.