Release PR: #438

BREAKING CHANGES (Rust only, JS is not affected)

Native script hash

The function NativeScript.hash() does NOT take any arguments now. Before it was taking the parameter ScriptHashNamespace::NativeScript. This will break at Rust compile time if you have calls to this function in your Rust code.

The change is caused by the addition of the new function PlutusScript.hash() which allows to produce a ScriptHash instance from a plutus script similar to native scripts. It has proved the accepting of the ScriptHashNamespace both unnecessary and potentially problematic. Both functions now work in a consistent way with no arguments.

In JS the existing code where the parameter is passed into the function call does NOT break at runtime, so JS is backward compatible and the removing of the argument in the existing calls is not necessary. It will break type-checkers though, but this is considered a minor issue, the highest priority is to not cause issues in runtime.

Slot type change #367 #430

The type Slot was an alias for u32 and is now replaced with two new types: Slot32 (u32) and SlotBigNum (BigNum). Internally all structs are changed to contain SlotBigNum that allows to deserialise instances with a huge slot number present with no crashing. Any getters that returned Slot are now returning Slot32 (which is the same underlying type) and are deprecated with a new alternative getter added to receive SlotBigNum (e.g. TransactionBody.ttl() and new TransactionBody.ttl_bignum()). Any functions that accepted Slot as argument are now accepting Slot32 and are deprecated as well, and there's a new alternative function added that receives SlotBigNum (e.g. TimelockExpiry.new(Slot32) and new TimelockExpiry.new_timelockexpiry(SlotBigNum)).

The change is breaking for Rust compile time, because the functions that returned Slot are now returning Result<Slot32, JsError>, because the underlying value can be out of bounds and might cause error when trying to convert. In JS for regular cases as long as you are using only safe instances with slot values within the regular bounds - it will not break neither runtime, not type-checkers.

Important to understand that this change is caused by the fact that there are already present cases on the blockchain when transactions contain some fields of type slot out of the u32 bounds, so if your system is processing entire blockchain and potentially trying to parse entire transactions, including deconstructing addresses, for example - the old type Slot32 is not secure for you now and you must update your code to use the new alternative functions with SlotBigNum, otherwise you will get a runtime crash in JS, because the old deprecated getters can now throw an out of bounds conversion error. This is relevant for any fields that can be freely defined by the tx creator - for example, transaction ttl or validity interval start.

Other changes

Burn as part of output #374

The pre-existing function TransactionBuilder.get_total_input() is now changed to return the sum of the explicit input, the implicit input, and all the positive mint in the tx. There's now new function TransactionBuilder.get_total_output() which returns the sum of the explicit output, any redeemed deposits (implicit output), and all the burn (negative mint) in the tx.

Script inputs support in transaction builder #436

Registering script inputs with witnesses

Two new functions available:

1. .add_native_script_input - accepts a NativeScript and the input with its value
2. .add_plutus_script_input - accepts a PlutusWitness and the input with its value

The PlutusWitness is a new available type that combines together a single PlutusScript, single PlutusData datum, and a single Redeemer. The type is designed to provide the Plutus variant of a single combined witness for a separate input, similar how for a native script inputs the NativeScript itself is all that's needed.

The two mentioned above functions will both register the input and also register the corresponding witness for it right away and will then both correctly consider the size of the witnesses when calculating the required fee and also return the witnesses as part of the result transaction when using .build_tx().

Registering script witnesses for already added inputs

The existing generic functions .add_input and .add_script_input can still be used. The only new change is that when added generically script inputs will leave a "missing script slot" which then needs to be filled before the transaction building can happen. The current number of missing scripts can be checked with the new function .count_missing_input_scripts() which just returns the number.

To fill the missing scripts, there are two new functions:

1. .add_required_native_input_scripts - takes an instance of NativeScripts
2. .add_required_plutus_input_scripts - takes an instance of PlutusWitnesses (which is just a collection type, similar to NativeScripts)

These functions will compare the passed scripts with the script-hashes in the registered inputs and only take and register the relevant witness scripts. NOTE: any scripts that don't match any existing input will just be ignored, so first calling to add required scripts and then adding the input later will not work - you must first add the inputs and then call these functions to add the missing scripts (if any required). Both functions return the new number of remaining missing scripts (if zero - then all required scripts are present).

(Note once again: functions to add required scripts must ONLY be used if you have not been using specialised functions .add_native_script_input and .add_plutus_script_input - these functions register scripts automatically.)

Function .get_native_input_scripts and .get_plutus_input_scripts can be used to query the already registered data from the builder.

Script data hash

NOTE: whenever a transaction with plutus script inputs is created, it MUST contain the correct "script data hash" value present or it will not be accepted by nodes. This new field can be operated with new functions:

1. .set_script_data_hash(ScriptDataHash) - in case you already have this value calculated yourself
2. .remove_script_data_hash() - for any case when you need to wipe it from the builder for some reason
3. .calc_script_data_hash(Costmdls) - this function allows to calculate the hash automatically from the witnesses present in the builder at this moment (so it must be called after adding all inputs and all scripts)

The function .calc_script_data_hash takes a single parameter with the Plutus language cost models, which you can create yourself from the protocol parameters, or you can use the predefined constant value for the language version PlutusV1, like this:

txBuilder.calc_script_data_hash(
  CardanoWasm.TxBuilderConstants.plutus_default_cost_models(),
);

The new module TxBuilderConstants contains this single function with the valid (for now) cost model and later might be updated with newer appearing cost models.

Building with scripts validation

The function .build_tx is now updated to perform two new validations:

1. In case there are any missing witness scripts for registered inputs - the function will raise an error
2. In case there are any plutus script inputs, but no value for the script data hash - the function will raise another error

This can be avoided by using new function .build_tx_unsafe, just in case it's needed for some reason.

Fixes

• Large negative integer deserialisation is "fixed" (a hack had to be added, because of an issue in the used library) #392
• Error message in tx_builder fixed #409