Referendum proposal's metadata

bin/node/runtime/src/lib.rs

@@ -847,6 +847,14 @@ impl pallet_referenda::TracksInfo<Balance, BlockNumber> for TracksInfo {
 }
 pallet_referenda::impl_tracksinfo_get!(TracksInfo, Balance, BlockNumber);
 
+#[derive(Encode, Decode, Clone, PartialEq, Eq, RuntimeDebug, scale_info::TypeInfo, MaxEncodedLen)]
+pub enum MetadataSchema {
+	IpfsJsonV1,
+	IpfsJsonV2,
+	BinJsonV1,
+	BinJsonV2,
+}
+
 impl pallet_referenda::Config for Runtime {
 	type WeightInfo = pallet_referenda::weights::SubstrateWeight<Self>;
 	type RuntimeCall = RuntimeCall;
@@ -865,6 +873,7 @@ impl pallet_referenda::Config for Runtime {
 	type AlarmInterval = AlarmInterval;
 	type Tracks = TracksInfo;
 	type Preimages = Preimage;
+	type MetadataSchema = MetadataSchema;
 }
 
 impl pallet_referenda::Config<pallet_referenda::Instance2> for Runtime {
@@ -885,6 +894,7 @@ impl pallet_referenda::Config<pallet_referenda::Instance2> for Runtime {
 	type AlarmInterval = AlarmInterval;
 	type Tracks = TracksInfo;
 	type Preimages = Preimage;
+	type MetadataSchema = MetadataSchema;
 }
 
 impl pallet_ranked_collective::Config for Runtime {

frame/referenda/src/lib.rs

@@ -93,9 +93,9 @@ pub use self::{
 	pallet::*,
 	types::{
 		BalanceOf, BoundedCallOf, CallOf, Curve, DecidingStatus, DecidingStatusOf, Deposit,
-		InsertSorted, NegativeImbalanceOf, PalletsOriginOf, ReferendumIndex, ReferendumInfo,
-		ReferendumInfoOf, ReferendumStatus, ReferendumStatusOf, ScheduleAddressOf, TallyOf,
-		TrackIdOf, TrackInfo, TrackInfoOf, TracksInfo, VotesOf,
+		InsertSorted, MetadataOf, NegativeImbalanceOf, PalletsOriginOf, ReferendumIndex,
+		ReferendumInfo, ReferendumInfoOf, ReferendumStatus, ReferendumStatusOf, ScheduleAddressOf,
+		TallyOf, TrackIdOf, TrackInfo, TrackInfoOf, TracksInfo, VotesOf,
 	},
 	weights::WeightInfo,
 };
@@ -217,6 +217,13 @@ pub mod pallet {
 
 		/// The preimage provider.
 		type Preimages: QueryPreimage + StorePreimage;
+
+		/// The schema type of the referendum [`MetadataOf`].
+		/// e.g. enum of `IpfsJsonV1` (the hash of an off-chain IPFS json file),
+		/// `BinJsonV2` (on-chain json dump).
+		/// Consider a garbage collection for [`MetadataFor`] of finished referendums
+		/// to `unrequest` large preimages.
+		type MetadataSchema: Clone + Codec + Eq + Debug + TypeInfo + MaxEncodedLen;
 	}
 
 	/// The next free referendum index, aka the number of referenda started so far.
@@ -246,6 +253,11 @@ pub mod pallet {
 	pub type DecidingCount<T: Config<I>, I: 'static = ()> =
 		StorageMap<_, Twox64Concat, TrackIdOf<T, I>, u32, ValueQuery>;
 
+	/// The metadata of the referendum.
+	#[pallet::storage]
+	pub type MetadataFor<T: Config<I>, I: 'static = ()> =
+		StorageMap<_, Blake2_128Concat, ReferendumIndex, MetadataOf<T, I>>;
+
 	#[pallet::event]
 	#[pallet::generate_deposit(pub(super) fn deposit_event)]
 	pub enum Event<T: Config<I>, I: 'static = ()> {
@@ -342,6 +354,16 @@ pub mod pallet {
 			/// The final tally of votes in this referendum.
 			tally: T::Tally,
 		},
+		/// Metadata for a referendum has been set.
+		MetadataSet {
+			/// Index of the referendum.
+			index: ReferendumIndex,
+		},
+		/// Metadata for a referendum has been cleared.
+		MetadataCleared {
+			/// Index of the referendum.
+			index: ReferendumIndex,
+		},
 	}
 
 	#[pallet::error]
@@ -368,6 +390,8 @@ pub mod pallet {
 		NoPermission,
 		/// The deposit cannot be refunded since none was made.
 		NoDeposit,
+		/// The metadata preimage for a given hash does not exist.
+		BadMetadata,
 	}
 
 	#[pallet::call]
@@ -519,6 +543,7 @@ pub mod pallet {
 			Self::deposit_event(Event::<T, I>::Killed { index, tally: status.tally });
 			Self::slash_deposit(Some(status.submission_deposit.clone()));
 			Self::slash_deposit(status.decision_deposit.clone());
+			Self::do_clear_metadata(index);
 			let info = ReferendumInfo::Killed(frame_system::Pallet::<T>::block_number());
 			ReferendumInfoFor::<T, I>::insert(index, info);
 			Ok(())
@@ -579,6 +604,46 @@ pub mod pallet {
 				};
 			Ok(Some(branch.weight::<T, I>()).into())
 		}
+
+		/// Set the metadata to an ongoing referendum.
+		///
+		/// - `origin`: Must be `Signed`, and the creator of the referendum.
+		/// - `index`: The index of the referendum to add metadata for.
+		/// - `metadata`: The metadata of the referendum.
+		// TODO replace the weight function
+		#[pallet::weight(1)]
+		pub fn set_metadata(
+			origin: OriginFor<T>,
+			index: ReferendumIndex,
+			metadata: MetadataOf<T, I>,
+		) -> DispatchResult {
+			let who = ensure_signed(origin)?;
+			let status = Self::ensure_ongoing(index)?;
+			ensure!(status.submission_deposit.who == who, Error::<T, I>::NoPermission);
+			ensure!(T::Preimages::len(&metadata.hash).is_some(), Error::<T, I>::BadMetadata);
+			T::Preimages::request(&metadata.hash);
+			MetadataFor::<T, I>::insert(index, metadata);
+			Self::deposit_event(Event::<T, I>::MetadataSet { index });
+			Ok(())
+		}
+
+		/// Clear the referendum metadata.
+		///
+		/// - `origin`: Must be `Signed` or `Root`. If the referendum is ongoing, it must also be
+		///   the creator of the referendum.
+		/// - `index`: The index of the ongoing referendum to clear metadata for.
+		// TODO replace the weight function
+		#[pallet::weight(1)]
+		pub fn clear_metadata(origin: OriginFor<T>, index: ReferendumIndex) -> DispatchResult {
+			let maybe_who = ensure_signed_or_root(origin)?;
+			if let Some(who) = maybe_who {
+				if let Some(status) = Self::ensure_ongoing(index).ok() {
+					ensure!(status.submission_deposit.who == who, Error::<T, I>::NoPermission);
+				}
+			}
+			Self::do_clear_metadata(index);
+			Ok(())
+		}
 	}
 }
 
@@ -1137,4 +1202,14 @@ impl<T: Config<I>, I: 'static> Pallet<T, I> {
 		support_needed.passing(x, tally.support(id)) &&
 			approval_needed.passing(x, tally.approval(id))
 	}
+
+	/// Clear metadata, if `Some` and unrequest associated preimage.
+	fn do_clear_metadata(index: ReferendumIndex) {
+		if let Some(metadata) = MetadataFor::<T, I>::take(index) {
+			if T::Preimages::is_requested(&metadata.hash) {
+				T::Preimages::unrequest(&metadata.hash);
+			}
+			Self::deposit_event(Event::<T, I>::MetadataCleared { index });
+		}
+	}
 }

frame/referenda/src/mock.rs

@@ -33,7 +33,7 @@ use sp_core::H256;
 use sp_runtime::{
 	testing::Header,
 	traits::{BlakeTwo256, IdentityLookup},
-	DispatchResult, Perbill,
+	DispatchResult, Perbill, RuntimeDebug,
 };
 
 type UncheckedExtrinsic = frame_system::mocking::MockUncheckedExtrinsic<Test>;
@@ -61,6 +61,14 @@ impl Contains<RuntimeCall> for BaseFilter {
 	}
 }
 
+#[derive(Encode, Decode, Clone, PartialEq, Eq, RuntimeDebug, TypeInfo, MaxEncodedLen)]
+pub enum MetadataSchema {
+	IpfsJsonV1,
+	IpfsJsonV2,
+	BinJsonV1,
+	BinJsonV2,
+}
+
 parameter_types! {
 	pub MaxWeight: Weight = Weight::from_ref_time(2_000_000_000_000);
 	pub BlockWeights: frame_system::limits::BlockWeights =
@@ -228,6 +236,7 @@ impl Config for Test {
 	type AlarmInterval = AlarmInterval;
 	type Tracks = TestTracksInfo;
 	type Preimages = Preimage;
+	type MetadataSchema = MetadataSchema;
 }
 
 pub fn new_test_ext() -> sp_io::TestExternalities {

frame/referenda/src/tests.rs

@@ -519,3 +519,82 @@ fn curve_handles_all_inputs() {
 	let threshold = test_curve.threshold(Perbill::one());
 	assert_eq!(threshold, Perbill::zero());
 }
+
+#[test]
+fn set_metadata_works() {
+	new_test_ext().execute_with(|| {
+		use sp_std::borrow::Cow;
+
+		let invalid_metadata =
+			MetadataOf::<Test, ()> { schema: MetadataSchema::IpfsJsonV1, hash: [1u8; 32].into() };
+		let metadata = MetadataOf::<Test, ()> {
+			schema: MetadataSchema::IpfsJsonV1,
+			hash: Preimage::note(Cow::from(vec![1])).unwrap(),
+		};
+
+		// fails to set metadata for a finished referendum.
+		assert_ok!(Referenda::submit(
+			RuntimeOrigin::signed(1),
+			Box::new(RawOrigin::Root.into()),
+			set_balance_proposal_bounded(1),
+			DispatchTime::At(1),
+		));
+		let index = ReferendumCount::<Test>::get() - 1;
+		assert_ok!(Referenda::kill(RuntimeOrigin::root(), index));
+		assert_noop!(
+			Referenda::set_metadata(RuntimeOrigin::signed(1), index, invalid_metadata.clone(),),
+			Error::<Test>::NotOngoing,
+		);
+		// no permission to set metadata
+		assert_ok!(Referenda::submit(
+			RuntimeOrigin::signed(1),
+			Box::new(RawOrigin::Root.into()),
+			set_balance_proposal_bounded(1),
+			DispatchTime::At(1),
+		));
+		let index = ReferendumCount::<Test>::get() - 1;
+		assert_noop!(
+			Referenda::set_metadata(RuntimeOrigin::signed(2), index, invalid_metadata.clone(),),
+			Error::<Test>::NoPermission,
+		);
+		// preimage does not exist
+		let index = ReferendumCount::<Test>::get() - 1;
+		assert_noop!(
+			Referenda::set_metadata(RuntimeOrigin::signed(1), index, invalid_metadata,),
+			Error::<Test>::BadMetadata,
+		);
+		// metadata set
+		let index = ReferendumCount::<Test>::get() - 1;
+		assert_ok!(Referenda::set_metadata(RuntimeOrigin::signed(1), index, metadata.clone(),));
+		System::assert_last_event(RuntimeEvent::Referenda(crate::Event::MetadataSet { index }));
+		assert!(Preimage::is_requested(&metadata.hash));
+	});
+}
+
+#[test]
+fn clear_metadata_works() {
+	new_test_ext().execute_with(|| {
+		use sp_std::borrow::Cow;
+
+		let metadata = MetadataOf::<Test, ()> {
+			schema: MetadataSchema::IpfsJsonV1,
+			hash: Preimage::note(Cow::from(vec![1, 2])).unwrap(),
+		};
+
+		assert_ok!(Referenda::submit(
+			RuntimeOrigin::signed(1),
+			Box::new(RawOrigin::Root.into()),
+			set_balance_proposal_bounded(1),
+			DispatchTime::At(1),
+		));
+		let index = ReferendumCount::<Test>::get() - 1;
+		assert_ok!(Referenda::set_metadata(RuntimeOrigin::signed(1), index, metadata.clone(),));
+		assert!(Preimage::is_requested(&metadata.hash));
+		assert_noop!(
+			Referenda::clear_metadata(RuntimeOrigin::signed(2), index,),
+			Error::<Test>::NoPermission,
+		);
+		assert_ok!(Referenda::clear_metadata(RuntimeOrigin::signed(1), index,),);
+		System::assert_last_event(RuntimeEvent::Referenda(crate::Event::MetadataCleared { index }));
+	});
+}

frame/referenda/src/types.rs

@@ -20,7 +20,7 @@
 use super::*;
 use codec::{Decode, Encode, EncodeLike, MaxEncodedLen};
 use frame_support::{
-	traits::{schedule::v3::Anon, Bounded},
+	traits::{schedule::v3::Anon, Bounded, Hash as PreimageHash},
 	Parameter,
 };
 use scale_info::TypeInfo;
@@ -72,6 +72,8 @@ pub type ScheduleAddressOf<T, I> = <<T as Config<I>>::Scheduler as Anon<
 	PalletsOriginOf<T>,
 >>::Address;
 
+pub type MetadataOf<T, I> = Metadata<<T as Config<I>>::MetadataSchema>;
+
 /// A referendum index.
 pub type ReferendumIndex = u32;
 
@@ -512,6 +514,18 @@ impl Debug for Curve {
 	}
 }
 
+/// General information about the item referring to the metadata.
+#[derive(Encode, Decode, Clone, PartialEq, Eq, RuntimeDebug, TypeInfo, MaxEncodedLen)]
+pub struct Metadata<Schema: Eq + PartialEq + Debug + Encode + Decode + TypeInfo + Clone> {
+	/// The schema/s descriptor of the data the preimage `hash` referring to.
+	/// e.g. enum of `IpfsJsonV1` (the hash of an off-chain IPFS json file),
+	/// `BinJsonV2` (on-chain json dump).
+	pub(super) schema: Schema,
+
+	/// The hash of the preimage holding the data of the `schema`.
+	pub(super) hash: PreimageHash,
+}
+
 #[cfg(test)]
 mod tests {
 	use super::*;