feat(sns): Add the upgrade_journal to the get_upgrade_journal SNS-Gov…

… endpoint (#2169)

The idea is for the upgrade journal to have all the information
necessary to understand when and why the SNS got to its current version.
This PR adds the journal to the API (but doesn't yet populate the
journal, generally).

A follow-up PR will use the new endpoint in tests, and populate it in
more places. As a proof of concept, I've made refreshing the upgrade
steps add an entry to the journal, although the purpose of this PR is
just to implement the API.

rs/sns/governance/canister/governance.did

@@ -290,8 +290,9 @@ type Governance = record {
   sns_metadata : opt ManageSnsMetadata;
   neurons : vec record { text; Neuron };
   genesis_timestamp_seconds : nat64;
-  target_version: opt Version;
+  target_version : opt Version;
   timers : opt Timers;
+  upgrade_journal : opt UpgradeJournal;
 };
 
 type Timers = record {
@@ -719,12 +720,56 @@ type WaitForQuietState = record {
   current_deadline_timestamp_seconds : nat64;
 };
 
+type UpgradeJournalEntry = record {
+  event : opt variant {
+    UpgradeStepsRefreshed : UpgradeStepsRefreshed;
+    TargetVersionSet : TargetVersionSet;
+    TargetVersionReset : TargetVersionSet;
+    UpgradeStarted : UpgradeStarted;
+    UpgradeOutcome : UpgradeOutcome;
+  };
+  timestamp_seconds : opt nat64;
+};
+
+type UpgradeStepsRefreshed = record {
+  upgrade_steps : opt Versions;
+};
+
+type TargetVersionSet = record {
+  new_target_version : opt Version;
+  old_target_version : opt Version;
+};
+
+type UpgradeStarted = record {
+  current_version : opt Version;
+  expected_version : opt Version;
+  reason : opt variant {
+    UpgradeSnsToNextVersionProposal : ProposalId;
+    BehindTargetVersion : record {};
+  }
+};
+
+type UpgradeOutcome = record {
+  human_readable : opt text;
+  status : opt variant {
+    Success : record {};
+    Timeout : record {};
+    InvalidState : record { version : opt Version };
+    ExternalFailure : record {};
+  };
+};
+
+type UpgradeJournal = record {
+  entries : vec UpgradeJournalEntry;
+};
+
 type GetUpgradeJournalRequest = record {};
 
 type GetUpgradeJournalResponse = record {
   upgrade_steps : opt Versions;
   response_timestamp_seconds : opt nat64;
   target_version : opt Version;
+  upgrade_journal : opt UpgradeJournal;
 };
 
 service : (Governance) -> {
@@ -740,13 +785,9 @@ service : (Governance) -> {
   get_proposal : (GetProposal) -> (GetProposalResponse) query;
   get_root_canister_status : (null) -> (CanisterStatusResultV2);
   get_running_sns_version : (record {}) -> (GetRunningSnsVersionResponse) query;
-  get_sns_initialization_parameters : (record {}) -> (
-      GetSnsInitializationParametersResponse,
-    ) query;
+  get_sns_initialization_parameters : (record {}) -> (GetSnsInitializationParametersResponse) query;
   get_upgrade_journal : (GetUpgradeJournalRequest) -> (GetUpgradeJournalResponse) query;
-  list_nervous_system_functions : () -> (
-      ListNervousSystemFunctionsResponse,
-    ) query;
+  list_nervous_system_functions : () -> (ListNervousSystemFunctionsResponse) query;
   list_neurons : (ListNeurons) -> (ListNeuronsResponse) query;
   list_proposals : (ListProposals) -> (ListProposalsResponse) query;
   manage_neuron : (ManageNeuron) -> (ManageNeuronResponse);

rs/sns/governance/canister/governance_test.did

@@ -301,6 +301,7 @@ type Governance = record {
   genesis_timestamp_seconds : nat64;
   target_version: opt Version;
   timers : opt Timers;
+  upgrade_journal : opt UpgradeJournal;
 };
 
 type Timers = record {
@@ -733,12 +734,56 @@ type WaitForQuietState = record {
   current_deadline_timestamp_seconds : nat64;
 };
 
+type UpgradeJournalEntry = record {
+  event : opt variant {
+    UpgradeStepsRefreshed : UpgradeStepsRefreshed;
+    TargetVersionSet : TargetVersionSet;
+    TargetVersionReset : TargetVersionSet;
+    UpgradeStarted : UpgradeStarted;
+    UpgradeOutcome : UpgradeOutcome;
+  };
+  timestamp_seconds : opt nat64;
+};
+
+type UpgradeStepsRefreshed = record {
+  upgrade_steps : opt Versions;
+};
+
+type TargetVersionSet = record {
+  new_target_version : opt Version;
+  old_target_version : opt Version;
+};
+
+type UpgradeStarted = record {
+  current_version : opt Version;
+  expected_version : opt Version;
+  reason : opt variant {
+    UpgradeSnsToNextVersionProposal : ProposalId;
+    BehindTargetVersion : record {};
+  }
+};
+
+type UpgradeOutcome = record {
+  human_readable : opt text;
+  status : opt variant {
+    Success : record {};
+    Timeout : record {};
+    InvalidState : record { version : opt Version };
+    ExternalFailure : record {};
+  };
+};
+
+type UpgradeJournal = record {
+  entries : vec UpgradeJournalEntry;
+};
+
 type GetUpgradeJournalRequest = record {};
 
 type GetUpgradeJournalResponse = record {
   upgrade_steps : opt Versions;
   response_timestamp_seconds : opt nat64;
   target_version : opt Version;
+  upgrade_journal : opt UpgradeJournal;
 };
 
 type AdvanceTargetVersionRequest = record { target_version : opt Version; };

rs/sns/governance/proto/ic_sns_governance/pb/v1/governance.proto

@@ -1473,6 +1473,21 @@ message Governance {
 
   // Information about the timers that perform periodic tasks of this Governance canister.
   optional ic_nervous_system.pb.v1.Timers timers = 31;
+
+  UpgradeJournal upgrade_journal = 32;
+}
+
+message Timers {
+  optional uint64 last_reset_timestamp_seconds = 1;
+  optional uint64 last_spawned_timestamp_seconds = 2;
+}
+
+message ResetTimersRequest {}
+message ResetTimersResponse {}
+
+message GetTimersRequest {}
+message GetTimersResponse {
+  optional Timers timers = 1;
 }
 
 // Request message for 'get_metadata'.
@@ -2140,6 +2155,58 @@ message AdvanceTargetVersionRequest {
 // The response to a request to advance the target version of the SNS.
 message AdvanceTargetVersionResponse {}
 
+// Represents a single entry in the upgrade journal.
+message UpgradeJournalEntry {
+  oneof event {
+    UpgradeStepsRefreshed upgrade_steps_refreshed = 1;
+    TargetVersionSet target_version_set = 2;
+    TargetVersionSet target_version_reset = 3;
+    UpgradeStarted upgrade_started = 4;
+    UpgradeOutcome upgrade_outcome = 5;
+  }
+  optional uint64 timestamp_seconds = 6;
+
+  message UpgradeStepsRefreshed {
+    optional Governance.Versions upgrade_steps = 2;
+  }
+
+  message TargetVersionSet {
+    optional Governance.Version old_target_version = 1;
+    optional Governance.Version new_target_version = 2;
+  }
+
+  message UpgradeStarted {
+    optional Governance.Version current_version = 1;
+    optional Governance.Version expected_version = 2;
+    oneof reason {
+      ProposalId upgrade_sns_to_next_version_proposal = 3;
+      Empty behind_target_version = 4;
+    }
+  }
+
+  message UpgradeOutcome {
+    optional string human_readable = 1;
+
+    oneof status {
+      Empty success = 2;
+      Empty timeout = 3;
+      // The SNS ended up being upgraded to a version that was not the expected one.
+      InvalidState invalid_state = 4;
+      Empty external_failure = 5;
+    }
+
+    message InvalidState {
+      Governance.Version version = 1;
+    }
+  }
+}
+
+// Needed to cause prost to generate a type isomorphic to Option<Vec<UpgradeJournalEntry>>.
+message UpgradeJournal {
+  // The entries in the upgrade journal.
+  repeated UpgradeJournalEntry entries = 1;
+}
+
 // The upgrade journal contains all the information neede to audit previous SNS upgrades and understand its current state.
 // It is being implemented as part of the "effortless SNS upgrade" feature.
 message GetUpgradeJournalRequest {}
@@ -2151,6 +2218,8 @@ message GetUpgradeJournalResponse {
   // Currently, this field is always None, but in the "effortless SNS upgrade"
   // feature, it reflect the version of the SNS that the community has decided to upgrade to.
   Governance.Version target_version = 3;
+
+  UpgradeJournal upgrade_journal = 4;
 }
 
 // A request to mint tokens for a particular principal. The associated endpoint