chore(gateway-contracts): ensure there is always a single active context

Author: melanciani

gateway-contracts/contracts/CoprocessorContexts.sol

@@ -235,15 +235,13 @@ contract CoprocessorContexts is
                 $.coprocessorContextSuspendedTimePeriod[activeContextId];
             $.coprocessorContextDeactivatedBlockTimestamp[activeContextId] = deactivatedBlockTimestamp;
 
-            // Set the current active coprocessor context to the suspended state
-            ContextLifecycle.setSuspended($.coprocessorContextLifecycle, activeContextId);
+            // Set the new context as active and the current active context as suspended
+            ContextLifecycle.setActiveAndSuspended(
+                $.coprocessorContextLifecycle,
+                preActivationContextId,
+                activeContextId
+            );
             emit SuspendCoprocessorContext(activeContextId, deactivatedBlockTimestamp);
-
-            // Set the new active coprocessor context
-            // It is mandatory to directly set the new active coprocessor context right after suspending
-            // the current one in order to avoid having a state where no active context is available,
-            // which should never happen.
-            ContextLifecycle.setActive($.coprocessorContextLifecycle, preActivationContextId);
             emit ActivateCoprocessorContext(preActivationContextId);
         }
 
@@ -260,25 +258,20 @@ contract CoprocessorContexts is
 
     /**
      * @dev See {ICoprocessorContexts-forceUpdateContextToStatus}.
-     * ⚠️ This function should be used with caution as it can lead to unexpected behaviors if not
-     * used correctly. See the interface documentation for more details. ⚠️
      */
     function forceUpdateContextToStatus(
         uint256 contextId,
         ContextStatus status
     ) external virtual onlyGatewayOwner ensureContextInitialized(contextId) {
         CoprocessorContextsStorage storage $ = _getCoprocessorContextsStorage();
         if (status == ContextStatus.Active) {
-            ContextLifecycle.setActive($.coprocessorContextLifecycle, contextId);
-            emit ActivateCoprocessorContext(contextId);
+            // Get the current active context ID
+            uint256 activeContextId = getActiveCoprocessorContextId();
 
-            // Set the suspended block timestamp to the current block timestamp (i.e., the status update
-            // is immediate)
-            // ⚠️ This should be used with caution as it will create a state where no context is active,
-            // which should never happen. Please make sure to activate a context right after. ⚠️
-        } else if (status == ContextStatus.Suspended) {
-            ContextLifecycle.setSuspended($.coprocessorContextLifecycle, contextId);
-            emit SuspendCoprocessorContext(contextId, block.timestamp);
+            // Set the new context as active and the current active context as suspended
+            ContextLifecycle.setActiveAndSuspended($.coprocessorContextLifecycle, contextId, activeContextId);
+            emit SuspendCoprocessorContext(activeContextId, block.timestamp);
+            emit ActivateCoprocessorContext(contextId);
         } else if (status == ContextStatus.Deactivated) {
             ContextLifecycle.setDeactivated($.coprocessorContextLifecycle, contextId);
             emit DeactivateCoprocessorContext(contextId);
@@ -307,17 +300,14 @@ contract CoprocessorContexts is
 
         CoprocessorContextsStorage storage $ = _getCoprocessorContextsStorage();
 
-        // Suspend the (problematic) active coprocessor context
-        ContextLifecycle.setSuspended($.coprocessorContextLifecycle, activeContextId);
+        // Re-activate the suspended coprocessor context and suspend the (problematic) active context
+        ContextLifecycle.setActiveAndSuspended($.coprocessorContextLifecycle, suspendedContextId, activeContextId);
 
         // Define the deactivation block timestamp for the current active coprocessor context
         uint256 deactivatedBlockTimestamp = block.timestamp + suspendedTimePeriod;
         $.coprocessorContextDeactivatedBlockTimestamp[activeContextId] = deactivatedBlockTimestamp;
 
         emit SuspendCoprocessorContext(activeContextId, deactivatedBlockTimestamp);
-
-        // Re-activate the suspended coprocessor context
-        ContextLifecycle.setActive($.coprocessorContextLifecycle, suspendedContextId);
         emit ActivateCoprocessorContext(suspendedContextId);
     }
 

gateway-contracts/contracts/interfaces/ICoprocessorContexts.sol

@@ -232,19 +232,14 @@ interface ICoprocessorContexts {
 
     /**
      * @notice Manually force the status update of a coprocessor context.
-     * ⚠️ This function should be used with caution as it can lead to unexpected behaviors if not
-     * used correctly. ⚠️
-     * Hence, prior to using this function, the caller should make sure that:
-     * - the status update is not against any of the lifecycle's rules (else it will revert)
-     * - the usually expected requirements (in the whole protocol) for the status update are met
-     * Additionally:
-     * - this function expects the context to already have been added and thus will revert if the
-     * targeted status does not reflect that
-     * - if a status update needs to be associated to a block timestamp, the current block timestamp
-     * will be used (i.e., the status update is immediate)
+     * This function reverts if
+     * - the status update is against any of the lifecycle's rules
+     * - the context has not been added yet
      * The following context status updates are only possible through this function:
      * - Compromised
      * - Destroyed
+     * Additionally, if a status update needs to be associated to a block timestamp, the current
+     * block timestamp is used (i.e., the status update is immediate)
      * @param contextId The ID of the coprocessor context to update.
      * @param status The status to update the coprocessor context to.
      */

gateway-contracts/contracts/libraries/ContextLifecycle.sol

@@ -48,6 +48,11 @@ library ContextLifecycle {
      */
     error PreActivationContextOngoing(uint256 preActivationContextId);
 
+    /**
+     * @notice Error indicating that an active context is ongoing.
+     */
+    error ActiveContextOngoing(uint256 activeContextId);
+
     /**
      * @notice Error indicating that a suspended context is ongoing.
      */
@@ -170,7 +175,7 @@ library ContextLifecycle {
     ) internal onlyNonNullContextId(contextId) {
         // This function should only be called if there is no active context yet
         if ($.activeContextId != 0) {
-            revert ContextIsActive($.activeContextId);
+            revert ActiveContextOngoing($.activeContextId);
         }
 
         $.contextStatuses[contextId] = ContextStatus.Active;
@@ -182,12 +187,18 @@ library ContextLifecycle {
      * @dev There should only be one active context at a time.
      * @param contextId The ID of the context to set as active.
      */
-    function setActive(ContextLifecycleStorage storage $, uint256 contextId) internal onlyNonNullContextId(contextId) {
+    function _setActive(ContextLifecycleStorage storage $, uint256 contextId) internal onlyNonNullContextId(contextId) {
         // Only a pre-activated or suspended context can be set as active
         if (!isPreActivation($, contextId) && !isSuspended($, contextId)) {
             revert ContextNotPreActivatedOrSuspended(contextId);
         }
 
+        // There should only be one active context at a time. The old active context must be suspended
+        // first before a new active context can be set.
+        if ($.activeContextId != 0) {
+            revert ActiveContextOngoing($.activeContextId);
+        }
+
         $.contextStatuses[contextId] = ContextStatus.Active;
         $.activeContextId = contextId;
 
@@ -205,13 +216,13 @@ library ContextLifecycle {
     /**
      * @notice Sets the context as suspended.
      * ⚠️ This function should be used with caution as it can lead to unexpected behaviors if not
-     * used correctly. ⚠️
+     * used correctly. Use `setActiveAndSuspended` instead. ⚠️
      * A suspended context is expected to always be followed by a context activation in order to
      * avoid having a state where no active context is available, which should never happen.
      * @dev There can only be one suspended context at a time.
      * @param contextId The ID of the context to set as suspended.
      */
-    function setSuspended(
+    function _setSuspended(
         ContextLifecycleStorage storage $,
         uint256 contextId
     ) internal onlyNonNullContextId(contextId) {
@@ -227,6 +238,22 @@ library ContextLifecycle {
         $.activeContextId = 0;
     }
 
+    /**
+     * @notice Sets the contexts as active and suspended.
+     * @dev This function should be favored over setting the contexts separately as it ensures that
+     * there is always a (single) active context.
+     * @param contextIdToActivate The ID of the context to set as active.
+     * @param contextIdToSuspend The ID of the context to set as suspended.
+     */
+    function setActiveAndSuspended(
+        ContextLifecycleStorage storage $,
+        uint256 contextIdToActivate,
+        uint256 contextIdToSuspend
+    ) internal {
+        _setSuspended($, contextIdToSuspend);
+        _setActive($, contextIdToActivate);
+    }
+
     /**
      * @notice Sets the context as deactivated.
      * @dev There can be multiple deactivated contexts at the same time.

gateway-contracts/contracts/mocks/CoprocessorContextsMock.sol

@@ -61,10 +61,10 @@ contract CoprocessorContextsMock {
     function forceUpdateContextToStatus(uint256 contextId, ContextStatus status) external {
         uint256 deactivatedBlockTimestamp;
 
-        emit ActivateCoprocessorContext(contextId);
-
         emit SuspendCoprocessorContext(contextId, deactivatedBlockTimestamp);
 
+        emit ActivateCoprocessorContext(contextId);
+
         emit DeactivateCoprocessorContext(contextId);
 
         emit CompromiseCoprocessorContext(contextId);

gateway-contracts/docs/.assets/lifecycle_contexts.png

@@ -91,7 +91,10 @@ Additionally:
 - in case of emergency (ex: bad software update), the owner can directly move a context from `suspended` back to `active`, which deactivates the context with issues.
 - an `active` context cannot be set to `compromised`,`deactivated` or `destroyed`, in order to ensure that the fhevm Gateway always has one active context.
 
-The complete lifecycle of a coprocessor context is represented in the following diagram:
+The complete lifecycle of a coprocessor context is represented in the following diagram, with the following legend:
+
+- _Red_: Automated status update
+- _Black_: Manual only status update
 
 ![Context lifecycle](../../.assets/lifecycle_contexts.png)