Conway

[lisicky]

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.

[sonarqube-yoroi[bot]]

SonarQube Quality Gate

0.0% Coverage on New Code (is less than 80%)

See analysis details on SonarQube

[klarkc]

@lisicky I'm using this branch in mlabs-haskell/cardano-serialization-lib-gc#1, it looks MintsAssets flow definition is not matching MintsAssets rust definition

[lisicky]

Hi @klarkc ! Could you explain the problem ?

[lisicky]

@klarkc thanks, double checked it. Will fix it in 1h

[lisicky]

@klarkc CSL12 alpha 23 is released

[klarkc]

Tested here, fixed, thanks.

Just another thing, it looks like Mint:get now returns MintsAssets instead of MintAssets, this caused a breaking change here because MintsAssets lacks the keys function. It might be helpful for users to notice this change in the changelog - not only a rename, but a whole different structure.

https://github.com/Emurgo/cardano-serialization-lib/blob/ce1cad2276de3f26ed6140e79a33bb305d498b7a/rust/src/lib.rs#L3607

https://github.com/Emurgo/cardano-serialization-lib/blob/3e3380ce3ea8c1f2f27bf81b48ea489756b38f37/rust/src/lib.rs#L2074

[lisicky]

Thanks @klarkc, CSL 12 is not finished yet, and something can be missed

[errfrom]

Hi there, I'm integrating these changes into https://github.com/mlabs-haskell/purescript-cardano-serialization-lib/pull/4 right now and noticed that PoolVotingThresholds is lacking a getter for security_relevant_threshold. Also, committee_term_limit in ProtocolParamUpdate should probably be of type Option<Epoch> rather than Option<u32>.

[lisicky]

Hi there, I'm integrating these changes into mlabs-haskell/purescript-cardano-serialization-lib#4 right now and noticed that PoolVotingThresholds is lacking a getter for security_relevant_threshold. Also, committee_term_limit in ProtocolParamUpdate should probably be of type Option<Epoch> rather than Option<u32>.

Thanks @errfrom ! We will fix it shortly

[errfrom]

Thanks for addressing it, @lisicky! Can you publish the latest version on NPM?

[lisicky]

@errfrom new alpha has been released