diff --git a/ops/dsl-baselists-dump.sh b/ops/dsl-baselists-dump.sh
new file mode 100644
index 0000000..a995feb
--- /dev/null
+++ b/ops/dsl-baselists-dump.sh
@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+#
+# The deterministic masternode list at every Sentinel epoch base, as JSONL, for
+# ops/dsl-enforcement-replay.py.
+#
+# Runs on the explorer VPS against the seed's RPC, read-only and paced: one
+# `protx diff 1 ` per epoch, reduced to proRegTxHash, confirmedHash and
+# isValid, which is all the replay needs to reproduce the commitment's bit order
+# (the list sorted by proTxHash in the node's internal byte order). The explorer
+# stores the bit indices and, where it could resolve them, the proTxHashes; it
+# does not store the list itself, and its resolver refuses a partial answer.
+#
+# Usage: ops/dsl-baselists-dump.sh [first-epoch] [last-epoch] > baselists.jsonl
+# defaults: from the devnet's first committable epoch (228, base 5472) to the
+# tip's epoch. ~0.3 s per epoch.
+set -euo pipefail
+
+CLI="${DEFCON_CLI:-/usr/local/bin/defcon-cli -datadir=/home/defcon/.defcon -conf=/home/defcon/.defcon/defcon.conf}"
+EPOCH_INTERVAL=24
+FIRST="${1:-228}"
+TIP=$($CLI getblockcount)
+LAST="${2:-$(( TIP / EPOCH_INTERVAL ))}"
+
+for e in $(seq "$FIRST" "$LAST"); do
+ b=$(( e * EPOCH_INTERVAL ))
+ hash=$($CLI getblockhash "$b") || continue
+ $CLI protx diff 1 "$b" | jq -c --argjson e "$e" --argjson b "$b" --arg h "$hash" \
+ '{epoch: $e, base: $b, baseHash: $h, mnList: [.mnList[] | {proRegTxHash, confirmedHash, isValid}]}'
+ sleep 0.2
+done
diff --git a/ops/dsl-enforcement-replay.py b/ops/dsl-enforcement-replay.py
new file mode 100644
index 0000000..e3ffcfe
--- /dev/null
+++ b/ops/dsl-enforcement-replay.py
@@ -0,0 +1,321 @@
+#!/usr/bin/env python3
+"""Replay the Sentinel layer's enforcement arithmetic over recorded commitments (G5).
+
+The question that decides when punishment may be switched on -- "what would the
+enforcement arithmetic have done to the commitments actually recorded?" -- can
+be answered from the chain, with no chain change. This is a line-for-line port
+of CDeterministicMNList::ApplyServiceCommitment (evo/deterministicmns.cpp:402-475,
+v22.1.x at 0c758792ca), applied in epoch order:
+
+ absent epoch the function never runs: every counter is frozen
+ removed member in the base list but gone from the list at the boundary
+ (:423, "removed from the list since the epoch base"): skipped
+ mass outage missed*100 >= size*nDSLMassOutagePct: record the epoch, change nothing
+ unobserved member no verdict (format v2): change nothing; v1 observes everyone
+ online member counter = 0; if enforcing, the suspension and the DSL ban are cleared
+ missed member counter += 1; if enforcing, >= suspend -> suspended, >= ban -> banned
+ at the boundary height, once
+
+Enforcement is decided the way the node decides it -- the boundary block's height
+against nDSLEnforcementHeight (:419) -- with --enforce-from-height. The epoch form,
+--enforce-from-epoch, is for counterfactual windows; mapping a height to "the epoch
+that begins there" is one epoch late, because the commitment applied AT that height
+belongs to the epoch that ends there (8304 on this devnet is epoch 345's boundary).
+
+WHAT THIS IS, AND IS NOT. A first-order counterfactual: the arithmetic applied to
+the commitments as they were recorded. Under real enforcement a DSL ban sets
+isValid=false, which changes the sentinel assignment and who can report at all,
+so the later commitments would not have been the same ones. That answers the G5
+gate ("would anyone have been punished in this window?"); it is not a proof that
+enforcement is safe.
+
+Inputs are the explorer's epoch rows (GET /api/v1/dsl/epochs, saved to a file)
+and the deterministic masternode list at every epoch base (a JSONL written by
+ops/dsl-baselists-dump.sh from `protx diff 1 `). The base list is needed
+because the commitment's bit order is that list sorted by proTxHash -- in the
+node's INTERNAL byte order, which is the display hex reversed bytewise. Sorting
+the display strings names the wrong masternodes. The list at an epoch's boundary
+is the next epoch's base list (base(k+1) == boundary(k)); a member of base(k)
+missing from it was removed during the epoch and is skipped as the node skips
+it. Without that next list every base member is counted, and the run says so.
+
+Three checks, and what each is worth. The stored proTxHash lists are compared
+against the index resolution, so a wrong sort cannot pass silently -- but both
+sides are ports of the same ordering rule, not an oracle. --expect compares the
+events inside the window with the declared stopped set, and assumes a clean
+starting state (no live streak at the window's first epoch; both recorded
+outage runs began that way). --compare-counters is the only oracle -- the node's
+own missedServiceEpochs -- and it discriminates only while streaks are live: at
+a quiet tip every counter is 0 and an all-zero replay passes it too. Capture
+that snapshot during an outage run; the tool says when the comparison is empty.
+
+Validated 2026-09-20 against every window with a known answer: the shadow
+outage of 2026-09-03 (five stopped -> exactly the five suspended and banned),
+E1b of 2026-09-05 where the chain itself enforced from height 8304 (suspended
+at 8496, banned at 8520, recovered at 8568 -- the replay reproduces those
+heights and names), E2 of 2026-09-06 (the 15% guard opens at 23 of 152 and
+nobody is suspended), the 100-epoch baseline of 2026-09-15 (nobody), and the
+whole history against the node's counters (152 of 152 equal -- all zero at that
+tip, so that one carried no weight). Raising the guard to 16% suspends 21 in
+E2, which is the control that the guard branch is live.
+
+ ops/dsl-enforcement-replay.py --epochs epochs.json --baselists baselists.jsonl \\
+ --from-epoch 581 --to-epoch 680 --enforce-from-epoch 581 [--expect stopped.json]
+ ops/dsl-enforcement-replay.py --epochs epochs.json --baselists baselists.jsonl \\
+ --from-epoch 340 --to-epoch 360 --enforce-from-height 8304 --expect e1b.json
+
+Read-only over its input files; it never talks to a node.
+"""
+import argparse
+import collections
+import json
+import sys
+
+UNSET_BAN = -1
+
+
+def internal(h):
+ """A hash as the node holds it: the display hex reversed bytewise."""
+ return bytes.fromhex(h)[::-1]
+
+
+def canonical_order(mn_list):
+ """The commitment's bit order: the epoch-base list sorted by proTxHash the way
+ uint256 sorts -- base_blob::Compare is a memcmp over the internal bytes."""
+ return sorted((m["proRegTxHash"] for m in mn_list), key=internal)
+
+
+def load_epochs(path):
+ with open(path, encoding="utf-8") as f:
+ data = json.load(f)
+ rows = data["data"]["items"] if isinstance(data, dict) and "data" in data else data
+ return sorted(rows, key=lambda e: e["epoch"])
+
+
+def load_baselists(path):
+ out = {}
+ with open(path, encoding="utf-8") as f:
+ for line in f:
+ line = line.strip()
+ if line:
+ e = json.loads(line)
+ out[int(e["epoch"])] = e
+ return out
+
+
+def boundary_list(bases, row):
+ """The set of proTxHashes on the list at the epoch's boundary block -- the next
+ epoch's base list, since base(k+1) == boundary(k). None when the dump does not
+ hold it, or holds it at a different height (then it is not that block's list)."""
+ nxt = bases.get(row["epoch"] + 1)
+ if nxt is None:
+ return None
+ if nxt.get("base") is not None and nxt["base"] != row["boundaryHeight"]:
+ return None
+ return {m["proRegTxHash"] for m in nxt["mnList"]}
+
+
+class Replay:
+ """State of every masternode's Sentinel counters, advanced one epoch at a time."""
+
+ def __init__(self, suspend=4, ban=5, mass_outage_pct=15, hold_unobserved=True):
+ self.suspend, self.ban, self.mass_pct = suspend, ban, mass_outage_pct
+ self.hold_unobserved = hold_unobserved
+ self.counter = collections.defaultdict(int) # proTxHash -> nMissedEpochs
+ self.suspended = set() # fRewardSuspended
+ self.banned = {} # proTxHash -> nDSLBanHeight
+ self.last_epoch = {} # nLastServiceEpoch
+ self.events = [] # (epoch, height, kind, proTxHash)
+ self.table = [] # per-epoch rows
+ self.warnings = []
+ # Branch coverage: how often a protective branch guarded a member that had a
+ # streak to protect. A window where these stay at zero has not exercised
+ # that branch, and a control that flips it cannot discriminate there.
+ self.hold_protected = 0 # unobserved member with counter > 0
+ self.mass_protected = 0 # mass-outage epoch skipping a member with counter > 0
+ self.absent_frozen = 0 # absent epoch while any counter was > 0
+ self.removed_skipped = 0 # member-epochs skipped because the member had left the list
+
+ def apply(self, row, base, enforce, present=None):
+ """One epoch. `present` is the set of proTxHashes on the list at the boundary
+ block (None: unknown, every base member is counted)."""
+ epoch, height = row["epoch"], row["boundaryHeight"]
+ if row["status"] != "committed":
+ if any(self.counter.values()):
+ self.absent_frozen += 1
+ self.table.append((epoch, height, "absent", None, None, None, len(self.suspended), len(self.banned)))
+ return
+ order = canonical_order(base["mnList"])
+ size = len(order)
+ if row["listSize"] != size:
+ self.warnings.append("epoch %d: listSize %s != base list %d" % (epoch, row["listSize"], size))
+ self.table.append((epoch, height, "size-mismatch", None, None, None, len(self.suspended), len(self.banned)))
+ return
+ if present is None:
+ self.warnings.append("epoch %d: no list at the boundary %d (the next epoch's base): "
+ "a member removed during the epoch would be counted" % (epoch, height))
+ missed_idx = set(row.get("missedIndices") or [])
+ unobs_idx = set(row.get("unobservedIndices") or [])
+ missed = {order[i] for i in missed_idx if i < size}
+ unobserved = {order[i] for i in unobs_idx if i < size} if self.hold_unobserved else set()
+ stored = set(row.get("missedProTxHashes") or [])
+ if stored and stored != missed:
+ self.warnings.append("epoch %d: stored missedProTxHashes differ from index resolution" % epoch)
+ missed_count = len(missed_idx)
+ mass = size > 0 and missed_count * 100 >= size * self.mass_pct
+ for p in order:
+ if present is not None and p not in present:
+ # deterministicmns.cpp:423 -- GetMN() finds nothing, the node skips it
+ self.removed_skipped += 1
+ continue
+ self.last_epoch[p] = epoch
+ if mass:
+ if self.counter[p]:
+ self.mass_protected += 1
+ continue
+ if p in unobserved:
+ if self.counter[p]:
+ self.hold_protected += 1
+ continue
+ if p not in missed:
+ if self.counter[p] != 0 and enforce and (p in self.suspended or p in self.banned):
+ self.events.append((epoch, height, "recovered", p))
+ self.counter[p] = 0
+ if enforce:
+ self.suspended.discard(p)
+ self.banned.pop(p, None)
+ else:
+ self.counter[p] += 1
+ if enforce:
+ if self.counter[p] >= self.suspend and p not in self.suspended:
+ self.suspended.add(p)
+ self.events.append((epoch, height, "suspended", p))
+ if self.counter[p] >= self.ban and p not in self.banned:
+ self.banned[p] = height
+ self.events.append((epoch, height, "banned", p))
+ self.table.append((epoch, height, "mass-outage" if mass else "applied", size, missed_count,
+ len(unobs_idx), len(self.suspended), len(self.banned)))
+
+
+def run(rows, bases, enforce_from=None, enforce_from_height=None, **kw):
+ rp = Replay(**kw)
+ skipped = 0
+ for r in rows:
+ base = bases.get(r["epoch"])
+ if r["status"] == "committed" and base is None:
+ rp.warnings.append("epoch %d: no base list" % r["epoch"])
+ skipped += 1
+ continue
+ # The node's rule is by height (:419); the epoch form is for counterfactual windows.
+ enforce = ((enforce_from is not None and r["epoch"] >= enforce_from) or
+ (enforce_from_height is not None and r["boundaryHeight"] >= enforce_from_height))
+ rp.apply(r, base, enforce, boundary_list(bases, r))
+ return rp, skipped
+
+
+def main():
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("--epochs", required=True, help="JSON: the /api/v1/dsl/epochs rows (envelope or bare list)")
+ ap.add_argument("--baselists", required=True, help="JSONL from ops/dsl-baselists-dump.sh")
+ ap.add_argument("--from-epoch", type=int)
+ ap.add_argument("--to-epoch", type=int)
+ enf = ap.add_mutually_exclusive_group()
+ enf.add_argument("--enforce-from-epoch", type=int,
+ help="counterfactual: apply the enforcing branch from this epoch (default: never, i.e. shadow)")
+ enf.add_argument("--enforce-from-height", type=int,
+ help="the node's rule: enforce when the boundary block's height >= this (nDSLEnforcementHeight)")
+ ap.add_argument("--suspend", type=int, default=4)
+ ap.add_argument("--ban", type=int, default=5)
+ ap.add_argument("--mass-outage-pct", type=int, default=15)
+ ap.add_argument("--no-hold-unobserved", action="store_true",
+ help="CONTROL: treat unobserved members as online, the v1 healing that v2 ended")
+ ap.add_argument("--expect", help='JSON {"stopped": [proTxHash...], "note": "..."}: the G5 verdict against it '
+ '(events inside the window only; assumes no live streak at the first epoch)')
+ ap.add_argument("--compare-counters", help="JSON {proTxHash: missedServiceEpochs} from the node -- the oracle, "
+ "but only a snapshot with live streaks can discriminate")
+ ap.add_argument("--verbose", action="store_true")
+ a = ap.parse_args()
+
+ rows = load_epochs(a.epochs)
+ if a.from_epoch is not None:
+ rows = [r for r in rows if r["epoch"] >= a.from_epoch]
+ if a.to_epoch is not None:
+ rows = [r for r in rows if r["epoch"] <= a.to_epoch]
+ if not rows:
+ sys.exit("no epochs in range")
+ rp, skipped = run(rows, load_baselists(a.baselists), a.enforce_from_epoch, a.enforce_from_height,
+ suspend=a.suspend, ban=a.ban, mass_outage_pct=a.mass_outage_pct,
+ hold_unobserved=not a.no_hold_unobserved)
+
+ committed = [t for t in rp.table if t[2] in ("applied", "mass-outage")]
+ absent = [t for t in rp.table if t[2] == "absent"]
+ mass = [t for t in rp.table if t[2] == "mass-outage"]
+ print("window: epochs %d..%d (%d rows: %d committed, %d absent, %d mass-outage, %d skipped)" %
+ (rows[0]["epoch"], rows[-1]["epoch"], len(rows), len(committed), len(absent), len(mass), skipped))
+ if a.enforce_from_height is not None:
+ enforcing = "height %d (boundary blocks >= it, the node's rule)" % a.enforce_from_height
+ elif a.enforce_from_epoch is not None:
+ enforcing = "epoch %d" % a.enforce_from_epoch
+ else:
+ enforcing = "never (shadow)"
+ print("rules: suspend >= %d, ban >= %d, mass-outage >= %d%%, unobserved %s; enforcing from %s" %
+ (a.suspend, a.ban, a.mass_outage_pct, "held" if not a.no_hold_unobserved else "TREATED AS ONLINE (control)",
+ enforcing))
+ if a.verbose:
+ print("\nepoch height state size missed unobs susp banned")
+ for e, h, st, sz, mc, uo, ns, nb in rp.table:
+ print("%5d %6d %-12s %4s %6s %5s %4d %6d" % (
+ e, h, st, "-" if sz is None else sz, "-" if mc is None else mc, "-" if uo is None else uo, ns, nb))
+ print()
+ ev = collections.Counter(k for _, _, k, _ in rp.events)
+ print("events: %s" % (dict(ev) if ev else "none"))
+ for e, h, k, p in rp.events:
+ print(" epoch %d @%d %-9s %s" % (e, h, k, p[:12]))
+ nonzero = {p: c for p, c in rp.counter.items() if c}
+ print("final: %d members with a non-zero counter, %d suspended, %d banned" % (len(nonzero), len(rp.suspended), len(rp.banned)))
+ for p, c in sorted(nonzero.items(), key=lambda kv: -kv[1])[:12]:
+ print(" %s counter=%d%s%s" % (p[:12], c, " SUSPENDED" if p in rp.suspended else "",
+ " BANNED@%d" % rp.banned[p] if p in rp.banned else ""))
+ print("branch coverage (member-epochs where a protective branch guarded a non-zero counter): "
+ "unobserved-hold %d, mass-outage %d; absent epochs while any counter was non-zero: %d; "
+ "members skipped as removed before the boundary: %d"
+ % (rp.hold_protected, rp.mass_protected, rp.absent_frozen, rp.removed_skipped))
+ if rp.hold_protected == 0:
+ print(" NOTE: the unobserved-hold branch never guarded a streak in this window; a control that flips it cannot discriminate here")
+ for w in rp.warnings:
+ print("warning:", w)
+
+ rc = 0
+ if a.expect:
+ with open(a.expect, encoding="utf-8") as f:
+ exp = json.load(f)
+ stopped = set(exp["stopped"])
+ print("\nG5 verdict against '%s' (%d stopped; events inside the window, clean start assumed):"
+ % (exp.get("note", a.expect), len(stopped)))
+ for name, got in (("suspended", {p for _, _, k, p in rp.events if k == "suspended"}),
+ ("banned", {p for _, _, k, p in rp.events if k == "banned"})):
+ extra, missing = got - stopped, stopped - got
+ ok = not extra and not missing
+ print(" %-9s %s (got %d, expected %d%s%s)" % (
+ name, "PASS" if ok else "FAIL", len(got), len(stopped),
+ "; EXTRA " + ",".join(p[:8] for p in sorted(extra)) if extra else "",
+ "; MISSING " + ",".join(p[:8] for p in sorted(missing)) if missing else ""))
+ rc |= 0 if ok else 1
+ if a.compare_counters:
+ with open(a.compare_counters, encoding="utf-8") as f:
+ node = {k: int(v) for k, v in json.load(f).items()}
+ diffs = [(p, rp.counter.get(p, 0), n) for p, n in node.items() if rp.counter.get(p, 0) != n]
+ live = sum(1 for n in node.values() if n)
+ print("\ncounter cross-check against the node: %d members compared, %d differ; node counters non-zero: %d"
+ % (len(node), len(diffs), live))
+ if live == 0:
+ print(" NOTE: every node counter is 0 -- an all-zero replay passes this too; the check discriminates "
+ "only on a snapshot taken while streaks are live (during an outage run)")
+ for p, mine, theirs in diffs[:10]:
+ print(" %s replay=%d node=%d" % (p[:12], mine, theirs))
+ rc |= 0 if not diffs else 2
+ sys.exit(rc)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/ops/tests/fixtures/dsl-enforcement-replay-synthetic.json b/ops/tests/fixtures/dsl-enforcement-replay-synthetic.json
new file mode 100644
index 0000000..4cdaf2f
--- /dev/null
+++ b/ops/tests/fixtures/dsl-enforcement-replay-synthetic.json
@@ -0,0 +1,56 @@
+{
+ "_comment": [
+ "Synthetic fourteen-masternode chain for ops/tests/test_dsl_enforcement_replay.py.",
+ "Fourteen and not fewer: with six members one missed masternode is already 16.7% of the",
+ "list and the 15% mass-outage guard swallows every epoch -- the first draft of this fixture",
+ "did exactly that and no counter ever moved. With fourteen, one miss is 7.1%, two are 14.3%",
+ "(below the guard), three are 21.4% (the guard opens).",
+ "The proTxHashes are chosen so that display order (01.., 02.., ..., 0e..) is the REVERSE of",
+ "the node's internal byte order (last byte 22 < 33 < ... < ff): canonical index 0 is member",
+ "N (0e..22) and index 13 is member A (01..ff). A tool that sorts display strings puts A at 0.",
+ "Members by canonical index: 13=A 12=B 11=C ... 0=N.",
+ "Story: A (index 13) misses epochs 2-6 -> counter 1..5, suspended at epoch 5 (count 4),",
+ "banned at epoch 6 (count 5, height 168). B (index 12) misses epoch 3 (counter 1), is",
+ "UNOBSERVED in epoch 4 while that streak is live (the hold branch no recorded devnet epoch",
+ "has exercised), is online in epoch 5 (reset). Epoch 2 is format v1 (everyone observed).",
+ "Epoch 7 is absent (freeze). Epoch 8 is a mass outage (3 of 14 = 21.4%): nothing changes.",
+ "Epoch 9: A online -> recovered; B missed -> counter 1. Epoch 10 has a wrong listSize and",
+ "must be skipped, so C (index 11) is never counted.",
+ "Epoch 11: N (index 0) is missed, but N left the list during the epoch -- the test builds",
+ "the base list of epoch 12 (the list at boundary 288) without N -- so the node skips it",
+ "(deterministicmns.cpp:423) and the counter must not move. Without that list the tool",
+ "counts N and says it could not tell.",
+ "Epoch 3's stored missedProTxHashes is DELIBERATELY the display-order resolution (indices",
+ "13 and 12 read in display order are N and M), so the cross-check warning must fire there",
+ "and nowhere else."
+ ],
+ "members": {
+ "A": "01000000000000000000000000000000000000000000000000000000000000ff",
+ "B": "02000000000000000000000000000000000000000000000000000000000000ee",
+ "C": "03000000000000000000000000000000000000000000000000000000000000dd",
+ "D": "04000000000000000000000000000000000000000000000000000000000000cc",
+ "E": "05000000000000000000000000000000000000000000000000000000000000bb",
+ "F": "06000000000000000000000000000000000000000000000000000000000000aa",
+ "G": "0700000000000000000000000000000000000000000000000000000000000099",
+ "H": "0800000000000000000000000000000000000000000000000000000000000088",
+ "I": "0900000000000000000000000000000000000000000000000000000000000077",
+ "J": "0a00000000000000000000000000000000000000000000000000000000000066",
+ "K": "0b00000000000000000000000000000000000000000000000000000000000055",
+ "L": "0c00000000000000000000000000000000000000000000000000000000000044",
+ "M": "0d00000000000000000000000000000000000000000000000000000000000033",
+ "N": "0e00000000000000000000000000000000000000000000000000000000000022"
+ },
+ "epochs": [
+ {"epoch": 1, "boundaryHeight": 48, "status": "committed", "commitmentVersion": 2, "listSize": 14, "missedCount": 0, "missedIndices": [], "unobservedIndices": [], "missedProTxHashes": []},
+ {"epoch": 2, "boundaryHeight": 72, "status": "committed", "commitmentVersion": 1, "listSize": 14, "missedCount": 1, "missedIndices": [13], "missedProTxHashes": ["01000000000000000000000000000000000000000000000000000000000000ff"]},
+ {"epoch": 3, "boundaryHeight": 96, "status": "committed", "commitmentVersion": 2, "listSize": 14, "missedCount": 2, "missedIndices": [13, 12], "unobservedIndices": [], "missedProTxHashes": ["0e00000000000000000000000000000000000000000000000000000000000022", "0d00000000000000000000000000000000000000000000000000000000000033"]},
+ {"epoch": 4, "boundaryHeight": 120, "status": "committed", "commitmentVersion": 2, "listSize": 14, "missedCount": 1, "missedIndices": [13], "unobservedIndices": [12], "missedProTxHashes": ["01000000000000000000000000000000000000000000000000000000000000ff"]},
+ {"epoch": 5, "boundaryHeight": 144, "status": "committed", "commitmentVersion": 2, "listSize": 14, "missedCount": 1, "missedIndices": [13], "unobservedIndices": [], "missedProTxHashes": ["01000000000000000000000000000000000000000000000000000000000000ff"]},
+ {"epoch": 6, "boundaryHeight": 168, "status": "committed", "commitmentVersion": 2, "listSize": 14, "missedCount": 1, "missedIndices": [13], "unobservedIndices": [], "missedProTxHashes": ["01000000000000000000000000000000000000000000000000000000000000ff"]},
+ {"epoch": 7, "boundaryHeight": 192, "status": "absent", "commitmentVersion": null, "listSize": null, "missedCount": null, "missedIndices": [], "unobservedIndices": [], "missedProTxHashes": []},
+ {"epoch": 8, "boundaryHeight": 216, "status": "committed", "commitmentVersion": 2, "listSize": 14, "missedCount": 3, "missedIndices": [13, 12, 11], "unobservedIndices": [], "missedProTxHashes": ["01000000000000000000000000000000000000000000000000000000000000ff", "02000000000000000000000000000000000000000000000000000000000000ee", "03000000000000000000000000000000000000000000000000000000000000dd"]},
+ {"epoch": 9, "boundaryHeight": 240, "status": "committed", "commitmentVersion": 2, "listSize": 14, "missedCount": 1, "missedIndices": [12], "unobservedIndices": [], "missedProTxHashes": ["02000000000000000000000000000000000000000000000000000000000000ee"]},
+ {"epoch": 10, "boundaryHeight": 264, "status": "committed", "commitmentVersion": 2, "listSize": 15, "missedCount": 1, "missedIndices": [11], "unobservedIndices": [], "missedProTxHashes": []},
+ {"epoch": 11, "boundaryHeight": 288, "status": "committed", "commitmentVersion": 2, "listSize": 14, "missedCount": 1, "missedIndices": [0], "unobservedIndices": [], "missedProTxHashes": ["0e00000000000000000000000000000000000000000000000000000000000022"]}
+ ]
+}
diff --git a/ops/tests/test_dsl_enforcement_replay.py b/ops/tests/test_dsl_enforcement_replay.py
new file mode 100644
index 0000000..4131fb7
--- /dev/null
+++ b/ops/tests/test_dsl_enforcement_replay.py
@@ -0,0 +1,250 @@
+"""
+ops/dsl-enforcement-replay.py against a synthetic fourteen-masternode chain
+(fixtures/dsl-enforcement-replay-synthetic.json) built so that every branch of
+CDeterministicMNList::ApplyServiceCommitment runs at least once -- including the
+two no recorded devnet epoch has exercised: an UNOBSERVED verdict on a member
+whose missed streak is live, which must hold the counter rather than heal it, and
+a member removed from the list between the epoch base and the boundary, which the
+node skips (deterministicmns.cpp:423) and so must the tool.
+
+Fourteen members, not fewer: the first draft had six, where one missed
+masternode is already 16.7% of the list and the 15% mass-outage guard swallowed
+every epoch, so no counter ever moved. That is the guard doing its job on a
+fixture that was too small, and it is kept in the fixture's comment as the
+reason for the size.
+
+The fourteen proTxHashes sort in the opposite order by display hex and by the
+node's internal byte order, so a tool that sorts the display strings names the
+wrong masternode at every index. That is the bug the real-data validation
+caught on 2026-09-20 (five right heights, four wrong names); the fixture pins it.
+
+Real-data validation is not repeated here (the base lists are 13 MB): on
+2026-09-20 the tool reproduced the chain's own E1b events (suspended at 8496,
+banned at 8520, recovered at 8568, the five host-1 masternodes), the 2026-09-03
+shadow outage, the E2 guard at 23 of 152 and the 100-epoch baseline (nobody).
+The node's live counters agreed too (152 of 152), but every one of them was 0
+at that tip, so that comparison carried no weight -- it discriminates only on
+a snapshot taken while streaks are live.
+
+ python3 -m unittest discover -s ops/tests -p 'test_*.py' -v
+"""
+import importlib.util
+import json
+import os
+import unittest
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+SCRIPT = os.path.join(HERE, "..", "dsl-enforcement-replay.py")
+FIXTURE = os.path.join(HERE, "fixtures", "dsl-enforcement-replay-synthetic.json")
+
+spec = importlib.util.spec_from_file_location("dsl_enforcement_replay", SCRIPT)
+mod = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(mod)
+
+with open(FIXTURE, encoding="utf-8") as f:
+ FIX = json.load(f)
+
+M = FIX["members"]
+NAMES = "ABCDEFGHIJKLMN"
+A, B, C, N = M["A"], M["B"], M["C"], M["N"]
+DISPLAY_ORDER = [M[k] for k in NAMES]
+
+
+def base_for(epoch, members):
+ # base(k) = 24k, so base(k+1) is the list at epoch k's boundary block 24(k+1).
+ return {"epoch": epoch, "base": 24 * epoch,
+ "mnList": [{"proRegTxHash": h, "confirmedHash": "00" * 32, "isValid": True} for h in members]}
+
+
+BASES = {e: base_for(e, DISPLAY_ORDER) for e in range(1, 12)}
+# N's collateral is spent during epoch 11: the list at boundary 288 (= base 12) lacks it.
+BASES[12] = base_for(12, [h for h in DISPLAY_ORDER if h != N])
+BASE = BASES[1]
+
+
+def replay(enforce_from=1, upto=None, bases=None, enforce_from_height=None, **kw):
+ rows = [r for r in FIX["epochs"] if upto is None or r["epoch"] <= upto]
+ rp, skipped = mod.run(rows, BASES if bases is None else bases, enforce_from, enforce_from_height, **kw)
+ return rp, skipped
+
+
+class CanonicalOrder(unittest.TestCase):
+ def test_internal_byte_order_is_the_reverse_of_display_order_here(self):
+ order = mod.canonical_order(BASE["mnList"])
+ self.assertEqual(order, list(reversed(DISPLAY_ORDER)))
+ self.assertEqual(order[13], A)
+ self.assertEqual(order[0], N)
+ # The display-sorted order is what a naive tool would use; it must differ.
+ self.assertEqual(sorted(DISPLAY_ORDER), DISPLAY_ORDER)
+ self.assertNotEqual(sorted(DISPLAY_ORDER), order)
+
+ def test_internal_reverses_bytes(self):
+ self.assertEqual(mod.internal("00" * 31 + "ff"), b"\xff" + b"\x00" * 31)
+
+
+class Arithmetic(unittest.TestCase):
+ def test_the_full_story_with_enforcement(self):
+ rp, skipped = replay(enforce_from=1)
+ self.assertEqual(skipped, 0)
+ self.assertEqual([(e, k, p) for e, _, k, p in rp.events],
+ [(5, "suspended", A), (6, "banned", A), (9, "recovered", A)])
+ # The ban height is the boundary block of the epoch that reached the count.
+ self.assertEqual([h for _, h, k, _ in rp.events if k == "banned"], [168])
+ # Final state: A recovered; B missed once at epoch 9 and was online again at 11;
+ # nobody else touched (N's miss at 11 does not count: it had left the list).
+ self.assertEqual(rp.counter[A], 0)
+ self.assertEqual(rp.counter[B], 0)
+ self.assertEqual(replay(enforce_from=1, upto=9)[0].counter[B], 1)
+ self.assertEqual(rp.suspended, set())
+ self.assertEqual(rp.banned, {})
+ for k in NAMES[2:]:
+ self.assertEqual(rp.counter[M[k]], 0, k)
+
+ def test_counters_epoch_by_epoch(self):
+ # A: 1..5 through epochs 2-6; frozen through 7 (absent) and 8 (mass outage); 0 at 9.
+ for upto, want in {2: 1, 3: 2, 4: 3, 5: 4, 6: 5, 7: 5, 8: 5, 9: 0, 10: 0}.items():
+ rp, _ = replay(enforce_from=1, upto=upto)
+ self.assertEqual(rp.counter[A], want, "A after epoch %d" % upto)
+ # B: missed at 3 (1), UNOBSERVED at 4 while the streak is live -> still 1,
+ # online at 5 -> 0, mass outage at 8 -> still 0, missed at 9 -> 1.
+ for upto, want in {3: 1, 4: 1, 5: 0, 8: 0, 9: 1}.items():
+ rp, _ = replay(enforce_from=1, upto=upto)
+ self.assertEqual(rp.counter[B], want, "B after epoch %d" % upto)
+
+ def test_suspension_and_ban_land_on_the_right_epochs(self):
+ four, _ = replay(enforce_from=1, upto=5)
+ self.assertEqual(four.suspended, {A})
+ self.assertEqual(four.banned, {})
+ five, _ = replay(enforce_from=1, upto=6)
+ self.assertEqual(five.banned, {A: 168})
+
+ def test_v1_epoch_observes_everyone(self):
+ # Epoch 2 is format v1: no unobservedIndices field at all, and A's miss counts.
+ rp, _ = replay(enforce_from=1, upto=2)
+ self.assertEqual(rp.counter[A], 1)
+ self.assertEqual(rp.hold_protected, 0)
+
+ def test_shadow_counts_but_never_punishes(self):
+ rp, _ = replay(enforce_from=None)
+ self.assertEqual(rp.events, [])
+ self.assertEqual(rp.suspended, set())
+ self.assertEqual(rp.banned, {})
+ # The counters are the same as under enforcement: shadow mode counts too.
+ enforced, _ = replay(enforce_from=1)
+ self.assertEqual(dict(rp.counter), dict(enforced.counter))
+
+ def test_size_mismatch_is_skipped_with_a_warning(self):
+ rp, _ = replay(enforce_from=1)
+ self.assertTrue(any(w.startswith("epoch 10:") and "listSize" in w for w in rp.warnings))
+ # Nothing from epoch 10 leaked into the state: C (index 11) was never counted
+ # (epoch 8, its other miss, was a mass outage).
+ self.assertEqual(rp.counter[C], 0)
+ self.assertEqual([t[2] for t in rp.table if t[0] == 10], ["size-mismatch"])
+
+ def test_branch_coverage_is_reported(self):
+ rp, _ = replay(enforce_from=1)
+ self.assertEqual(rp.hold_protected, 1) # B at epoch 4
+ self.assertEqual(rp.mass_protected, 1) # A at epoch 8 (B and C had no streak there)
+ self.assertEqual(rp.absent_frozen, 1) # epoch 7 with A at 5
+ self.assertEqual(rp.removed_skipped, 1) # N at epoch 11
+
+
+class RemovedMember(unittest.TestCase):
+ """deterministicmns.cpp:423 -- a member of the base list that GetMN() no longer
+ finds at the boundary is skipped: no counter, no last-epoch stamp, no event."""
+
+ def test_a_member_removed_before_the_boundary_is_skipped(self):
+ rp, _ = replay(enforce_from=1)
+ self.assertEqual(rp.counter[N], 0) # missed at 11, but gone from the list at 288
+ self.assertEqual(rp.last_epoch.get(N), 9) # 10 was skipped whole; 11 never touched N
+ self.assertEqual(rp.removed_skipped, 1)
+ self.assertFalse(any("no list at the boundary" in w for w in rp.warnings))
+
+ def test_without_the_boundary_list_the_member_is_counted_and_the_run_says_so(self):
+ # NEGATIVE CONTROL: drop base 12 and the skip cannot happen; the tool must count N
+ # (the old behaviour) and say that it could not tell.
+ bases = {e: b for e, b in BASES.items() if e != 12}
+ rp, _ = replay(enforce_from=1, bases=bases)
+ self.assertEqual(rp.counter[N], 1)
+ self.assertEqual(rp.removed_skipped, 0)
+ self.assertEqual([w for w in rp.warnings if "no list at the boundary" in w],
+ ["epoch 11: no list at the boundary 288 (the next epoch's base): "
+ "a member removed during the epoch would be counted"])
+
+ def test_a_next_list_at_the_wrong_height_is_not_used(self):
+ bases = dict(BASES)
+ bases[12] = dict(BASES[12], base=289)
+ rp, _ = replay(enforce_from=1, bases=bases)
+ self.assertEqual(rp.counter[N], 1)
+ self.assertTrue(any(w.startswith("epoch 11: no list at the boundary 288") for w in rp.warnings))
+
+
+class EnforceByHeight(unittest.TestCase):
+ """The node enforces when the boundary block's height >= nDSLEnforcementHeight
+ (deterministicmns.cpp:419); the height flag must follow that rule exactly."""
+
+ def test_the_boundary_block_itself_enforces(self):
+ by_height, _ = replay(enforce_from=None, enforce_from_height=168) # epoch 6's boundary
+ by_epoch, _ = replay(enforce_from=6)
+ self.assertEqual(by_height.events, by_epoch.events)
+ self.assertEqual([(e, k) for e, _, k, p in by_height.events if p == A],
+ [(6, "suspended"), (6, "banned"), (9, "recovered")])
+
+ def test_one_block_later_misses_that_epoch(self):
+ # From 169: epoch 7 is absent, 8 a mass outage, and at 9 A is online without
+ # ever having been suspended -- so no event at all, and the counters unchanged.
+ rp, _ = replay(enforce_from=None, enforce_from_height=169)
+ self.assertEqual(rp.events, [])
+ # The counters do not depend on where enforcement starts.
+ self.assertEqual(dict(rp.counter), dict(replay(enforce_from=1)[0].counter))
+
+
+class CrossCheck(unittest.TestCase):
+ def test_display_order_stored_list_is_flagged(self):
+ # Epoch 3's stored list was built with display-order resolution on purpose.
+ rp, _ = replay(enforce_from=1)
+ flagged = [w for w in rp.warnings if "differ" in w]
+ self.assertEqual(flagged, ["epoch 3: stored missedProTxHashes differ from index resolution"])
+ # And the wrong stored names did not leak into the arithmetic: N and M stay clean.
+ self.assertEqual(rp.counter[N], 0)
+ self.assertEqual(rp.counter[M["M"]], 0)
+
+
+class NegativeControls(unittest.TestCase):
+ """Each control flips one rule and must change the answer; a control that leaves
+ the answer unchanged would mean that rule is dead in the tool."""
+
+ def test_unobserved_treated_as_online_heals_the_streak(self):
+ held, _ = replay(enforce_from=1, upto=4)
+ healed, _ = replay(enforce_from=1, upto=4, hold_unobserved=False)
+ self.assertEqual(held.counter[B], 1)
+ self.assertEqual(healed.counter[B], 0)
+ self.assertEqual(held.hold_protected, 1)
+ self.assertEqual(healed.hold_protected, 0)
+
+ def test_guard_raised_lets_the_mass_outage_epoch_apply(self):
+ guarded, _ = replay(enforce_from=1, upto=8)
+ unguarded, _ = replay(enforce_from=1, upto=8, mass_outage_pct=40)
+ # With the guard, epoch 8 changed nothing: A stays at 5, B and C at 0.
+ self.assertEqual((guarded.counter[A], guarded.counter[B], guarded.counter[C]), (5, 0, 0))
+ # Without it, all three misses count.
+ self.assertEqual((unguarded.counter[A], unguarded.counter[B], unguarded.counter[C]), (6, 1, 1))
+ self.assertEqual(guarded.mass_protected, 1)
+ self.assertEqual(unguarded.mass_protected, 0)
+
+ def test_thresholds_move_the_events(self):
+ rp, _ = replay(enforce_from=1, suspend=2, ban=3)
+ self.assertEqual([(e, k) for e, _, k, p in rp.events if p == A][:2], [(3, "suspended"), (4, "banned")])
+
+ def test_enforcing_later_moves_the_events_but_not_the_counters(self):
+ late, _ = replay(enforce_from=6)
+ early, _ = replay(enforce_from=1)
+ self.assertEqual(dict(late.counter), dict(early.counter))
+ # Enforcement starting at epoch 6 finds A already at count 5: suspended and banned
+ # in the same epoch, recovered at 9.
+ self.assertEqual([(e, k) for e, _, k, p in late.events if p == A],
+ [(6, "suspended"), (6, "banned"), (9, "recovered")])
+
+
+if __name__ == "__main__":
+ unittest.main()