add validation and tracking of TCB evaluation data number to lcp client

Signed-off-by: Jun Kimura <jun.kimura@datachain.jp>

Author: bluele

modules/lcp-client/src/client_def.rs

@@ -105,6 +105,16 @@ impl LCPClient {
                 client_state.zkdcap_verifier_infos[0].as_type() == ZKVMType::Risc0,
                 "only Risc0 is supported"
             );
+            assert!(
+                client_state.current_tcb_evaluation_data_number != 0,
+                "current_tcb_evaluation_data_number must not be 0"
+            );
+            assert_eq!(
+                client_state.next_tcb_evaluation_data_number == 0,
+                client_state.next_tcb_evaluation_data_number_update_time == 0,
+                "next_tcb_evaluation_data_number and next_tcb_evaluation_data_number_update_time must be both 0 or both non-zero"
+            );
+            assert!(client_state.next_tcb_evaluation_data_number == 0 || client_state.next_tcb_evaluation_data_number > client_state.current_tcb_evaluation_data_number, "next_tcb_evaluation_data_number must be greater than current_tcb_evaluation_data_number");
         }
 
         // An initial consensus state must be empty
@@ -273,28 +283,11 @@ impl LCPClient {
             remote_attestation::dcap::INTEL_ROOT_CA_HASH,
         );
 
-        #[allow(clippy::comparison_chain)]
-        #[allow(clippy::assertions_on_constants)]
-        let new_client_state = if client_state.latest_tcb_evaluation_data_number
-            < output.min_tcb_evaluation_data_number
-        {
-            Some(ClientState {
-                latest_tcb_evaluation_data_number: output.min_tcb_evaluation_data_number,
-                ..client_state.clone()
-            })
-        } else if client_state.latest_tcb_evaluation_data_number
-            > output.min_tcb_evaluation_data_number
-        {
-            if !client_state.allow_previous_tcb_evaluation_data_number
-                || client_state.latest_tcb_evaluation_data_number
-                    != output.min_tcb_evaluation_data_number + 1
-            {
-                assert!(false, "unexpected tcb evaluation data number");
-            }
-            None
-        } else {
-            None
-        };
+        self.check_and_update_tcb_evaluation_data_number(
+            ctx,
+            client_id.clone(),
+            output.min_tcb_evaluation_data_number,
+        )?;
 
         assert!(
             output
@@ -338,12 +331,122 @@ impl LCPClient {
             report_data.enclave_key(),
             EKOperatorInfo::new(output.validity.not_after_min, operator),
         );
-        if let Some(new_client_state) = new_client_state {
-            ctx.store_any_client_state(client_id, new_client_state.into())?;
-        }
         Ok(())
     }
 
+    /// check_and_update_tcb_evaluation_data_number checks if the current or next TCB evaluation data number update is required.
+    #[allow(clippy::comparison_chain)]
+    fn check_and_update_tcb_evaluation_data_number(
+        &self,
+        ctx: &mut dyn HostClientKeeper,
+        client_id: ClientId,
+        output_tcb_evaluation_data_number: u32,
+    ) -> Result<(bool, bool), Error> {
+        let client_state = ClientState::try_from(ctx.client_state(&client_id)?)?;
+        let mut current_updated = false;
+
+        // check if the current or next TCB evaluation data number update is required
+        if client_state.next_tcb_evaluation_data_number != 0
+            && ctx.host_timestamp().as_unix_timestamp_secs()
+                >= client_state.next_tcb_evaluation_data_number_update_time
+        {
+            let mut new_client_state = client_state.clone();
+            new_client_state.current_tcb_evaluation_data_number =
+                client_state.next_tcb_evaluation_data_number;
+            new_client_state.next_tcb_evaluation_data_number = 0;
+            new_client_state.next_tcb_evaluation_data_number_update_time = 0;
+            current_updated = true;
+            // NOTE:
+            // - If the current number is updated again in a subsequent process, only one event is emitted
+            // - A new next TCB evaluation data number is not set, so the `next_updated` is false here
+            ctx.store_any_client_state(client_id.clone(), new_client_state.into())?;
+        }
+
+        if output_tcb_evaluation_data_number > client_state.current_tcb_evaluation_data_number {
+            if client_state.tcb_evaluation_data_number_update_grace_period == 0 {
+                // If the grace period is zero, the client immediately updates the current TCB evaluation data number
+                let mut new_client_state = client_state.clone();
+                new_client_state.current_tcb_evaluation_data_number =
+                    output_tcb_evaluation_data_number;
+                // If the grace period is zero, the `next_tcb_evaluation_data_number` and `next_tcb_evaluation_data_number_update_time` must always be zero
+                // Otherwise, there is an internal error in the client
+                assert!(
+                    new_client_state.next_tcb_evaluation_data_number == 0
+                        && new_client_state.next_tcb_evaluation_data_number_update_time == 0
+                );
+                ctx.store_any_client_state(client_id, new_client_state.into())?;
+                Ok((true, false))
+            } else {
+                // If the grace period is not zero, there may be a next TCB evaluation data number update in the client state
+
+                let next_update_time = ctx.host_timestamp().as_unix_timestamp_secs()
+                    + client_state.tcb_evaluation_data_number_update_grace_period as u64;
+
+                // If the next TCB evaluation data number is not set, the client sets the next TCB evaluation data number to the output's TCB evaluation data number
+                if client_state.next_tcb_evaluation_data_number == 0 {
+                    let mut new_client_state = client_state.clone();
+                    new_client_state.next_tcb_evaluation_data_number =
+                        output_tcb_evaluation_data_number;
+                    new_client_state.next_tcb_evaluation_data_number_update_time = next_update_time;
+                    ctx.store_any_client_state(client_id, new_client_state.into())?;
+                    return Ok((current_updated, true));
+                }
+
+                // If the next TCB evaluation data number is set, the client updates the next TCB evaluation data number
+
+                if output_tcb_evaluation_data_number > client_state.next_tcb_evaluation_data_number
+                {
+                    // Edge case 1. clientState.current_tcb_evaluation_data_number < clientState.next_tcb_evaluation_data_number < outputTcbEvaluationDataNumber
+                    //
+                    // In this case, the client immediately updates the current TCB evaluation data number with the `clientState.next_tcb_evaluation_data_number`
+                    // and updates the next TCB evaluation data number with the `outputTcbEvaluationDataNumber`
+                    //
+                    // This case can be caused by too long grace period values or multiple TCB Recovery Events with very short intervals.
+                    // Note that in this case the current number is updated ignoring the grace period setting.
+                    // However, the current number is still a non-latest number, so there should be no problem for the operator operating as expected.
+                    let mut new_client_state = client_state.clone();
+                    new_client_state.current_tcb_evaluation_data_number =
+                        client_state.next_tcb_evaluation_data_number;
+                    new_client_state.next_tcb_evaluation_data_number =
+                        output_tcb_evaluation_data_number;
+                    new_client_state.next_tcb_evaluation_data_number_update_time = next_update_time;
+                    ctx.store_any_client_state(client_id, new_client_state.into())?;
+                    Ok((true, true))
+                } else if output_tcb_evaluation_data_number
+                    < client_state.next_tcb_evaluation_data_number
+                {
+                    // Edge case 2. clientState.current_tcb_evaluation_data_number < outputTcbEvaluationDataNumber < clientState.next_tcb_evaluation_data_number
+                    //
+                    // In this case, the client immediately updates the current TCB evaluation data number with the `outputTcbEvaluationDataNumber`
+                    // and does not update the next TCB evaluation data number.
+                    //
+                    // This case can be caused by too long grace period values or multiple TCB Recovery Events with very short intervals.
+                    // Note that in this case the current number is updated ignoring the grace period setting.
+                    // However, the current number is still a non-latest number, so there should be no problem for the operator operating as expected.
+                    let mut new_client_state = client_state.clone();
+                    new_client_state.current_tcb_evaluation_data_number =
+                        output_tcb_evaluation_data_number;
+                    ctx.store_any_client_state(client_id, new_client_state.into())?;
+                    Ok((true, false))
+                } else {
+                    // General case. outputTcbEvaluationDataNumber == clientState.next_tcb_evaluation_data_number
+                    // In this case, the client already has the next TCB evaluation data number, so it does not need to be updated
+                    Ok((current_updated, false))
+                }
+            }
+        } else if output_tcb_evaluation_data_number
+            < client_state.current_tcb_evaluation_data_number
+        {
+            // The client must revert if the output's TCB evaluation data number is less than the current TCB evaluation data number
+            Err(Error::unexpected_tcb_evaluation_data_number(
+                client_state.current_tcb_evaluation_data_number,
+            ))
+        } else {
+            // nop: case outputTcbEvaluationDataNumber == clientState.current_tcb_evaluation_data_number
+            Ok((current_updated, false))
+        }
+    }
+
     fn update_operators(
         &self,
         ctx: &mut dyn HostClientKeeper,

modules/lcp-client/src/client_state.rs

@@ -29,8 +29,10 @@ pub struct ClientState {
     pub operators_nonce: u64,
     pub operators_threshold_numerator: u64,
     pub operators_threshold_denominator: u64,
-    pub latest_tcb_evaluation_data_number: u32,
-    pub allow_previous_tcb_evaluation_data_number: bool,
+    pub current_tcb_evaluation_data_number: u32,
+    pub tcb_evaluation_data_number_update_grace_period: u32,
+    pub next_tcb_evaluation_data_number: u32,
+    pub next_tcb_evaluation_data_number_update_time: u64,
     pub zkdcap_verifier_infos: Vec<ZKDCAPVerifierInfo>,
 }
 
@@ -147,9 +149,12 @@ impl From<ClientState> for RawClientState {
             operators_nonce: 0,
             operators_threshold_numerator: 0,
             operators_threshold_denominator: 0,
-            latest_tcb_evalulation_data_number: value.latest_tcb_evaluation_data_number,
-            allow_previous_tcb_evalulation_data_number: value
-                .allow_previous_tcb_evaluation_data_number,
+            current_tcb_evaluation_data_number: value.current_tcb_evaluation_data_number,
+            tcb_evaluation_data_number_update_grace_period: value
+                .tcb_evaluation_data_number_update_grace_period,
+            next_tcb_evaluation_data_number: value.next_tcb_evaluation_data_number,
+            next_tcb_evaluation_data_number_update_time: value
+                .next_tcb_evaluation_data_number_update_time,
             zkdcap_verifier_infos: value
                 .zkdcap_verifier_infos
                 .iter()
@@ -179,9 +184,12 @@ impl TryFrom<RawClientState> for ClientState {
             operators_nonce: raw.operators_nonce,
             operators_threshold_numerator: raw.operators_threshold_numerator,
             operators_threshold_denominator: raw.operators_threshold_denominator,
-            latest_tcb_evaluation_data_number: raw.latest_tcb_evalulation_data_number,
-            allow_previous_tcb_evaluation_data_number: raw
-                .allow_previous_tcb_evalulation_data_number,
+            current_tcb_evaluation_data_number: raw.current_tcb_evaluation_data_number,
+            tcb_evaluation_data_number_update_grace_period: raw
+                .tcb_evaluation_data_number_update_grace_period,
+            next_tcb_evaluation_data_number: raw.next_tcb_evaluation_data_number,
+            next_tcb_evaluation_data_number_update_time: raw
+                .next_tcb_evaluation_data_number_update_time,
             zkdcap_verifier_infos: raw
                 .zkdcap_verifier_infos
                 .into_iter()

modules/lcp-client/src/errors.rs

@@ -61,6 +61,13 @@ define_error! {
             "Invalid Risc0 proof format"
         },
 
+        UnexpectedTcbEvaluationDataNumber {
+            number: u32
+        }
+        |e| {
+            format_args!("Unexpected TCB evaluation data number: number={}", e.number)
+        },
+
         AttestationReport
         [attestation_report::Error]
         |_| { "Attestation report error" },

proto/definitions/ibc/lightclients/lcp/v1/lcp.proto

@@ -82,15 +82,20 @@ message ClientState {
   uint64 operators_threshold_numerator = 9;
   // The denominator of the signature threshold for operator updates.
   uint64 operators_threshold_denominator = 10;
-  // The latest TCB evaluation data number
+  // The current TCB evaluation data number
   //
-  // The client updates this when receiving TCB evaluation data whose number is greater than the current number.
-  uint32 latest_tcb_evalulation_data_number = 11;
-  // Indicates whether to allow the previous TCB evaluation data number.
+  // The client only accepts the zkDCAP output generated using collateral with a TCB evaluation data number equal to or greater than this number.
+  uint32 current_tcb_evaluation_data_number = 11;
+  // The grace period for updating to the latest TCB evaluation data number (in seconds)
   //
-  // If this is true, the client will accept the previous TCB evaluation data number (i.e., `latest_tcb_evalulation_data_number` - 1).
-  // Otherwise, the client will only accept the latest TCB evaluation data number or greater.
-  bool allow_previous_tcb_evalulation_data_number = 12;
+  // Note that this grace period is not affected for updates to non-latest numbers.
+  uint32 tcb_evaluation_data_number_update_grace_period = 12;
+  // The next TCB evaluation data number to be updated
+  //
+  // If this number is non-zero, `next_tcb_evaluation_data_number` must be greater than `current_tcb_evaluation_data_number`.
+  uint32 next_tcb_evaluation_data_number = 13;
+  // The update time of the next TCB evaluation data number (in UNIX time seconds)
+  uint64 next_tcb_evaluation_data_number_update_time = 14;
   // The verifier information for the zkDCAP
   //
   // The format is as follows:
@@ -101,7 +106,7 @@ message ClientState {
   // | 0 |  1 - 31  |  32 - 64  |
   // |---|----------|-----------|
   // | 1 | reserved | image id  |
-  repeated bytes zkdcap_verifier_infos = 14;
+  repeated bytes zkdcap_verifier_infos = 15;
 }
 
 message ConsensusState {
@@ -110,6 +115,6 @@ message ConsensusState {
   // Please check the state ID details: <https://docs.lcp.network/protocol/elc#state-id>
   bytes state_id = 1;
   // The timestamp of the target chain's block corresponding to the consensus height,
-  // expressed in Unix time (seconds).
+  // expressed in UNIX time (seconds).
   uint64 timestamp = 2;
 }

proto/src/descriptor.bin

@@ -106,17 +106,24 @@ pub struct ClientState {
     /// The denominator of the signature threshold for operator updates.
     #[prost(uint64, tag = "10")]
     pub operators_threshold_denominator: u64,
-    /// The latest TCB evaluation data number
+    /// The current TCB evaluation data number
     ///
-    /// The client updates this when receiving TCB evaluation data whose number is greater than the current number.
+    /// The client only accepts the zkDCAP output generated using collateral with a TCB evaluation data number equal to or greater than this number.
     #[prost(uint32, tag = "11")]
-    pub latest_tcb_evalulation_data_number: u32,
-    /// Indicates whether to allow the previous TCB evaluation data number.
+    pub current_tcb_evaluation_data_number: u32,
+    /// The grace period for updating to the latest TCB evaluation data number (in seconds)
     ///
-    /// If this is true, the client will accept the previous TCB evaluation data number (i.e., `latest_tcb_evalulation_data_number` - 1).
-    /// Otherwise, the client will only accept the latest TCB evaluation data number or greater.
-    #[prost(bool, tag = "12")]
-    pub allow_previous_tcb_evalulation_data_number: bool,
+    /// Note that this grace period is not affected for updates to non-latest numbers.
+    #[prost(uint32, tag = "12")]
+    pub tcb_evaluation_data_number_update_grace_period: u32,
+    /// The next TCB evaluation data number to be updated
+    ///
+    /// If this number is non-zero, `next_tcb_evaluation_data_number` must be greater than `current_tcb_evaluation_data_number`.
+    #[prost(uint32, tag = "13")]
+    pub next_tcb_evaluation_data_number: u32,
+    /// The update time of the next TCB evaluation data number (in UNIX time seconds)
+    #[prost(uint64, tag = "14")]
+    pub next_tcb_evaluation_data_number_update_time: u64,
     /// The verifier information for the zkDCAP
     ///
     /// The format is as follows:
@@ -127,7 +134,7 @@ pub struct ClientState {
     /// | 0 |  1 - 31  |  32 - 64  |
     /// |---|----------|-----------|
     /// | 1 | reserved | image id  |
-    #[prost(bytes = "vec", repeated, tag = "14")]
+    #[prost(bytes = "vec", repeated, tag = "15")]
     pub zkdcap_verifier_infos: ::prost::alloc::vec::Vec<::prost::alloc::vec::Vec<u8>>,
 }
 #[allow(clippy::derive_partial_eq_without_eq)]
@@ -139,7 +146,7 @@ pub struct ConsensusState {
     #[prost(bytes = "vec", tag = "1")]
     pub state_id: ::prost::alloc::vec::Vec<u8>,
     /// The timestamp of the target chain's block corresponding to the consensus height,
-    /// expressed in Unix time (seconds).
+    /// expressed in UNIX time (seconds).
     #[prost(uint64, tag = "2")]
     pub timestamp: u64,
 }