IntersectMBO / IntersectMBO/ouroboros-network

Genesis Snapshot Versioning

Open
#5,288 0 comments 0 reactions 0 assignees View on GitHub
Genesis high-priority
Dominant language
Haskell
Stars
296
Forks
104
Avg merge
2d 10h
Merged PRs (30d)
4

Description

# Genesis Snapshot Versioning Scheme

At the top level, we'd like to use the `NodeToClient` version for snapshot versioning in a backwards-compatible way. It is important for a `cardano-cli` to be able to produce a valid snapshot when working with a non-compatible version of `cardano-node`, or for the node to be able to use a snapshot created by an older `cardano-node` version.

# Implementation details

For the reasons outlined at the bottom, I suggest using the following implementation:

* `LedgerPeerSnapshotV23` and forward, should hold a `NodeToClientVersion` record field
* No hard-coded versions in the snapshot `FromJSON` instances.
* `cardano-cli` when creating a snapshot, records `NodeToClientVersion` in the snapshot which then is serialised to json. The `NodeToClientVersion` must come from the handshake negotiated with `cardano-node`.
* The `ToJSON` instance, instead of using a hard-coded version, should use the `NodeToClientVersion` field.
* The `FromJSON` instance, should read the version field into `NodeToCleintVersion`. Instead of:
```hs
parseJSON = withObject "LedgerPeerSnapshot" \v -> do
-- TODO: remove "version" key after NtC V22 support is removed
vNum :: Int <- v .: "version" <|> v .: "NodeToClientVersion"
allPools <- v .: "allLedgerPools"
case vNum of
23 -> do
...
```
it should do
```hs
parseJSON = withObject "LedgerPeerSnapshot" \v -> do
-- TODO: remove "version" key after NtC V22 support is removed
vNum :: Int <- v .: "version" <|> v .: "NodeToClientVersion"
allPools <- v .: "allLedgerPools"
case vNum of
_ | vNum >= NodeToClientV_23 -> do
```

# Release management

## Adding a new `NodeToClientVersion`, without snapshot modifications

This is the most common case, where a `NodeToClientVersion` is added for some snapshot-unrelated reason (e.g., a new query is added to the local-state-query mini-protocol).

The `FromJSON` & `ToJSON` instances, if they follow the suggestions above, will not need to be upgraded. They will automatically deal with a new `NodeToClientVersion`.

## Adding backwards-compatible snapshot changes

1. Add a new `NodeToClientVersion`, e.g. `NodeToClientV_100`. Then modify the `parseJSON` to use `vnum >= NodeToClientV_22 && vNum < NodeToClientV_100`, and add a new parser guarded by `vnum >= NodeToClientV_100`.
2. No changes are required in `cardano-cli` regarding the version, other than what currently needs to be done to support a new `NodeToClientVersion`.

# Notes

## Backwards and forward compatibility

This scheme will produce snapshots supported by `cardano-node`, and properly version them, without requiring a compatible `cardano-cli`. In the current approach, `cardano-cli` produces an unparsable snapshot when used with an incompatible `cardano-node` version. This gives us backwards and forward compatibility, a desired property by SPOs.

## Code clarity

The versioning of `NodeToClient` is done in a single module. It also makes it easy to preserve backward/forward compatibility.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.