chaindiff 0.1.0__tar.gz → 0.2.0__tar.gz

{chaindiff-0.1.0/src/chaindiff.egg-info → chaindiff-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chaindiff
-Version: 0.1.0
+Version: 0.2.0
 Summary: Decide whether an Ethereum node client upgrade is safe.
 Author: ehsanhajian
 License-Expression: MIT
@@ -64,7 +64,7 @@ The shipping catalog is Ethereum mainnet. The tool also covers these networks, o
 - zkSync Era
 - Starknet
 
-Not in this cut: Lodestar, Grandine, applying the upgrade, node metrics, peer or disk checks, and RPC benchmarks. Configuration scanning and execution/consensus pairing are tracked as later work. They need sourced rules, not guesses.
+Not in this cut: Lodestar, Grandine, applying the upgrade, node metrics, peer or disk checks, and RPC benchmarks. A general execution and consensus pair report is later work. `check --network ethereum` compares the two clients you run with the next mainnet upgrade. `scan` reads a config file you already have and compares it with sourced flag rules. A setting with no rule is reported as not covered. It is not called safe.
 
 Calendar-versioned clients (Besu, Teku, Nimbus) do not treat a new year in the version as a breaking change by itself. Semver clients do: an unreviewed major bump is **not safe**.
 
@@ -74,22 +74,42 @@ Calendar-versioned clients (Besu, Teku, Nimbus) do not treat a new year in the v
 pip install chaindiff
 ```
 
-That package is published from a GitHub release. Until the first release is on PyPI:
-
-```bash
-pip install git+https://github.com/ehsanhajian/chaindiff.git
-```
+That package is published from a GitHub release.
 
 ## Commands
 
 ```bash
 chaindiff versions
+chaindiff detect --client geth --binary /usr/bin/geth
+chaindiff detect --client lighthouse --image sigp/lighthouse:v8.2.3
 chaindiff check --client geth --from <installed>
 chaindiff check --client lighthouse --from <installed> --to v8.2.3
+chaindiff check --network ethereum --execution geth --execution-version <installed> --consensus lighthouse --consensus-version <installed>
 chaindiff plan --client nethermind --from <installed>
+chaindiff scan --client geth --from <installed> --to <target> --config <file>
 chaindiff refresh
 ```
 
+`check`, `plan`, `scan`, and `detect` read the client binary. Use them for a mainnet node or a testnet node. A Sepolia Geth upgrade is the same command as a mainnet one. A release note that names a testnet deadline is included when that release is in the range.
+
+`detect` reads the version from a client binary, or from a Docker image tag. It does not pull or start an image, and it does not run `check`. Geth is asked with `version`. The other clients are asked with `--version`. Prysm's binary is `beacon-chain` or `validator`.
+
+When the output or the tag is one precise release, `detect` prints that version and the `check` command. A tag such as `1.17` is not treated as `1.17.0`. `latest`, `stable`, `nightly`, and the other channel names are not versions. If the binary fails, the tag is not a release, or more than one version appears, it prints:
+
+```bash
+chaindiff check --client geth --from <installed>
+```
+
+Exit 0 means a version was read. Exit 1 means it was not. Exit 3 means the client is unknown.
+
+`check --network ethereum` asks whether the execution client and the consensus client you run are the versions the next mainnet upgrade requires, and whether an upgrade order is stated. The schedule is `src/chaindiff/data/networks/ethereum.json`, taken from the network announcement. A Sepolia date in that announcement is not a mainnet deadline. No required mainnet version is invented from a testnet table.
+
+**Already current** means both clients are the announced requirement and the mainnet time is set. **Review required** means a required version or the activation time has not been announced, or the installed version is newer than the announcement. **Not safe** means an installed version is older than an announced requirement. A prerelease is still refused on mainnet.
+
+`scan` accepts CLI flags, TOML, JSON, or YAML. The format follows the file extension (`.toml`, `.json`, `.yaml`, `.yml`). A file of command-line flags has no extension requirement. `--format cli|toml|json|yaml` overrides that. `--to` defaults to the latest stable release. The command prints what to change. It does not edit the file.
+
+Exit 2 means a setting in the file was removed or renamed. Exit 1 means a default changed, a setting is deprecated, or the catalog does not cover a setting. Exit 0 means every setting is covered and none of those changes apply. A stale catalog cannot return exit 0 for `latest`.
+
 `check` and `plan` use the local catalog. `refresh` is the only command that talks to GitHub. Set `GH_TOKEN` or `GITHUB_TOKEN` if you hit the unauthenticated rate limit.
 
 ### Verdicts
@@ -134,6 +154,56 @@ Safe and not-safe both require a review. Put reviews in `src/chaindiff/data/advi
 
 `severity` is `breaking`, `deprecated`, `note`, or `none`. `none` means the release was reviewed and there is nothing to do. `breaking` and `deprecated` need an `action`. Every advisory needs an `http` or `https` source. Do not mark a release reviewed without reading it.
 
+## Flag rules
+
+`scan` uses `src/chaindiff/data/flags/<client>.json`. A missing file means the catalog covers nothing for that client.
+
+```json
+{
+  "schema_version": 1,
+  "rules": [
+    {
+      "version": "1.17.4",
+      "flag": "txlookuplimit",
+      "effect": "removed",
+      "action": "Drop the flag.",
+      "source": "https://github.com/ethereum/go-ethereum/releases/tag/v1.17.4"
+    }
+  ]
+}
+```
+
+`effect` is `removed`, `renamed`, `deprecated`, or `default`. `renamed` also needs `replacement`. Every rule needs an action and an `http` or `https` source. `flag` is the key the operator set: a CLI name without the leading dashes, or a dotted path such as `JsonRpc.Enabled`. Dashes and underscores match dots. A rule may list `values`. It then matches only when the file sets the key to one of those values, so a new valid value is left alone.
+
+A rule applies when its version is after `--from` and at or before `--to`. Removed, renamed, and deprecated rules are reported when the file sets that key. A `default` rule is reported when the file does not set it. The same key outside that range is covered, and it is not listed as a change.
+
+## Networks
+
+`check --network` reads `src/chaindiff/data/networks/<network>.json`:
+
+```json
+{
+  "schema_version": 1,
+  "id": "ethereum",
+  "name": "Ethereum mainnet",
+  "upgrade": {
+    "name": "Glamsterdam",
+    "activation": null,
+    "source": "https://blog.ethereum.org/2026/09/17/glamsterdam-testnet-announcement",
+    "summary": "What the announcement says about mainnet.",
+    "order": null,
+    "order_summary": "What the announcement says about upgrade order.",
+    "warning": "A date or table the operator must not treat as the mainnet requirement.",
+    "required": {
+      "execution": {},
+      "consensus": {}
+    }
+  }
+}
+```
+
+`activation` is an ISO time, or `null` when mainnet is not scheduled. `order` is `execution-first`, `consensus-first`, or `null`. `required` maps a client id to a `major.minor.patch` version from the announcement. An empty map means that role has no announced requirement. Do not fill it from a testnet table.
+
 ## Development
 
 ```bash
@@ -143,4 +213,4 @@ pip install -e ".[dev]"
 pytest
 ```
 
-Tests that need a private catalog can set `CHAINDIFF_DATA` to a directory with the same `clients.json`, `releases/`, and `advisories/` layout.
+Tests that need a private catalog can set `CHAINDIFF_DATA` to a directory with the same `clients.json`, `releases/`, `advisories/`, and `flags/` layout.

chaindiff-0.2.0/README.md

@@ -0,0 +1,191 @@
+# ChainDiff
+
+Decide whether an Ethereum node client upgrade is safe.
+
+ChainDiff compares the client you run with the release you want. It answers **safe** only when every release in between has a sourced review and none of those reviews is breaking. Otherwise the answer is **review required** or **not safe**.
+
+It does not restart a node, edit config, or apply an upgrade.
+
+## Scope
+
+Supported clients:
+
+| Client | Role | Release source |
+| --- | --- | --- |
+| Geth | execution | ethereum/go-ethereum |
+| Nethermind | execution | NethermindEth/nethermind |
+| Erigon | execution | erigontech/erigon |
+| Besu | execution | besu-eth/besu |
+| Reth | execution | paradigmxyz/reth |
+| Lighthouse | consensus | sigp/lighthouse |
+| Prysm | consensus | OffchainLabs/prysm |
+| Teku | consensus | Consensys-Incorporated/teku |
+| Nimbus | consensus | status-im/nimbus-eth2 |
+
+Reth and Nimbus are in the catalog because operators run them. Besu and Teku are read from their current GitHub repositories.
+
+The shipping catalog is Ethereum mainnet. The tool also covers these networks, one task each. A check has to use the clients that network actually runs, and that chain's upgrade, not only the latest tag of an upstream Ethereum client.
+
+- Ethereum mainnet
+- Gnosis
+- BNB Smart Chain
+- Avalanche
+- OP Mainnet
+- Base
+- Arbitrum One
+- Polygon PoS
+- Linea
+- Scroll
+- zkSync Era
+- Starknet
+
+Not in this cut: Lodestar, Grandine, applying the upgrade, node metrics, peer or disk checks, and RPC benchmarks. A general execution and consensus pair report is later work. `check --network ethereum` compares the two clients you run with the next mainnet upgrade. `scan` reads a config file you already have and compares it with sourced flag rules. A setting with no rule is reported as not covered. It is not called safe.
+
+Calendar-versioned clients (Besu, Teku, Nimbus) do not treat a new year in the version as a breaking change by itself. Semver clients do: an unreviewed major bump is **not safe**.
+
+## Install
+
+```bash
+pip install chaindiff
+```
+
+That package is published from a GitHub release.
+
+## Commands
+
+```bash
+chaindiff versions
+chaindiff detect --client geth --binary /usr/bin/geth
+chaindiff detect --client lighthouse --image sigp/lighthouse:v8.2.3
+chaindiff check --client geth --from <installed>
+chaindiff check --client lighthouse --from <installed> --to v8.2.3
+chaindiff check --network ethereum --execution geth --execution-version <installed> --consensus lighthouse --consensus-version <installed>
+chaindiff plan --client nethermind --from <installed>
+chaindiff scan --client geth --from <installed> --to <target> --config <file>
+chaindiff refresh
+```
+
+`check`, `plan`, `scan`, and `detect` read the client binary. Use them for a mainnet node or a testnet node. A Sepolia Geth upgrade is the same command as a mainnet one. A release note that names a testnet deadline is included when that release is in the range.
+
+`detect` reads the version from a client binary, or from a Docker image tag. It does not pull or start an image, and it does not run `check`. Geth is asked with `version`. The other clients are asked with `--version`. Prysm's binary is `beacon-chain` or `validator`.
+
+When the output or the tag is one precise release, `detect` prints that version and the `check` command. A tag such as `1.17` is not treated as `1.17.0`. `latest`, `stable`, `nightly`, and the other channel names are not versions. If the binary fails, the tag is not a release, or more than one version appears, it prints:
+
+```bash
+chaindiff check --client geth --from <installed>
+```
+
+Exit 0 means a version was read. Exit 1 means it was not. Exit 3 means the client is unknown.
+
+`check --network ethereum` asks whether the execution client and the consensus client you run are the versions the next mainnet upgrade requires, and whether an upgrade order is stated. The schedule is `src/chaindiff/data/networks/ethereum.json`, taken from the network announcement. A Sepolia date in that announcement is not a mainnet deadline. No required mainnet version is invented from a testnet table.
+
+**Already current** means both clients are the announced requirement and the mainnet time is set. **Review required** means a required version or the activation time has not been announced, or the installed version is newer than the announcement. **Not safe** means an installed version is older than an announced requirement. A prerelease is still refused on mainnet.
+
+`scan` accepts CLI flags, TOML, JSON, or YAML. The format follows the file extension (`.toml`, `.json`, `.yaml`, `.yml`). A file of command-line flags has no extension requirement. `--format cli|toml|json|yaml` overrides that. `--to` defaults to the latest stable release. The command prints what to change. It does not edit the file.
+
+Exit 2 means a setting in the file was removed or renamed. Exit 1 means a default changed, a setting is deprecated, or the catalog does not cover a setting. Exit 0 means every setting is covered and none of those changes apply. A stale catalog cannot return exit 0 for `latest`.
+
+`check` and `plan` use the local catalog. `refresh` is the only command that talks to GitHub. Set `GH_TOKEN` or `GITHUB_TOKEN` if you hit the unauthenticated rate limit.
+
+### Verdicts
+
+- **ALREADY CURRENT** (exit 0) — you are on the target release.
+- **SAFE** (exit 0) — every release in the range has a sourced review, and none is breaking.
+- **REVIEW REQUIRED** (exit 1) — ChainDiff will not call it safe. Releases are missing a review, something is deprecated, or the catalog is too old to trust "latest".
+- **NOT SAFE** (exit 2) — a reviewed breaking change, or an unreviewed semver major bump.
+- **PRERELEASE** (exit 2) — the target is a prerelease. Don't run it on a mainnet node.
+- **DOWNGRADE** (exit 2) — the target is older than what you run.
+
+A stale catalog (older than 5 days) cannot produce **safe** or **already current** for `latest`. Comparing two explicit versions still works; the report warns that the catalog is old.
+
+The checklist always includes the operator steps that are worth doing on any upgrade: read the notes, back up, keep the old binary, upgrade one client at a time, and roll back if the node fails. Client-specific steps appear only when an advisory says what to change.
+
+## Release catalog
+
+GitHub Actions refreshes the catalog twice a week, Monday and Thursday at 06:15 UTC, and commits it when the run succeeds. Run `chaindiff refresh` yourself any time.
+
+Erigon tags from the old date scheme, such as `v2022.10.01`, are left out. They are not comparable with the 2.x and 3.x line, and treating them as newer versions would hide the current release.
+
+The stored catalog is tags, dates, titles, and URLs. It does not copy release-note bodies. A release title that mentions a security fix is reported as a warning. That warning does not by itself make the upgrade safe or unsafe.
+
+## Advisories
+
+Safe and not-safe both require a review. Put reviews in `src/chaindiff/data/advisories/<client>.json`:
+
+```json
+{
+  "schema_version": 1,
+  "advisories": [
+    {
+      "version": "2.0.0",
+      "severity": "breaking",
+      "summary": "What breaks.",
+      "action": "What the operator changes.",
+      "source": "https://github.com/org/repo/releases/tag/2.0.0"
+    }
+  ]
+}
+```
+
+`severity` is `breaking`, `deprecated`, `note`, or `none`. `none` means the release was reviewed and there is nothing to do. `breaking` and `deprecated` need an `action`. Every advisory needs an `http` or `https` source. Do not mark a release reviewed without reading it.
+
+## Flag rules
+
+`scan` uses `src/chaindiff/data/flags/<client>.json`. A missing file means the catalog covers nothing for that client.
+
+```json
+{
+  "schema_version": 1,
+  "rules": [
+    {
+      "version": "1.17.4",
+      "flag": "txlookuplimit",
+      "effect": "removed",
+      "action": "Drop the flag.",
+      "source": "https://github.com/ethereum/go-ethereum/releases/tag/v1.17.4"
+    }
+  ]
+}
+```
+
+`effect` is `removed`, `renamed`, `deprecated`, or `default`. `renamed` also needs `replacement`. Every rule needs an action and an `http` or `https` source. `flag` is the key the operator set: a CLI name without the leading dashes, or a dotted path such as `JsonRpc.Enabled`. Dashes and underscores match dots. A rule may list `values`. It then matches only when the file sets the key to one of those values, so a new valid value is left alone.
+
+A rule applies when its version is after `--from` and at or before `--to`. Removed, renamed, and deprecated rules are reported when the file sets that key. A `default` rule is reported when the file does not set it. The same key outside that range is covered, and it is not listed as a change.
+
+## Networks
+
+`check --network` reads `src/chaindiff/data/networks/<network>.json`:
+
+```json
+{
+  "schema_version": 1,
+  "id": "ethereum",
+  "name": "Ethereum mainnet",
+  "upgrade": {
+    "name": "Glamsterdam",
+    "activation": null,
+    "source": "https://blog.ethereum.org/2026/09/17/glamsterdam-testnet-announcement",
+    "summary": "What the announcement says about mainnet.",
+    "order": null,
+    "order_summary": "What the announcement says about upgrade order.",
+    "warning": "A date or table the operator must not treat as the mainnet requirement.",
+    "required": {
+      "execution": {},
+      "consensus": {}
+    }
+  }
+}
+```
+
+`activation` is an ISO time, or `null` when mainnet is not scheduled. `order` is `execution-first`, `consensus-first`, or `null`. `required` maps a client id to a `major.minor.patch` version from the announcement. An empty map means that role has no announced requirement. Do not fill it from a testnet table.
+
+## Development
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+Tests that need a private catalog can set `CHAINDIFF_DATA` to a directory with the same `clients.json`, `releases/`, `advisories/`, and `flags/` layout.

{chaindiff-0.1.0 → chaindiff-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "chaindiff"
-version = "0.1.0"
+version = "0.2.0"
 description = "Decide whether an Ethereum node client upgrade is safe."
 readme = "README.md"
 license = "MIT"
@@ -39,7 +39,7 @@ build-backend = "setuptools.build_meta"
 where = ["src"]
 
 [tool.setuptools.package-data]
-chaindiff = ["data/*.json", "data/releases/*.json", "data/advisories/*.json"]
+chaindiff = ["data/*.json", "data/releases/*.json", "data/advisories/*.json", "data/flags/*.json", "data/networks/*.json"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{chaindiff-0.1.0 → chaindiff-0.2.0}/src/chaindiff/__init__.py

@@ -1,3 +1,3 @@
 """Decide whether an Ethereum node client upgrade is safe."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

chaindiff-0.2.0/src/chaindiff/catalog.py

@@ -0,0 +1,321 @@
+"""Load and store the client registry, release catalog, and advisories."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+from chaindiff.configparse import normalize_flag
+from chaindiff.models import FLAG_EFFECTS, SEVERITIES, Advisory, Client, FlagRule, NetworkSchedule, Release
+from chaindiff.versions import Version, parse_version
+
+SCHEMA_VERSION = 1
+_NETWORK_ORDERS = ("execution-first", "consensus-first")
+_PRECISE_RELEASE = re.compile(r"v?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$")
+
+
+def data_dir() -> Path:
+    override = os.environ.get("CHAINDIFF_DATA")
+    if override:
+        return Path(override)
+    return Path(__file__).resolve().parent / "data"
+
+
+def format_time(moment: datetime) -> str:
+    return moment.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def parse_time(value: str) -> datetime:
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def _read_json(path: Path) -> dict:
+    try:
+        payload = json.loads(path.read_text())
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{path} is not valid JSON") from exc
+    if not isinstance(payload, dict):
+        raise ValueError(f"{path} must contain a JSON object")
+    if payload.get("schema_version") != SCHEMA_VERSION:
+        raise ValueError(f"{path} has an unsupported schema_version")
+    return payload
+
+
+def load_clients() -> list[Client]:
+    path = data_dir() / "clients.json"
+    payload = _read_json(path)
+    clients: list[Client] = []
+    seen: set[str] = set()
+    for raw in payload.get("clients", []):
+        client_id = str(raw.get("id", "")).strip()
+        role = raw.get("role")
+        versioning = raw.get("versioning")
+        github = str(raw.get("github", "")).strip()
+        name = str(raw.get("name", "")).strip()
+        if not client_id or not name or not github:
+            raise ValueError(f"{path} has a client missing id, name, or github")
+        if role not in ("execution", "consensus"):
+            raise ValueError(f"{client_id} has an unknown role")
+        if versioning not in ("semver", "calver"):
+            raise ValueError(f"{client_id} has an unknown versioning scheme")
+        if client_id in seen:
+            raise ValueError(f"{client_id} is listed twice")
+        seen.add(client_id)
+        clients.append(
+            Client(
+                id=client_id,
+                name=name,
+                role=role,
+                github=github,
+                versioning=versioning,
+            )
+        )
+    if not clients:
+        raise ValueError(f"{path} does not list any clients")
+    return clients
+
+
+def client_by_id(clients: list[Client], client_id: str) -> Client | None:
+    key = client_id.strip().lower()
+    for client in clients:
+        if client.id == key:
+            return client
+    return None
+
+
+def releases_path(client_id: str) -> Path:
+    return data_dir() / "releases" / f"{client_id}.json"
+
+
+def load_releases(client_id: str) -> tuple[datetime, list[Release]] | None:
+    path = releases_path(client_id)
+    if not path.exists():
+        return None
+    payload = _read_json(path)
+    fetched_at = parse_time(str(payload["fetched_at"]))
+    releases: list[Release] = []
+    for raw in payload.get("releases", []):
+        tag = str(raw.get("tag", ""))
+        version = parse_version(tag)
+        if version is None:
+            continue
+        releases.append(
+            Release(
+                tag=tag,
+                name=str(raw.get("name") or tag),
+                published_at=str(raw.get("published_at") or ""),
+                prerelease=bool(raw.get("prerelease")),
+                url=str(raw.get("url") or ""),
+                version=version,
+            )
+        )
+    return fetched_at, releases
+
+
+def save_releases(
+    client: Client,
+    releases: list[Release],
+    ignored_tag_count: int,
+    fetched_at: datetime,
+) -> None:
+    path = releases_path(client.id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    ordered = sorted(releases, key=lambda item: (item.version, item.published_at, item.tag), reverse=True)
+    payload = {
+        "schema_version": SCHEMA_VERSION,
+        "client": client.id,
+        "github": client.github,
+        "fetched_at": format_time(fetched_at),
+        "ignored_tag_count": ignored_tag_count,
+        "releases": [
+            {
+                "tag": item.tag,
+                "name": item.name,
+                "published_at": item.published_at,
+                "prerelease": item.prerelease,
+                "url": item.url,
+            }
+            for item in ordered
+        ],
+    }
+    text = json.dumps(payload, indent=2) + "\n"
+    temporary = path.with_suffix(".json.tmp")
+    temporary.write_text(text)
+    temporary.replace(path)
+
+
+def load_advisories(client_id: str) -> list[Advisory]:
+    path = data_dir() / "advisories" / f"{client_id}.json"
+    if not path.exists():
+        return []
+    payload = _read_json(path)
+    advisories: list[Advisory] = []
+    for index, raw in enumerate(payload.get("advisories", []), start=1):
+        version_text = str(raw.get("version", "")).strip()
+        version = parse_version(version_text)
+        severity = str(raw.get("severity", "")).strip()
+        summary = str(raw.get("summary", "")).strip()
+        action = str(raw.get("action", "")).strip()
+        source = str(raw.get("source", "")).strip()
+        where = f"{path} advisory {index} ({version_text or 'missing version'})"
+        if version is None:
+            raise ValueError(f"{where} has a version ChainDiff cannot parse")
+        if severity not in SEVERITIES:
+            raise ValueError(f"{where} has an unknown severity")
+        if not summary:
+            raise ValueError(f"{where} needs a summary")
+        if severity in ("breaking", "deprecated") and not action:
+            raise ValueError(f"{where} needs an action")
+        if not source.startswith(("https://", "http://")):
+            raise ValueError(f"{where} needs an http(s) source URL")
+        advisories.append(
+            Advisory(
+                version=version,
+                severity=severity,
+                summary=summary,
+                action=action,
+                source=source,
+            )
+        )
+    return advisories
+
+
+def load_flag_rules(client_id: str) -> list[FlagRule]:
+    path = data_dir() / "flags" / f"{client_id}.json"
+    if not path.exists():
+        return []
+    payload = _read_json(path)
+    rules: list[FlagRule] = []
+    for index, raw in enumerate(payload.get("rules", []), start=1):
+        if not isinstance(raw, dict):
+            raise ValueError(f"{path} rule {index} must be an object")
+        version_text = str(raw.get("version", "")).strip()
+        version = parse_version(version_text)
+        flag = str(raw.get("flag", "")).strip().removeprefix("--")
+        effect = str(raw.get("effect", "")).strip()
+        action = str(raw.get("action", "")).strip()
+        source = str(raw.get("source", "")).strip()
+        replacement = str(raw.get("replacement", "")).strip().removeprefix("--")
+        raw_values = raw.get("values", [])
+        where = f"{path} rule {index} ({flag or version_text or 'missing flag'})"
+        if version is None:
+            raise ValueError(f"{where} has a version ChainDiff cannot parse")
+        if effect not in FLAG_EFFECTS:
+            raise ValueError(f"{where} has an unknown effect")
+        if normalize_flag(flag) == "":
+            raise ValueError(f"{where} needs a flag")
+        if not action:
+            raise ValueError(f"{where} needs an action")
+        if effect == "renamed" and normalize_flag(replacement) == "":
+            raise ValueError(f"{where} needs a replacement")
+        if not source.startswith(("https://", "http://")):
+            raise ValueError(f"{where} needs an http(s) source URL")
+        if not isinstance(raw_values, list) or any(not isinstance(item, str) or not item.strip() for item in raw_values):
+            raise ValueError(f"{where} values must be a list of strings")
+        values = tuple(item.strip() for item in raw_values)
+        if effect == "default" and values:
+            raise ValueError(f"{where} matches a missing key, so it cannot list values")
+        rules.append(
+            FlagRule(
+                version=version,
+                flag=flag,
+                effect=effect,
+                action=action,
+                source=source,
+                replacement=replacement,
+                values=values,
+            )
+        )
+    return rules
+
+
+def network_ids() -> list[str]:
+    directory = data_dir() / "networks"
+    if not directory.is_dir():
+        return []
+    return sorted(path.stem for path in directory.glob("*.json"))
+
+
+def load_network(network_id: str) -> NetworkSchedule:
+    key = network_id.strip().lower()
+    path = data_dir() / "networks" / f"{key}.json"
+    if not path.exists():
+        known = ", ".join(network_ids()) or "none"
+        raise ValueError(f"Unknown network '{network_id}'. Known networks: {known}")
+    payload = _read_json(path)
+    if str(payload.get("id", "")).strip() != key:
+        raise ValueError(f"{path} id does not match the file name")
+    name = str(payload.get("name", "")).strip()
+    upgrade = payload.get("upgrade")
+    if not name or not isinstance(upgrade, dict):
+        raise ValueError(f"{path} needs a name and an upgrade object")
+    upgrade_name = str(upgrade.get("name", "")).strip()
+    source = str(upgrade.get("source", "")).strip()
+    summary = str(upgrade.get("summary", "")).strip()
+    order_summary = str(upgrade.get("order_summary", "")).strip()
+    order = upgrade.get("order")
+    warning = str(upgrade.get("warning", "")).strip()
+    if not upgrade_name or not summary or not order_summary:
+        raise ValueError(f"{path} needs an upgrade name, summary, and order summary")
+    if not source.startswith(("https://", "http://")):
+        raise ValueError(f"{path} needs an http(s) source URL")
+    if order is not None and order not in _NETWORK_ORDERS:
+        raise ValueError(f"{path} has an unknown upgrade order")
+    activation = _optional_time(path, upgrade.get("activation"), "activation")
+    clients = load_clients()
+    required = upgrade.get("required")
+    if not isinstance(required, dict):
+        raise ValueError(f"{path} needs a required object")
+    return NetworkSchedule(
+        id=key,
+        name=name,
+        upgrade=upgrade_name,
+        activation=activation,
+        source=source,
+        summary=summary,
+        order=order,
+        order_summary=order_summary,
+        warning=warning,
+        required_execution=_required_versions(path, required, "execution", clients),
+        required_consensus=_required_versions(path, required, "consensus", clients),
+    )
+
+
+def _optional_time(path: Path, value: object, label: str) -> datetime | None:
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{path} has an unreadable {label}")
+    try:
+        return parse_time(value.strip())
+    except ValueError as exc:
+        raise ValueError(f"{path} has an unreadable {label}") from exc
+
+
+def _required_versions(
+    path: Path,
+    required: dict,
+    role: str,
+    clients: list[Client],
+) -> dict[str, Version]:
+    raw = required.get(role)
+    if not isinstance(raw, dict):
+        raise ValueError(f"{path} needs required.{role}")
+    versions: dict[str, Version] = {}
+    for client_id, version_text in raw.items():
+        client = client_by_id(clients, str(client_id))
+        where = f"{path} required {role} {client_id}"
+        if client is None or client.role != role:
+            article = "an" if role[:1] in "aeiou" else "a"
+            raise ValueError(f"{where} is not {article} {role} client")
+        text = str(version_text).strip()
+        if _PRECISE_RELEASE.fullmatch(text) is None:
+            raise ValueError(f"{where} needs a major.minor.patch version")
+        version = parse_version(text)
+        if version is None:
+            raise ValueError(f"{where} has a version ChainDiff cannot parse")
+        versions[client.id] = version
+    return versions