add pruning of generations

Author: ross-weir

Cargo.lock

@@ -553,6 +553,14 @@ impl<S: Spec> ChainState<S> {
             .unwrap_infallible();
     }
 
+    /// Returns the admin address, if one has been set.
+    pub fn admin_address<Accessor: StateReader<User>>(
+        &self,
+        state: &mut Accessor,
+    ) -> Result<Option<S::Address>, Accessor::Error> {
+        self.admin_address.get(state)
+    }
+
     /// Returns the current operating mode of the rollup.
     pub fn operating_mode<Accessor: StateReader<User>>(
         &self,

crates/module-system/module-implementations/sov-chain-state/src/lib.rs

@@ -16,8 +16,12 @@ borsh = { workspace = true, features = ["rc"] }
 schemars = { workspace = true }
 serde = { workspace = true }
 
+serde_json = { workspace = true }
+sov-chain-state = { workspace = true }
 sov-modules-api = { workspace = true }
 sov-state = { workspace = true }
+strum = { workspace = true }
+thiserror = { workspace = true }
 
 [dev-dependencies]
 alloy-consensus = { workspace = true }
@@ -57,6 +61,7 @@ arbitrary = [
 ]
 native = [
 	"reth-primitives/std",
+	"sov-chain-state/native",
 	"sov-modules-api/native",
 	"sov-uniqueness/native",
 	"sov-state/native",

crates/module-system/module-implementations/sov-uniqueness/Cargo.toml

@@ -0,0 +1,89 @@
+use schemars::JsonSchema;
+use sov_modules_api::macros::{serialize, UniversalWallet};
+use sov_modules_api::{Context, CoreModuleError, CredentialId, Spec, TxState};
+use strum::{EnumDiscriminants, EnumIs, VariantArray};
+
+use crate::error::{PruneGenerationsError, PruneSelfGenerationsError};
+use crate::Uniqueness;
+
+/// The available call messages for the `sov-uniqueness` module.
+#[derive(Debug, PartialEq, Eq, Clone, JsonSchema, EnumDiscriminants, EnumIs, UniversalWallet)]
+#[serialize(Borsh, Serde)]
+#[schemars(rename = "CallMessage")]
+#[strum_discriminants(derive(VariantArray, EnumIs))]
+#[serde(rename_all = "snake_case")]
+pub enum CallMessage {
+    /// Prune generation deduplication data for the specified credentials.
+    /// Only callable by the chain state admin.
+    PruneGenerations {
+        /// The credential IDs whose generation data should be deleted.
+        credential_ids: Vec<CredentialId>,
+    },
+    /// Prune the caller's own generation deduplication data.
+    /// The caller must provide their credential ID, and the module verifies
+    /// that it derives to the sender's address.
+    PruneSelfGenerations {
+        /// The caller's credential ID whose generation data should be deleted.
+        credential_id: CredentialId,
+    },
+}
+
+impl<S: Spec> Uniqueness<S> {
+    /// Prune generation deduplication data for the specified credentials.
+    ///
+    /// Only the chain state admin is authorized to call this method.
+    /// Each credential's entire generation entry is removed from state.
+    pub(crate) fn prune_generations(
+        &mut self,
+        credential_ids: &[CredentialId],
+        context: &Context<S>,
+        state: &mut impl TxState<S>,
+    ) -> Result<(), PruneGenerationsError> {
+        let admin = self
+            .chain_state
+            .admin_address(state)
+            .map_err(CoreModuleError::state_read)?
+            .ok_or(PruneGenerationsError::NoAdmin)?;
+
+        if context.sender() != &admin {
+            return Err(PruneGenerationsError::NotAdmin {
+                admin: admin.to_string(),
+                sender: context.sender().to_string(),
+            });
+        }
+
+        for credential_id in credential_ids {
+            self.generations
+                .delete(credential_id, state)
+                .map_err(CoreModuleError::state_write)?;
+        }
+
+        Ok(())
+    }
+
+    /// Prune the caller's own generation deduplication data.
+    ///
+    /// The caller provides their credential ID, and the module verifies that
+    /// `S::Address::from(credential_id) == context.sender()` before deleting.
+    pub(crate) fn prune_self_generations(
+        &mut self,
+        credential_id: &CredentialId,
+        context: &Context<S>,
+        state: &mut impl TxState<S>,
+    ) -> Result<(), PruneSelfGenerationsError> {
+        let expected_sender = S::Address::from(*credential_id);
+        if *context.sender() != expected_sender {
+            return Err(PruneSelfGenerationsError::NotOwner {
+                credential_id: credential_id.to_string(),
+                expected_sender: expected_sender.to_string(),
+                actual_sender: context.sender().to_string(),
+            });
+        }
+
+        self.generations
+            .delete(credential_id, state)
+            .map_err(CoreModuleError::state_write)?;
+
+        Ok(())
+    }
+}

crates/module-system/module-implementations/sov-uniqueness/src/call.rs

@@ -0,0 +1,64 @@
+use sov_modules_api::{err_detail, CoreModuleError, ErrorContext, ErrorDetail};
+
+/// Errors that can occur when pruning generation data (admin operation).
+#[derive(Debug, thiserror::Error, serde::Serialize)]
+#[serde(tag = "error_code", rename_all = "snake_case")]
+pub enum PruneGenerationsError {
+    /// A core module error occurred (e.g. state read/write failure).
+    #[error(transparent)]
+    CoreModuleError(#[from] CoreModuleError),
+    /// The sender is not the chain state admin.
+    #[error("Only the chain state admin can prune generations. Admin: {admin}, sender: {sender}")]
+    NotAdmin {
+        /// The expected admin address.
+        admin: String,
+        /// The actual sender address.
+        sender: String,
+    },
+    /// No admin address has been configured in chain state.
+    #[error("No admin address configured in chain state")]
+    NoAdmin,
+}
+
+/// Errors that can occur when pruning own generation data (self-service operation).
+#[derive(Debug, thiserror::Error, serde::Serialize)]
+#[serde(tag = "error_code", rename_all = "snake_case")]
+pub enum PruneSelfGenerationsError {
+    /// A core module error occurred (e.g. state read/write failure).
+    #[error(transparent)]
+    CoreModuleError(#[from] CoreModuleError),
+    /// The provided credential ID does not derive to the sender's address.
+    #[error("Credential {credential_id} does not belong to sender. Expected sender: {expected_sender}, actual: {actual_sender}")]
+    NotOwner {
+        /// The credential ID that was provided.
+        credential_id: String,
+        /// The address derived from the credential ID.
+        expected_sender: String,
+        /// The actual sender address.
+        actual_sender: String,
+    },
+}
+
+/// The top-level error type for all uniqueness module operations.
+#[derive(Debug, thiserror::Error, serde::Serialize)]
+#[serde(tag = "call", rename_all = "snake_case")]
+pub enum Error {
+    /// An error occurred during admin generation pruning.
+    #[error("Prune generations error: {0}")]
+    PruneGenerations(#[from] PruneGenerationsError),
+    /// An error occurred during self generation pruning.
+    #[error("Prune self generations error: {0}")]
+    PruneSelfGenerations(#[from] PruneSelfGenerationsError),
+}
+
+impl ErrorDetail for Error {
+    fn error_detail(&self) -> Result<ErrorContext, Box<dyn std::error::Error + Send + Sync>> {
+        Ok(err_detail!(self))
+    }
+}
+
+impl From<anyhow::Error> for Error {
+    fn from(err: anyhow::Error) -> Self {
+        PruneGenerationsError::from(CoreModuleError::Generic(err)).into()
+    }
+}

crates/module-system/module-implementations/sov-uniqueness/src/error.rs

@@ -1,13 +1,18 @@
 #![deny(missing_docs)]
 #![doc = include_str!("../README.md")]
+/// Contains the call methods used by the module.
+mod call;
 mod capabilities;
+/// Error types for the module.
+pub mod error;
 mod generations;
 mod nonces;
 use std::collections::{BTreeMap, HashSet};
 
+pub use call::*;
 use sov_modules_api::{
-    Context, CredentialId, DaSpec, GenesisState, Module, ModuleId, ModuleInfo, ModuleRestApi,
-    NotInstantiable, Spec, StateMap, StateReader, TxHash, TxState,
+    Context, CredentialId, DaSpec, GenesisState, Module, ModuleId, ModuleInfo, ModuleRestApi, Spec,
+    StateMap, StateReader, TxHash, TxState,
 };
 use sov_state::User;
 
@@ -34,6 +39,10 @@ pub struct Uniqueness<S: Spec> {
     #[state]
     pub(crate) nonces: StateMap<CredentialId, u64>,
 
+    /// Reference to the chain state module for admin address lookup.
+    #[module]
+    pub(crate) chain_state: sov_chain_state::ChainState<S>,
+
     #[phantom]
     phantom: std::marker::PhantomData<S>,
 }
@@ -100,27 +109,34 @@ impl<S: Spec> Module for Uniqueness<S> {
 
     type Config = ();
 
-    type CallMessage = NotInstantiable;
+    type CallMessage = call::CallMessage;
 
     type Event = ();
 
-    type Error = anyhow::Error;
+    type Error = error::Error;
 
     fn genesis(
         &mut self,
         _genesis_rollup_header: &<<S as Spec>::Da as DaSpec>::BlockHeader,
         _config: &Self::Config,
         _state: &mut impl GenesisState<S>,
-    ) -> Result<(), Self::Error> {
+    ) -> anyhow::Result<()> {
         Ok(())
     }
 
     fn call(
         &mut self,
-        _msg: Self::CallMessage,
-        _context: &Context<S>,
-        _state: &mut impl TxState<S>,
+        msg: Self::CallMessage,
+        context: &Context<S>,
+        state: &mut impl TxState<S>,
     ) -> Result<(), Self::Error> {
-        unreachable!()
+        match msg {
+            CallMessage::PruneGenerations { credential_ids } => {
+                Ok(self.prune_generations(&credential_ids, context, state)?)
+            }
+            CallMessage::PruneSelfGenerations { credential_id } => {
+                Ok(self.prune_self_generations(&credential_id, context, state)?)
+            }
+        }
     }
 }

crates/module-system/module-implementations/sov-uniqueness/src/lib.rs

@@ -1,4 +1,5 @@
 mod call_tests;
 mod hooks_tests;
+mod prune_tests;
 mod runtime;
 pub mod utils;