chaindiff 0.1.0__py3-none-any.whl

chaindiff/versions.py

@@ -0,0 +1,131 @@
+"""Parse and compare client release tags."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from functools import total_ordering
+
+_TAG = re.compile(r"^v?(?P<num>\d+(?:\.\d+)*)(?:-(?P<pre>[0-9A-Za-z.-]+))?$")
+_TOKEN = re.compile(r"^([A-Za-z]+)(\d+)$")
+_PRE_WORD = re.compile(
+    r"(?i)(?:^|[^A-Za-z])(alpha|beta|rc|preview|dev|nightly|unstable)(?:[^A-Za-z]|$)"
+)
+_NAMED_RANK = {
+    "a": 0,
+    "alpha": 0,
+    "b": 1,
+    "beta": 1,
+    "c": 2,
+    "rc": 2,
+    "preview": 3,
+    "dev": 4,
+    "nightly": 5,
+    "unstable": 6,
+}
+
+
+def _rank(name: str) -> int:
+    return _NAMED_RANK.get(name.lower(), 50)
+
+
+def _pre_tuple(pre: str) -> tuple[tuple[int, int], ...]:
+    parts: list[tuple[int, int]] = []
+    for token in pre.split("."):
+        if not token or token.lower() == "stable":
+            continue
+        matched = _TOKEN.fullmatch(token)
+        if matched:
+            parts.append((_rank(matched.group(1)), int(matched.group(2))))
+        elif token.isdigit():
+            parts.append((100, int(token)))
+        else:
+            parts.append((_rank(token), 0))
+    return tuple(parts)
+
+
+def _strip_trailing_zeros(numbers: tuple[int, ...]) -> tuple[int, ...]:
+    trimmed = numbers
+    while len(trimmed) > 1 and trimmed[-1] == 0:
+        trimmed = trimmed[:-1]
+    return trimmed
+
+
+@total_ordering
+@dataclass(frozen=True, eq=False)
+class Version:
+    numbers: tuple[int, ...]
+    pre: tuple[tuple[int, int], ...] | None
+    text: str = field(compare=False, hash=False)
+
+    def _identity(self) -> tuple[tuple[int, ...], tuple[tuple[int, int], ...] | None]:
+        return (_strip_trailing_zeros(self.numbers), self.pre)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Version):
+            return NotImplemented
+        return self._identity() == other._identity()
+
+    def __hash__(self) -> int:
+        return hash(self._identity())
+
+    def __lt__(self, other: object) -> bool:
+        if not isinstance(other, Version):
+            return NotImplemented
+        left = _strip_trailing_zeros(self.numbers)
+        right = _strip_trailing_zeros(other.numbers)
+        size = max(len(left), len(right))
+        left_nums = left + (0,) * (size - len(left))
+        right_nums = right + (0,) * (size - len(right))
+        if left_nums != right_nums:
+            return left_nums < right_nums
+        if self.pre is None:
+            return False
+        if other.pre is None:
+            return True
+        return self.pre < other.pre
+
+
+def parse_version(tag: str) -> Version | None:
+    text = tag.strip()
+    if text.lower().endswith("-stable"):
+        text = text[: -len("-stable")]
+    matched = _TAG.fullmatch(text)
+    if not matched:
+        return None
+    numbers = tuple(int(part) for part in matched.group("num").split("."))
+    # Erigon used four-digit date tags (v2022.10.01). They are not semver and
+    # must not sort above the 2.x/3.x line. Two-digit calver (26.9.0) stays valid.
+    if numbers[0] >= 2000:
+        return None
+    if len(numbers) < 3:
+        numbers = numbers + (0,) * (3 - len(numbers))
+    pre_text = matched.group("pre")
+    pre = None
+    if pre_text and pre_text.lower() != "stable":
+        pre = _pre_tuple(pre_text)
+        if not pre:
+            pre = None
+    display_numbers = ".".join(str(part) for part in numbers)
+    display = display_numbers if pre is None else f"{display_numbers}-{pre_text}"
+    return Version(numbers=numbers, pre=pre, text=display)
+
+
+def explain_unparsed(tag: str) -> str:
+    text = tag.strip()
+    if text.lower().endswith("-stable"):
+        text = text[: -len("-stable")]
+    matched = _TAG.fullmatch(text)
+    if matched and int(matched.group("num").split(".")[0]) >= 2000:
+        return (
+            f"'{tag}' is a date-based release tag. "
+            "ChainDiff does not compare those with the current release line."
+        )
+    return f"Cannot parse version '{tag}'."
+
+
+def tag_is_prerelease(tag: str) -> bool:
+    version = parse_version(tag)
+    if version is not None and version.pre is not None:
+        return True
+    return _PRE_WORD.search(tag) is not None

chaindiff-0.1.0.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: chaindiff
+Version: 0.1.0
+Summary: Decide whether an Ethereum node client upgrade is safe.
+Author: ehsanhajian
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ehsanhajian/chaindiff
+Project-URL: Repository, https://github.com/ehsanhajian/chaindiff
+Project-URL: Issues, https://github.com/ehsanhajian/chaindiff/issues
+Project-URL: Changelog, https://github.com/ehsanhajian/chaindiff/releases
+Keywords: ethereum,blockchain,geth,node,upgrade,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# 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. Configuration scanning and execution/consensus pairing are tracked as later work. They need sourced rules, not guesses.
+
+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. Until the first release is on PyPI:
+
+```bash
+pip install git+https://github.com/ehsanhajian/chaindiff.git
+```
+
+## Commands
+
+```bash
+chaindiff versions
+chaindiff check --client geth --from <installed>
+chaindiff check --client lighthouse --from <installed> --to v8.2.3
+chaindiff plan --client nethermind --from <installed>
+chaindiff refresh
+```
+
+`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.
+
+## 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/`, and `advisories/` layout.

chaindiff-0.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+chaindiff/__init__.py,sha256=twwf8sHQjZH6EJ7WujgdeNHTSpsWkY3V4-GDcWxP5W4,85
+chaindiff/__main__.py,sha256=AY-59LlSZTz4M0ez2ut9CMElF7GsSp9REqq9QgDwSHw,88
+chaindiff/catalog.py,sha256=l0UauOrFC9cagrnf8xVmeA3Gw3kA1SOdeOeubAoV7Eg,6059
+chaindiff/cli.py,sha256=MNUTjp4MoBMZqjU9CUewAw5YY24dhe2hvAsKR8Y7-qo,5500
+chaindiff/evaluate.py,sha256=OQrwVNZXLgqIfnHXVRzPK7Xur6plLhFjV5QzKEHssBY,8639
+chaindiff/models.py,sha256=EZTo7pzpKe4aZBE8IM7moBE1I8_vE3xh6FMnkshQNS0,1228
+chaindiff/refresh.py,sha256=vwkub7g9UCpCD_KletOCd8_3sRM5KLFiRowpNWLWJW4,5189
+chaindiff/report.py,sha256=5RHGLelMgQHBv8xdkdUmdIRfb3Jh17bUqTMBbUGh6Tk,5976
+chaindiff/versions.py,sha256=-nBHHorNLAsc8zSQikJpLeXpF2kGsx3Xl7nbnfJbN5A,4140
+chaindiff/data/clients.json,sha256=I1JJ7DyeIrh5inxsi3Wyd2Q0_4jYpqRGjO9JhWyvtD8,1429
+chaindiff/data/releases/besu.json,sha256=pzfXLOl8KL2qCsKMXcbo0zqQPBrq0xujDiv6E9b0ldI,35807
+chaindiff/data/releases/erigon.json,sha256=ku5AhVCpjtNlADdyjoef1xR_RxSJLh7NobgtIHpgxcg,31788
+chaindiff/data/releases/geth.json,sha256=aowjoouikfYbA8AeV2QTiJb9I6SbJSBAfsqvgFQXHb0,52700
+chaindiff/data/releases/lighthouse.json,sha256=bAoIkZMukI2NXMUI2bSYga5hxUvFh0fXgGTuuXaK40Q,27342
+chaindiff/data/releases/nethermind.json,sha256=gTiuDZygGMs-4SQi20KNx4KXbcnrcZTJo7ILIpwujpo,70701
+chaindiff/data/releases/nimbus.json,sha256=LB5sX6sO7QzNM64nBqZCqBqXg0Z2PKbXzuBnDhz2ay4,23915
+chaindiff/data/releases/prysm.json,sha256=QWVvumqlqBaFoQMUuEed0w8Ii7Uf0vqR26fedqY8zfg,38283
+chaindiff/data/releases/reth.json,sha256=OS0wGqsILuGttjv0HlMMqdRCy1OJNnI1uK3og5fypZ8,21889
+chaindiff/data/releases/teku.json,sha256=2sDXBBXgoDxxrUa-hkJymB0iG5Y8b9QwTrL84hV0Zs4,28601
+chaindiff-0.1.0.dist-info/licenses/LICENSE,sha256=lqHxWzKcfMSMJyVvItKPbs0F1i3WwxukYmzkA7z-7A8,1079
+chaindiff-0.1.0.dist-info/METADATA,sha256=VndAcbxD99nm6BGa95F5Aloz_qW4prKYXcs7Qvq95SQ,5970
+chaindiff-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+chaindiff-0.1.0.dist-info/entry_points.txt,sha256=UqkB6NcTd9UTnzjhM3YxdEdSjz8fxt2J0wN_Q0kSaFI,49
+chaindiff-0.1.0.dist-info/top_level.txt,sha256=SL6Zy6xpeOGBPd-HUotKgjQcuvmwUFeFw53NG45IbDM,10
+chaindiff-0.1.0.dist-info/RECORD,,

chaindiff-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

chaindiff-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+chaindiff = chaindiff.cli:main

chaindiff-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChainDiff contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chaindiff-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+chaindiff