github.com/Finschia/finschia-sdk@v0.49.1/x/upgrade/spec/01_concepts.md (about)

     1  <!--
     2  order: 1
     3  -->
     4  
     5  # Concepts
     6  
     7  ## Plan
     8  
     9  The `x/upgrade` module defines a `Plan` type in which a live upgrade is scheduled
    10  to occur. A `Plan` can be scheduled at a specific block height.
    11  A `Plan` is created once a (frozen) release candidate along with an appropriate upgrade
    12  `Handler` (see below) is agreed upon, where the `Name` of a `Plan` corresponds to a
    13  specific `Handler`. Typically, a `Plan` is created through a governance proposal
    14  process, where if voted upon and passed, will be scheduled. The `Info` of a `Plan`
    15  may contain various metadata about the upgrade, typically application specific
    16  upgrade info to be included on-chain such as a git commit that validators could
    17  automatically upgrade to.
    18  
    19  ### Sidecar Process
    20  
    21  If an operator running the application binary also runs a sidecar process to assist
    22  in the automatic download and upgrade of a binary, the `Info` allows this process to
    23  be seamless. Namely, the `x/upgrade` module fulfills the
    24  [cosmosd Upgradeable Binary Specification](https://github.com/regen-network/cosmosd#upgradeable-binary-specification)
    25  specification and `cosmosd` can optionally be used to fully automate the upgrade
    26  process for node operators. By populating the `Info` field with the necessary information,
    27  binaries can automatically be downloaded. See [here](https://github.com/regen-network/cosmosd#auto-download)
    28  for more info.
    29  
    30  ```go
    31  type Plan struct {
    32    Name   string
    33    Time   Time
    34    Height int64
    35    Info   string
    36  }
    37  ```
    38  
    39  ## Handler
    40  
    41  The `x/upgrade` module facilitates upgrading from major version X to major version Y. To
    42  accomplish this, node operators must first upgrade their current binary to a new
    43  binary that has a corresponding `Handler` for the new version Y. It is assumed that
    44  this version has fully been tested and approved by the community at large. This
    45  `Handler` defines what state migrations need to occur before the new binary Y
    46  can successfully run the chain. Naturally, this `Handler` is application specific
    47  and not defined on a per-module basis. Registering a `Handler` is done via
    48  `Keeper#SetUpgradeHandler` in the application.
    49  
    50  ```go
    51  type UpgradeHandler func(Context, Plan, VersionMap) (VersionMap, error)
    52  ```
    53  
    54  During each `EndBlock` execution, the `x/upgrade` module checks if there exists a
    55  `Plan` that should execute (is scheduled at that height). If so, the corresponding
    56  `Handler` is executed. If the `Plan` is expected to execute but no `Handler` is registered
    57  or if the binary was upgraded too early, the node will gracefully panic and exit.
    58  
    59  ## StoreLoader
    60  
    61  The `x/upgrade` module also facilitates store migrations as part of the upgrade. The
    62  `StoreLoader` sets the migrations that need to occur before the new binary can
    63  successfully run the chain. This `StoreLoader` is also application specific and
    64  not defined on a per-module basis. Registering this `StoreLoader` is done via
    65  `app#SetStoreLoader` in the application.
    66  
    67  ```go
    68  func UpgradeStoreLoader (upgradeHeight int64, storeUpgrades *store.StoreUpgrades) baseapp.StoreLoader
    69  ```
    70  
    71  If there's a planned upgrade and the upgrade height is reached, the old binary writes `UpgradeInfo` to the disk before panic'ing.
    72  
    73  ```go
    74  type UpgradeInfo struct {
    75    Name    string
    76    Height  int64
    77  }
    78  ```
    79  
    80  This information is critical to ensure the `StoreUpgrades` happens smoothly at correct height and
    81  expected upgrade. It eliminiates the chances for the new binary to execute `StoreUpgrades` multiple
    82  times everytime on restart. Also if there are multiple upgrades planned on same height, the `Name`
    83  will ensure these `StoreUpgrades` takes place only in planned upgrade handler.
    84  
    85  ## Proposal
    86  
    87  Typically, a `Plan` is proposed and submitted through governance via a `SoftwareUpgradeProposal`.
    88  This proposal prescribes to the standard governance process. If the proposal passes,
    89  the `Plan`, which targets a specific `Handler`, is persisted and scheduled. The
    90  upgrade can be delayed or hastened by updating the `Plan.Height` in a new proposal.
    91  
    92  ```go
    93  type SoftwareUpgradeProposal struct {
    94    Title       string
    95    Description string
    96    Plan        Plan
    97  }
    98  ```
    99  
   100  ### Cancelling Upgrade Proposals
   101  
   102  Upgrade proposals can be cancelled. There exists a `CancelSoftwareUpgrade` proposal
   103  type, which can be voted on and passed and will remove the scheduled upgrade `Plan`.
   104  Of course this requires that the upgrade was known to be a bad idea well before the
   105  upgrade itself, to allow time for a vote.
   106  
   107  If such a possibility is desired, the upgrade height is to be
   108  `2 * (VotingPeriod + DepositPeriod) + (SafetyDelta)` from the beginning of the
   109  upgrade proposal. The `SafetyDelta` is the time available from the success of an
   110  upgrade proposal and the realization it was a bad idea (due to external social consensus).
   111  
   112  A `CancelSoftwareUpgrade` proposal can also be made while the original
   113  `SoftwareUpgradeProposal` is still being voted upon, as long as the `VotingPeriod`
   114  ends after the `SoftwareUpgradeProposal`.