feat(governance): Added new TakeCanisterSnapshot NNS proposal type. (#8283)

Disabled by flag.

# Previous Work

Previously, I tried to do this in [PR 8228], but during code review,
radical changes were requested; hence this new PR. Concretely, in the
previous PR, the new proposal type was implemented as an NnsFunction;
whereas, here, it is implemented as a direct Action. The rationale for
switching is that the it was requested that the topic of this
TakeCanisterSnapshot depend on the target canister, which means that the
Governance canister cannot treat the arguments of the proposal as an
opaque blob (when determining the proposal's topic).

[PR 8228]: #8228

# References

Addresses [NNS1-4295].

[NNS1-4295]: https://dfinity.atlassian.net/browse/NNS1-4295

[👈 Previous PR][prev] | [Next PR 👉][next]

[prev]: #8159
[next]: #8285

Author: daniel-wong-dfinity-org

rs/nns/governance/api/src/types.rs

@@ -405,6 +405,16 @@ pub struct Motion {
     /// The text of the motion. Maximum 100kib.
     pub motion_text: String,
 }
+/// Take a snapshot of the state of a canister.
+#[derive(
+    candid::CandidType, candid::Deserialize, serde::Serialize, Clone, PartialEq, Debug, Default,
+)]
+pub struct TakeCanisterSnapshot {
+    /// The canister being snapshotted.
+    pub canister_id: Option<PrincipalId>,
+    /// If set, the existing snapshot with this content will be replaced.
+    pub replace_snapshot: Option<Vec<u8>>,
+}
 /// For all Neurons controlled by the given principals, set their
 /// KYC status to `kyc_verified=true`.
 #[derive(
@@ -641,6 +651,8 @@ pub mod proposal {
         /// back to a healthy state, to recover from some kind of disaster, like
         /// a boot loop, or something like that.
         BlessAlternativeGuestOsVersion(super::BlessAlternativeGuestOsVersion),
+        /// Take a canister snapshot.
+        TakeCanisterSnapshot(super::TakeCanisterSnapshot),
     }
 }
 /// Empty message to use in oneof fields that represent empty
@@ -1399,6 +1411,7 @@ pub enum ProposalActionRequest {
     UpdateCanisterSettings(UpdateCanisterSettings),
     FulfillSubnetRentalRequest(FulfillSubnetRentalRequest),
     BlessAlternativeGuestOsVersion(BlessAlternativeGuestOsVersion),
+    TakeCanisterSnapshot(TakeCanisterSnapshot),
 }
 
 #[derive(

rs/nns/governance/canister/governance.did

@@ -22,6 +22,7 @@ type Action = variant {
   Motion : Motion;
   FulfillSubnetRentalRequest : FulfillSubnetRentalRequest;
   BlessAlternativeGuestOsVersion : BlessAlternativeGuestOsVersion;
+  TakeCanisterSnapshot : TakeCanisterSnapshot
 };
 
 type AddHotKey = record {
@@ -1031,6 +1032,7 @@ type ProposalActionRequest = variant {
   Motion : Motion;
   FulfillSubnetRentalRequest : FulfillSubnetRentalRequest;
   BlessAlternativeGuestOsVersion : BlessAlternativeGuestOsVersion;
+  TakeCanisterSnapshot : TakeCanisterSnapshot;
 };
 
 // Creates a rented subnet from a rental request (in the Subnet Rental
@@ -1099,6 +1101,10 @@ type GuestLaunchMeasurementMetadata = record {
   kernel_cmdline : opt text;
 };
 
+type TakeCanisterSnapshot = record {
+  canister_id : opt principal;
+  replace_snapshot : opt blob;
+};
 
 type ProposalData = record {
   id : opt ProposalId;

rs/nns/governance/proto/ic_nns_governance/pb/v1/governance.proto

@@ -707,9 +707,19 @@ message Proposal {
     // Allow node operators to manually intervene in case of disaster to run
     // (NNS-approved) new software.
     BlessAlternativeGuestOsVersion bless_alternative_guest_os_version = 31;
+    // Take a canister snapshot.
+    TakeCanisterSnapshot take_canister_snapshot = 32;
   }
 }
 
+// Take a canister snapshot.
+message TakeCanisterSnapshot {
+  // The canister being snapshotted.
+  ic_base_types.pb.v1.PrincipalId canister_id = 1;
+  // If set, the existing snapshot with this content will be replaced.
+  optional bytes replace_snapshot = 2;
+}
+
 // Empty message to use in oneof fields that represent empty
 // enums.
 message Empty {}

rs/nns/governance/src/gen/ic_nns_governance.pb.v1.rs

@@ -432,7 +432,7 @@ pub struct Proposal {
     /// take.
     #[prost(
         oneof = "proposal::Action",
-        tags = "10, 12, 13, 14, 15, 16, 17, 18, 19, 21, 29, 22, 23, 24, 25, 26, 27, 28, 31"
+        tags = "10, 12, 13, 14, 15, 16, 17, 18, 19, 21, 29, 22, 23, 24, 25, 26, 27, 28, 31, 32"
     )]
     pub action: ::core::option::Option<proposal::Action>,
 }
@@ -542,8 +542,29 @@ pub mod proposal {
         /// (NNS-approved) new software.
         #[prost(message, tag = "31")]
         BlessAlternativeGuestOsVersion(super::BlessAlternativeGuestOsVersion),
+        /// Take a canister snapshot.
+        #[prost(message, tag = "32")]
+        TakeCanisterSnapshot(super::TakeCanisterSnapshot),
     }
 }
+/// Take a canister snapshot.
+#[derive(
+    candid::CandidType,
+    candid::Deserialize,
+    serde::Serialize,
+    comparable::Comparable,
+    Clone,
+    PartialEq,
+    ::prost::Message,
+)]
+pub struct TakeCanisterSnapshot {
+    /// The canister being snapshotted.
+    #[prost(message, optional, tag = "1")]
+    pub canister_id: ::core::option::Option<::ic_base_types::PrincipalId>,
+    /// If set, the existing snapshot with this content will be replaced.
+    #[prost(bytes = "vec", optional, tag = "2")]
+    pub replace_snapshot: ::core::option::Option<::prost::alloc::vec::Vec<u8>>,
+}
 /// Empty message to use in oneof fields that represent empty
 /// enums.
 #[derive(

rs/nns/governance/src/governance.rs

@@ -42,8 +42,8 @@ use crate::{
             NeuronsFundSnapshot as NeuronsFundSnapshotPb, NnsFunction, NodeProvider, Proposal,
             ProposalData, ProposalRewardStatus, ProposalStatus, RestoreAgingSummary, RewardEvent,
             RewardNodeProvider, RewardNodeProviders, SettleNeuronsFundParticipationRequest,
-            SettleNeuronsFundParticipationResponse, StopOrStartCanister, Tally, Topic,
-            UpdateCanisterSettings, UpdateNodeProvider, Vote, VotingPowerEconomics,
+            SettleNeuronsFundParticipationResponse, StopOrStartCanister, TakeCanisterSnapshot,
+            Tally, Topic, UpdateCanisterSettings, UpdateNodeProvider, Vote, VotingPowerEconomics,
             WaitForQuietState, archived_monthly_node_provider_rewards,
             create_service_nervous_system::LedgerParameters,
             get_neurons_fund_audit_info_response,
@@ -512,6 +512,7 @@ impl Action {
             Action::BlessAlternativeGuestOsVersion(_) => {
                 "ACTION_BLESS_ALTERNATIVE_GUEST_OS_VERSION"
             }
+            Action::TakeCanisterSnapshot(_) => "ACTION_TAKE_CANISTER_SNAPSHOT",
         }
     }
 }
@@ -4174,6 +4175,10 @@ impl Governance {
                 pid,
                 bless_alternative_guest_os_version,
             ),
+            ValidProposalAction::TakeCanisterSnapshot(take_canister_snapshot) => {
+                self.perform_take_canister_snapshot(pid, take_canister_snapshot)
+                    .await;
+            }
         }
     }
 
@@ -4254,6 +4259,17 @@ impl Governance {
         self.set_proposal_execution_status(proposal_id, result);
     }
 
+    async fn perform_take_canister_snapshot(
+        &mut self,
+        proposal_id: u64,
+        take_canister_snapshot: TakeCanisterSnapshot,
+    ) {
+        let result = self
+            .perform_call_canister(proposal_id, take_canister_snapshot)
+            .await;
+        self.set_proposal_execution_status(proposal_id, result);
+    }
+
     async fn perform_call_canister(
         &mut self,
         proposal_id: u64,
@@ -4771,6 +4787,9 @@ impl Governance {
             ValidProposalAction::BlessAlternativeGuestOsVersion(
                 bless_alternative_guest_os_version,
             ) => bless_alternative_guest_os_version.validate(),
+            ValidProposalAction::TakeCanisterSnapshot(take_canister_snapshot) => {
+                take_canister_snapshot.validate()
+            }
         }
     }
 

rs/nns/governance/src/pb/conversions/mod.rs

@@ -457,6 +457,9 @@ impl From<api::proposal::Action> for pb::proposal::Action {
             api::proposal::Action::BlessAlternativeGuestOsVersion(v) => {
                 pb::proposal::Action::BlessAlternativeGuestOsVersion(v.into())
             }
+            api::proposal::Action::TakeCanisterSnapshot(v) => {
+                pb::proposal::Action::TakeCanisterSnapshot(v.into())
+            }
         }
     }
 }
@@ -509,6 +512,9 @@ impl From<api::ProposalActionRequest> for pb::proposal::Action {
             api::ProposalActionRequest::BlessAlternativeGuestOsVersion(v) => {
                 pb::proposal::Action::BlessAlternativeGuestOsVersion(v.into())
             }
+            api::ProposalActionRequest::TakeCanisterSnapshot(v) => {
+                pb::proposal::Action::TakeCanisterSnapshot(v.into())
+            }
         }
     }
 }
@@ -4141,3 +4147,21 @@ impl From<pb::MaturityDisbursement> for api::MaturityDisbursement {
         }
     }
 }
+
+impl From<pb::TakeCanisterSnapshot> for api::TakeCanisterSnapshot {
+    fn from(item: pb::TakeCanisterSnapshot) -> Self {
+        Self {
+            canister_id: item.canister_id,
+            replace_snapshot: item.replace_snapshot,
+        }
+    }
+}
+
+impl From<api::TakeCanisterSnapshot> for pb::TakeCanisterSnapshot {
+    fn from(item: api::TakeCanisterSnapshot) -> Self {
+        Self {
+            canister_id: item.canister_id,
+            replace_snapshot: item.replace_snapshot,
+        }
+    }
+}

rs/nns/governance/src/pb/proposal_conversions.rs

@@ -240,6 +240,9 @@ fn convert_action(
         pb::proposal::Action::BlessAlternativeGuestOsVersion(v) => {
             api::proposal::Action::BlessAlternativeGuestOsVersion(v.clone().into())
         }
+        pb::proposal::Action::TakeCanisterSnapshot(v) => {
+            api::proposal::Action::TakeCanisterSnapshot(v.clone().into())
+        }
 
         // The action types with potentially large fields need to be converted in a way that avoids
         // cloning the action first.

rs/nns/governance/src/proposals/mod.rs

@@ -4,8 +4,8 @@ use crate::{
         ApproveGenesisKyc, BlessAlternativeGuestOsVersion, CreateServiceNervousSystem,
         DeregisterKnownNeuron, GovernanceError, InstallCode, KnownNeuron, ManageNeuron, Motion,
         NetworkEconomics, ProposalData, RewardNodeProvider, RewardNodeProviders,
-        SelfDescribingProposalAction, StopOrStartCanister, Topic, UpdateCanisterSettings, Vote,
-        governance_error::ErrorType, proposal::Action,
+        SelfDescribingProposalAction, StopOrStartCanister, TakeCanisterSnapshot, Topic,
+        UpdateCanisterSettings, Vote, governance_error::ErrorType, proposal::Action,
     },
     proposals::{
         add_or_remove_node_provider::ValidAddOrRemoveNodeProvider,
@@ -32,6 +32,7 @@ pub mod manage_neuron;
 pub mod register_known_neuron;
 pub mod self_describing;
 pub mod stop_or_start_canister;
+pub mod take_canister_snapshot;
 pub mod update_canister_settings;
 
 mod decode_candid_args_to_self_describing_value;
@@ -57,6 +58,7 @@ pub(crate) enum ValidProposalAction {
     UpdateCanisterSettings(UpdateCanisterSettings),
     FulfillSubnetRentalRequest(ValidFulfillSubnetRentalRequest),
     BlessAlternativeGuestOsVersion(BlessAlternativeGuestOsVersion),
+    TakeCanisterSnapshot(TakeCanisterSnapshot),
 }
 
 impl TryFrom<Option<Action>> for ValidProposalAction {
@@ -117,6 +119,9 @@ impl TryFrom<Option<Action>> for ValidProposalAction {
                     bless_alternative_guest_os_version,
                 ))
             }
+            Action::TakeCanisterSnapshot(take_canister_snapshot) => Ok(
+                ValidProposalAction::TakeCanisterSnapshot(take_canister_snapshot),
+            ),
 
             // Obsolete actions
             Action::SetDefaultFollowees(_) => Err(GovernanceError::new_with_message(
@@ -161,6 +166,9 @@ impl ValidProposalAction {
             }
             ValidProposalAction::FulfillSubnetRentalRequest(_) => Topic::SubnetRental,
             ValidProposalAction::BlessAlternativeGuestOsVersion(_) => Topic::NodeAdmin,
+            ValidProposalAction::TakeCanisterSnapshot(take_canister_snapshot) => {
+                take_canister_snapshot.valid_topic()?
+            }
         };
         Ok(topic)
     }

rs/nns/governance/src/proposals/take_canister_snapshot.rs

@@ -0,0 +1,58 @@
+use crate::{
+    pb::v1::{GovernanceError, TakeCanisterSnapshot, Topic},
+    proposals::{call_canister::CallCanister, invalid_proposal_error, topic_to_manage_canister},
+};
+use candid::Encode;
+use ic_base_types::{CanisterId, PrincipalId};
+use ic_nns_constants::ROOT_CANISTER_ID;
+use ic_nns_handler_root_interface::TakeCanisterSnapshotRequest;
+
+impl TakeCanisterSnapshot {
+    pub fn validate(&self) -> Result<(), GovernanceError> {
+        self.valid_canister_id()?;
+        Ok(())
+    }
+
+    pub fn valid_topic(&self) -> Result<Topic, GovernanceError> {
+        let canister_id = self.valid_canister_id()?;
+        Ok(topic_to_manage_canister(&canister_id))
+    }
+
+    fn valid_canister_id(&self) -> Result<CanisterId, GovernanceError> {
+        let canister_principal_id = self
+            .canister_id
+            .ok_or(invalid_proposal_error("Canister ID is required"))?;
+        let canister_id = CanisterId::try_from(canister_principal_id)
+            .map_err(|_| invalid_proposal_error("Invalid canister ID"))?;
+
+        Ok(canister_id)
+    }
+}
+
+impl CallCanister for TakeCanisterSnapshot {
+    fn canister_and_function(&self) -> Result<(CanisterId, &str), GovernanceError> {
+        Ok((ROOT_CANISTER_ID, "take_canister_snapshot"))
+    }
+
+    fn payload(&self) -> Result<Vec<u8>, GovernanceError> {
+        let args = convert_take_canister_snapshot_from_proposal_to_root_request(self)?;
+        Encode!(&args)
+            .map_err(|e| invalid_proposal_error(&format!("Failed to encode payload: {e}")))
+    }
+}
+
+pub fn convert_take_canister_snapshot_from_proposal_to_root_request(
+    original: &TakeCanisterSnapshot,
+) -> Result<TakeCanisterSnapshotRequest, GovernanceError> {
+    let TakeCanisterSnapshot {
+        replace_snapshot,
+        canister_id: _,
+    } = original.clone();
+
+    let canister_id = PrincipalId::from(original.valid_canister_id()?);
+
+    Ok(TakeCanisterSnapshotRequest {
+        canister_id,
+        replace_snapshot,
+    })
+}