cardano-serialization-lib
cardano-serialization-lib copied to clipboard
Conway
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
: Addedref_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 calladd_change_if_needed
after it. -
add_inputs_from_and_change_with_collateral_return
: Considers change calculation and collateral return; no need to calladd_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.
- NOTE:
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 toCredential
. -
StakeCredKind
was renamed toCredKind
. -
StakeCredentials
was renamed toCredentials
.
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 removednew_coins_per_word
inDataCost
. - In
TransactionOutputAmountBuilder
, switch towith_asset_and_min_required_coin_by_utxo_cost
, aswith_asset_and_min_required_coin
is now removed.
- Use
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
, andadd_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
, oradd_bootstrap_input
. - For script inputs: Use
add_native_script_input
oradd_plutus_script_input
.
- For non-script inputs: Use
PlutusScriptSource Enhancement:
-
Updated:
new_ref_input
inPlutusScriptSource
now includes a language version argument, replacing the oldnew_ref_input
. -
Removed:
new_ref_input_with_lang_ver
becausenew_ref_input
has the same functionality and no need for a specific function with a language version. -
Changed:
PlutusScriptSource.new_ref_input
now requiresscript_size
parameter to respectref_script_coins_per_byte
from protocol parameters and correct fee calculation from Conway era. You need also setref_script_coins_per_byte
viaTransactionBuilderConfig
to use it correctly.
Script Source Unification:
-
Updated:
new_ref_input
inNativeScriptSource
now requiresrequired_signers
. To set it, useNativeScriptSource.set_required_signers
.
Multiple Mints:
-
Updated:
Mint.get()
now returnsMintsAssets
type to respect key duplication inMint
field. -
Replacement Guideline: Use
MintsAssets
instead ofMintAssets
.
Referenced Native Script:
-
Changed:
TxInputsBuilder.add_native_script_input
now requiresNativeScriptSource
to support referenced native script. UseNativeScriptSource::new
to useNativeScript
witness as before, and useNativeScriptSource::new_ref_input
to use referenced native script. -
Replacement Guideline: Use
NativeScriptSource::new(NativeScript::new())
instead ofNativeScript::new()
.
Duplicated Keys Support in Plutus Datum Maps:
-
Changed:
PlutusMap.get
returns an instance ofPlutusMapValues
,PlutusMap.insert
accepts an instance ofPlutusMapValues
to support duplicated keys in a datum map. -
Replacement Guideline: Use
PlutusMapValues.add
and thenPlutusMap.insert
or just usePlutusMap.add_value
.PlutusMapValues
has an accessor functionPlutusMapValues.get()
to get a specific value andPlutusMapValues.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 useTransactionBuilderConfigBuilder.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.