Skip to content

Update ouroboros-consensus, cardano-api, cardano-cli and cardano-rpc for 11.2 release. - #6677

Merged
johnalotoski merged 45 commits into
masterfrom
koslambrou/prepare-11.2
Oct 27, 2026
Merged

johnalotoski merged 45 commits into
masterfrom
koslambrou/prepare-11.2

Conversation

@koslambrou

@koslambrou koslambrou commented Sep 3, 2026 •

Copy link
Copy Markdown
Contributor

Description

Cuts the 11.2.0 release of cardano-node, along with cardano-node-chairman, cardano-submit-api and cardano-testnet. It moves to the new upstream dependency set, uses cardano-config to read node configuration, and moves the shipped configs, Nix packaging and NixOS module to the cardano-config envelope format.

Dependency bumps

Package From To
ouroboros-consensus 4.2.0.1 ^>= 5.2 (now also uses its tracing sublib)
ouroboros-network ^>= 1.2 ^>= 2.0
cardano-diffusion ^>= 1.1.1 ^>= 1.3
cardano-api ^>= 11.7 ^>= 11.11
cardano-cli ^>= 11.2.2 ^>= 11.6
cardano-rpc ^>= 11.4 ^>= 11.5
cardano-ledger-conway >= 1.22.1 >= 1.24
plutus-* ^>= 1.65 ^>= 1.71
cardano-config — ^>= 2.2 (new)
  • Updated the Hackage and CHaP index-states. Cleaned up the allow-newer and constraints for GHC 9.14 (pinned some < 1.1, required grapesy >= 1.2.1).
  • Bumped the iohkNix flake input (enveloped environment configs, mkEnvelope, configFormat) and Mithril (v2642.0, signer 1.2.5).

Tracing: switched to consensus's tracing instances

  • Removed the node's own copies of the consensus, ChainDB, era (Byron/Shelley/HardFork), KES and render tracing instances (~9k lines). The node now uses ouroboros-consensus:tracing instead.
  • Replaced the Leios tracers with the Peras tracers:
    • Peras.{Cert,Vote}.{Inbound,Outbound}
    • Peras.Cert.Inclusion
    • Peras.Vote.Forging
  • Handled the new ExtValidationError constructors (PerasEpochContextResolver, PerasCertInBlock) and the updated TraceRpc constructors.
  • Removed the namespaces of tracers that no longer exist, including Net.ErrorPolicy.
  • Changes log consumers will see:
    • Mempool rejections always carry errdetails.
    • The detailed mempool "tx" field is now hex-encoded CBOR.
    • New namespaces:
      • Mempool.CapacityChanged
      • Snapshot.ConfiguredSnapshotPolicy
      • Snapshot.ImplausibleSnapshotPolicy
      • RPC.SubmitService.{ReadMempool,WatchMempool}.Span
    • StakeKeyAlreadyRegisteredDELEG is now DelegAccountAlreadyRegistered.
  • Enabling trace forwarding now fails if it would otherwise drop tracing settings.

Configuration: cardano-config integration

  • The node reads its configuration through cardano-config, alongside the existing POM parser. Three new modules:
    • CardanoConfigResolve detects the config dialect and picks the parser.
    • CardanoConfigAdapter maps a cardano-config result onto NodeConfiguration; the fields it can't map are listed in adapterGaps.
    • CardanoConfigCompare diffs the two parsers' results field by field.
  • Legacy (flat) configs are parsed by both parsers. Any difference is reported as a non-fatal warning.
  • Envelope configs are resolved by cardano-config alone, since POM cannot read them.
  • Tracing settings are passed to trace-dispatcher as an object (FromJSONObject), because an envelope keeps them under Configuration.HermodTracing. This also fixes trace-documentation.
  • New cardano-node config {migrate,schema,resolve} subcommands:
    • migrate and schema come straight from cardano-config.
    • resolve also cross-checks a legacy config against POM and exits non-zero if the two disagree, so CI can use it as a parity check.
  • New cardano-config-compare-test suite: one fixture config written in both dialects, checking classification, that POM rejects the envelope, that both dialects resolve to the same config, and that the dual parse differs only on the documented fields.
  • The node's CLI parsers now come from cardano-config (Parsers.hs: −426/+98 lines).

Shipped configuration files

  • mainnet-config.json and mainnet-config.yaml now use the envelope format (format version 2, shorter section keys).
    • Mainnet now defaults to GenesisMode.
    • The snapshot policy gains MinDelay/MaxDelay.
    • Removed keys: Protocol, MaxKnownMajorProtocolVersion, and LastKnownBlockVersion-*.
    • ⚠️ A pre-11.2 node can no longer read these files.
  • Regenerated mainnet-peer-snapshot.json together with the topology's useLedgerAfterSlot.
  • Removed the obsolete Byron/PBFT keys from testnet-template-config.json. testnet-template-dijkstra.json picks up the Leios genesis parameters.

Nix / NixOS / Docker

  • binary-release.nix writes the dialect the environment selects, so release tarballs now ship the envelope format.
  • The Docker entrypoint rewrites relative *File paths inside the envelope sections too.
  • ⚠️ Breaking change for CARDANO_CONFIG_JSON_MERGE users: merge documents must use the envelope shape now. The README explains the new shape and gives examples.
  • NixOS module (cardano-node-service.nix):
    • New configFormat option ("legacy", the default, or "enveloped"). Warnings at evaluation time list the keys that enveloping would leave unresolved.
    • Writes the peer target key names the selected dialect expects.
    • New immutableDatabasePath/volatileDatabasePath and lsmExportPath options.
    • The BLS key option now takes a single key file instead of a list.
  • NixOS tests:
    • cardanoOciReadonly is renamed to cardanoOci, with new graceful-shutdown and submit-api subtests.
    • New cardanoNodeEnveloped test.
    • cardanoNodeDbtools: global timeout raised to 300s.
    • cardanoNodeArtifact: added a nameserver.

Other packages

  • cardano-testnet (breaking): node configs are written in the cardano-config format, and genesis hashes are refreshed on every start. Removed:
    • createConfigJson and createConfigJsonNoHash
    • get{Byron,Shelley}GenesisHash
    • GenesisHashesPolicy
    • SubmitApiConf.configPath
  • cardano-node-chairman: reads envelope configs.
  • cardano-submit-api: release notes include the Dijkstra transaction decoding fix (Fix cardano-submit-api rejecting Dijkstra era transactions #6725).
  • tx-generator 2.19:
    • Supports extraConfig.initialFunds.file genesis injections, read through the ledger's foldInjectionData.
    • getGenesis/getGenesisPath are renamed to getShelleyGenesis/getShelleyGenesisPath; the old names are kept as deprecated aliases.
    • Replaced the deprecated caseByronOrShelleyBasedEra.
  • plutus-scripts-bench 1.0.6.0.
  • Workbench: added epoch 638 (Van Rossem) and made it the default, added the Leios genesis (PV11 + PV12 preview), and fixed the genesis-ripper and genesis-jq caching.

Release housekeeping

  • Bumped the cabal versions to 11.2.0. Generated the changelogs from the herald fragments and removed the fragments already released.

Checklist

  • Commit sequence broadly makes sense and commits have useful messages
  • New tests are added if needed and existing tests are updated. These may include:
    • golden tests
    • property tests
    • roundtrip tests
    • integration tests
      See Running tests for more details
  • Any changes are noted in the CHANGELOG.md for affected package
    • cardano-node-chairman, cardano-submit-api and cardano-testnet instead need a
      changelog fragment in <package>/.changes/, because their CHANGELOG.md is generated
      from fragments at release time. Copy _TEMPLATE.yml from that directory, or run
      nix run github:input-output-hk/cardano-dev#herald -- new
  • The version bounds in .cabal files are updated
  • CI passes. See note on CI. The following CI checks are required:
    • Code is linted with hlint. See .github/workflows/check-hlint.yml to get the hlint version
    • Code is formatted with stylish-haskell. See .github/workflows/stylish-haskell.yml to get the stylish-haskell version
    • Code builds on Linux, MacOS and Windows for ghc-9.6 and ghc-9.12
  • Self-reviewed the diff

Note on CI

If your PR is from a fork, the necessary CI jobs won't trigger automatically for security reasons.
You will need to get someone with write privileges. Please contact IOG node developers to do this
for you.

@koslambrou koslambrou mentioned this pull request Sep 3, 2026
@koslambrou
koslambrou force-pushed the koslambrou/prepare-11.2 branch 4 times, most recently from df2ac99 to 3b679a6 Compare September 4, 2026 13:55
@koslambrou
koslambrou force-pushed the koslambrou/prepare-11.2 branch 4 times, most recently from f006ac2 to 3d77a7d Compare September 11, 2026 17:55
@koslambrou koslambrou changed the title Prepare release 11.2 Update ouroboros-consensus, cardano-api, cardano-cli and cardano-rpc for 11.2 release. Sep 11, 2026
@koslambrou
koslambrou force-pushed the koslambrou/prepare-11.2 branch from a384d4a to 8ff994d Compare September 14, 2026 22:13
jasagredo added a commit to IntersectMBO/ouroboros-consensus that referenced this pull request Sep 16, 2026
cardano-ledger replaced two predicate-failure constructors and removed a third:

  conway: StakeKeyRegisteredDELEG        -> DelegAccountAlreadyRegistered,
          wrapping the new AccountAlreadyRegistered rather than a
          Credential Staking directly
  conway: WithdrawalsNotInRewardsCERTS   removed from ConwayCertsPredFailure
  shelley: StakeKeyAlreadyRegisteredDELEG -> DelegAccountAlreadyRegistered

The payload is unchanged in both renames -- AccountAlreadyRegistered is a
newtype over the same Credential Staking -- so only the pattern and the "kind"
string move. The removed constructor's case goes rather than being renamed;
CertFailure is the only one left, and the match stays exhaustive.

This matches how cardano-node handles the same three sites in
IntersectMBO/cardano-node#6677, so the two do not diverge while that is open.
Note the "kind" values change with the constructors, from
StakeKeyRegisteredDELEG and StakeKeyAlreadyRegisteredDELEG to
DelegAccountAlreadyRegistered.
jasagredo added a commit to IntersectMBO/ouroboros-consensus that referenced this pull request Sep 16, 2026
cardano-ledger replaced two predicate-failure constructors and removed a third:

  conway: StakeKeyRegisteredDELEG        -> DelegAccountAlreadyRegistered,
          wrapping the new AccountAlreadyRegistered rather than a
          Credential Staking directly
  conway: WithdrawalsNotInRewardsCERTS   removed from ConwayCertsPredFailure
  shelley: StakeKeyAlreadyRegisteredDELEG -> DelegAccountAlreadyRegistered

The payload is unchanged in both renames -- AccountAlreadyRegistered is a
newtype over the same Credential Staking -- so only the pattern and the "kind"
string move. The removed constructor's case goes rather than being renamed;
CertFailure is the only one left, and the match stays exhaustive.

This matches how cardano-node handles the same three sites in
IntersectMBO/cardano-node#6677, so the two do not diverge while that is open.
Note the "kind" values change with the constructors, from
StakeKeyRegisteredDELEG and StakeKeyAlreadyRegisteredDELEG to
DelegAccountAlreadyRegistered.
@koslambrou
koslambrou force-pushed the koslambrou/prepare-11.2 branch 17 times, most recently from 544a735 to 474f851 Compare October 10, 2026 00:24
johnalotoski and others added 13 commits October 27, 2026 08:00
The published configs and release artifacts moved to the cardano-config
envelope, but the service still writes a flat config. Add configFormat,
"legacy" or "enveloped", so consumers can move a host at a time.

Enveloping happens last, on the assembled instance config, so nodeConfig,
extraNodeConfig and extraNodeInstanceConfig stay flat and keep today's key
names. mkEnvelope applies the renames and sections each key. A key it does
not recognise is kept outside any section, where the node will not resolve
it, so opting a host in is worth checking against its warnings.

Ignored when nodeConfigFile is set, so workbench is unaffected. The default
stays legacy.
Added warnings, raised at eval time when configFormat is "enveloped", for
keys cardano-config will not resolve.

Lifted the config assembly out of mkScript to module level so the warnings
check the same document that gets written, rather than a second assembly
of it.

Needs the cardanoLib exports added in iohk-nix: removedKeys, renamedKeys
and unrecognisedKeys.
POM reads these only as TargetNumberOf*, cardano-config only as
DeadlineTargetNumberOf*. The module emitted the former unconditionally,
which mkEnvelope renamed, so an enveloped host warned that four keys were
stale when nothing the operator set could change them.
globalTimeout bounds the whole test, so 45s had to cover the vm boot plus
create-env, synthesis, both analyser passes, truncation and the asserted
synthesis. It was raised from 30 to 45 in c310c0d and is still tight
enough that runner variance can reach it.

300s keeps the override useful for surfacing a hang while leaving room
under the one hour framework default.
Added SIGTERM and SIGINT cases for both ways into the image, scripts mode
and custom mode, asserting docker did not have to SIGKILL after the grace
period.

These were the first four items of the Manual Testing section in
nix/docker/README.md, which nobody ran and which predated merge mode, the
/tmp runtime dir, read-only root and non-root UIDs. Its fifth item, cli
access, is already covered three times here. Dropped the section.

Use util-linux rather than the utillinux alias to resolve eval warn.
Added a submit-api subtest covering scripts mode startup and a metrics
scrape.

Renamed cardanoOciReadonly to cardanoOci. The test has covered more than
read-only roots since its second commit and the name described only the
first.

Grouped the stages into subtests so a failure names its concern rather than
a line number. Kept as one test: the shared cost is the vm, the docker
daemon and four image loads, which a split would pay per test.

All eleven subtests pass in ~120s.
Boot a preview node on `configFormat = "enveloped"` with `withUtxoHdLsmt`
and an envelope-shaped `extraNodeConfig`, and assert the node took the
cardano-config path, that it reported nothing to migrate or ignore, that the
LSM backend resolved with its path, that the envelope-shaped key reached the
resolved configuration, and that `config resolve` on the generated file says
nothing on stderr.

The service assembles the config it envelopes, so this is the only check
that sees one as a host writes it: iohk-nix lints and envelopes environment
configs, which carry neither the flat `V2LSM` pair the service adds nor
anything a caller supplies.

Reading two settings back out of the resolved `NodeConfiguration` is the
part the iohk-nix checks cannot do at all. Those compare against
cardano-config's own output, so a key its adapter never maps is lost
identically on both sides and agrees.
The service writes `Backend = "V2LSM"` with a sibling `LSMDatabasePath`,
which is the legacy spelling of the tagged `Backend.LSM` form. POM reads
`Backend` as a string, so the nested form fails to parse on a legacy config,
and mkEnvelope folds the flat one anyway, which it must do regardless for a
caller supplying the same keys through extraNodeConfig.

Writing the nested form here is therefore gated on no consumer still setting
`configFormat = "legacy"`, and is a single flip at that point rather than a
branch on the dialect. The envelope.nix header lists this as the last of the
four conditions for retiring the translation; this is where the mechanics
live.
The LSM backend can export a standalone copy of each snapshot, which is what
Mithril signing consumes, but the service had no way to ask for one: it set
`LSMDatabasePath` and nothing else.

Emitted only when set, and only under `withUtxoHdLsmt`.
The node resolves relay names from the peer snapshot. With no nameserver the
dns resolver is built from an empty list and throws BadConfiguration, which on
the aarch64 builder escaped diffusion's retry path and took the node down
instead of being retried as it is on x86_64.
@koslambrou
koslambrou force-pushed the koslambrou/prepare-11.2 branch from 2691236 to 632883f Compare October 27, 2026 12:01
@johnalotoski
johnalotoski force-pushed the koslambrou/prepare-11.2 branch 3 times, most recently from 741b75f to f61f91e Compare October 27, 2026 15:49
cardano-testnet create-env now refreshes the genesis hashes when it writes
the node configuration, so the db tools find them already in place.

Drop the add-genesis-hashes wrapper, which had become a no-op twice over:
the hashes it computed were already correct in the file, and it added them
as top-level keys, where splitEnvelope discards everything outside
Configuration.
@johnalotoski
johnalotoski force-pushed the koslambrou/prepare-11.2 branch from f61f91e to afb6c20 Compare October 27, 2026 17:06
@koslambrou
koslambrou enabled auto-merge October 27, 2026 17:41
@koslambrou
koslambrou added this pull request to the merge queue Oct 27, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to no response for status checks Oct 27, 2026
@johnalotoski
johnalotoski added this pull request to the merge queue Oct 27, 2026
Merged via the queue into master with commit dac0d7a Oct 27, 2026
31 checks passed
@johnalotoski
johnalotoski deleted the koslambrou/prepare-11.2 branch October 27, 2026 20:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

9 participants