Metadata-Version: 2.4
Name: chaindiff
Version: 0.2.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. 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.
