12.0.0 beta 1

THIS IS A BETA RELEASE, AND SOME THINGS MIGHT CHANGE IN THE FINAL 12.0.0

Update Summary

1. Address Types:

• Added network_id getter to Address types.
• Introduced new address type: Malformed. Used when it's impossible to deserialize an address in structs where the address is a nested type.
• New getter for address: kind(). Returns an enum with address type.
• New getter for address: payment_cred(). Returns payment credential.
• New function for address: is_malformed().

2. PlutusV3 Support:

• Added PlutusV3 support in all Plutus-specific structures.

3. Token Handling:

• Prohibited sending and minting of zero tokens.

4. New Certificates:

Added support for the following certificates (can be added via CertificatesBuilder):

• CommitteeColdResign
• CommitteeHotAuth
• DrepDeregistration
• DrepRegistration
• DrepUpdate
• StakeAndVoteDelegation
• StakeRegistrationAndDelegation
• StakeVoteRegistrationAndDelegation
• VoteDelegation
• VoteRegistrationAndDelegation

5. Reference Script Fee:

• TransactionBuilderConfigBuilder: Added ref_script_coins_per_byte setter to account for new fees for reference script inputs.
• PlutusScriptSource: Now requires an additional mandatory parameter for script size for reference inputs.

6. New Builder Types:

• VotingBuilder: For participation in voting for governance actions.
• VotingProposalBuilder: For proposing voting actions.
• TransactionBuilder: Now has setters for these new builders.

7. Extended Coin Selection Functions:

TransactionBuilder has two new coin selection functions to account for change output and collateral return during fee estimation:

• add_inputs_from_and_change: Considers change calculation; no need to call add_change_if_needed after it.
• add_inputs_from_and_change_with_collateral_return: Considers change calculation and collateral return; no need to call add_change_if_needed after it.
  • NOTE: add_inputs_from_and_change_with_collateral_return doesn't perform coin selection for collateral inputs; you need to specify collateral inputs manually.

8. New Protocol Types for Governance-related Actions:

• VotingProcedure: Vote for specific governance action proposal.
• VotingProcedures: Collection of votes.
• VotingProposal: Proposal of specific governance action.
• VotingProposals: Collection of VotingProposal.
• DRep: Abstraction of delegate representative; can be a credential or a predefined DRep type.
• Voter: Abstraction of voter; can be DRep, SPO, or CC member.
• GovernanceActionId: ID of governance action; tuple of (tx_hash, index_of_voting_proposal). Similar to tx input abstraction.
• Anchor: Abstraction to specify off-chain data; tuple of URL and data hash.
• Governance action types:
  • HardForkInitiationAction
  • InfoAction
  • NewConstitutionAction
  • NoConfidenceAction
  • ParameterChangeAction
  • TreasuryWithdrawalsAction
  • UpdateCommitteeAction

9. Serialization Improvement:

• CSL now doesn't serialize empty collections for most witness types, in accordance with CDDL.

10. Set Behavior and Add Function:

The following types work as a set, and their add function returns a boolean. It returns true if the element is added and false if the element already exists in the collection. In the case of false, the size of the collection remains unchanged:

• Credentials
• Ed25519KeyHashes
• Vkeywitnesses
• VotingProposals
• TransactionInputs
• Certificates

Breaking Changes:

StakeCredential Renaming:

• StakeCredential was renamed to Credential.
• StakeCredKind was renamed to CredKind.
• StakeCredentials was renamed to Credentials.

TransactionBody Struct Changes:

• Removed: multiassets() due to its confusing naming.
• Note: Use mint() to obtain information about minting in a transaction.

Fee Calculation Functions Changes:

• Removed: All functions based on 'cons per word', aligning with the protocol's transition to 'coins per byte' in the Babbage era.
• Replacement Guidelines:
  • Use new_coins_per_byte instead of the removed new_coins_per_word in DataCost.
  • In TransactionOutputAmountBuilder, switch to with_asset_and_min_required_coin_by_utxo_cost, as with_asset_and_min_required_coin is now removed.

ADA Requirement Function Updates:

• Removed: min_ada_required due to its inability to account for full transaction output fields and reliance on the outdated coins per word parameter.
• Replacement Guideline: Use min_ada_for_output.

TransactionBuilderConfigBuilder Adjustments:

• Removed: coins_per_utxo_word.
• Replacement Guideline: Use coins_per_utxo_byte.

NetworkInfo Simplification:

• Removed: testnet() function, as the testnet has been replaced by testnet preprod and testnet preview.

Script Transaction Inputs Overhaul:

• Removed: Functions like add_script_input, add_input, count_missing_input_scripts, add_required_script_input_witnesses, and add_required_plutus_input_scripts, used for adding script transaction inputs without a script witness.
• Replacement Guideline:
  • For non-script inputs: Use add_regular_input, add_key_input, or add_bootstrap_input.
  • For script inputs: Use add_native_script_input or add_plutus_script_input.

PlutusScriptSource Enhancement:

• Updated: new_ref_input in PlutusScriptSource now includes a language version argument, replacing the old new_ref_input.
• Removed: new_ref_input_with_lang_ver because new_ref_input has the same functionality and no need for a specific function with a language version.
• Changed: PlutusScriptSource.new_ref_input now requires script_size parameter to respect ref_script_coins_per_byte from protocol parameters and correct fee calculation from Conway era. You need also set ref_script_coins_per_byte via TransactionBuilderConfig to use it correctly.

Script Source Unification:

• Updated: new_ref_input in NativeScriptSource now requires required_signers. To set it, use NativeScriptSource.set_required_signers.

Multiple Mints:

• Updated: Mint.get() now returns MintsAssets type to respect key duplication in Mint field.
• Replacement Guideline: Use MintsAssets instead of MintAssets.

Referenced Native Script:

• Changed: TxInputsBuilder.add_native_script_input now requires NativeScriptSource to support referenced native script. Use NativeScriptSource::new to use NativeScript witness as before, and use NativeScriptSource::new_ref_input to use referenced native script.
• Replacement Guideline: Use NativeScriptSource::new(NativeScript::new()) instead of NativeScript::new().

Duplicated Keys Support in Plutus Datum Maps:

• Changed: PlutusMap.get returns an instance of PlutusMapValues, PlutusMap.insert accepts an instance of PlutusMapValues to support duplicated keys in a datum map.
• Replacement Guideline: Use PlutusMapValues.add and then PlutusMap.insert or just use PlutusMap.add_value. PlutusMapValues has an accessor function PlutusMapValues.get() to get a specific value and PlutusMapValues.len() to get the total number of values.

Ref Script Fee Support:

• Changed: TransitionBuilder now can throw an error during the building process if you are using reference inputs with a Plutus script. To avoid it, you need to use TransactionBuilderConfigBuilder.ref_script_coins_per_byte to specify ref script byte cost and have correct fee calculations. PlutusScriptSource.new_ref_input requires script size to have correct fee calculation.
• Note: If you use CSL in a pre-Conway environment, you can set script size and ref_script_coins_per_byte to zero.

Published

https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-browser/v/12.0.0-beta.1
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-nodejs/v/12.0.0-beta.1
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-asmjs/v/12.0.0-beta.1
https://crates.io/crates/cardano-serialization-lib/12.0.0-beta.1

Experimental packages with gc support

https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-nodejs-gc
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-browser-gc
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-asmjs-gc

Full Changelog: 11.5.0...12.0.0-beta.1

11.5.0 "Amnesia"

Release PR: #633

Changes

Added add_change_if_needed_with_datum function to the TransactionBuilder type. The function provides ability to send change to a plutus script address with a datum or datum hash. Added a new type OutputDatum specify datum or datum hash as function argument. .
Fixed memory issue for asmjs version.
Updated link in the CSL doc. Thanks @katomm

Published

https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-browser/v/11.5.0
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-nodejs/v/11.5.0
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-asmjs/v/11.5.0
https://crates.io/crates/cardano-serialization-lib/11.5.0

11.4.0 "Who are you, mister tx output"

Release PR: #612

Changes

Added from_address function to the PlutusData type. The function converts address to a datum format.
Added serialization_formatfunction to the TransactionOutput type. This function provides access to information about TransactionOutput format after deserialization.

Published

https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-browser/v/11.4.0
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-nodejs/v/11.4.0
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-asmjs/v/11.4.0
https://crates.io/crates/cardano-serialization-lib/11.4.0

11.3.1 "Small steps"

Release PR: #603

Changes

• Fixed reordering in the PlutusMap
• Fixed protocol_magic -> network_id mapping for the ByronAddress
• Updated Plutus cost models for the new HF

Published:

https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-browser/v/11.3.1
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-nodejs/v/11.3.1
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-asmjs/v/11.3.1
https://crates.io/crates/cardano-serialization-lib/11.3.1

11.3.0 "I know that reference"

API Changes

Safe transaction body serialization roundtrip. #582

We introduce FixedTransaction. That new type can help you save the original CBOR bytes of a transaction body for reasons you need to keep it unchanged. For example, when you need to add a new witness to a transaction.
Example:

let mut original_tx = FixedTransaction::from_hex("tx hex").unwrap();
original_tx.set_witness_set(get_new_witness_set().to_bytes())
let tx_bytes = original_tx.to_bytes()
// submit your tx or use it somewhere else

Non API Changes

Plutus script minting by ref script. #568

Despite that you can use PlutusScriptSource in the MinBuilder. The MinBuilder doesn't support ref inputs inside itself. Since this version we fixed that and you can easily mint something by plutus script ref.

Published:

https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-browser/v/11.3.0
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-nodejs/v/11.3.0
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-asmjs/v/11.3.0
https://crates.io/crates/cardano-serialization-lib/11.3.0

11.2.1 "Unbelievable protocol params"

Release PR: #566

Fixed ProtocolParamUpdate serialization

Published:

https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-browser/v/11.2.1
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-nodejs/v/11.2.1
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-asmjs/v/11.2.1
https://crates.io/crates/cardano-serialization-lib/11.2.1

11.2.0 "Mint 'em all"

Release PR: #560

API Changes

Mint builder and plutus mint support. #551

We introduce MintBuilder. MintBuilder can help you to make mints with native scripts or Plutus scripts.
Example:

        let mut mint_builder = MintBuilder::new();
        let plutus_script_source = PlutusScriptSource::new(&get_plutus_script());
        let mint_witnes = MintWitness::new_plutus_script(&plutus_script_source, &get_redeemer());
        let mint_witnes_native_script = MintWitness::new_native_script(&get_native_script());
        mint_builder.add_asset(&mint_witnes, &get_asset_name(), &get_amount());
        mint_builder.add_asset(&mint_witnes_native_script, &get_asset_name(), &get_amount());

Send all #480

Added create_send_all function. The fuction prepares batch of Transaction with all utxos that you put to the create_send_all argument. NOTE: create_send_all supports only non script inputs.

Lang version and ref script input #544

Now PlutusScriptSource has function .new_ref_input_with_lang_ver. The new function consider plutus lang version in its argument. .new_ref_input_with_lang_ver helps for correct .calc_script_data_hash calculation in TransactionBuilder. We recommend to use .new_ref_input_with_lang_ver instead .new_ref_input.

Multiple script inputs #539

We fixed logic for inputs with the same script addresses. Now if you wanna add missed scripts to your inputs you should use .add_required_script_input_witnesses instead of .add_required_plutus_input_scripts.

set_prefer_alonzo_format #522

Added .set_prefer_alonzo_format function to AuxiliaryData. It helps to keep alonzo format during AuxiliaryData serialization.

New testnet NetworkInfo #563

Added testnet_preview and testnet_preprod functions for preview and preprod networks.

Published:

https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-browser/v/11.2.0
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-nodejs/v/11.2.0
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-asmjs/v/11.2.0
https://crates.io/crates/cardano-serialization-lib/11.2.0

11.1.1 "Plumbing"

Release PR: #555

Bindgen library dependency updated

11.1.0 "Dancing Babbage"

Release PR: #529

API Changes

Reference inputs support. #514

We introduce DatumSource and PlutusScriptSource types for easily use plutus scripts and datums references. Just create them and put to a new PlutusWitness instance by PlutusWitness::new_with_ref() . See example below.

        let datum: PlutusData = get_datum();
        let input_with_ref_datum: TransactionInput = get_input_with_ref_datum();

        //You can create datum source with a datum or with a ref input
        let datum_source = DatumSource::new(&datum);
        let datum_ref_source = DatumSource::new_ref_input(&input_with_ref_datum);

        let script: PlutusScript = get_script();
        let input_with_ref_script: TransactionInput = get_input_with_ref_script();
        let script_hash: ScriptHash = get_script_hash();

        //You can create script source with a script or with a ref input
        let script_source = PlutusScriptSource::new(&script);
        let script_ref_source = PlutusScriptSource::new_ref_input(&script_hash, &input_with_ref_script);

        //and use script and datum source to create a plutus witness
        let plutus_witness = PlutusWitness::new_with_ref(&script_ref_source, &datum_ref_source, &get_redeemer());

        //also possible to mix ref inputs source and non-ref inputs source or use just non-ref inputs sources
        let plutus_witness = PlutusWitness::new_with_ref(&script_source, &datum_ref_source, &get_redeemer());

        //and in the and you just add plutus script input as you do it before
        let tx_inputs_builder = TxInputsBuilder::new();
        tx_inputs_builder.add_plutus_script_input(&plutus_witness, &get_script_input(), &get_amount());

Json and hex serialization support for protocol types. #345 #489 #293

Now, most of the protocol types (but not all) in the CSL contains to_json, from_json, to_hex, from_hex functions.
By to_hex and from_hex you can serialize and deserialize a type instance to or from string with CBOR represented in hex format.
By to_json, from_json you can serialize and deserialize a type instance to or from JSON string, that might help to provide more information when you create an issue on CSL GitHub. Or to build or change protocol type instance by your hands.
There is alsoto_js_value that is available only in js API. to_js_value map a type instance to a js type. For example TransactionInput instance maps to a TransactionInputJSON type. All available ***JSON types you can see in js API.

Cardano-cli JSON datum format support. #357

Despite that we have to_json, from_json support for protocol types. Datum JSON in the cardano-cli format can be represented in two ways by BasicConversions (ScriptDataJsonNoSchema in cardano node ) and DetailedSchema(ScriptDataJsonDetailedSchema in cardano node ). For the PlutusDatum type the functions to_json and from_json are implemented with additional parameter of PlutusDatumSchema type. Also there are 'old style' functions encode_json_str_to_plutus_datum and decode_plutus_datum_to_json_str like as for a metadatum.

Additional changes.

• Now error text from add_change_if_needed contains information about how much assets or ada not enough to cover all outputs, except a change. #520
• The min_ada_for_output function now uses only babbage era algorithm, it usually calculates less ada then pre-babbage algorithm. #526
• Fixed the add_mint_asset function. Now it adds mint assets without replacing old value. #513
• Fixed RandomImproveMultiAsset algorithm for add_inputs_from function. Now it take into account previously added assets and ada into a tx builder. #523
• DeserializeError and JsError now implements std::error::Error #506

Thank all who took part in this release!

Published:

https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-browser/v/11.1.0
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-nodejs/v/11.1.0
https://www.npmjs.com/package/@emurgo/cardano-serialization-lib-asmjs/v/11.1.0
https://crates.io/crates/cardano-serialization-lib/11.1.0

11.0.5 "Cost per Byte"

Release PR: #504

An update to the min-ada fix introduced in two previous releases