Define a skeleton for self-describing proposals

Author: jasonz-dfinity

rs/nns/governance/src/governance.rs

@@ -5124,6 +5124,14 @@ impl Governance {
             ));
         }
 
+        let self_describing_action = if is_self_describing_proposal_actions_enabled() {
+            // TODO(NNS1-4271): handle the error case when the self-describing action is fully
+            // implemented.
+            action.to_self_describing(self.env.clone()).await.ok()
+        } else {
+            None
+        };
+
         // Before actually modifying anything, we first make sure that
         // the neuron is allowed to make this proposal and create the
         // electoral roll.
@@ -5263,10 +5271,14 @@ impl Governance {
 
             Proposal {
                 title,
+                self_describing_action,
                 ..proposal.clone()
             }
         } else {
-            proposal.clone()
+            Proposal {
+                self_describing_action,
+                ..proposal.clone()
+            }
         };
 
         // Wait-For-Quiet is not enabled for ManageNeuron

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

@@ -1,19 +1,22 @@
 use crate::{
-    governance::LOG_PREFIX,
+    governance::{Environment, LOG_PREFIX},
     pb::v1::{
         AddOrRemoveNodeProvider, ApproveGenesisKyc, CreateServiceNervousSystem,
         DeregisterKnownNeuron, FulfillSubnetRentalRequest, GovernanceError, InstallCode,
         KnownNeuron, ManageNeuron, Motion, NetworkEconomics, ProposalData, RewardNodeProvider,
-        RewardNodeProviders, StopOrStartCanister, Topic, UpdateCanisterSettings, Vote,
-        governance_error::ErrorType, proposal::Action,
+        RewardNodeProviders, SelfDescribingProposalAction, StopOrStartCanister, Topic,
+        UpdateCanisterSettings, Vote, governance_error::ErrorType, proposal::Action,
+    },
+    proposals::{
+        execute_nns_function::ValidExecuteNnsFunction,
+        self_describing::LocallyDescribableProposalAction,
     },
-    proposals::execute_nns_function::ValidExecuteNnsFunction,
 };
 use ic_base_types::CanisterId;
 use ic_cdk::println;
 use ic_nns_common::pb::v1::NeuronId;
 use ic_nns_constants::{PROTOCOL_CANISTER_IDS, SNS_AGGREGATOR_CANISTER_ID, SNS_WASM_CANISTER_ID};
-use std::collections::HashMap;
+use std::{collections::HashMap, sync::Arc};
 
 pub mod call_canister;
 pub mod create_service_nervous_system;
@@ -22,6 +25,7 @@ pub mod execute_nns_function;
 pub mod fulfill_subnet_rental_request;
 pub mod install_code;
 pub mod register_known_neuron;
+pub mod self_describing;
 pub mod stop_or_start_canister;
 pub mod update_canister_settings;
 
@@ -170,6 +174,20 @@ impl ValidProposalAction {
             None
         }
     }
+
+    /// Converts the proposal action to a self describing representation of itself.
+    pub async fn to_self_describing(
+        &self,
+        _env: Arc<dyn Environment>,
+    ) -> Result<SelfDescribingProposalAction, GovernanceError> {
+        match self {
+            ValidProposalAction::Motion(motion) => Ok(motion.to_self_describing()),
+            _ => Err(GovernanceError::new_with_message(
+                ErrorType::InvalidProposal,
+                "Self describing proposal actions are not supported for this proposal action yet.",
+            )),
+        }
+    }
 }
 
 const SNS_RELATED_CANISTER_IDS: [&CanisterId; 2] =

rs/nns/governance/src/proposals/self_describing.rs

@@ -0,0 +1,71 @@
+use std::collections::HashMap;
+
+use crate::pb::v1::{
+    Motion, SelfDescribingProposalAction, Value, ValueMap,
+    value::Value::{Map, Text},
+};
+
+/// A proposal action that can be described locally, without having to call `canister_metadata`
+/// management canister method to get the candid file of an external canister. Every proposal action
+/// except for `ExecuteNnsFunction` should implement this trait.
+pub trait LocallyDescribableProposalAction {
+    const TYPE_NAME: &'static str;
+    const TYPE_DESCRIPTION: &'static str;
+
+    fn to_value(&self) -> Value;
+
+    fn to_self_describing(&self) -> SelfDescribingProposalAction {
+        SelfDescribingProposalAction {
+            type_name: Self::TYPE_NAME.to_string(),
+            type_description: Self::TYPE_DESCRIPTION.to_string(),
+            value: Some(self.to_value()),
+        }
+    }
+}
+
+impl LocallyDescribableProposalAction for Motion {
+    const TYPE_NAME: &'static str = "Motion";
+    const TYPE_DESCRIPTION: &'static str = "A motion is a text that can be adopted or rejected. \
+    No code is executed when a motion is adopted. An adopted motion should guide the future \
+    strategy of the Internet Computer ecosystem.";
+
+    fn to_value(&self) -> Value {
+        ValueBuilder::new()
+            .add_string_field("motion_text".to_string(), self.motion_text.clone())
+            .build()
+    }
+}
+
+/// A builder for `Value` objects.
+pub(crate) struct ValueBuilder {
+    fields: HashMap<String, Value>,
+}
+
+impl ValueBuilder {
+    pub fn new() -> Self {
+        Self {
+            fields: HashMap::new(),
+        }
+    }
+
+    pub fn add_string_field(mut self, key: String, value: String) -> Self {
+        self.fields.insert(
+            key,
+            Value {
+                value: Some(Text(value)),
+            },
+        );
+        self
+    }
+
+    pub fn build(self) -> Value {
+        let Self { fields } = self;
+        Value {
+            value: Some(Map(ValueMap { values: fields })),
+        }
+    }
+}
+
+#[path = "self_describing_tests.rs"]
+#[cfg(test)]
+pub mod tests;

rs/nns/governance/src/proposals/self_describing_tests.rs

@@ -0,0 +1,28 @@
+use super::*;
+
+use ic_nns_governance_api::Value as ApiValue;
+use maplit::hashmap;
+
+fn assert_self_describing_value_is(
+    action: impl LocallyDescribableProposalAction,
+    expected: ApiValue,
+) {
+    let SelfDescribingProposalAction { value, .. } = action.to_self_describing();
+    // Use ApiValue for testing because: (1) it should only be used for API responses, and (2) it's
+    // more straightforward to construct (while the protobuf type only exists for storage).
+    let value = ApiValue::from(value.unwrap());
+    assert_eq!(value, expected);
+}
+
+#[test]
+fn test_motion_to_self_describing() {
+    let motion = Motion {
+        motion_text: "This is a motion".to_string(),
+    };
+    assert_self_describing_value_is(
+        motion,
+        ApiValue::Map(hashmap! {
+            "motion_text".to_string() => ApiValue::Text("This is a motion".to_string()),
+        }),
+    );
+}