IntersectMBO / IntersectMBO/ouroboros-network
Genesis Snapshot Versioning
- 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
Assessment
This issue has not been assessed yet.