feat(storagext): Add terminate sectors extrinsic (#465)

Co-authored-by: José Duarte <[email protected]>

cli/polka-storage/storagext-cli/src/cmd/storage_provider.rs

@@ -14,6 +14,7 @@ use storagext::{
         RecoveryDeclaration as SxtRecoveryDeclaration,
         SectorPreCommitInfo as SxtSectorPreCommitInfo,
         SubmitWindowedPoStParams as SxtSubmitWindowedPoStParams,
+        TerminationDeclaration as SxtTerminationDeclaration,
     },
     PolkaStorageConfig, StorageProviderClientExt,
 };
@@ -82,6 +83,12 @@ pub enum StorageProviderCommand {
         #[arg(value_parser = <Vec<SxtRecoveryDeclaration> as DeserializablePath>::deserialize_json)]
         recoveries: std::vec::Vec<SxtRecoveryDeclaration>,
     },
+
+    /// Terminate sectors.
+    TerminateSectors {
+        #[arg(value_parser = <Vec<SxtTerminationDeclaration> as DeserializablePath>::deserialize_json)]
+        terminations: std::vec::Vec<SxtTerminationDeclaration>,
+    },
 }
 
 impl StorageProviderCommand {
@@ -165,6 +172,9 @@ impl StorageProviderCommand {
             StorageProviderCommand::DeclareFaultsRecovered { recoveries } => {
                 Self::declare_faults_recovered(client, account_keypair, recoveries).await?
             }
+            StorageProviderCommand::TerminateSectors { terminations } => {
+                Self::terminate_sectors(client, account_keypair, terminations).await?
+            }
             _unsigned => unreachable!("unsigned commands should have been previously handled"),
         };
 
@@ -316,4 +326,23 @@ impl StorageProviderCommand {
 
         Ok(submission_result)
     }
+
+    async fn terminate_sectors<Client>(
+        client: Client,
+        account_keypair: MultiPairSigner,
+        terminations: Vec<SxtTerminationDeclaration>,
+    ) -> Result<SubmissionResult<PolkaStorageConfig>, subxt::Error>
+    where
+        Client: StorageProviderClientExt,
+    {
+        let submission_result = client
+            .terminate_sectors(&account_keypair, terminations)
+            .await?;
+        tracing::debug!(
+            "[{}] Successfully terminated sectors.",
+            submission_result.hash
+        );
+
+        Ok(submission_result)
+    }
 }

cli/polka-storage/storagext/src/clients/storage_provider.rs

@@ -18,7 +18,9 @@ use crate::{
         },
         storage_provider::calls::types::register_storage_provider::PeerId,
     },
-    types::storage_provider::{FaultDeclaration, RecoveryDeclaration, SectorPreCommitInfo},
+    types::storage_provider::{
+        FaultDeclaration, RecoveryDeclaration, SectorPreCommitInfo, TerminationDeclaration,
+    },
     BlockNumber, Currency, PolkaStorageConfig,
 };
 pub trait StorageProviderClientExt {
@@ -71,6 +73,14 @@ pub trait StorageProviderClientExt {
     where
         Keypair: subxt::tx::Signer<PolkaStorageConfig>;
 
+    fn terminate_sectors<Keypair>(
+        &self,
+        account_keypair: &Keypair,
+        terminations: Vec<TerminationDeclaration>,
+    ) -> impl Future<Output = Result<SubmissionResult<PolkaStorageConfig>, subxt::Error>>
+    where
+        Keypair: subxt::tx::Signer<PolkaStorageConfig>;
+
     fn retrieve_storage_provider(
         &self,
         account_id: &AccountId32,
@@ -217,6 +227,22 @@ impl StorageProviderClientExt for crate::runtime::client::Client {
         self.traced_submission(&payload, account_keypair).await
     }
 
+    #[tracing::instrument(level = "debug", skip_all)]
+    async fn terminate_sectors<Keypair>(
+        &self,
+        account_keypair: &Keypair,
+        terminations: Vec<TerminationDeclaration>,
+    ) -> Result<SubmissionResult<PolkaStorageConfig>, subxt::Error>
+    where
+        Keypair: subxt::tx::Signer<PolkaStorageConfig>,
+    {
+        let payload = runtime::tx()
+            .storage_provider()
+            .terminate_sectors(terminations.into());
+
+        self.traced_submission(&payload, account_keypair).await
+    }
+
     #[tracing::instrument(level = "debug", skip_all)]
     async fn retrieve_storage_provider(
         &self,

cli/polka-storage/storagext/src/runtime/display/storage_provider.rs

@@ -125,6 +125,21 @@ impl std::fmt::Display for Event {
                 )
                 .collect::<String>()
             )),
+            Event::SectorsTerminated {
+                owner,
+                terminations,
+            } => f.write_fmt(format_args!(
+                "Sectors terminated: {{ owner: {}, terminations: [{}]",
+                owner,
+                itertools::Itertools::intersperse(
+                    terminations
+                        .0
+                        .iter()
+                        .map(|termination| format!("{termination:?}")),
+                    ", ".to_string()
+                )
+                .collect::<String>()
+            )),
         }
     }
 }

cli/polka-storage/storagext/src/runtime/mod.rs

@@ -87,6 +87,10 @@ pub mod display;
         path = "pallet_storage_provider::fault::RecoveryDeclaration",
         derive = "::serde::Serialize"
     ),
+    derive_for_type(
+        path = "pallet_storage_provider::sector::TerminationDeclaration",
+        derive = "::serde::Serialize"
+    ),
     derive_for_type(
         path = "pallet_market::pallet::ActiveDealState",
         derive = "::serde::Serialize"

cli/polka-storage/storagext/src/types/storage_provider.rs

@@ -27,6 +27,8 @@ use crate::{
                 sector::{
                     ProveCommitSector as RuntimeProveCommitSector,
                     SectorPreCommitInfo as RuntimeSectorPreCommitInfo,
+                    TerminateSectorsParams as RuntimeTerminateSectorsParams,
+                    TerminationDeclaration as RuntimeTerminationDeclaration,
                 },
             },
         },
@@ -273,6 +275,32 @@ impl Into<RuntimeSubmitWindowedPoStParams> for SubmitWindowedPoStParams {
     }
 }
 
+#[derive(Debug, Clone, PartialEq, Eq, serde::Deserialize)]
+pub struct TerminationDeclaration {
+    pub deadline: u64,
+    pub partition: u32,
+    pub sectors: BTreeSet<u64>,
+}
+
+impl From<TerminationDeclaration> for RuntimeTerminationDeclaration {
+    fn from(value: TerminationDeclaration) -> Self {
+        Self {
+            deadline: value.deadline,
+            partition: value.partition,
+            // Converts from BTreeSet -> Vec -> BoundedBTreeSet because subxt...
+            sectors: bounded_btree_set::BoundedBTreeSet(value.sectors.into_iter().collect()),
+        }
+    }
+}
+
+impl From<Vec<TerminationDeclaration>> for RuntimeTerminateSectorsParams {
+    fn from(value: Vec<TerminationDeclaration>) -> Self {
+        Self {
+            terminations: bounded_vec::BoundedVec(value.into_iter().map(Into::into).collect()),
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use std::{collections::BTreeSet, str::FromStr};
@@ -286,6 +314,7 @@ mod tests {
             market::DealProposal,
             storage_provider::{
                 FaultDeclaration, PoStProof, RecoveryDeclaration, SubmitWindowedPoStParams,
+                TerminationDeclaration,
             },
         },
         PolkaStorageConfig,
@@ -448,4 +477,24 @@ mod tests {
             }
         );
     }
+
+    #[test]
+    fn ensure_serde_for_termination_declaration() {
+        let termination = serde_json::from_str::<Vec<TerminationDeclaration>>(
+            r#"[{
+                "deadline": 69,
+                "partition": 420,
+                "sectors": [1, 2]
+            }]"#,
+        )
+        .unwrap();
+        assert_eq!(
+            termination,
+            vec![TerminationDeclaration {
+                deadline: 69,
+                partition: 420,
+                sectors: BTreeSet::from([1, 2]),
+            }]
+        )
+    }
 }

docs/src/pallets/storage-provider.md

@@ -281,7 +281,26 @@ Where the termination declarations contain:
 
 #### <a class="header" id="terminate_sectors.example" href="#terminate_sectors.example">Example</a>
 
-TODO(@aidan46, #463, 2024/10/18): Add storagext example after implementation
+Storage provider `//Alice` terminating sectors[^terminate_sectors] on deadline 0, partition 0, sector 1.
+
+
+```bash
+storagext-cli --sr25519-key "//Alice" storage-provider terminate-sectors @terminate-sectors.json
+```
+
+Where `terminate-sectors.json` is a file with contents similar to:
+
+```json
+[
+  {
+    "deadline": 0,
+    "partition": 0,
+    "sectors": [1]
+  }
+]
+```
+
+[^terminate_sectors]: Read more about the `terminate-sectors` command in [_Storagext CLI/Subcommand `storage-provider`/`terminate-sectors`_](../storagext-cli/storage-provider.md#terminate-sectors)
 
 ## Events