10.0.4 "Script Inputs"

Release PR: #376

Main change:

• The issue that has been causing hash_script_data function to produce incorrect hashes for transactions with script inputs is resolved

10.0.3 "Script Signers"

Release PR: #365

Single change:

• New function NativeScript.get_required_signers() is added

10.0.2 "Total Input"

Release PR: #363

Single change:

• The function tx_builder.get_total_input() is made public

10.0.1 "Confusing Seed"

Release PR: #361

Changes:

• Versions of the cryptoxide and ed25519-bip32 libraries are updated in dependencies
• Small internal improvements removing code warnings

10.0.0 "Coins per UTXO Word"

Release PR: #358
Milestone: https://github.com/Emurgo/cardano-serialization-lib/milestone/5?closed=1

Breaking Changes

1. Old protocol param minimum_utxo_val is replaced with coins_per_utxo_word (#219 #248)

The TransactionBuilder and the min_ada_required function now require new value introduced in Alonzo: coins per utxo word, see spec from IOHK: https://github.com/input-output-hk/cardano-ledger/blob/master/doc/explanations/min-utxo-alonzo.rst

The mainnet value for this at the moment is 34_482 (lovelaces).

The min_ada_required function API changed from two required arguments to three: the Value to be estimated, the boolean flag has_data_hash (// whether the output includes a plutus data hash), and the coins_per_utxo_word as BigNum.

2. TransactionBuilder construction API changed (#261 #269 #270)

The list of arguments is replaced with a new config struct and the config-builder, see example of the new usage in Rust here: https://github.com/Emurgo/cardano-serialization-lib/blob/master/rust/src/tx_builder.rs#L1144-L1153

In JS it's something like:

    RustModule.TransactionBuilder.new(
      RustModule.TransactionBuilderConfigBuilder.new()
        .fee_algo(linearFee)
        .pool_deposit(poolDeposit)
        .key_deposit(keyDeposit)
        .coins_per_utxo_word(coinsPerUtxoWord)
        .max_value_size(maxValueBytes)
        .max_tx_size(maxTxBytes)
        .build()
    );

3. Field replacement in ConstrPlutusData (#250)

The ConstrPlutusData field tag: Int is replaced to be alternative: BigNum

4. NativeScript hash return type fixed (#234)

The function ScriptHash.hash return type changed from incorrect Ed25519KeyHash to correct ScriptHash. They are both defined as 28-byte hash types, so functionally there's no fifference but type-checking might fail in strict systems if the incorrect type were used on the client side.

New API features

1. Minting in TransactionBuilder (#231 #273)

The Mint is now can be set to the tx-builder using new .set_mint function, but this requires additional manual handling of witness scripts for minting using the new .set_mint_scripts function. If the fee estimation is attempted without having all matching witness scripts for each used policy-id in the mint - an error will be raised as the correct estimation is not possible. You can still use Mint without providing witness scripts and use automatic change calculation if you set the fee value manually.

Instead, new helper functions can be used: .set_mint_asset, .add_mint_asset, .add_mint_asset_and_output, .add_mint_asset_and_output_min_required_coin. These function take the minting script itself instead of just the policy-id and they both produce the correct mint entry with the policy-id AND include the minting script into the list of witnesses so that the correct fee estimation is possible. The *_and_output functions additionally produce a new output specifically for this new minted asset and either include the specified ADA value or automatically calculate and include the minimum required ADA value.

NOTE: added mint is correctly considered as part of the total input so if you don't send it to any explicit output and calculate the change - it will be added to the change output.

2. Metadata in TransactionBuilder (#231)

Few new helper functions for easier metadata handling: .set_metadata, .add_metadatum, .add_json_metadatum, .add_json_metadatum_with_schema. The set function overwrites the existing value. All add_* functions are null-secure, meaning that in case the auxiliary data or the metadata does not exist yet - it will be safely created and then the new entry will be added to it.

3. Building full Tx in TransactionBuilder (#231)

New function .build_tx() is added which produces an instance of the full Transaction, compared to the existing .build() which returns only the TransactionBody. The important difference is that the full returned Transaction contains the witness_set which will already include all the native scripts if minting were added, plus it contains the auxiliary_data in case the metadata were added, and the validity flag for better compatibility with Alonzo.

If NO minting and no metadata were used - there's not much difference which variant to use. But if minting and/or metadata were added - then it is much more recommended to use .build_tx() and then only add vkey witnesses into the existing witness_set after signing the transaction.

4. Coin-selection in TransactionBuilder (#232 #253 #254 #264)

New function .add_inputs_from is now available which takes an array of available utxo and allows to select the selection strategy: largest-first or random-improve (see CIP2), the function will try to select enough utxo to add them as inputs to cover the required outputs and the fees, which is why it is better to call this function after all target outputs, the mint, and the metadata are added, and before calling .add_change_if_needed.

5. Building outputs (#231 #304 #359)

New structure TransactionOutputBuilder is available now to simplify the output creation. It splits the process into two main parts: specifying the address and optional data-hash, and specifying the value in various optional ways.

The flow of using the builder is like:

1. TransactionOutputBuilder.new() - creates the initial output-builder and provides these functions:
   1. .with_address(Address) - returns new instance with the set address
   2. .with_data_hash(DataHash) - returns new instance with the set hash
   3. .next() - returns the next step output-value-builder, will fail in case the address is not specified, next builder provides these functions:
      1. .with_value(Value) - returns new instance with the exact specified Value
      2. .with_coin(Coin) - returns new instance with the value having only the specified Coin
      3. .with_coin_and_asset(Coin, MultiAsset) - returns new instance with the value having both specified Coin and MultiAsset
      4. .with_asset_and_min_required_coin(MultiAsset, Coin) - returns new instance with the value having the specified MultiAsset and with the coin value calculated automatically as the minimum required amount to cover the assets. (NOTE: the second argument of type Coin is the protocol parameter coins-per-utxo-word and is required for the min-required-ada calculation.)
      5. .build() - returns the final constructed TransactionOutput instance, will fail in case the amount were not specified in any way.

Example of using this from JS would be something like:

txBuilder.add_output(
    TransactionOutputBuilder.new()
    .with_address(address)
    .next()
    .with_asset_and_min_required_coin(multiAsset, config.coins_per_utxo_word)
    .build()
);

6. PrivateKey from bech32 (#244 #245)

New construction option PrivateKey::from_bech32 is now available

7. Cardano-wallet style multisig (#221)

New function are now available to create multisig scripts as supported by cardano-wallet, independent to CIP29.

8. Deprecated Int.as_i32 (#258)

Function Int.as_i32() is deprecated because it silently ignores potential overflow errors and does not indicate it with the name that well. New functions added: .as_i32_or_nothing() which does the same thing and .as_i32_or_fail() which potentially returns an error.

Additionally new function Int.to_str is added, which produces normal decimal string rendering of the underlying i128. Without that function before clients were forced to either use as_i32 or use the awkward BigNum conversion API which requires to do a positive/negative check first.

9. Deprecated TransactionBody.multiassets (#330)

Function TransactionBody.multiassets() is a weirdly named getter for the Mint field in a transaction. This function is deprecated, new properly named function TransactionBody.mint() is now available and must be used.

Internal improvements

1. More secure change with assets with breaking same-policy bundles into multiple outputs if needed (#236 #290)
2. Plutus data serialisation fixes (#228)
3. Plutus hash script data fixes (#217 #347)
4. Asset size calculation fixed to reduce the min-required-ada for utxo a bit (#211)
5. Protocol parameters collateral_percentage and max_collateral_inputs are supported (#308)
6. Plutus datums now preserve the deserialized bytes and will produce exactly same output if serialized again after being parsed (#317)

9.1.4 "Less Crypto in Our Crypto"

Release PR: #323

Changes:

• TransactionBuilder performance is improved by removing unnecessary cryptographic operations

9.1.3 "Duplicate Key"

Release PR: #318

Single change:

• Allow entries with duplicate keys when deserializing transaction metadata

9.1.2 "isValid"

Release PR: #251

Single change that handles new optional transaction flag is_valid - #208

9.1.1 "Canonical"

Release PR: #246

Single change that fixes AssetName to have canonical CBOR ordering implemented for it.
(See related issue: #240)

9.1.0

Release PR: #212

Includes a single change, fixing that the max size limit is checked on output values and not outputs themselves