Skip to content

10.2.0 ".set_collateral"
Compare
Choose a tag to compare
@vsubhuman vsubhuman released this 08 Jun 14:39
· 858 commits to master since this release
10.2.0
1ad1c17

Release PR: #447

Transaction Builder API changes

⚠️ ExUnitPrices (new optional config field)!

TransactionBuilderConfigBuilder now has a new setter function .ex_unit_prices(ExUnitPrices). This property is optional and only required to calculate the fees correctly in case you are using Plutus inputs. The property is NOT required by default for backward compatibility and in case you are not using Plutus inputs at all or in case you are not calculating the fee and change automatically - it will not be required at all.

NOTE: in case you DON'T specify this parameter and you use Plutus inputs with redeemers - calling .add_inputs_from, .fee_for_input, .fee_for_output, .add_change_if_needed, or .min_fee will fail with an error.

Handling collateral inputs with .set_inputs and .set_collateral

All functions related to adding inputs are extracted into a new type TxInputsBuilder, specifically:

  1. .add_input
  2. .add_key_input
  3. .add_script_input
  4. .add_native_script_input
  5. .add_plutus_script_input
  6. .add_bootstrap_input
  7. .count_missing_input_scripts
  8. .add_required_native_input_scripts
  9. .add_required_plutus_input_scripts
  10. .get_native_input_scripts
  11. .get_plutus_input_scripts

The TransactionBuilder still has all these functions for backward compatibility in relation to regular inputs, but they are deprecated now and will be removed in one of the next major versions.

Instead, there are two new function in the TransactionBuilder:

  1. .set_inputs(TxInputsBuilder)
  2. .set_collateral(TxInputsBuilder)

So instead of

txBuilder.add_input(address, input, value);

The proper way of doing it from now on is:

let inputBuilder = TxInputsBuilder.new();
inputBuilder.add_input(address, input, value);

txBuilder.set_inputs(inputBuilder);

Collateral inputs

For collateral inputs there are no functions on the transaction-builder itself, they must be entirely handled though a TxInputsBuilder instance and then added to the transaction-builder using .set_collateral

NOTE: a copy of the inputs is taken when .set_inputs or .set_collateral is called, so changing the TxInputsBuilder instance after that will not affect the transaction-builder itself in any way.

NOTE: there's a new assertion happening at a .build_tx() call - it will also now fail with an error in case the builder has some Plutus inputs, but no collateral inputs specified. The function .build_tx_unsafe() can still be used to avoid that for whatever reason.

Required signers

There's also a single new function .add_required_signer(Ed25519KeyHash) which adds the key into the required_signers field of the transaction in case it's needed for some functionality.

Other new functions

.calculate_ex_units_ceil_cost(ExUnits, ExUnitPrices) -> BigNum

Given the ex-units and the ex-unit prices, calculates the coin required to pay for it. Since the ex-unit prices are specified as fractions the calculations are not as straight as just multiplying two simple numbers. So this function encapsulates all that.

.min_script_fee(Transaction, ExUnitPrices)

Is a new function to be consistent with the the previously existing .min_fee. Given a transaction and the ex-unit prices, it checks if the transaction involves any Plutus inputs and then calculates the combined price of their ex-units.

BigInt

The BigInt wrapper type now includes new functions: self-explanatory .add(BigInt), .mul(BigInt), and .increment(); plus static BigInt.one() which just returns the 1 values as bigint, plus the .div_ceil(BigInt) function which performs the division of two bigint numbers and then CEIL rounds the result to return as also a bigint.

NOTE: that a BigInt instance is immutable and all these functions return the result as a new instance.

Plus also a new function .is_zero() which returns a boolean.

BigNum

Static function BigNum.one() is now available, along with the previously existing BigNum.zero()

PlutusData

New function PlutusData.new_empty_constr_plutus_data(BigNum) creates a new instance of PlutusData containing a ConstrPlutusData with the specified BigNum alternative and empty parameter list.

Similar to calling:

PlutusData.new_constr_plutus_data(ConstrPlutusData.new(BigNum, PlutusList::new()))

Redeemers

New function redeemers.total_ex_units() -> ExUnits return the sum total of all ex-units in the redeemer list.

Assets 2
Loading