L2 removal: capability reweight, the CapabilityType wire hazard, and what it reclaims

[defenwycke]

Ghost Pay / L2 is being removed once Stage 6 completes. Ghost Wallet replaces it — existing Bitcoin infrastructure for self-custody, payments via Wraith protocol with Ghost locks.

Scoping the consequences now, while the code is still in front of us, rather than discovering them during the removal.

⛔ This is a follow-on to Stage 6, not part of it. It changes payout weighting, so it cannot ride the Stage 6 deletion release — that one is already carrying the BFT payout cutover, and stacking a weighting change on a money-path cutover loses the rollback position.

Stage 6 (BFT payout + sweep + gate collapse)
   -> L2 removal + capability reweight
      -> Ghost Wallet

---

1. GhostPay is +4 of the 15 capability shares

The 5-4-3-2-1 system weights node rewards: Archive +5, GhostPay +4, Public Mining +3, Reaper +2, Elder +1.

Removing ghost-pay means either the maximum drops to 11, or something takes those 4. Either way node reward weighting changes, so it needs a height gate and fleet uniformity like every other weighting change.

⚠ Deciding how to reweight is the real question and it is not obvious. Dropping to 11 silently re-scales every node's relative share; substituting a new capability means defining and verifying one. Neither should be picked during the removal.

It also makes part of #605 moot rather than fixed

#605 asks for GhostPay's epoch_state_hash to be anchored in a fleet-visible commitment, because today a node with no L2 at all passes with a random hex string. If the capability is being deleted, that work should not be done. Close that item as superseded rather than building it.

2. CapabilityType::GhostPay — the same wire hazard as H-7, in reverse

CapabilityType is a plain serde enum with no unknown-variant fallback. #729 hit this adding Address: a peer on an older binary does not ignore an unknown variant, it fails to deserialise the whole message and drops the verdict silently.

Removal is the worse direction. A node still on the old binary emitting "ghostpay" to an upgraded peer makes that peer drop the entire message — so during any mixed-version window, upgraded nodes discard verdicts from un-upgraded ones, including verdicts about capabilities that are not being removed.

So the removal needs the same treatment the addition got: ship the tolerance first, roll the whole fleet, then remove the emitter. Not one release.

Also to check before removing the variant: it is the capability column value in the convergence ledger and the key ChallengeConvergence reconciles on — a stored format, not a label. Historical rows will still carry "ghostpay".

3. What it reclaims

l2_checkpoints is 443 MB of the 5.3 GB pool DB (measured on vm1, 2026-08-22).

That matters because #690 is a working-set problem — the DB does not fit in RAM on 7 of 8 nodes (20-27% iowait against vm8's 0.9% on identical work). Revised outlook for the four big consumers:

table	size	fate
shares_archive	2.6 GB	DROP after v1 — already planned (migrations.rs:2731)
verification_ledger	1.0 GB	#585 retention — the one with no exit yet
l2_checkpoints	443 MB	goes with this removal
sbc_batches	133 MB	kept deliberately; migrations must stay replayable

Two of the four now have a named exit, which leaves verification_ledger as the genuine long-term storage problem.

4. Also removed by this

• The L2 nullifier checkpoint tree and its sync (nullifier_route_handler.rs). Nodes currently run a continuous catch-up on it — measured closing at 86 heights/min on 2026-08-22 — which is real I/O on the small nodes. Deliberately not fixed, since it is going.
• ghostpay_challenges table and the GhostPay arm of the verification rotation.
• The /resolve and bond endpoints on ghost-pay, subject to the wraith_bonds check (confirmed empty on all 8 and dropped by v57).

Open questions for whoever picks this up

1. Reweight to 11, or substitute a capability? (Not a removal-time decision.)
2. Does anything outside the pool read l2_checkpoints before it is dropped?
3. Confirm the Ghost Wallet path covers what ghost-pay users have today before the endpoints go.

[defenwycke]

Correction from the operator, 2026-08-22: the +4 is not deleted, it MOVES

The original framing above assumed removing Ghost Pay deletes the GhostPay capability and drops the maximum from 15 to 11. That is wrong.

The +4 transfers to running a Wraith coordinator. The weight stays in the 5-4-3-2-1 system; what changes is what has to be proven to earn it.

That is a materially better outcome than either option this issue originally posed, and it changes the work:

What this means

• No reweight decision is needed. The maximum stays 15, every node's relative share keeps its shape, and no height gate is required for a weighting change — because there isn't one. That removes the largest open question from this issue.
• The work becomes a capability SWAP, not a removal. CapabilityType::GhostPay is replaced by a coordinator capability, and the challenge that verifies it has to be written. A node claiming it must be shown to actually be running a coordinator.
• ⛔ The verification is the whole job, and it is the H-7: challenger /24 subnets are self-reported, so the diversity floor is fabricable (was: capability proofs do not prove the capability) #605 lesson repeating. GhostPay's +4 was unearned precisely because its challenge checked field shapes and nonce binding and never anchored anything — "a node with no L2 at all passes with a random hex string." A coordinator capability that merely checks coordinator_enabled = true in config, or that a port answers, reproduces that exactly. It must prove the node is doing coordinator work, not that it claims to.
• ⚠ The wire hazard is unchanged and still applies. CapabilityType has no unknown-variant fallback, so swapping a variant has the same failure as removing one: an old node emitting "ghostpay" makes an upgraded peer drop the entire message, silently. Ship the tolerance, roll the fleet, then change the emitter. Not one release.
• ⚠ coordinator_enabled is currently true on exactly one node (vm4) and the roster is one node, so the election is vacuous (Wraith coordinator roster is one node in production, so the election is vacuous #708). A capability that pays +4 for running a coordinator needs that resolved first, or it pays four shares for an uncontested role.

Unchanged from above

The 443 MB l2_checkpoints reclaim, retiring the nullifier tree sync, and the ghostpay_challenges table all still happen. And #605's GhostPay epoch-anchoring work should still not be built — but the reason is now "the capability is being redefined", not "the capability is going away".

[defenwycke]

Correction to the framing, confirmed today.

The body says "Ghost Pay / L2 is being removed once Stage 6 completes. Ghost Wallet replaces it." That is not quite what is happening, and the difference is material: ghost-pay is being superseded and MODIFIED into Wraith coordination, not deleted. The L2 role goes; the component survives in a new job.

Two consequences worth capturing while the issue is open:

1. The reweight question changes shape. The issue frames it as "either the maximum drops to 11, or something takes those 4". If GhostPay's +4 becomes a Wraith-coordination capability, there is a third answer: the capability is renamed and re-earned against a different challenge. That is a better outcome than either listed option — it keeps the weighting intact and gives the +4 something it can actually prove, which is exactly what #605 is about. It is also the only one of the three that does not re-scale every node's relative share.

2. Instant payments need a destination before L2 is switched off. Lightning Wraith — liquidity for Wraith, instant payments, fees to liquidity providers — is the intended replacement for that capability. It is currently greenfield: zero implementation in the tree, the only "Lightning" being BUDS classifying small OP_RETURNs. So the dependency is not just Stage 6 → L2 removal, it is:

Stage 6 (BFT payout + sweep + gate collapse)
   -> Lightning Wraith designed  (instant payments have somewhere to go)
   -> L2 removal + capability reweight
      -> Ghost Wallet

Removing L2 before that replacement exists trades instant settlement for nothing.

Operational note: because the component survives, ghost-pay is still a shipped binary and is being rolled to 1.11.32 with the rest of the fleet under #759. I had queried whether that was wasted effort on a doomed binary; it is not.

[defenwycke]

⚠ Measured against e97e71c93: the removal has already partly happened, ahead of the sequencing this issue sets out.

bins/ no longer contains ghost-pay or ghost-gsp — they went with the bond deletion (#699/#721). But the things this issue says must come first have not:

• CapabilityType::GhostPay still exists, and so do ChallengeType::GhostPayBalance / GhostPayTransfer and GhostPayChallenge/GhostPayResponse (crates/ghost-verification/src/challenge.rs:42-466)
• the capability reweight — the +4 of 15 — has not been decided or gated

So a node built from current main cannot serve the capability it is still weighted for. That is not yet a live break, because vm1–vm4 still run the old binaries and vm5–vm8 never ran ghost-pay at all (see #708), so the fleet's weighting is already whatever it has been. But the next roll that replaces vm1–vm4's binaries removes ghost-pay from the four nodes that still have it, and this issue's own analysis says that changes node reward weighting and therefore needs a height gate.

⇒ Worth deciding the reweight before the roll that follows MESH_ENVELOPE_V2 (966,400), rather than discovering it as a payout change afterwards. The wire-hazard sequencing in section 2 — ship the tolerance, roll the fleet, then remove the emitter — is unaffected and still applies to CapabilityType itself, which is untouched.

Cross-referenced from #605, whose GhostPay item I have marked superseded rather than fixable.

[defenwycke]

The +4 cannot simply move to coordinator — that bool is self-reported

Scoping the reweight against c604f7ad3, and there is a trap worth naming before anyone writes the change.

NodeCapabilities already carries a coordinator: bool (ghost-common/src/types.rs:51), and its own doc explains why it is currently harmless:

Wraith coordinator role opted in. Earns the mixing service fee, NOT 5-4-3-2-1 shares — so it is deliberately excluded from total_shares() and needs no verification challenge.

That reasoning is exactly right, and it inverts the moment the field earns shares. coordinator arrives in a peer's own health ping. Attaching +4 to it as it stands would pay four shares for a self-attested boolean — which is precisely the defect #605 exists to complain about ("a node with no L2 passes with a random hex string"), reintroduced on a fresh capability rather than inherited.

So the order is forced:

1. A verified Wraith coordinator capability first. Not the flag — a challenge. The good news is a real proof is available here, unlike GhostPay: a challenger can re-derive the epoch beacon from its own chain and check the target's published election view matches (the wallet already does this — beacon_anchor_expectation / beacon_matches_chain), then require a live protocol handshake on the advertised port, the same shape as verify_sv1 for stratum. Both halves are things a liar cannot fake without actually running a coordinator.
2. Then move the weight, height-gated, so every node switches at the same block regardless of roll order.

Doing (2) without (1) is not a smaller version of the change — it is a worse state than today, because today the flag is honest precisely by being worthless.

Surface, now that it is mapped

• ghost-common/src/constants.rs:81-85 — ARCHIVE_MODE_SHARES … GHOST_PAY_SHARES, and the compile-time max-shares assertion that will need to move with them
• NodeCapabilities::total_shares() — the gate goes here
• ghost-verification/src/qualification.rs — per-capability pass rates and unique-challenger floors; a new capability needs both, or it qualifies on one friendly challenger
• mesh_capability_shares() (routes.rs:4216) — the dashboard's own copy of the weighting, which will silently disagree with the payout path if only one is changed

⚠ That last one is worth flagging on its own: the weighting exists twice, once for payouts and once for display. Whatever the reweight does, both move together or the dashboard starts lying about what nodes earn.

Still gated behind #871 reaching the whole fleet before any new variant is emitted.

[defenwycke]

The coordinator cannot currently prove it is a particular node, so the obvious challenge would be theatre

Scoping the verified capability against 36d0d80bb. What a challenger could probe today:

endpoint	what it proves
GET /health	something is listening and says it is a coordinator — service, version, network, uptime. No signature, no node id
GET /api/v1/pool/discover	the coordinator identity, tiers, fee — again unsigned
session routes	require a real session; side effects

And CoordinatorState holds no node identity key at all — grepping it for identity/signing turns up nothing.

⇒ A challenge built from these is passed by nc -l 9100 serving a static JSON blob. That is #605's Stratum finding word for word ("a bare TCP connect; nc -l 3333 passes"), rebuilt on a new capability. It would be worse than the GhostPay +4 it replaces, because it would be new work rather than inherited debt.

What a real proof needs

Two things, and neither alone is enough:

1. Identity. A signature over the challenger's nonce by the node's identity key. This is exactly the target_signed_response pattern the other capabilities already use — the recipient verifies it is signed by target_node_id, so a relay cannot answer for somebody else. The coordinator process does not have that key, but ghost-pool does, and ghost-pool runs the coordinator in-process when elected (coordinator_supervisor.rs). So the attestation belongs on the pool side, not in the standalone binary.
2. Liveness at the advertised endpoint. The challenger dials the advertised_endpoint from the published election view and confirms a coordinator answers there. This is the half that cannot be faked by a node that merely opted in.

Together they say: this node, provably, is serving a coordinator at the address it advertises. Either alone is forgeable — a signature without a probe proves only that a key exists, and a probe without a signature proves only that something listens.

⚠ One thing NOT to mistake for proof

Verifying the target's published election document is not evidence about the target. The draw is derived from public inputs — beacon, epoch, roster — so any node can compute and publish a correct one without coordinating anything. It is worth checking as a consistency test, and it is worth nothing as a capability proof.

That is the same shape as #605's Archive finding: "every response field is derivable from the public 80-byte header," so a pruned node passes. Deriving-from-public-data is the recurring way these challenges end up honesty-graded.

Consequence for sequencing

The verified capability is not a wiring job on top of existing endpoints — it needs a new signed attestation endpoint on ghost-pool. That is the real prerequisite for moving the +4, and it should be its own change with its own review, before either the weight move or the emission gate.

Order: signed attestation → challenge that requires it AND a live probe → gated weight move.