refactor(ledger): give each ledger version its own wrapper

[ozgb]

Overview

Closes #1768.

ledger/src/versions/common/** (4451 lines) was compiled twice through a
#[path = "versions"] module-parameterization trick — once bound to the ledger-8
crates, once to the ledger-9 crates — with super:: resolving differently in each
instantiation:

#[path = "versions"]
pub mod ledger_8 {
    pub(crate) use { mn_ledger_8 as mn_ledger_local, ... };   // the parameters
    #[allow(clippy::duplicate_mod)]
    mod common;                 // -> ledger/src/versions/common/**
    pub use common::*;
}

A reader of versions/common/api/ledger.rs could not tell what mn_ledger_local
referred to, and an edit meant for one version silently applied to both. Per the
issue, that footgun cost several days of investigation and crashed nodes.

Each version now owns its files, with absolute crate::ledger_N::… imports so
every file states the version it binds:

ledger/src/
  lib.rs        pub mod ledger_8;  pub mod ledger_9;   (no #[path], no duplicate_mod)
  boundary/     was common/ — the SCALE types crossing the runtime/client
                interface, version-independent by design, still ONE copy
  host_api/     already used absolute paths; 2 lines changed
  ledger_8/     mod, types, storage, conversions, utxo_ordering_override,
                block_context, error_ext, system_tx, guaranteed_validation,
                post_block_update, api/{mod,ledger,transaction}
  ledger_9/     same 12 files

Nothing is called common any more, which is the other half of the issue: the
crate-level common/ was never shared behaviour — it is the runtime/client wire
format, deliberately version-agnostic, and the pallet has one decoder for it. It is
renamed to boundary/ rather than duplicated; versioning that wire format would be
a design change, not a refactor.

No behaviour change. rustc already emitted both instantiations, so the +4.6k
lines only make the existing duplication visible in the source tree — no new machine
code, no binary-size or compile-time change. There was no non-test version branching
in the shared half to reinterpret (the only CRATE_NAME comparisons are
if CRATE_NAME != crate::latest::CRATE_NAME { return } test guards, which still
work unchanged). Every import rewrite is compile-checked, so there is no
silent-failure mode.

Public paths are untouched — ledger_8::…, ledger_9::…, latest::…, types::…
(incl. types::active_version and types::active_ledger_bridge), host_api::….
The 27 files outside ledger/ that import from this crate needed zero changes;
the only edits outside lib.rs/ledger_8/ledger_9 are two common:: →
boundary:: import lines in host_api/.

🗹 TODO before merging

• Ready

📌 Submission Checklist

• All commits are signed off (git commit -s) for the DCO
• Changes are backward-compatible (or flagged if breaking)
• Pull request description explains why the change is needed
• Self-reviewed the diff
• I have included a change file, or skipped for this reason:
• If the changes introduce a new feature, I have bumped the node minor version
• Update documentation (if relevant)
• Updated AGENTS.md if build commands, architecture, or workflows changed
• No new todos introduced

🧪 Testing Evidence

The review artifact

The point of the layout is that the two directories can be diffed. Normalise the
version path away, then diff:

cp -r ledger/src/ledger_9 /tmp/n9
grep -rl ledger_9 /tmp/n9 | xargs sed -i 's/ledger_9::/ledger_8::/g'
diff -ru ledger/src/ledger_8 /tmp/n9

Exactly five files differ, and they are precisely the ones that were already
per-version before this PR:

file	divergence
error_ext.rs	GenerationInfoAlreadyPresent (v8) vs InitialNonceAlreadyPresent (v9)
guaranteed_validation.rs	full apply() dry-run (v8) vs apply_guaranteed_only (v9)
post_block_update.rs	no-op (v8) vs prevalidate_post_block_update (v9)
system_tx.rs	tuple vs struct SystemTransaction variants; PayBlockRewardsToTreasury only on v8
mod.rs	the crate aliases, CRATE_NAME, TransactionSignature

Everything else — types.rs, storage.rs, conversions.rs,
utxo_ordering_override.rs, block_context.rs, api/{mod,ledger,transaction}.rs —
is byte-identical modulo the version path. That is the evidence the copy is faithful,
and going forward it is the standing check for what the two versions actually do
differently.

Builds and tests

check	result
cargo check -p midnight-node-ledger --all-targets	0 errors, no new warnings
cargo clippy --workspace --all-targets --features runtime-benchmarks,try-runtime	0 errors, no new warnings
SKIP_WASM_BUILD=1 cargo check --workspace --all-targets	0 errors
cargo build -p midnight-node-runtime (real no_std / WASM path)	builds
cargo test -p midnight-node-ledger	82 passed — same count as before the change
cargo test -p pallet-midnight -p pallet-midnight-system -p pallet-c2m-bridge (+ ledger)	124 passed, 2 ignored
external consumers: rg 'midnight_node_ledger::' -g '!ledger/**'	27 files, unchanged

Note: bare cargo check -p midnight-node-ledger --no-default-features fails, but it
fails identically on main (405 errors) — it is not a supported feature
configuration. The no_std path is exercised by the runtime WASM build above.

Metadata rebuild required

scale-info's #[derive(TypeInfo)] records module_path!() in each type's Path,
so the runtime metadata embeds Rust module paths. Moving these modules therefore
changes the metadata even though nothing about the encoding changed — no variant,
discriminant, field, or field order moved, and boundary/types.rs is a 100% rename
while ledger_9/types.rs differs from its old copy by a single use line.

Decoding every midnight_node_ledger-rooted path out of the old and new blobs
gives 18 renames, 18 unchanged type names, nothing added or removed:

• common::types::{Op, Tx, UtxoInfo} -> boundary::types::{…}
• ledger_9::common::types::{DeserializationError, DisjointCheckErrorCode, EffectsCheckErrorCode, FeeCalculationErrorCode, InvalidError, LedgerApiError, MalformedContractDeployErrorCode, MalformedError, MalformedZswapErrorCode, SequencingCheckErrorCode, SerializationError, SystemTransactionError, TransactionApplicationErrorCode, TransactionError, ZswapInvalidErrorCode}
  -> ledger_9::types::{…}

The blob shrinks by exactly 99 bytes (148858 -> 148759), which is the arithmetic of
those renames and nothing else: 15 paths drop the common segment (-7 bytes each, a
compact length prefix plus six characters) and 3 grow from common to boundary
(+2 bytes each). Anything already encoded on chain still decodes identically.

Renaming ledger_9::common::types is unavoidable — that module is what the issue
asks to remove — so metadata had to be rebuilt either way; the crate-root
common -> boundary rename adds three more paths to the same churn. Downstream
subxt codegen will see the new runtime_types::… module paths. No in-repo consumer
references them (the indexer's runtimes/v*.rs are pinned to older metadata
snapshots), but it is worth a heads-up to anyone generating fresh bindings.

No genesis rebuild: no storage item, extrinsic, or runtime API changed.

• Additional tests are provided (if possible)

🔱 Fork Strategy

• N/A

Source-layout only. The runtime WASM blob may differ byte-wise since panic locations
embed source paths, but spec_version and behaviour are unchanged, so no coordinated
update is needed.

Links

Closes #1768

Follow-ups (deliberately not in this PR)

• Hoist what is genuinely version-agnostic back to one copy. Now that the copies
  are separate you can diff them and decide per item — but that judgement call is the
  multi-day analysis the issue describes. Pure duplication first.
• ledger/helpers/src (6166 lines) and util/toolkit/src
  (commands/fork/common, tx_generator/builder/builders/common, 4003 lines) use the
  same trick. Same recipe, separate PRs.
• Drop the non-latest test copies. The
  if CRATE_NAME != crate::latest::CRATE_NAME { return } guards already make them
  no-ops.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 294f681d57

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Preserve the error-encoding invariant across copies

When either independently editable copy gains or reorders a version-specific error variant, the SCALE discriminants can diverge, but host_api/ledger_9.rs::as_ledger_9_error still converts v8 errors by encoding and decoding them as this v9 enum. The existing test samples only a few variants and does not cover nested transaction errors, so historical v8 reads can silently return the wrong v9 error or fall back to HostApiError. Keep the encoding-bearing error definitions shared, use an explicit conversion, or exhaustively enforce their compatibility.

Useful? React with 👍 / 👎.

[ozgb]

/bot rebuild-metadata

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b9425e310a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 60fb008a52

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Add the required license header

This newly added Rust source file starts directly with a cfg attribute and omits the repository’s mandatory license header. Prepend the contents of LICENSE_HEADER.txt so the new source file complies with the project’s licensing requirements.

AGENTS.md reference: AGENTS.md:L239-L241

Useful? React with 👍 / 👎.