revoke-epochs (#4070)

## Motivation

`finalize-committee` currently revokes all but the latest epoch. But
sometimes we may want to keep more than one epoch.

## Proposal

Change this to `revoke-epochs <EPOCH>` and revoke only up to the
specified one.

## Test Plan

CI; tests were updated.

## Release Plan

- Nothing to do / These changes follow the usual release cycle.

## Links

- Closes #3948
- [reviewer
checklist](https://github.com/linera-io/linera-protocol/blob/main/CONTRIBUTING.md#reviewer-checklist)

Author: afck

CLI.md

@@ -22,7 +22,7 @@ This document contains the help content for the `linera` command-line program.
 * [`linera sync-validator`↴](#linera-sync-validator)
 * [`linera set-validator`↴](#linera-set-validator)
 * [`linera remove-validator`↴](#linera-remove-validator)
-* [`linera finalize-committee`↴](#linera-finalize-committee)
+* [`linera revoke-epochs`↴](#linera-revoke-epochs)
 * [`linera resource-control-policy`↴](#linera-resource-control-policy)
 * [`linera create-genesis-config`↴](#linera-create-genesis-config)
 * [`linera watch`↴](#linera-watch)
@@ -86,7 +86,7 @@ A Byzantine-fault tolerant sidechain with low-latency finality and high throughp
 * `sync-validator` — Synchronizes a validator with the local state of chains
 * `set-validator` — Add or modify a validator (admin only)
 * `remove-validator` — Remove a validator (admin only)
-* `finalize-committee` — Deprecates all committees except the last one
+* `revoke-epochs` — Deprecates all committees up to and including the specified one
 * `resource-control-policy` — View or update the resource control policy
 * `create-genesis-config` — Create genesis configuration for a Linera deployment. Create initial user chains and print information to be used for initialization of validator setup. This will also create an initial wallet for the owner of the initial "root" chains
 * `watch` — Watch the network for notifications
@@ -461,11 +461,15 @@ Remove a validator (admin only)
 
 
 
-## `linera finalize-committee`
+## `linera revoke-epochs`
 
-Deprecates all committees except the last one
+Deprecates all committees up to and including the specified one
 
-**Usage:** `linera finalize-committee`
+**Usage:** `linera revoke-epochs <EPOCH>`
+
+###### **Arguments:**
+
+* `<EPOCH>`
 
 
 

linera-base/src/data_types.rs

@@ -812,6 +812,13 @@ impl Epoch {
         Ok(Self(val))
     }
 
+    /// Tries to return an epoch with a number decreased by one. Returns an error if an underflow
+    /// happens.
+    pub fn try_sub_one(self) -> Result<Self, ArithmeticError> {
+        let val = self.0.checked_sub(1).ok_or(ArithmeticError::Underflow)?;
+        Ok(Self(val))
+    }
+
     /// Tries to add one to this epoch's number. Returns an error if an overflow happens.
     #[inline]
     pub fn try_add_assign_one(&mut self) -> Result<(), ArithmeticError> {

linera-core/src/client/mod.rs

@@ -1509,6 +1509,12 @@ pub enum ChainClientError {
 
     #[error("signer error: {0:?}")]
     Signer(#[source] Box<dyn std::error::Error + Send + Sync>),
+
+    #[error("Cannot revoke the current epoch {0}")]
+    CannotRevokeCurrentEpoch(Epoch),
+
+    #[error("Epoch is already revoked")]
+    EpochAlreadyRevoked,
 }
 
 impl From<Infallible> for ChainClientError {
@@ -3381,20 +3387,29 @@ impl<Env: Environment> ChainClient<Env> {
             .await?)
     }
 
-    /// Deprecates all the configurations of voting rights but the last one (admin chains
+    /// Deprecates all the configurations of voting rights up to the given one (admin chains
     /// only). Currently, each individual chain is still entitled to wait before accepting
     /// this command. However, it is expected that deprecated validators stop functioning
     /// shortly after such command is issued.
     #[instrument(level = "trace")]
-    pub async fn finalize_committee(
+    pub async fn revoke_epochs(
         &self,
+        revoked_epoch: Epoch,
     ) -> Result<ClientOutcome<ConfirmedBlockCertificate>, ChainClientError> {
         self.prepare_chain().await?;
         let (current_epoch, committees) = self.epoch_and_committees().await?;
+        ensure!(
+            revoked_epoch < current_epoch,
+            ChainClientError::CannotRevokeCurrentEpoch(current_epoch)
+        );
+        ensure!(
+            committees.contains_key(&revoked_epoch),
+            ChainClientError::EpochAlreadyRevoked
+        );
         let operations = committees
             .keys()
             .filter_map(|epoch| {
-                if *epoch != current_epoch {
+                if *epoch <= revoked_epoch {
                     Some(Operation::system(SystemOperation::Admin(
                         AdminOperation::RemoveCommittee { epoch: *epoch },
                     )))

linera-core/src/unit_tests/client_tests.rs

@@ -1147,7 +1147,7 @@ where
     user.synchronize_from_validators().await.unwrap();
     user.process_inbox().await.unwrap();
     assert_eq!(user.chain_info().await?.epoch, Epoch::from(1));
-    admin.finalize_committee().await.unwrap();
+    admin.revoke_epochs(Epoch::ZERO).await.unwrap();
 
     // Create a new committee.
     let committee = Committee::new(validators.clone(), ResourceControlPolicy::only_fuel());
@@ -1192,8 +1192,18 @@ where
     user.process_inbox().await.unwrap();
     assert_eq!(user.chain_info().await?.epoch, Epoch::from(2));
 
+    // Revoking the current or an already revoked epoch fails.
+    assert_matches!(
+        admin.revoke_epochs(Epoch::ZERO).await,
+        Err(ChainClientError::EpochAlreadyRevoked)
+    );
+    assert_matches!(
+        admin.revoke_epochs(Epoch::from(3)).await,
+        Err(ChainClientError::CannotRevokeCurrentEpoch(Epoch(2)))
+    );
+
     // Have the admin chain deprecate the previous epoch.
-    admin.finalize_committee().await.unwrap();
+    admin.revoke_epochs(Epoch::from(1)).await.unwrap();
 
     // Try to make a transfer back to the admin chain.
     let cert = user

linera-service/src/cli/command.rs

@@ -6,7 +6,7 @@ use std::{borrow::Cow, num::NonZeroU16, path::PathBuf};
 use chrono::{DateTime, Utc};
 use linera_base::{
     crypto::{AccountPublicKey, CryptoHash, ValidatorPublicKey},
-    data_types::Amount,
+    data_types::{Amount, Epoch},
     identifiers::{Account, AccountOwner, ApplicationId, ChainId, ModuleId, StreamId},
     time::Duration,
     vm::VmRuntime,
@@ -309,8 +309,8 @@ pub enum ClientCommand {
         public_key: ValidatorPublicKey,
     },
 
-    /// Deprecates all committees except the last one.
-    FinalizeCommittee,
+    /// Deprecates all committees up to and including the specified one.
+    RevokeEpochs { epoch: Epoch },
 
     /// View or update the resource control policy
     ResourceControlPolicy {
@@ -902,7 +902,7 @@ impl ClientCommand {
             | ClientCommand::SetValidator { .. }
             | ClientCommand::RemoveValidator { .. }
             | ClientCommand::ResourceControlPolicy { .. }
-            | ClientCommand::FinalizeCommittee
+            | ClientCommand::RevokeEpochs { .. }
             | ClientCommand::CreateGenesisConfig { .. }
             | ClientCommand::PublishModule { .. }
             | ClientCommand::ListEventsFromIndex { .. }

linera-service/src/cli/main.rs

@@ -691,28 +691,28 @@ impl Runnable for Job {
                 info!("Operations confirmed after {} ms", time_total.as_millis());
             }
 
-            FinalizeCommittee => {
+            RevokeEpochs { epoch } => {
                 info!("Starting operations to remove old committees");
                 let time_start = Instant::now();
                 let mut context =
                     ClientContext::new(storage, options.inner.clone(), wallet, signer.into_value());
 
                 let chain_client = context.make_chain_client(context.wallet.genesis_admin_chain());
 
-                // Remove the old committee.
-                info!("Finalizing current committee");
+                // Remove the old committees.
+                info!("Revoking epochs");
                 context
                     .apply_client_command(&chain_client, |chain_client| {
                         let chain_client = chain_client.clone();
-                        async move { chain_client.finalize_committee().await }
+                        async move { chain_client.revoke_epochs(epoch).await }
                     })
                     .await
                     .context("Failed to finalize committee")?;
                 context.save_wallet().await?;
 
                 let time_total = time_start.elapsed();
                 info!(
-                    "Finalizing committee confirmed after {} ms",
+                    "Revoking committees confirmed after {} ms",
                     time_total.as_millis()
                 );
             }

linera-service/src/cli_wrappers/wallet.rs

@@ -964,10 +964,11 @@ impl ClientWrapper {
         Ok(())
     }
 
-    pub async fn finalize_committee(&self) -> Result<()> {
+    pub async fn revoke_epochs(&self, epoch: Epoch) -> Result<()> {
         self.command()
             .await?
-            .arg("finalize-committee")
+            .arg("revoke-epochs")
+            .arg(epoch.to_string())
             .spawn_and_wait_for_stdout()
             .await?;
         Ok(())

linera-service/tests/local_net_tests.rs

@@ -178,14 +178,14 @@ async fn test_end_to_end_reconfiguration(config: LocalNetConfig) -> Result<()> {
     client.query_validators(Some(chain_1)).await?;
     if let Some(service) = &node_service_2 {
         service.process_inbox(&chain_2).await?;
-        client.finalize_committee().await?;
+        client.revoke_epochs(Epoch(2)).await?;
         service.process_inbox(&chain_2).await?;
         let committees = service.query_committees(&chain_2).await?;
         let epochs = committees.into_keys().collect::<Vec<_>>();
         assert_eq!(&epochs, &[Epoch(3)]);
     } else {
         client_2.process_inbox(chain_2).await?;
-        client.finalize_committee().await?;
+        client.revoke_epochs(Epoch(2)).await?;
         client_2.process_inbox(chain_2).await?;
     }
 
@@ -195,14 +195,14 @@ async fn test_end_to_end_reconfiguration(config: LocalNetConfig) -> Result<()> {
         client.remove_validator(&validator_key.0).await?;
         if let Some(service) = &node_service_2 {
             service.process_inbox(&chain_2).await?;
-            client.finalize_committee().await?;
+            client.revoke_epochs(Epoch(3 + i as u32)).await?;
             service.process_inbox(&chain_2).await?;
             let committees = service.query_committees(&chain_2).await?;
             let epochs = committees.into_keys().collect::<Vec<_>>();
             assert_eq!(&epochs, &[Epoch(4 + i as u32)]);
         } else {
             client_2.process_inbox(chain_2).await?;
-            client.finalize_committee().await?;
+            client.revoke_epochs(Epoch(3 + i as u32)).await?;
             client_2.process_inbox(chain_2).await?;
         }
         net.remove_validator(i)?;
@@ -418,7 +418,7 @@ async fn test_end_to_end_receipt_of_old_remove_committee_messages(
 
     // Ensure the faucet is on the new epoch before removing the old ones.
     faucet_client.process_inbox(faucet_chain).await?;
-    client.finalize_committee().await?;
+    client.revoke_epochs(Epoch::ZERO).await?;
     faucet_client.process_inbox(faucet_chain).await?;
 
     if matches!(network, Network::Grpc) {