Genesis Snapshot Versioning

[coot]

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:

  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

  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.