ADR 047: Extend Upgrade Plan

​

Changelog

• Nov, 23, 2021: Initial Draft
• May, 16, 2023: Proposal ABANDONED. pre_run and post_run are not necessary anymore and adding the artifacts brings minor benefits.

​

Status

​

Abstract

​

Context

• name: A short string identifying the new version.
• height: The chain height at which the upgrade is to be performed.
• info: A string containing information about the upgrade.

1. An upgrade governance proposal is submitted and approved.
2. The upgrade height is reached.
3. The x/upgrade module writes the upgrade_info.json file.
4. The chain halts.
5. Cosmovisor backs up the data directory (if set up to do so).
6. Cosmovisor downloads the new executable (if not already in place).
7. Cosmovisor executes the ${DAEMON_NAME} pre-upgrade.
8. Cosmovisor restarts the app using the new version and same args originally provided.

​

Decision

​

Protobuf Updates

message Plan {
  // ... (existing fields)

  UpgradeInstructions instructions = 6;
}

message UpgradeInstructions {
  string pre_run              = 1;
  string post_run             = 2;
  repeated Artifact artifacts = 3;
  string description          = 4;
}

• pre_run is a command to run prior to the upgraded chain restarting. If defined, it will be executed after halting and downloading the new artifact but before restarting the upgraded chain. The working directory this command runs from MUST be {DAEMON_HOME}/cosmovisor/{upgrade name}. This command MUST behave the same as the current pre-upgrade command. It does not take in any command-line arguments and is expected to terminate with the following exit codes:

  Exit status code	How it is handled in Cosmosvisor
  0	Assumes pre-upgrade command executed successfully and continues the upgrade.
  1	Default exit code when pre-upgrade command has not been implemented.
  30	pre-upgrade command was executed but failed. This fails the entire upgrade.
  31	pre-upgrade command was executed but failed. But the command is retried until exit code 1 or 30 are returned.
  If defined, then the app supervisors (e.g. Cosmovisor) MUST NOT run app pre-run.

• post_run is a command to run after the upgraded chain has been started. If defined, this command MUST be only executed at most once by an upgrading node. The output and exit code SHOULD be logged but SHOULD NOT affect the running of the upgraded chain. The working directory this command runs from MUST be {DAEMON_HOME}/cosmovisor/{upgrade name}.
• artifacts define items to be downloaded. It SHOULD have only one entry per platform.
• description contains human-readable information about the upgrade and might contain references to external resources. It SHOULD NOT be used for structured processing information.

message Artifact {
  string platform      = 1;
  string url           = 2;
  string checksum      = 3;
  string checksum_algo = 4;
}

• platform is a required string that SHOULD be in the format {OS}/{CPU}, e.g. "linux/amd64". The string "any" SHOULD also be allowed. An Artifact with a platform of "any" SHOULD be used as a fallback when a specific {OS}/{CPU} entry is not found. That is, if an Artifact exists with a platform that matches the system’s OS and CPU, that should be used; otherwise, if an Artifact exists with a platform of any, that should be used; otherwise no artifact should be downloaded.
• url is a required URL string that MUST conform to RFC 1738: Uniform Resource Locators. A request to this url MUST return either an executable file or an archive containing either bin/{DAEMON_NAME} or {DAEMON_NAME}. The URL should not contain checksum - it should be specified by the checksum attribute.
• checksum is a checksum of the expected result of a request to the url. It is not required, but is recommended. If provided, it MUST be a hex encoded checksum string. Tools utilizing these UpgradeInstructions MUST fail if a checksum is provided but is different from the checksum of the result returned by the url.
• checksum_algo is a string identify the algorithm used to generate the checksum. Recommended algorithms: sha256, sha512. Algorithms also supported (but not recommended): sha1, md5. If a checksum is provided, a checksum_algo MUST also be provided.

​

Upgrade Module Updates

1. If UpgradeInstructions are provided:
   1. There MUST be at least one entry in artifacts.
   2. All of the artifacts MUST have a unique platform.
   3. For each Artifact, if the url contains a checksum query parameter:
      1. The checksum query parameter value MUST be in the format of {checksum_algo}:{checksum}.
      2. The {checksum} from the query parameter MUST equal the checksum provided in the Artifact.
      3. The {checksum_algo} from the query parameter MUST equal the checksum_algo provided in the Artifact.
2. The following validation is currently done using the info field. We will apply similar validation to the UpgradeInstructions. For each Artifact:
   1. The platform MUST have the format {OS}/{CPU} or be "any".
   2. The url field MUST NOT be empty.
   3. The url field MUST be a proper URL.
   4. A checksum MUST be provided either in the checksum field or as a query parameter in the url.
   5. If the checksum field has a value and the url also has a checksum query parameter, the two values MUST be equal.
   6. The url MUST return either a file or an archive containing either bin/{DAEMON_NAME} or {DAEMON_NAME}.
   7. If a checksum is provided (in the field or as a query param), the checksum of the result of the url MUST equal the provided checksum.

​

Cosmovisor Updates

1. The info field will be ignored.
2. The artifacts field will be used to identify the artifact to download based on the platform that Cosmovisor is running in.
3. If a checksum is provided (either in the field or as a query param in the url), and the downloaded artifact has a different checksum, the upgrade process will be interrupted and Cosmovisor will exit with an error.
4. If a pre_run command is defined, it will be executed at the same point in the process where the app pre-upgrade command would have been executed. It will be executed using the same environment as other commands run by Cosmovisor.
5. If a post_run command is defined, it will be executed after executing the command that restarts the chain. It will be executed in a background process using the same environment as the other commands. Any output generated by the command will be logged. Once complete, the exit code will be logged.

1. An upgrade governance proposal is submitted and approved.
2. The upgrade height is reached.
3. The x/upgrade module writes the upgrade_info.json file (now possibly with UpgradeInstructions).
4. The chain halts.
5. Cosmovisor backs up the data directory (if set up to do so).
6. Cosmovisor downloads the new executable (if not already in place).
7. Cosmovisor executes the pre_run command if provided, or else the ${DAEMON_NAME} pre-upgrade command.
8. Cosmovisor restarts the app using the new version and same args originally provided.
9. Cosmovisor immediately runs the post_run command in a detached process.

​

Consequences

​

Backwards Compatibility

​

Forwards Compatibility

1. The chain must already be using a sufficiently advanced version of the Cosmos SDK.
2. The chain’s nodes must be using a sufficiently advanced version of Cosmovisor.

​

Positive

1. The structure for defining artifacts is clearer since it is now defined in the proto instead of in documentation.
2. Availability of a pre-run command becomes more obvious.
3. A post-run command becomes possible.

​

Negative

1. The Plan message becomes larger. This is negligible because A) the x/upgrades module only stores at most one upgrade plan, and B) upgrades are rare enough that the increased gas cost isn’t a concern.
2. There is no option for providing a URL that will return the UpgradeInstructions.
3. The only way to provide multiple assets (executables and other files) for a platform is to use an archive as the platform’s artifact.

​

Neutral

1. Existing functionality of the info field is maintained when the UpgradeInstructions aren’t provided.

​

Further Discussions

1. Draft PR #10032 Comment: Consider different names for UpgradeInstructions instructions (either the message type or field name).
2. Draft PR #10032 Comment:
   1. Consider putting the string platform field inside UpgradeInstructions and make UpgradeInstructions a repeated field in Plan.
   2. Consider using a oneof field in the Plan which could either be UpgradeInstructions or else a URL that should return the UpgradeInstructions.
   3. Consider allowing info to either be a JSON serialized version of UpgradeInstructions or else a URL that returns that.
3. Draft PR #10032 Comment: Consider not including the UpgradeInstructions.description field, using the info field for that purpose instead.
4. Draft PR #10032 Comment: Consider allowing multiple artifacts to be downloaded for any given platform by adding a name field to the Artifact message.
5. PR #10502 Comment Allow the new UpgradeInstructions to be provided via URL.
6. PR #10502 Comment Allow definition of a signer for assets (as an alternative to using a checksum).

​

References

• Current upgrade.proto
• Upgrade Module README
• Cosmovisor README
• Pre-upgrade README
• Draft/POC PR #10032
• RFC 1738: Uniform Resource Locators