feat(restore): snapshot bootstrap + genesis-baked validators + consensus shard enforcement

.gitignore

@@ -9,7 +9,14 @@ dist/
 output/
 *.db
 *.sqlite3
-data/
+# Ignore everything in `data/` (runtime DBs, chain blobs, l2ps state, ...)
+# EXCEPT the committed state-restore snapshot under `data/snapshot/`.
+# The negation works because we use `data/*` (not `data/`) — `data/` with
+# trailing slash refuses to recurse, so any `!data/...` rule would be
+# ignored. The raw `.snapshot-restore/` source dump (213 MB uncompressed)
+# is NOT committed — see entry near the bottom.
+data/*
+!data/snapshot/
 docker_data/
 postgres_*/
 neo4j_data/
@@ -188,3 +195,8 @@ yarn.lock
 ISSUES.md
 PR_RAW.md
 .git.broken-2026-05-13
+# Raw pg_dump source for the state-restore snapshot (213 MB uncompressed).
+# Transform output lives in `data/snapshot/` and IS committed; this dir is
+# the local-only source-of-truth fed into `bun snapshot:transform`.
+.snapshot-restore/
+.test-identity/

data/genesis.json

@@ -7,36 +7,50 @@
   "mutables": {
       "minBlocksForValidationOnlineStatus": 4
   },
-  "balances": [
-      [
-          "0x10bf4da38f753d53d811bcad22e0d6daa99a82f0ba0dbbee59830383ace2420c",
-          "1000000000000000000"
-      ],
-      [
-          "0x51322c62dcefdcc19a6f2a556a015c23ecb0ffeeb8b13c47e7422974616ff4ab",
-          "1000000000000000000"
-      ],
-      [
-          "0xf7a1c3417e39563ca8f63f2e9a9ba08890888695768e95e22026e6f942addf23",
-          "1000000000000000000"
-      ],
-      [
-          "0x3e0d0c734d52540842e104c6a3fc2316453adda9b6042492e74da9687ecc8caa",
-          "1000000000000000000"
-      ],
-      [
-          "0xbf5a666b92751be3e1731bb7be6551ff66fab39c796bc8f26ffaff83fc553b15",
-          "1000000000000000000"
-      ],
-      [
-          "0x6d06e0cbf2c245aa86f4b7416cb999e434ffc66d92fa40b67f721712592b4aac",
-          "1000000000000000000"
-      ],
-      [
-          "0xe2e3d3446aa2abc62f085ab82a3f459e817c8cc8b56c443409723b7a829a08c2",
-          "1000000000000000000"
-      ]
-  ],
+  "forks": {
+      "osDenomination": {
+          "activationHeight": null
+      },
+      "gasFeeSeparation": {
+          "activationHeight": null,
+          "treasuryAddress": "0xf7a1c3417e39563ca8f63f2e9a9ba08890888695768e95e22026e6f942addf23"
+      }
+  },
+  "balances": [],
   "timestamp": "1692734616",
-  "status": "confirmed"
-}
+  "status": "confirmed",
+  "validators": [
+      {
+          "address": "0xc8bc5866fecf583bc1232f04fa54fd2c5a6f7c15b91c517ac60f468cdc0b8c82",
+          "status": "2",
+          "connection_url": "https://node2.demos.sh",
+          "staked_amount": "1000000000000000000",
+          "first_seen": 0,
+          "valid_at": 0
+      },
+      {
+          "address": "0x24c664d9ef529f798e979357c6a7a01088226eefe05cfdb77fb42841f771e156",
+          "status": "2",
+          "connection_url": "https://node3.demos.sh",
+          "staked_amount": "1000000000000000000",
+          "first_seen": 0,
+          "valid_at": 0
+      },
+      {
+          "address": "0x62f54cefb244538498b18687dbbb7faeb607b9ea51e8d9bcb952fd038b89ece9",
+          "status": "2",
+          "connection_url": null,
+          "staked_amount": "1000000000000000000",
+          "first_seen": 0,
+          "valid_at": 0
+      },
+      {
+          "address": "0xe6313748a6bbd8e0ebdb578ca0df5f050711819c8dba291930969f72a7f5cdac",
+          "status": "2",
+          "connection_url": null,
+          "staked_amount": "1000000000000000000",
+          "first_seen": 0,
+          "valid_at": 0
+      }
+  ]
+}

data/snapshot/manifest.json

@@ -0,0 +1,32 @@
+{
+  "schemaVersion": 1,
+  "source": {
+    "host": "node3.demos.sh",
+    "chain_block_height": 2285755,
+    "chain_block_hash": "3c6a0b81e4cc8fdd44719f79f5f71938e75f465802f312c4fb475886a36b8338",
+    "node_version": "0.9.8",
+    "pg_version": "17.0",
+    "dumped_at": "2026-05-19T15:22:00Z"
+  },
+  "files": {
+    "gcr_main.jsonl": {
+      "sha256": "b50513ce9632c5460a608d29cc0f4593cbb961bcf585a017323100a9bef10b55",
+      "rows": 13880,
+      "balance_sum": "15024999999998868586"
+    },
+    "gcr_storageprogram.jsonl": {
+      "sha256": "30f6f31243b77c66c25cadf5523c251a7aada7e858b669288f5c6b53cd11ee9f",
+      "rows": 1382,
+      "size_bytes_sum": 1269189
+    },
+    "identity_commitments.jsonl": {
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+      "rows": 0
+    }
+  },
+  "transforms_applied": {
+    "nonces_reset_to_zero": true,
+    "assigned_txs_emptied": true,
+    "test_identity_commitments_dropped": 1
+  }
+}

forking/RUNBOOK_FORK_ACTIVATION.md

@@ -4,6 +4,10 @@
 **Scope**: Single coordinated activation of the two bundled hard forks `osDenomination` (DEM → OS denomination, ×10⁹) AND `gasFeeSeparation` (DEM-665 — three-component fee + burn/treasury/rpc-operator distribution) at the same `activationHeight`.
 **Status**: Operational. Read end-to-end before fork day.
 
+> **Prerequisite — chain-wipe fork only**: When this runbook is executed against a freshly-wiped chain (rather than activating in-place), operators must first restore historical state via the snapshot-restore flow. See [`forking/restore/RUNBOOK.md`](restore/RUNBOOK.md) and [`forking/restore/PLAN.md`](restore/PLAN.md). The restore is automatic on the first `./run` against an empty PG when `data/snapshot/` is present.
+>
+> **Production environments**: set `DEMOS_REQUIRE_VALIDATORS=true` in the node's env. As of epic #17, `getShard()` enforces the genesis-baked validator set at the consensus layer. With the env var set, a node booting against an empty/non-active validators table refuses to operate (loud error) instead of silently falling back to permissive online-peer-only shard selection.
+
 ---
 
 ## 0. TL;DR