Cardano Node 1.31.0

Cardano node version 1.31.0 introduces a number of new features and provides performance improvements, including
reducing default logging information, and optimising memory and time behaviour. It also provides support for improved rewards logging in db-sync, includes a new CLI command to query stake pools, enhances the transaction build CLI command, fixes an issue where connections were dropped when using query tip, and provides various other CLI enhancements. It allows signatures to be specified when spending from pre-Plutus time-lock/multi-signature scripts, improves error logging for Plutus scripts, adds new logging modes, allows the size of the mempool to be configured, provides support for multiple versions of Plutus, and improves networking behaviour and robustness.
It is recommended that all users upgrade to this new version.

Breaking Changes

• Update min utxo calculation cli command #3181
  calculate-min-req-utxo requires a transaction output (TxOut era) instead of a Value in order to calculate the min required UTxO in the Alonzo era. This is required in the Alonzo era, and the change is made everywhere for consistency.

Technical Specification

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)
• 12GB of RAM
• 20GB of free storage

Platforms

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

Supported roles

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

Downloads

• Docker image
• Hydra binaries
• Configuration files

Documentation

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

Changelogs

Node

• Additional verification for the configuration files:
  • Added a CI check that the configuration files in git match those produced during the nix build. (#3222)
  • Add a test that the configuration file is valid. (#3236)
• Various documentation updates. (#3060, #3120, #3142, #3191, #3243, #3265, #3284)
• Introduce the trace-dispatcher library. This is built to replace the existing iohk-monitoring-framework. (#3073)
• Add an example using a Plutus script as a stake credential. (#3162)
• Don't inline a call to maybeToStrictMaybe during translation of ProtocolParameters. This turns out to trigger a GHC bug, resulting in extremely high compilation time. (#3275)
• Introduce a YAML version of the mainnet configuration file, which can and has been commented to explain the various options. (#3269)
• Add various additional metrics:
  • About block propagation. (#2476)
  • Tracking how many tips a node has served to downstream peers. (#3300)
  • Counting the number of forks seen. (#3305)
• Add the ability to configure the mempool capacity override. This allows an individual node operator to alter the maximum size of their mempool along various axes (size, execution units). (#3273)
• Fix the verbosity of some log messages, which was causing excess detail in the node logs. (#3046)

Consensus

• Improved documentation. (#2957, #3279)
• Removed strictness annotations in traces. (#3244)
• Exposing the ledger event logger. (#3292)
• Supporting Alonzo protocol version. (#3347)
• Overhauling the db analyser tool. This will allow the ledger team to run micro benchmarks without noise from other layers (like networking). (#3337)
• Add additional capabilities in the db-analyser. (#3376, #3379, #3397, #3400, #3414, #3418)
• Add a new version (10) of the node to client protocol, with two new queries: GetChainBlockNo and GetChainPoint. (#3346)
• Expose the ability to override the mempool capacity. (#3413)

Ledger

• Additions and corrections in the event logger. (#2441, #2487)
• Memory optimisations. (#2442)
• Updates to the Alonzo formal specification. (#2418, #2448)
• Additional exports needed for db-sync integration. (#2450)
• Moved protocol related types to a new module, cardano-protocol-tpraos. (#2445)
• Preparatory work for storing the ledger state on disk. (#2449)
• Updated the CHAINHEAD rule in the Shelley formal spec. (#2313)
• Providing more information about the reward calculation inside of the reward provenance. (#2433)
• Add a RetiredPools event, which gives details about retiring pools and the refund (or not) of the pool deposit. (#2487, #2495)
• Fix the CDDL specification for transactions. (#2456, #2507, #2523)
• Infrastructure and documentation improvements. (#2499, #2500, #2508)
• Various work factoring out the definition of the transitional Praos protocol and isolating it from the ledger. This is done in anticipation of introducing a new version of the consensus protocol in the Babbage release. (#2491, #2505, #2510, #2516, #2518)
• Document the minimum value computation for Alonzo. (#2486)
• Various changes to compactify the in-memory representation of the Cardano ledger state:
  • Unpack the TxId in a transaction input. (#2501)
• Add support for V2 of Plutus (and for multiple Plutus versions in general). (#2485)
• Expose more information concerning reward computation in the API. This is intended to support revised display of pool rankings in the wallet. (#2511)
• Document both Value and TxInfo in the spec. (#2383, #2494)
• Fix the serialisation of Alonzo transaction witnesses in the case of multiple Plutus versions. (#2525, #2526)
• When incrementally computing the rewards, we now require this computation to complete by the first block within 2k/f slots of the epoch end. Previously it was required to complete by the end of the epoch. The motivation for this is to allow db-sync some time to insert the rewards distributed this epoch (which may be substantial) into its database before the end of the epoch. (#2521)

Network

...

Cardano Node 1.30.1

Technical Specification

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)

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

Supported roles

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

Downloads

• Docker image
• Hydra binaries
• Configuration files

Documentation

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

Changelogs

Node

Consensus

Ledger

• Correctly translate time for Plutus (from protocol version 6 onwards). (#2451)
• Adding changes to the libsodium bindings. Those include a functional fix that makes it safe to call the function that generates a public key from a private key concurrently. We only use those functions in the CLI, in a non-concurrent manner, but they are exposed in cardano-api. This fix ensures that custom code written against cardano-api behaves as expected when run in multiple threads. Furthermore, there are performance improvements that should have a positive impact on sync times. (#236)

Network

Cardano-cli

Cardano-api

Deprecated features

Fixed issues

Sign off

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

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)
• Update...

Cardano Node 1.27.0

Node version 1.27.0 provides important new functionality, including supporting new CLI commands that have been requested by stake pools, providing garbage collection metrics.
It includes the performance fixes for the epoch boundary calculation that were released in node version 1.26.2, plus a number of bug fixes and code improvements.
It also includes many fundamental changes that are needed to prepare for forthcoming feature releases (notably Plutus scripts in the Alonzo era).
Note that this release includes breaking changes to the API and CLI commands, and that compilation using GHC version 8.6.5 is no longer supported.

API refactoring to move scripts into the txbody (#2547)

There are some breaking changes:

• You must specify auxiliary scripts with --auxiliary-script-file instead of --script-file
• Scripts witnessing txins, certificates, withdrawals and minting must be paired with the thing they are witnessing.
  E.g:

--certificate-file  $certfile --certificate-script-file $scriptfile
--tx-out $txout --minting-script-file $scriptfile
--withdrawal $withdrawal --withdrawal-script-file $scriptfile
--tx-in $txin --txin-script-file $scriptfile

• Scripts are no longer specified at the tx signing stage. They are specified at the txbody stage.

Node changes

• Add an additional GC heap metric to RTS. (#2592)
• Add details about registering relays on-chain to SPO documentation. (#2591)
• Improved installation documentation. (#2624)
• Preparatory support for Voltaire. (#2498)
• Add a docker image option for downloading cardano-node. (#2632)

Consensus changes

• Some preparation for upcoming work on Voltaire. (#2978)
• Introduce an option to configure the snapshot interval. This will primarily be used by downstream teams for testing and benchmarking. (#2966), (#3092)
• Preparatory work for the implementation of Ouroboros Genesis. (#3002)
• Add a peer label to chain sync client traces, allowing us to view which peer supplied which header and when. (#3091)
• Provide the ledger with the ability to perform slot to time conversion. This will be needed for Plutus scripts in the upcoming Alonzo release. (#3036), (#3098)

Ledger changes

• Work on implementing the upcoming Alonzo era. (#2192), (#2198), (#2200), (#2204), (#2210), (#2211), (#2212), (#2214), (#2215), (#2216), (#2218), (#2220), (#2221), (#2222), (#2225), (#2226), (#2227), (#2229), (#2231), (#2235), (#2237), (#2242), (#2243), (#2251), (#2256), (#2260), (#2264)
• Released the CDDL spec for Alonzo. (#2228)
• Add an optional network ID field to the transaction body. This will only come into use in the Alonzo era. (#2219), (#2254)
• Define a cardano-ledger-core package containing era-independent primitives. (#2207)
• Some work to reduce the extra CPU load at an epoch boundary, and reduce the resulting "pause" in normal operation. (#2240), (#2241), (#2250), (#2262)
• Added formal definitions for much of the crypto used to the Shelley spec. (#2236), (#2252)
• Expose AdaPots for use in downstream projects. (#2208)
• Some preparation for upcoming work on Voltaire. (#2135)(#2135)

Network changes

• Introduce new representation for local root peers. This is in preparation for P2P support. (#3006)
• Add a new KeepAlive codec that produces a valid CBOR encoding. (#3062)

Cardano-cli changes

• The query tip now also returns the era (e.g. Shelley, Allegra, Alonzo). (#2561, #2562, #2598)
• The address build command now incorporates the functionality of the script address build command, which is now deprecated. (#2486, #2587)
• Add additional commands for creating MIR certificates to the CLI. This supports the ability to transfer funds to the treasury for Catalyst projects. (#2503)
• The transaction view command now additionally shows detailed of minted non-native tokens. (#2550)
• Add a new command which computes the minimum ADA value/deposit for a multi-asset value. (#2612)
• Add two new query commands:
  • Query stake-snapshot allows querying the three stake snapshots for a given stake pool.
  • Query pool-params returns the current and future parameters, as well as the retiring information. (#2560)
• Preparatory support for Alonzo. (#2547)
• Updated the CLI reference documentation. (#2665)

Cardano-api changes

• Add initial support for the ledger state and folding over blocks to the API. (#2633)

Deprecated Features

• Removed the deprecated 'KThxBye' message from the TxSubmission protocol. (#2238)
• Removed support for Byron addresses using the Bech32 encoding. The only supported way to use Byron-era addresses is through a file, using the text envelope format. (#2605)

Fixed Issues

• Fixes to the ShelleyMA formal specification. (#2181)
• Fix a bug in reward update application which could have resulted in the wrong amount of funds being added to the treasury. (#2238)

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	✔️

Cardano Node 1.26.2

This point release is a recommended upgrade for all stake pool operators. It is not required for relays or other passive nodes. It ensures that block producing nodes do not unnecessarily re-evaluate the stake distribution at the epoch boundary.

Changes

• Do not force the evaluation of the Mark snapshot - leave this as a thunk (#2614)

Fixed Issues

• Stake pools unnecessarily evaluate the stake distribution at the epoch boundary (#2616)

Known Issues

• As for node version 1.26.1

Documentation

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

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

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	✔️

Cardano Node 1.26.1

This release includes significant performance improvements and numerous other minor improvements and feature additions. In particular the reward calculation pause is eliminated, and the CPU load for relays handling lots of incoming transactions should be significantly reduced.
The focus of the current development work is on completing and integrating support for the Alonzo era. This release includes many of the internal changes but does not yet include support for the new era.

• Note that this release will automatically perform a DB migration on the first startup after the update. The migration should take 10-20 minutes however it can take up to 60 minutes depending on your CPU. If this is a problem for your use, then see below for steps to mitigate this.
• The format of the cardano-cli query tip query has changed - see release notes for the CLI below.
• The cardano-cli query ledger-state query now produces a binary file if --out-file is specified. If required (e.g. for use in cncli), JSON output can be obtained by omitting this parameter, and redirecting the standard output to a file

Steps to mitigate downtime for this update

This release will automatically perform a DB migration on the first startup after the update. The migration should take 10-20 minutes however it can take up to 60 minutes depending on your CPU.

To mitigate downtime:

1. Update a non-production mainnet node
2. Take a DB snapshot
3. Stop production node
4. Backup and replace DB with snapshot
5. Restart production node on 1.26.1
6. Repeat steps 3-5 for all production nodes

See #311 for example scripts of how this can be done.

Node changes

• Expanded documentation for Windows builds (#1993, #2231)
• Other expanded and updated documentation (#2308, #2334, #2342, #2347, #2429, #2431, #2432, #2434, #2435, #2442)
• Simplified configuration for working with RTView (#2303)
• Prototype reporting metrics to EKG directly, rather than via the switchboard. (#2355)
• Multiple improvements to the configuration when running cardano-node as a Nixos service. (#2374, #2384, #2389, #2404, #2418, #2424, #2436, #2443, #2483)
• KES metrics are now traced even when the KES key has expired. This should make it easier for users to detect whether they have an expired KES key. (#2373)
• Add a metric to display the number of forged blocks "lost" due to switching to an alternative fork. (#2321)
• Set a flag which enables early return of memory to the OS. This should help in accurate reporting of memory consumption. (#2493, #2495)
• Disable the "uncoupled blocks" metric. This was shown in profiling to have an unfortunately large overhead. This reverts the change introduced in #2321. (#2510)

Consensus changes

• Add some additional tracing infrastructure (#2874)
• Continued work on the technical report of the consensus and storate layer (#2939), (#2943)
• Add the ability to query a node to determine whether it issued a block. This supports the "blocks lost due to switching" metric mentioned in the node changes above. (#2930)

Ledger changes

• Update the calculation of rewards to be done progressively, spreading the additional CPU load across a number of days. This should resolve the slowdown 4k/f slots into the epoch which has been seen by a number of node operators. (#2142), (#2183)
• Changed the aggregation of rewards, such that we store more data about reward provenance. This makes it easier for downstream applications to show e.g. where rewards come from. (#2117), (#2123), (#2164)
• Updates to the Alonzo formal specification (#2108), (#2189), (#2194)
• A lot of work on implementing the upcoming Alonzo era (#2124), (#2127), (#2148), (#2161), (#2165), (#2166), (#2169), (#2170), (#2176), (#2185), (#2190)
• Add the ability for MIR certificates to transfer money from the reserves to/from the treasury. This will be used to support Catalyst funding. (#2146)
• Additional properties added to the Mary/Allegra formal specification (#2178)

Network changes

• Various changes to support P2P (#2526), (#2911), (#2921)
• The LocalStQuery and ChainSync protocols now allow for additional effects to take place once the client has acquired a connection. This should allow for additional pipelining in clients such as the wallet. (#2896)
• Various tracing improvements:
  • Trace termination of mini-protocols (#2924)
  • Additional tracing of transaction submission (#2924)
• Allow configuring the timeouts for protocol handshakes. This should serve to mitigate a potential attack where handshakes are begun but not concluded, occupying resources on the node. (#2990)
• Add a tracer for the delay between when a block should have been forged and when we're ready to adopt it. (#2995)

Cardano-cli changes

• Add three new queries to the CLI, exposing functionality already present in the API:
  • Protocol parameters
  • Stake distribution
  • Individual stake addresses (#2275, #2290)
• Add the ability to calculate the minimum deposit needed for a transaction to the CLI, given a value. (#2325)
• Add cardano-cli transaction view, which allows for pretty-printing details about a serialised transaction. (#2348)
• When constructing MIR certificates, the CLI now takes stake addresses rather than stake certificates. These are strictly more general and can be deduced from the certificates.
• Make the Mary era the default era in the CLI (#2415)
• Migrate the cardano-submit-api tool from cardano-rest. (#2370)
• The 'tip' query now additionally returns the epoch at the tip. Some of the names of fields returned have changed and will need to be modified accordingly:
  • "blockNo" is now "block"
  • "slotNo" is now "slot"
  • "headerHash" is now "hash"
    (#2440)
• It's no longer possible to specify the era when making a CLI query, and it will default to the current era. (#2470)
• The 'ledger-state' query now outputs its result as a binary file if '--out-file' is specified

Cardano-api changes

• When querying the NodeLocalState, make the query point optional, and use the chain tip when not specified. (#2241)
• The cardano-submit-api now takes transactions encoded as CBOR rather than JSON. This reverts a change to existing behaviour for backwards compatibility. (#2491, #2512)
• Remove a backwards-compatibility workaround related to the optional query point (#2241 above) when querying the NodeLocalState. This had resulted in spurious notifications of disconnection in the logs. Note that as a consequence of this, instances of the CLI and other tools using the 1.26.1 API will fail to query node state from older versions of the node. (#2540)

Deprecated Features

• Removed code pertaining to the old IPC API (#2319)
• Support for GHC 8.6.5 has been dropped. (#2507)

Fixed Issues

• Fix the rendering of Byron-era TxOuts to be consistent with the rendering for Shelley-era addresses. (#2472)
• Fixed a performance regression in the Allegra and Mary eras. This resulted in node slowdown when validating failed transactions. (#2144)
• Fixed a subtle bug in reward computations, where the wrong amount of money would be added to the treasury. (#2136)
• Fix RTS options, which got accidentally corrupted in the previous release. (#2511)
• Update the iohk-monitoring framework to fix a file descriptor leak. (#2518)
• Fix an unevalutated thunk error in reward computation. (#2183)

Known Issues

Documentation

• [Cardano Node docume...

Cardano Node 1.25.1

This release is expected to be the final release for the upcoming Mary hard fork, and everyone must upgrade to this (or a later) version to cross the Mary hard fork.

The Mary hard fork introduces native token functionality to Cardano. This is directly useful and is also one of the significant building blocks for the later Goguen smart contracts.

A launchpad testnet for the native token functionality has been running since December, using the cardano-node 1.24.2 release. This 1.25.1 release contains relatively minor changes for the Mary era compared to the 1.24.2 release. It is nevertheless not compatible with the 1.24.2 version and the existing testnet. The launchpad testnet will not be restarted and will remain on 1.24.2. Public testnet and staging have been upgraded to 1.25.1. If you have already tested integration with the existing launchpad testnet then no new integration work is expected for this release other than upgrading the node version and moving to the staging or public testnet.

Exchanges and other users that integrate closely with Cardano must take action to test their integration before the transition takes place on mainnet. Exchanges can use launchpad or staging, SPOs can use staging, and everyone should use public testnet once it forks. Staging will go through the Mary hard fork on 28th January, and public testnet will go through the Mary hard fork during week commencing 1st February. The native token functionality does have an impact for all custom wallet implementations: it is not a feature that can be ignored and remain compatible. All addresses are capable of receiving native tokens.

Stake Pool Operators (SPOs) and Exchanges should take note that the metric namespace has undergone consolidation, so all metrics now reside in cardano.node.metrics:

• cardano.node.Forge.metrics.* -> cardano.node.metrics.Forge.*
• cardano.node.ChainDB.metrics.* -> cardano.node.metrics.ChainDB.*
• cardano.node.BlockFetchDecision.connectedPeers -> cardano.node.metrics.connectedPeers

The node configs require no changes, but allow dropping entries that became redundant: wherever cardano.node.Forge.metrics.*, cardano.node.ChainDB.metrics.* or cardano.node.BlockFetchDecision.connectedPeers were mentioned, those entries can be removed. Only cardano.node.metric needs to remain. Please see #2281 for further details.

This release uses a new cabal snapshot so could be rather resource intensive when building for the first time.

Node changes

• All metrics now use a common name prefix cardano.node.metrics. This requires a one-off change to the node configuration to route all metrics to the metrics backend and not have them in the log files. This should reduce the number of such changes in future. (#2281)
• More detailed tracer output for protocol tracers (#2178)

Consensus changes

• Improve the handling of the encoding of local IPC queries by older clients that do not understand later hard forks. In future this should mean that clients that do not understand a hard fork only fail at the time of the hard fork itself, and not earlier when the update proposal is confirmed (#2818)
• New query for rewards provenance. This is intended to help wallets explain more details about rewards, and to help SPOs and users better understand how pools' performance and ranking are calculated. This is not yet supported in the CLI in this release. (#2830)
• Support for using multiple leader credentials for the purpose of running large scale benchmarks. It supported in testnets only, not mainnet (#2832)
• Support in testnets for skipping initial eras. This makes it easier and quicker to automate the setup of Cardano-mode testnets that start in later eras, such as Allegra or Mary. This enables simplifications in the setup for integration tests or benchmarks (#2811)
• A first draft of a technical report on the design and the internals of the Cardano consensus and storage layer (#2663, #2838, #2841, #2842, #2853)

Ledger changes

• Enforce the size of multi-asset names, to match the specification (#2074)
• Minor change to the ledger CDDL binary specification for the Mary era: restrict the range of multi-asset values to -2^63..2^63-1 where previously the allowed range was -2^64..2^64-1 (#2092)
• Rename fields in the ledger's CDDL binary specification for clarity and consistency, but no actual changes to the binary format (#2045)
• Change the minimum ada UTxO value formula for multi-asset values to better reflect the resource costs and to pass on savings (in the form of a lower minimum ada UTxO value) for applications that use smaller asset bundles by sharing policy ids or using shorter asset names (#2107)
• Improvements to the size of the internal storage format of multi-asset values, enabling a lower minimum ada UTxO value for multi-asset output values (#2083)
• Restrict the maximum size of multi-asset output values (#2099)
• Terminology change: the metadata section is renamed to "auxiliary data" to distinguish it from the existing transaction metadata (#2052)
• Extra documentation on native tokens (#2046)
• Progress on the new Alonzo era (#2022, #2055, #2061, #2062, #2067, #2077, #2087, #2088, #2095)

Network changes

• Internal infrastructure to support seeding the P2P graph construction from the SPO relays registered on the chain, weighted by stake (#2535, #2536)
• Introduce v6 of the node-to-node protocol where we reverse the initial agency of the tx-submission protocol to match the others. This is preparation for the P2P governor which requires the initial agency for mini-protocols to be uniform (#2807)
• Introduce v8 of the node-to-client protocol with an extension to the local query protocol that allows acquiring the point at the node's current chain tip, without having to provide that point explicitly. Using this simplifies things for node clients for the common use case where the current tip is needed, and eliminates a rare race condition (#2875)
• Fix a resource leak for chain-sync clients (#2235, #2870, #2888)
• Tracing improvements for the mux component (#2794)

Cardano-cli changes

• Allow creating transactions with no outputs (#2223, #2226)
• Improved error messages for syntax errors in out-of-range lovelace quantities in transaction outputs (#2063, #2079)
• Improved reference documentation for simple scripts and their use (#2165)
• Remove support for changing the delegation from Genesis keys to operational keys in the Byron era. This feature was never used on the mainnet during the Byron era. (#2219)
• Clearer usage information in the CLI --help output (#2203)

Cardano-api changes

• New IPC modules for easier interaction with the node, including support for all existing local state queries (#2230, #2238, #2263, #2277, #2286)
• API support for Byron era update proposals and votes (#2209, #2271)
• Make Cardano.Api the primary public module for the API.
• API support for serialising multi-asset PolicyId and AssetName (#2270)
• API for pretty-printing JSON output (#2103)
• More precise error cases for tx outputs that are out of range (#2217)
• Host up-to-date generated API documentation via github https://input-output-hk.github.io/cardano-node/ (#2273, #2276, #2278)

Documentation

• Cardano Node documentation
• Cardano CLI
• Internal API docs for ledger, consensus and network
• [Configuration files](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/g...

Cardano Node 1.24.2

This release provides support for the upcoming Allegra (token locking) Hard Fork and Mary Hard Fork and the new features they bring.

Everyone must upgrade to this (or a later) version to cross the Allegra Hard Fork.
Daedalus users should look for Daedalus release 3.0.0 which includes a version of the node that will cross the Token locking Cardano update, however people using the node directly must upgrade.

• Token locking Cardano update adds some features needed to support the Catalyst treasury scheme. It extends the existing multi-sig script language with predicates for time, via the slot number. It allows, for example, to make a script address that is not spendable until a certain point in time.
• The native tokens Cardano update adds multi-asset support. This is comparable to ERC20 and ERC721 tokens, but supported natively in the UTxO ledger. This is part of the Goguen feature set. It is a very significant feature and will have implications for all Cardano wallet implementations, including exchanges.

Stake Pool Operators (SPOs) and Exchanges should update their node config "options" section with an extra entry:

  "options": {
    "mapBackends": {
      "cardano.node.resources": [
        "EKGViewBK"
      ],

See link to configuration files in documentation section below.

Node changes

• Add a nodeStartTime metric. This is a partial replacement for the uptime metric that was removed in the 1.23.0 release. (#2118)
• New metrics for the size of the UTxO and delegation maps (#2158)
• Tracing changes to support "K=1000" benchmarks (#2156, #2175)
• Mention the required xz tool in the Cabal build instructions (#2132)
• Eliminate the need to update the LastKnownBlockVersion-* entries in the node config files for the Shelley-based eras. This means the configuration does not need to be updated for the Token locking or native tokens eras. (#2193)
• Export some more metrics for selected OS and RTS stats (#2192)

Ledger changes

• Support for optional additional scripts in the tx auxiliary data (#1993)
• Update the CDDL specification of the blockchain binary format for Token locking and native tokens eras (#1994, #1999, #2009)
• Improved serialised binary format for multi-asset values (#1979)
• Add a compact in-memory storage format for multi-asset values (#1996)
• Updates to the multi-asset formal specifiation (#2003)
• Adjust how the major protocol version is handled for soft forks (#1998)
• Initial preparatory steps for the Alonzo era (#2016, #2027)
• Benchmarks for the transaction generators (#2024)

Consensus changes

• Use a single set of credentials for all Shelley-based eras. This keeps the node configuration simple for the new eras. (#2753)
• Add support for a token locking-only protocol mode to simplify benchmarking (#2754)
• Add support for the system wall clock time being adjusted backwards by a small amount without triggering a node shutdown and restart. Small backwards adjustments can be caused by NTP. (#2781, #2785)

Network changes

• Preparations for publishing io-sim as a public library (#2775)
• Improved logging of the creation of the node's sockets (#2746)
• Update the cardano-ping tool to support the node-to-node protocol V4 (#2787)

CLI changes

• CLI support for the Token locking and native tokens eras, including creating transactions for the new eras, and support for the special new features in the new eras: script extensions, tx validity intervals, auxiliary scripts, multi-asset tx outputs and asset minting. (#2072, #2129, #2136)
• It is now necessary to specify the target era (e.g. --allegra-era) when creating a transaction (with build-raw) so that the right format and feature-set is used. The --shelley-era remains the default.
• It is necessary for now to specify the target era when using the CLI query commands. This may become automatic in future. The default is --shelley-era.
• Move all the Shelley sub-commands to the top level of the command line. For example cardano-cli shelley transaction build-raw becomes simply cardano-cli transaction build-raw. The existing names are also kept for compatibility. (#2076, #2145)
• Updated help text for the ledger/protocol state queries to clarify that they are primarily for debugging and are not stable interfaces (#2125, #2126, #2133)
• New command transaction policyid for making multi-asset policy ids (#2176)
• New command byron transaction txid to help scripts with getting the transaction id for Byron transactions made using the cli (#2169)
• New --tx-file flag for the command transaction txid to accept complete txs, not just tx bodies (#2169)
• Hide the deprecated --ttl flag in the --help output (#2189, #2190)

API changes

• Full API support for the Token locking and native tokens eras, including creating transactions for the new eras, and support for the special new features in the new eras: script extensions, tx validity intervals, auxiliary scripts, multi-asset tx outputs and asset minting (#2092, #2110, #2111, #2121, #2127, #2128, #2141, #2149)

Documentation

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

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

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)
• 4GB of RAM (8GB for a relay or stake pool)
• 10GB of free storage (20GB for a stake pool)

Sign off

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

Cardano Node 1.23.0

This release includes a substantial amount of internal changes to support the upcoming Allegra and Mary hard forks and the new features they bring. This is not the final release before the Allegra hard fork, but it does include the bulk of the functionality for both Allegra and Mary hard forks.

• The Allegra hard fork adds some features needed to support the Catalyst treasury scheme. It extends the existing multi-sig script language with predicates for time, via the slot number. It allows, for example, to make an address not spendable until a certain point in time.
• The Mary hard fork adds multi-asset support. This is comparable to ERC20 and ERC721 tokens, but supported natively in the UTxO ledger. This is part of the Goguen feature set. It is a very significant feature and will have implications for all Cardano wallet implementations, including exchanges.

Another notable change in this release is an adjustment to the pool ranking that will benefit small pools that have not yet made many blocks. We have adjusted the initial Bayesian prior so that instead of assuming new pools will perform at some less-than-perfect average level, we assume they will perform more-or-less perfectly. This prior is still updated based on the actual performance history, so pools that perform poorly will still drop in ranking. This change will especially benefit small pools that have produce few blocks so far, because they have very little performance history and so their score will be more influenced by the initial prior.

Improvements

• Preliminary support for the upcoming Allegra and Mary eras (#1899, #1951, #1958, #1959, #1961, #1965, #1971, #1977, #1981, #1984, #1987, #1988, #1989, #1990, #2019, #2038, #2080, #2666, #2668, #2670, #2677, #2679)
• Preliminary support for the Allegra script language extensions (#1847, #1875, #1895, #1908, #2069)
• Preliminary support for the Mary multi-asset extensions (#1905, #1931, #1938 #2081, #2083, #2085, #2093)
• Adjust how the pool performance is estimated as part of the pool ranking: for pools with no performance history use a Bayesian prior that assumes that pools will perform well. This should benefit new small pools. (#1936)
• Adjust the ledger state dump to return the "extended" ledger state (#2019)
• Support bech32 and hex formats for reading verification keys (#1852)
• Improved documentation for CLI multi-signature support (#1976)
• Improve handling of invalid command line input (#2088)
• Improved ledger state serialisation performance (#1968)
• Restore build compatibility with GHC 8.6.5, so this release builds with both GHC 8.6.5 and 8.10.2. Future releases will support 8.10.x only. (#1956, #1990, #2540, #2652)
• Several new local state queries in v4 of the node-to-client protocol (#2694)
• Keep a compact form of the Shelley genesis content, to allow it to be queried later (#2704)
• Switch to the newly-published "nothunks" package (#1894, #2664)
• Address technical debt in the db-analyser tool (#2667)
• Allow most Shelley ledger rules to be reused in subsequent eras (#1922)
• Adjust how the ledger is parametrised to reflect the fact that some parts change with the ledger era, while others change with the consensus protocol. This makes it easier to handle ledger-only era changes that still use the same Praos consensus protocol. (#1915)
• Support serialisation for the Shelley genesis data structure to support a new node query that can return the genesis parameters (#1927)
• New cardano-ping demo and tool (#2701)
• Make the node fail on startup if we cannot bind to the necessary ports (#2696)
• Improvement to the calculation and collection of network connection performance metrics (#2636)
• Improvements to the handling of the initial connection handshake (#2691)
• Preparations for publishing io-sim as a public library (#2580, #2631, #2649)
• Improved IPv6 support (#1928, #2662)
• Preparation for the p2p governor: add a new node-to-node protocol version (4) with a new negotiated handshake parameter to determine if the connection will be uni-directional or bi-directional (#2658)
• Documentation for the hard fork transition (#1741)
• Check VRF signing key files have the correct file permissions (#1936, #1938)
• Improve IPv6 support and related internal refactoring (#1928)

Resolved issues

• Fix a space leak in the stake pool performance tracking that caused writing ledger state snapshots in consensus to take too long (#1967)
• Fix a corner case in the way the pool performance history is calculated as part of the overall pool score calculation (#1897)
• Fix a failure that occurs on starting a node when there are certain kinds of DB corruption (specifically a ledger snapshot that is newer than the tip of the immutable DB, which would typically occur when chain DB files are manually moved or removed) (#2651)
• Fix a long-standing (highly unlikely) bug in evaluating alternative chains that cross a hard fork boundary (#2314, #2318, #2657, #2661)

Deprecated Features

• Remove the HardForkNotBeforeEpoch setting from the config file (#2073, #2736, #2739)
• Remove the deprecated LiveView feature, now that RTView is released (#1977)

Known Issues

• #1734 ErrorPolicyUnhandledApplicationException may be observed when running CLI commands on windows
• See GitHub Issues for further issues that have been reported

Documentation

• Cardano Node documentation
• Cardano CLI
• Internal API docs for ledger, consensus and network

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

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)
• 4GB of RAM (8GB for a relay or stake pool)
• 10GB of free storage ...

Cardano Node 1.21.1

This patch release updates Cardano Node 1.21.0 with a few minor fixes. In particular, it resolves a problem on startup when the node is configured to use systemd socket activation.

Deployed on the testnet on 6 October 2020.
Deployed on the mainnet on 6 October 2020.

Improvements

• Added more detail to the logging of the keep-alive protocol (#1873)

Resolved issues

• Fixed configuration defaults that were interfering with using systemd socket activation (#1927)
• Added workaround for building on Linux systems without systemd (#1775)
• Fixed the severity level for some protocol tracers (#1910)

Known Issues

• #1734 ErrorPolicyUnhandledApplicationException may be observed when running CLI commands on windows
• See GitHub Issues for further issues that have been reported

Documentation

• Cardano Node documentation
• Cardano CLI
• Internal API docs for ledger, consensus and network

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

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)
• 4GB of RAM (8GB for a relay or stake pool)
• 10GB of free storage (20GB for a stake pool)

Sign off

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