github.com/pokt-network/tendermint@v0.32.11-0.20230426215212-59310158d3e9/docs/architecture/adr-017-chain-versions.md (about)

     1  # ADR 017: Chain Versions
     2  
     3  ## TODO
     4  
     5  - clarify how to handle slashing when ChainID changes
     6  
     7  ## Changelog
     8  
     9  - 28-07-2018: Updates from review
    10    - split into two ADRs - one for protocol, one for chains
    11  - 16-07-2018: Initial draft - was originally joint ADR for protocol and chain
    12    versions
    13  
    14  ## Context
    15  
    16  Software and Protocol versions are covered in a separate ADR.
    17  
    18  Here we focus on chain versions.
    19  
    20  ## Requirements
    21  
    22  We need to version blockchains across protocols, networks, forks, etc.
    23  We need chain identifiers and descriptions so we can talk about a multitude of chains,
    24  and especially the differences between them, in a meaningful way.
    25  
    26  ### Networks
    27  
    28  We need to support many independent networks running the same version of the software,
    29  even possibly starting from the same initial state.
    30  They must have distinct identifiers so that peers know which one they are joining and so
    31  validators and users can prevent replay attacks.
    32  
    33  Call this the `NetworkName` (note we currently call this `ChainID` in the software. In this
    34  ADR, ChainID has a different meaning).
    35  It represents both the application being run and the community or intention
    36  of running it.
    37  
    38  Peers only connect to other peers with the same NetworkName.
    39  
    40  ### Forks
    41  
    42  We need to support existing networks upgrading and forking, wherein they may do any of:
    43  
    44      - revert back to some height, continue with the same versions but new blocks
    45      - arbitrarily mutate state at some height, continue with the same versions (eg. Dao Fork)
    46      - change the AppVersion at some height
    47  
    48  Note because of Tendermint's voting power threshold rules, a chain can only be extended under the "original" rules and under the new rules
    49  if 1/3 or more is double signing, which is expressly prohibited, and is supposed to result in their punishment on both chains. Since they can censor
    50  the punishment, the chain is expected to be hardforked to remove the validators. Thus, if both branches are to continue after a fork,
    51  they will each require a new identifier, and the old chain identifier will be retired (ie. only useful for syncing history, not for new blocks)..
    52  
    53  TODO: explain how to handle slashing when chain id changed!
    54  
    55  We need a consistent way to describe forks.
    56  
    57  ## Proposal
    58  
    59  ### ChainDescription
    60  
    61  ChainDescription is a complete immutable description of a blockchain. It takes the following form:
    62  
    63  ```
    64  ChainDescription = <NetworkName>/<BlockVersion>/<AppVersion>/<StateHash>/<ValHash>/<ConsensusParamsHash>
    65  ```
    66  
    67  Here, StateHash is the merkle root of the initial state, ValHash is the merkle root of the initial Tendermint validator set,
    68  and ConsensusParamsHash is the merkle root of the initial Tendermint consensus parameters.
    69  
    70  The `genesis.json` file must contain enough information to compute this value. It need not contain the StateHash or ValHash itself,
    71  but contain the state from which they can be computed with the given protocol versions.
    72  
    73  NOTE: consider splitting NetworkName into NetworkName and AppName - this allows
    74  folks to independently use the same application for different networks (ie we
    75  could imagine multiple communities of validators wanting to put up a Hub using
    76  the same app but having a distinct network name. Arguably not needed if
    77  differences will come via different initial state / validators).
    78  
    79  #### ChainID
    80  
    81  Define `ChainID = TMHASH(ChainDescriptor)`. It's the unique ID of a blockchain.
    82  
    83  It should be Bech32 encoded when handled by users, eg. with `cosmoschain` prefix.
    84  
    85  #### Forks and Uprades
    86  
    87  When a chain forks or upgrades but continues the same history, it takes a new ChainDescription as follows:
    88  
    89  ```
    90  ChainDescription = <ChainID>/x/<Height>/<ForkDescription>
    91  ```
    92  
    93  Where
    94  
    95  - ChainID is the ChainID from the previous ChainDescription (ie. its hash)
    96  - `x` denotes that a change occured
    97  - `Height` is the height the change occured
    98  - ForkDescription has the same form as ChainDescription but for the fork
    99  - this allows forks to specify new versions for tendermint or the app, as well as arbitrary changes to the state or validator set