Cardano Node 1.29.0

This release is an important update to the node that provides the functionality that is needed following the Alonzo hard fork.
All users, including stake pool operators, must upgrade to this version (or a later version) of the node.

The release includes features that will enable the use of the node in the Alonzo era, allowing the on-chain execution of Plutus scripts,
including extended CLI commands to support the construction of transactions that include Plutus scripts, datums and redeemers.
It incorporates several improvements, including a new transaction build command that calculates transaction fees and Plutus script execution units, and a new version of the query tip command that provides additional information, including node synchronisation progress. The transaction build command requires a local instance of the node in order to check Plutus script validity and to provide information that is used by the fee calculation. The Shelley specification has also been updated with respect to rewards calculation.

Note that this release changes the log format of traces configured by TraceChainSyncHeaderServer and TraceChainSyncClient . See #2746 for more detail.

• When migrating to 1.29.0, SPOs need to make the following changes:
  • Download mainnet-alonzo-genesis.json file
  • Update mainnet-config.json file to include the following 2 lines:

  "AlonzoGenesisFile": "mainnet-alonzo-genesis.json",
  "AlonzoGenesisHash": "7e94a15f55d1e82d10f09203fa1d40f8eede58fd8066542cf6566008068ed874",

Node changes

• Introduce support for running an Alonzo node. (#2642, #2649, #2657, #2738, #2759)
• Add a separate genesis file for Alonzo. This must be present when forking to the Alonzo era. It provides initial configuration for new parameters required in Alonzo, such as cost models and pricing for Plutus scripts. (#2743, #2765)
• Update the genesis hash mismatch error for Alonzo. (#3003)
• Add cardano-tx-generator. This is a testing utility. (#2603)
• Add additional capabilities to the tx generator:
  • Plutus. (#2853)
  • Fees and UTxO. (#2980)
  • Miscellaneous bugfixes. (#3015)
• Introduce the trace-forward library, which is part of the replacement for the logging infrastructure. (#2960)
• Add the difference in chain length to the AddedToCurrentChain and SwitchedToAFork traces. (#2678)
• Additional block hashes added to TraceBlockFetchServerSendBlock, TraceForgedBlock, CompletedBlockFetch events. (#2710)
• The various ChainSync server traces provide additional fields that help in debugging. Note that this entails a change to the log format. (#2746)
• Various documentation updates. (#2681, #2689, #2713, #2837, #2857, #2860, #2870, #2874, #2914, #2933)
• Various build, testing and benchmarking infrastructure improvements. (#2672, #2676, #2682, #2705, #2719, #2722, #2730, #2737, #2748, #2766, #2768, #2777, #2796, #2812, #2813, #2826, #2827, #2831, #2832, #2833, #2849, #2855, #2861, #2864, #2865, #2866, #2879, #2887, #2888, #2894, #2900, #2902, #2909, #2912)

Consensus changes

• Introduce the Alonzo era. (#3131, #3138)
• Enable the Alzono era by default. (#3295)
• Additional testing in the Alonzo era. (#3191, #3210)
• Allow the EpochInfo provided to the ledger to fail. This is necessary when the ledger may be querying for time conversions outside of the forecast window. (#3098)
• The mempool now checks bounds on the capacity of execution units allowed when forging a new block. This is needed to avoid trying to create invalid blocks in Alonzo. (#3224)
• Allow the node to modify the maximum capacity of the mempool, in terms of various factors (size, execution units) on a per-node basis. (#3238, #3246, #3261, #3266)
• Update the mempool design for compatibility with Alonzo, which requires some additional logic to deal with 2-phase validation. (#3066)
• Update consensus documentation. (#3071, #3155, #3195)
• Updates to the io-sim testing infrastructure. (#3076, #3172, #3196, #3222)
• Node to client queries are now wrapped in a top-level versioned Query type, in preparation for adding new queries to the node. (#3106)
• Support additional queries now exposed through the API/CLI. (#3220)
• Documentation updates. (#3269, #3273)
• Reject invalid scripts coming from the local wallet. This is a fallback measure which allows the node to protect the user from accidentally losing their collateral. (#3230)

Ledger changes

• Implementation of the Alonzo era. (#2260, #2264, #2265, #2270, #2273, #2274, #2277, #2283, #2287, #2294, #2295, #2296, #2299, #2302, #2303, #2304, #2305, #2306, #2317, #2320, #2322, #2324, #2328, #2329, #2335, #2342, #2345, #2355, #2359)
• Define the CDDL for Alonzo datatypes. (#2281, #2315, #2337, #2362)
• Testing work for the Alonzo era. (#2259, #2261, #2263, #2272, #2275, #2279, #2280, #2293, #2311, #2334, #2340, #2361)
• Additional testing for serialisation of types which are depended on by consensus. (#2298, #2323)
• Add the ability to query the UTxO by TxIn, which is now used by the CLI. (#2331)
• Updates to the Alonzo formal specification. (#2353, #2258, #2271, #2341)
• Rename the IsValidating field in Alonzo to IsValid. (#2396)
• Testing for the Alonzo era. (#2348, #2380, #2390)
• Update the Alonzo Tx to include the validity flag, which will now be passed by the client and other nodes. (#2379)
• Add the ability to convert from slot time to UTC time within the forecast window. This will be necessary for Plutus scripts. (#2297)
• Fix the version of Plutus to be used in release. ((#2369, #2372, #2384, #2420, #2425)
• Canonically encode the subset of protocol parameters presented to Plutus scripts. Since this is not user-provided, but instead generated by the node, we need to use the canonical encoding here. (#2357)
• Add utilities for computing the transaction fee, for use in the CLI. (#2376)
• Improved error message when collateral fails. (#2409)
• Add reporting of why Plutus scripts fail, sufficient to locally reproduce the failure. (#2386, #2430)
• Expanded benchmarks for performance critical functions. (#2262)
• Introduce the event logger. This allows the ledger to emit extra information during normal operation for the use of downstream components. The initial use of this will be for db-sync to validate its computation of rewards. (#2373, #2405, #2417, #2431)
• Add utilities to measure ExUnits in order to allow consensus to apply block-level limits. (#2391)
• Disallow extra redeemers in the witness set. (#2392, #2393)
• Allow script stake credentials to earn rewards. (#2400)
• Updated the Shelley spec with an image depicting the reward process and the various phases it goes through. (#2282)
• Add an errata to the Shelley spec, which addresses:
  • Reward calculation & stake addresses registration timing.
  • Add a note about Byron redeem addresses being returned to the reserves.
  • Define precisely how reward aggregation works.
  • A discrepancy in the use of the Stability window between the spec and the
    implementation.
  • The use of the incorrect reserve pot when creating the reward update.
    (#2323)
• Align the Shelley spec with code. (#2339)
• Restrict the pool metadata hash to the correct size for such a hash. (#2358)

Network changes

• Work on the network-mux. (#2999, #3100, #3121, #3160, #3166, #3193, #3204)
• Add an additional tracer to the BlockFetch protocol. (#3190)
• Monitor exceptions thrown by the accept loop. This addresses an issue where the accept loop could die and the node stop accepting connections. (#3299, #3305)
• Update the specification document. (#3257)
• Update network documentation. (#2887, #3071, #3089, #3126, #3217)

Cardano-cli changes

• The query tip command is now tidier (#2885) and shows additional information:
  • The epoch number is now shown during the Byron era. Previously this worked only in the Shelley and subsequent eras. (#2688)
• Attempting to use an IPv6/IPv4 address where the other is expected will now give a more helpful error message. (#2691)
• Queries should now work during the Alonzo era. (#2727, #2755)
• Support for submitting transactions during the Alonzo era. (#2774, #2798, #2806, #2811, #2823, #2863, #2848)
• cardano-cli genesis create now also creates the new Alonzo genesis file. (#2743)
• The UTxO CLI query now allows an additional --tx-in flag which allows filtering the UTxO by TxIn, and requires the addition of the --whole-utxo flag to return the complete UTxO set (which was previously the default). Returning the whole UTxO set is an expensive operation only useful in small testnets, so we don't want it as the default option. (#2843, #2854)
• The parser for rational units (as used in for example execution unit prices) now supports rational syntax (e.g. 1/2). (#2922)
• Add a "tx build" command to the CLI. This command takes care of calculating the appropriate fee for a transaction, and balancing the transaction appropriately. It does not do input selection for fees, so sufficient balance must be available in the inputs to pay the computed fee, and sufficient collateral must also be present when phase-2 validating scripts are used. The tx build command is capable of computing both the fees required from transaction size and the fees incurred by script execution. (#2921, #2953, #2995, #3025)
  Improve the output format for rational fields in protocol parameters and genesis. When these are simple, we now convert them to decimal format. (#2992)
• Improved formatting of the CLI help text. (#2945)
• Introduce the --script-valid and --script-invalid flags. The latter can be used to mark a script as being known invalid, such that the node will allow it to be submitted anyway (whereas under normal operation it would reject such a transaction in order to avoid loss of collateral). This flag is only likely to be of use in testing. The --script-valid flag is set as a default. (#3050, #3091, #3093)
• Add colours to the CLI output. (#3023)

Cardano-api changes

• Support for the Alonzo era, including protocol parameters, Plutus scripts and collateral inputs. (#2784, #2798, #2808, #2810, #2815, #2818, #2823, #2828)
• Add support for querying the Alonzo ledger state. (#2974)
• Add a function 'getTransactionBodyContent'. This extracts a general view of the TxBody from the era-specific bodies. (#2663)
• Add API support for new node queries:
  • QuerySystemStart gets the system start time.
  • QueryStakePools and QueryStakePoolParameters can be used to get details on the currently known stake pools.
  • QueryUTxOFilter provides various ways to query a filtered subset of the UTxO.
    (#2843)
• Add functions to the API to assist in automated transaction building:
  • evaluateTransactionBalance computes the current balance of a (partial) transaction, which is helpful for determining what needs to be done to correctly balance it (such that value produced equals value consumed).
  • evaluateTransactionExecutionUnits computes how many ExUnits will be needed by all the scripts in a (partial) transaction.
  • evaluateTransactionFee computes the fee for a (partial) transaction, assuming a given number of VKey witnesses (corresponding to inputs).
  • estimateTransactionKeyWitnessCount attempts to estimate the number of VKey witnesses needed.
  • makeTransactionBodyAutoBalance attempts to create and automatically balance a transaction body, using the above tools.
    (#2906)
• Support for automated Tx building. (#2953)
• A few additional exports for API consumers. (#3001, #3055)
• Block folding interface now derives the network ID automatically from the ledger config. (#2955, #2975)
• Improve the error generated when a Tx output does not meet the minimum UTxO value. (#3027)
• Update the API documentation.

Deprecated Features

Fixed Issues

• Fix a bug in deserialisation of witnesses. This would allow for somebody to include signatures of something other than the transaction body, which would not be deserialised and hence could persist on the chain. Unfortunately we have to continue to allow this in pre-Alonzo eras since it has been observed on the public testnet. (#2419, #2432)

Known Issues

• Sync times may be 10%-20% worse than 1.27.0
• [FR] - Cli to pass required signer (reqSignerHashes) to plutus script for txInfoSignatories (#3106)
• Transaction's valid time range is not passed to ScriptContext (#3090)
• transaction view does not work for Alonzo era transactions (#3039)
• Withdrawal doesn't work with transaction build command (#3074)
• [FR] - Lovelace output needed when output address for native tokens is the same as change address (#3057)
• Plutus transaction txins are not properly validated in build command (#3018)
• transaction build does not balance correctly when the certificate is already submitted (#3040)
• transaction build attempts to create UTxO with 0 lovelace as change (#3041)
• [FR] - Reject non-key-locked collateral inputs (#3112)
• [FR] - Make transaction build to balance automatically also the multi-assets (#3068)
• [FR] - Add input utxo validation to transaction build cmd (#2996)
• [FR] - improve the formatting of the additional information that is provided when Plutus scripts fail (#3126)
• [FR] - Return the transaction fee when executing transaction build command (#3024)

Documentation

• Cardano Node documentation
• Cardano CLI
• Internal API docs for ledger, consensus and network
• Configuration files
• Compatibility matrix

Platforms

• Linux 64-bit (Ubuntu 18.04 LTS, 20.04 LTS; Mint 19.3, 20; Debian 10.3)
• Windows 64-bit (8.1, 10)
• MacOS 10.13, 10.14, 10.15
• Docker image
• Hydra binaries

Supported roles

Platform	Block Production	Relay	Client (Desktop)
Linux	✔️	✔️	✔️
Windows	❌	❌	✔️
MacOS	❌	❌	✔️

Minimum System Requirements

• An Intel or AMD x86 processor with two or more cores, at 1.6GHz or faster (2GHz or faster for a stake pool or relay)
• 8GB of RAM
• 10GB of free storage (20GB for a stake pool)

Sign off

Role	Approval
Technical Lead	✔️
QA Engineer	✔️
Ops	✔️
Release Manager	✔️