Release Notes
Node version 10.7.0 contains a number of major improvements, and also includes internal changes that will be enacted by the forthcoming hard fork to Protocol Version 11 in a future node version. A key change is that introduces the LSM Tree backend for storage layer that delivers the UTxO-HD OnDisk storage backend. This is enabled by a new LSM (Log-Structured Merge) tree implementation in Consensus (LedgerDB V2) that replaces the previous LMDB backend. Operators running with the OnDisk backend now require only 8GB of RAM, compared to 24GB for the InMemory backend. The new backend is capable of tracking table sizes and uses versioned on-disk encoding (TablesCodecVersion1). Additional highlights include KES Agent support for improved operational key security, the first experimental release of cardano-rpc (a gRPC/UTxO-RPC interface), dmq-node and kes-agent binaries added to the release, TLS/SSL support for EKG/Prometheus in cardano-tracer, and support for a protocol minor version bump.
Local root changes:
- Local root peers can be configured with a new boolean field
behindFirewall(falseis the default). - For
Trustablelocal root peers,Chain-Syncwon't timeout in theStNext StMustReplystate (e.g. awaiting for a header announcement).
Note: This release requires a full chain replay due to the introduction of versioned ledger table encoding.
Breaking changes
- Chain replay required: Versioned ledger table encoding (
TablesCodecVersion1) alters on-disk serialisation forLedgerStateandExtLedgerState. Upgrading from any prior release requires a full chain replay. - cardano-api:
submitTxToNodeLocalnow returnsTxSubmitResultinstead ofSubmitResult TxValidationErrorInCardanoMode. Network-level errors no longer escape as exceptions; see the API changelog for details.
Known issues
- There is a known issue with increased memory use when testing with large numbers of DReps
- The new
behindFirewallfield for local root peers is not reflected in the log file (IntersectMBO/ouroboros-network#5343).
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)
- Or, for MacOS, an Apple Silicon (M1, M2, M3, M4 or M5) processor
- 24GB of RAM when running with the
InMemorybackend, 8GB when running with theOnDiskbackend - 300GB of free storage (350GB recommended for future growth)
Platforms
- Linux 64-bit (Ubuntu 20.04 LTS, 22.04 LTS, 24.04 LTS, 26.04 LTS; Mint 20, 21, 21.1, 21.2, 21.3, 22, 22.1, 22.2; Debian 11, 12, 13)
- Windows 64-bit (10, 11)
- MacOS 10.15, 11 (Big Sur), 12 (Monterey), 13 (Ventura), 14 (Sonoma), 15 (Sequoia), 26 (Tahoe)
GHC/Cabal supported versions
- GHC 9.6.7
- Cabal 3.8/3.12
Supported roles
| Platform | Block Production | Relay | Client (Desktop) |
|---|---|---|---|
| Linux | 🟢 | 🟢 | 🟢 |
| Windows | 🟥 | 🟥 | 🟢 |
| MacOS | 🟥 | 🟥 | 🟢 |
Downloads
- Pre-release configuration files
- Docker Images: cardano-node, cardano-tracer, cardano-submit-api
Documentation
- Cardano Node documentation
- For details about changes to configuration for
UTxO-HDplease refer to the Consensus docs on UTxO-HD - The getting started guide may also be helpful for general queries.
- Networking options and related changes are listed on the P2P section
- For details about changes to configuration for
- Cardano CLI
- Internal API docs for ledger, consensus and network
- Compatibility matrix
Sign-off
| Role | Approval |
|---|---|
| Technical Steering Committee (Intersect) | 🟢 |
| Product Committee (Intersect) | 🟢 |
| Test Engineer | N/A |
| Performance Engineer | N/A |
| Site Reliability Engineer | 🟢 |
| Release Engineer | 🟢 |
Legend
- 🟢 - signed / agreed / supported
- 🟥 - not agreed / unsupported
Changelogs
Node
-
Configuration of LedgerDB:
V1InMemoryvariant removed,V2LSMvariant added (with optionalFilePath). -
New config fields:
TxSubmissionLogicVersion(defaultV1) andTxSubmissionInitDelayparsed from node config JSON, forwarded toRunNodeArgs. -
Node feature flags added to
RunNodeArgs, for now always initialised asrnFeatureFlags = mempty. -
New
KESSourcetype:KESKeyFilePath FilePath | KESAgentSocketPath FilePath. -
ProtocolFilepaths.shelleyKESFilereplaced byshelleyKESSource :: Maybe KESSource. -
CLI offers
--shelley-kes-keyor--shelley-kes-agent-socket.
Tracing
- The
trace-dispatcherpackage was moved to a standalone repository, see https://github.com/IntersectMBO/hermod-tracing. - All P2P tracing orphan instances (
TracePeerSelection,DebugPeerSelection,PeerSelectionCounters,ConnectionManagerTrace,
InboundGovernorTrace,ServerTrace, etc.) moved upstream intoouroboros-network:tracingandcardano-diffusion:tracing. dtDebugPeerSelectionInitiatorTraceranddtDebugPeerSelectionInitiatorResponderTracermerged into a singledtDebugPeerSelectionTracer.TraceTxSubmissionCollectednow carries[txid]instead ofInt; new constructorsTraceTxInboundAddedToMempool,TraceTxInboundRejectedFromMempool,TraceTxInboundError,TraceTxInboundDecision.- The types related to the network topology (
NetworkTopology/LocalRootPeersGroup/PublicRootPeers/RootConfig) were moved tocardano-diffusion, seeCardanoNetworkTopologyfromCardano.Network.Diffusion.Topology. - Dijkstra era stubs:
LogFormatting/ToObjectinstances added for Dijkstra ledger predicate failures (allerror "Dijkstra era is not active yet").
Consensus
- Peras Protocol Integration: Major foundational work was added for the Peras protocol, including the introduction of
PerasCertDB, Peras voting APIs, and a shift in chain selection to prioritize Peras weight over chain length when enabled. - LedgerDB V2 and LSM-Trees: The new LedgerDB V2 was implemented featuring an LSM-trees backend (capable of tracking table sizes) and the extraction of backend storage logic into dedicated sub-libraries (
ouroboros-consensus-lsm,ouroboros-consensus-lmdb). - Mempool Timeouts and Tracking: The mempool was significantly upgraded to support execution timeouts (
MempoolTimeoutConfig) and track how much monotonic clock time transactions take to validate (DiffTimeMeasure). - Enhanced Chain Selection Tracing: Chain selection was refactored to explicitly carry and emit a
ReasonForSwitch(e.g., length, weight, or tiebreaker) in traces likeAddedToCurrentChainandSwitchedToAFork. - Networking and Protocol Updates: Node-to-Client protocols were bumped to
NodeToClientV_23, introducing queries likeGetLedgerPeerSnapshotand adding crucial size limits for keep-alive servers and peer-sharing clients. - Transaction and Serialization Changes: The codebase adapted to Ledger's nested transaction levels and changes in
ApplyTxErrorserialization. It also introducedtxWireSizeto accurately measure CBOR-encoded transaction sizes over the network. - Critical Memory and Resource Fixes: Numerous patches addressed resource management, fixing double read lock acquisitions, leaky handles in LedgerDB, and ensuring proper garbage collection of
ProtocolInfoandLedgerDbArgs. - Codebase Consolidation: Several previously standalone libraries (including
diffusion,protocol,cardano,lsm, andlmdb) were absorbed directly into theouroboros-consensuspackage to streamline the architecture. - Ledger Table Versioning: Ledger tables encoding was versioned (
TablesCodecVersion1), altering on-disk serialization forLedgerStateandExtLedgerState, which will require a chain replay.
Ledger
- Finished implementation of all features needed for the upcoming intra-era hard fork into protocol version 11: #5015:
- Block header CDDL spec fixes: #5518
- Various performance improvements and bug fixes.
- Plethora of features for Dijkstra era, which as a whole is not functional yet.
- Transaction CDDL specification for Dijkstra era is mostly complete, yet is not fully tested.
Network
- Local root peers behind a firewall. In the topology file one can
specify a boolean fieldbehindFirewall(the default is
false). Withfalsethe node will try to create connection in order
to use that peer as a downstream one, when set totruethe node will only start using that peer as downstream when
a connection from that peer was accepted. This feature is intendent for the
case where some local root peers are behind a firewall, and thus cannot be
connected directly. Now, instead of peer selection trying to connect and
failing until a connection is accepted, peer selection will only promote the
peer when it can succeed. IntersectMBO/ouroboros-network#4381 - Chain-Sync won't timeout for trustable local root peers in the
StNext StMustReplystate (e.g. awaiting for next header announcment).
IntersectMBO/ouroboros-network#5250 - Chain-Sync timeouts in the
StNext StMustReplywere bumped to between601
and911seconds (~5-8 minutes). - Connection manager propagates disconnection reasons and exceptions to peer selection and
inbound governor. This gives a chance to log & handle the exception in the
right context. - More robust Wireshark dissector plugin
- More robust churn: enforce a minimum number of churned established and known
peers based on the number of replaced active and established peers. IntersectMBO/ouroboros-network#5240 - Updates to the ledger peer snapshot.
- Added
NodeToClientV_23: addedGetDRepsDelegationsquery, ledger peer snapshot
CBOR encoding changed. - Bug fixes in peer selection (IntersectMBO/ouroboros-network#5209,
intersect/ouroboros-network#5330) - Fixed trailing bytes handling by the multiplexer (intersect/ouroboros-network#5254)
Full list of PRs / issues included in this release see ouroboros-network release board for: 1.1.0.0, 1.0.0.0 and 0.24.0.0 releases.
CLI
- Print friendly stderr message when query future-pparams returns null (feature) PR 1344
- Removed requirement of "current treasury value" in transactions (compatible) PR 1322
- Fix supplemental datum propagation in transaction outputs: Previously, supplemental datums (datum hashes referenced in transaction outputs) were not being propagated into the transaction body. This meant that when a transaction output included a datum hash, the corresponding datum was not included in the transaction's supplemental data map, causing validation failures for consumers expecting to resolve those datum hashes. (bugfix) PR 1341
- Modify readAnyScript to handle text envelope formatted simple scripts (bugfix) PR 1333
API
- Integrate new Ledger and Consensus packages for Node 10.7. (breaking) PR 1050
- Fix mapScriptWitnessesCertificates silently dropping key-witnessed certs (e.g. shelley stake registration certificates) when rebuilding the transaction body during fee balancing. The function previously iterated only over script-witnessed certs, so certs stored with a Nothing witness were omitted from the balanced transaction. (bugfix) PR 1136
- submitTxToNodeLocal now returns TxSubmitResult instead of SubmitResult TxValidationErrorInCardanoMode. TxSubmitResult has three constructors: TxSubmitSuccess, TxSubmitFail TxValidationErrorInCardanoMode, and TxSubmitError SomeException, so network-level errors no longer escape as exceptions. (breaking) PR 1126
- Fix RFC 7049 canonical CBOR map key ordering and add property test (bugfix, test) PR 1075
- Export fromLedgerTxValidityLowerBound and fromLedgerTxValidityUpperBound. (compatible) PR 1118
- Introduce recursive minimum fee calculation (feature) PR 1106
- Fix supplemental datum handling in experimental API. toLedgerDatum now correctly produces DatumHash for supplemental datums instead of inline Datum representation. getDatums uses new explicit txSupplementalDatums field instead of extracting from outputs, which incorrectly included inline datums in TxDats. (bugfix) PR 1112
Submit API
- The tx submission result type changed from
Net.Tx.SubmitSuccess/SubmitFail
(ouroboros-network) toCardano.Api.TxSubmitSuccess/TxSubmitFail/TxSubmitError--- the
submit API now lives incardano-apidirectly. - A new TxSubmitError case is handled, representing connection-level errors (as
opposed to validation errors). - Added
TxCmdTxSubmitConnectionError !TexttoTxCmdErrorto surface connection
failures from the newCardano.Api.TxSubmitErrorconstructor.
RPC
This is a very first release of cardano-rpc. One should treat it as **EXPERIMENTAL**. The configuration and non-UTXO RPC endpoints are not stable.-
Upgrade proto definitions to utxorpc v1 beta utxorpc/spec#183
(feature, breaking)
PR 1080 -
gRPC: Add tracing datatypes
(compatible)
PR 1079 -
gRPC: Add TxOut CBOR representation to
readUtxosmethod, fix address serialisation in TxOutput.
(bugfix)
PR 1021 -
Add decoded PlutusData and NativeScript in proto definition #947
(feature, compatible)
PR 947 -
Add getProtocolParamsJson gRPC endpoint
(feature, compatible)
PR 919 -
Add UTxO RPC: submitTx method
(feature)
PR 905 -
Add
readUtxosUTxO RPC query
(feature)
PR 889 -
Add UTxO RPC protocol parameters query
(feature)
PR 888
Submit API
Plutus
Detailed Changelogs
Individual packages' changelogs
Package changelogs| Package | Version | Changelog |
|---|---|---|
| acts-generic | 0.1.1.0 | CHANGELOG.md |
| byron-spec-chain | 1.0.1.1 | CHANGELOG.md |
| byron-spec-ledger | 1.1.0.1 | CHANGELOG.md |
| cardano-api | 10.25.0.0 | CHANGELOG.md |
| cardano-base | 0.1.2.0 | CHANGELOG.md |
| cardano-binary | 1.8.0.0 | CHANGELOG.md |
| cardano-cli | 10.15.1.0 | CHANGELOG.md |
| cardano-crypto-class | 2.3.1.0 | CHANGELOG.md |
| cardano-crypto-praos | 2.2.2.0 | CHANGELOG.md |
| cardano-crypto-wrapper | 1.7.0.0 | CHANGELOG.md |
| cardano-data | 1.3.0.0 | CHANGELOG.md |
| cardano-diffusion | 1.0.0.0 | CHANGELOG.md |
| cardano-ledger-allegra | 1.9.0.0 | CHANGELOG.md |
| cardano-ledger-alonzo | 1.15.0.0 | CHANGELOG.md |
| cardano-ledger-alonzo-test | 1.4.0.1 | CHANGELOG.md |
| cardano-ledger-api | 1.13.0.0 | CHANGELOG.md |
| cardano-ledger-babbage | 1.13.0.0 | CHANGELOG.md |
| cardano-ledger-binary | 1.8.0.0 | CHANGELOG.md |
| cardano-ledger-byron | 1.3.0.0 | CHANGELOG.md |
| cardano-ledger-conway | 1.21.0.0 | CHANGELOG.md |
| cardano-ledger-core | 1.19.0.0 | CHANGELOG.md |
| cardano-ledger-dijkstra | 0.2.0.0 | CHANGELOG.md |
| cardano-ledger-mary | 1.10.0.0 | CHANGELOG.md |
| cardano-ledger-shelley | 1.18.0.0 | CHANGELOG.md |
| cardano-ledger-shelley-ma-test | 1.4.0.1 | CHANGELOG.md |
| cardano-ledger-shelley-test | 1.8.0.0 | CHANGELOG.md |
| cardano-ping | 0.10.2.0 | CHANGELOG.md |
| cardano-protocol-tpraos | 1.5.0.0 | CHANGELOG.md |
| cardano-rpc | 10.2.0.0 | CHANGELOG.md |
| cardano-slotting | 0.2.1.0 | CHANGELOG.md |
| cardano-strict-containers | 0.1.6.0 | CHANGELOG.md |
| dmq-node | 0.3.0.0 | CHANGELOG.md |
| ekg-forward | 1.2 | CHANGELOG.md |
| fingertree-rm | 1.0.0.4 | CHANGELOG.md |
| kes-agent | 1.2.0.0 | CHANGELOG.md |
| kes-agent-crypto | 1.1.0.0 | CHANGELOG.md |
| network-mux | 0.10.1.0 | CHANGELOG.md |
| ouroboros-consensus | 1.0.0.0 | CHANGELOG.md |
| ouroboros-network | 1.1.0.0 | CHANGELOG.md |
| plutus-core | 1.59.0.0 | CHANGELOG.md |
| plutus-ledger-api | 1.59.0.0 | CHANGELOG.md |
| plutus-metatheory | 1.59.0.0 | CHANGELOG.md |
| plutus-tx | 1.59.0.0 | CHANGELOG.md |
| plutus-tx-plugin | 1.59.0.0 | CHANGELOG.md |
| quickcheck-monoids | 0.1.1.0 | CHANGELOG.md |
| small-steps | 1.1.3.0 | CHANGELOG.md |
| vector-map | 1.2.0.0 | CHANGELOG.md |