Skip to content

12.0.0 Conway's Game Of Li... CSL
Compare
Choose a tag to compare
@lisicky lisicky released this 28 Aug 04:45
· 156 commits to master since this release
12.0.0
a2774f6

We are happy to announce a new CSL release.

Release 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

11. New Transaction Builder Functions:

TransactionBuilder has a new functions to set donation to the treasury (TransactionBuilder.set_donation()) and the current treasury value (TransactionBuilder.set_current_treasury_value()). However, if you use these fields, the Cardano node will reject all non-Plutus V3 scripts. These transaction fields can help facilitate direct donations to the treasury and limit transaction execution based on the current treasury value.

12. New Packages With GC Support (EXPERIMENTAL):

CSL now includes NPM packages with GC (Garbage Collection) support, which means you no longer need to manually call .free for every CSL object. This was achieved by enabling the WEAK_REF flag on wasm_bindgen, and it utilizes FinalizationRegistry to automatically call free for each CSL struct when it is no longer needed. However, please use this feature with caution, as it may lead to unpredictable behavior. For package links, refer to the packages in the "Published" section.

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.

NativeScriptSource Enhancement:

  • Changed: NativeScriptSource.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: NativeScriptSource and PlutusScriptSource now has required_signers option. To set it, use NativeScriptSource.set_required_signers or PlutusScriptSource.set_required_signers and TrsansactionBuilder will allocate space for these required_signers during fee calculation.

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.

Transaction Inputs and Reference Inputs Deduplication:

  • Changed: TransactionBuilder now automatically removes reference inputs that are also present in the transaction inputs field. The Cardano node will not accept a transaction that has the same transaction input in both the transaction inputs field and the reference inputs field. The deduplication logic applies to all reference inputs set via builders, except for those explicitly set using TransactionBuilder.set_ref_inputs(). If there is a duplicate between explicitly set reference inputs (via TransactionBuilder.set_ref_inputs()) and the transaction inputs field, TransactionBuilder will throw an error during the building process. To avoid this and enforce deduplication for explicitly set reference inputs, use TransactionBuilderConfigBuilder.deduplicate_explicit_ref_inputs_with_regular_inputs during TransactionBuilder configuration.

Published

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

Experimental packages with gc support

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

Full Changelog: 11.5.0...12.0.0

Emurgo's Contributors:

@lisicky
@vsubhuman
@twwu123

Special thanks to everyone who participated in CSL 12 testing, reviewing, suggesting enhancements, and providing new PRs:

@Ryun1
@itsfarseen
@klntsky
@errfrom
@zxpectre
@klarkc
@kxbt-del
@Scitz0
@gitmachtl
@teebaumcrypto

Contributors

klarkc, vsubhuman, and 11 other contributors
Assets 2
Loading