Add EmergencyPause functionality and related events to IAssetManager and IAssetManagerEvents interfaces. Introduce consolidateSmallTickets method for managing small redemption tickets. Update AssetManagerSettings and CollateralType to reflect changes in token invalidation handling.

Author: fassko

coston/IAssetManager.sol

@@ -12,6 +12,7 @@ import {AvailableAgentInfo} from "./data/AvailableAgentInfo.sol";
 import {RedemptionTicketInfo} from "./data/RedemptionTicketInfo.sol";
 import {RedemptionRequestInfo} from "./data/RedemptionRequestInfo.sol";
 import {CollateralReservationInfo} from "./data/CollateralReservationInfo.sol";
+import {EmergencyPause} from "./data/EmergencyPause.sol";
 import {IAssetManagerEvents} from "./IAssetManagerEvents.sol";
 import {IAgentPing} from "./IAgentPing.sol";
 import {IRedemptionTimeExtension} from "./IRedemptionTimeExtension.sol";
@@ -96,22 +97,18 @@ interface IAssetManager is
     function emergencyPaused() external view returns (bool);
 
     /**
-     * The time when emergency pause mode will end automatically.
-     */
-    function emergencyPausedUntil() external view returns (uint256);
-
-    ////////////////////////////////////////////////////////////////////////////////////
-    // Emergency pause transfers
-
-    /**
-     * If true, the system is in emergency pause mode and most operations (mint, redeem, liquidate) are disabled.
+     * Emergency pause level defines which operations are paused:
+     * NONE - pause is not active,
+     * START_OPERATIONS - prevent starting mint, redeem, liquidation (start/liquidate) and core vault transfer/return,
+     * FULL - everything from START_OPERATIONS, plus prevent finishing or defulating already started mints and redeems,
+     * FULL_AND_TRANSFER - everything from FULL, plus prevent FAsset transfers.
      */
-    function transfersEmergencyPaused() external view returns (bool);
+    function emergencyPauseLevel() external view returns (EmergencyPause.Level);
 
     /**
      * The time when emergency pause mode will end automatically.
      */
-    function transfersEmergencyPausedUntil() external view returns (uint256);
+    function emergencyPausedUntil() external view returns (uint256);
 
     ////////////////////////////////////////////////////////////////////////////////////
     // Asset manager upgrading state
@@ -264,13 +261,6 @@ interface IAssetManager is
         string memory _name
     ) external;
 
-    /**
-     * If the current agent's vault collateral token gets deprecated, the agent must switch with this method.
-     * NOTE: may only be called by the agent vault owner.
-     * NOTE: at the time of switch, the agent must have enough of both collaterals in the vault.
-     */
-    function switchVaultCollateral(address _agentVault, IERC20 _token) external;
-
     /**
      * When current pool collateral token contract (WNat) is replaced by the method setPoolWNatCollateralType,
      * pools don't switch automatically. Instead, the agent must call this method that swaps old WNat tokens for
@@ -808,7 +798,7 @@ interface IAssetManager is
         );
 
     ////////////////////////////////////////////////////////////////////////////////////
-    // Dust
+    // Dust and small ticket management
 
     /**
      * Due to the minting pool fees or after a lot size change by the governance,
@@ -824,6 +814,20 @@ interface IAssetManager is
      */
     function convertDustToTicket(address _agentVault) external;
 
+    /**
+     * If lot size is increased, there may be many tickets less than one lot in the queue.
+     * In extreme cases, this could prevent redemptions, if there weren't any tickets above 1 lot
+     * among the first `maxRedeemedTickets` tickets.
+     * To fix this, call this method. It converts small tickets to dust and when the dust exceeds one lot
+     * adds it to the ticket.
+     * Since the method just cleans the redemption queue it can be called by anybody.
+     * @param _firstTicketId if nonzero, the ticket id of starting ticket; if zero, the starting ticket will
+     *   be the redemption queue's first ticket id.
+     *   When the method finishes, it emits RedemptionTicketsConsolidated event with the nextTicketId
+     *   parameter. If it is nonzero, the method should be invoked again with this value as _firstTicketId.
+     */
+    function consolidateSmallTickets(uint256 _firstTicketId) external;
+
     ////////////////////////////////////////////////////////////////////////////////////
     // Liquidation
 

coston/IAssetManagerEvents.sol

@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: MIT
 pragma solidity >=0.7.6 <0.9;
 
+import {EmergencyPause} from "./data/EmergencyPause.sol";
+
 /**
  * All asset manager events.
  */
@@ -337,6 +339,16 @@ interface IAssetManagerEvents {
         uint256 indexed redemptionTicketId
     );
 
+    /**
+     * Method `consolidateSmallTickets` has finished.
+     * @param firstTicketId first handled ticket id (different from the method param _firstTicketId if it was 0).
+     * @param nextTicketId the first remaining (not handled) ticket id, or 0 if the end of queue was reached.
+     */
+    event RedemptionTicketsConsolidated(
+        uint256 firstTicketId,
+        uint256 nextTicketId
+    );
+
     /**
      * Due to lot size change, some dust was created for this agent during
      * redemption. Value `dustUBA` is the new amount of dust. Dust cannot be directly redeemed,
@@ -512,33 +524,18 @@ interface IAssetManagerEvents {
         uint256 safetyMinCollateralRatioBIPS
     );
 
-    /**
-     * Collateral token has been marked as deprecated. After the timestamp `validUntil` passes, it will be
-     * considered invalid and the agents who haven't switched their collateral before will be liquidated.
-     */
-    event CollateralTypeDeprecated(
-        uint8 collateralClass,
-        address collateralToken,
-        uint256 validUntil
-    );
-
     /**
      * Emergency pause was triggered.
      */
-    event EmergencyPauseTriggered(uint256 pausedUntil);
+    event EmergencyPauseTriggered(
+        EmergencyPause.Level externalLevel,
+        uint256 externalPausedUntil,
+        EmergencyPause.Level governanceLevel,
+        uint256 governancePausedUntil
+    );
 
     /**
      * Emergency pause was canceled.
      */
     event EmergencyPauseCanceled();
-
-    /**
-     * Emergency pause transfers was triggered.
-     */
-    event EmergencyPauseTransfersTriggered(uint256 pausedUntil);
-
-    /**
-     * Emergency pause transfers was canceled.
-     */
-    event EmergencyPauseTransfersCanceled();
 }

coston/data/AssetManagerSettings.sol

@@ -170,11 +170,11 @@ library AssetManagerSettings {
         // Shouldn't be much bigger than Flare data connector response time, so that payments can be confirmed without
         // extra wait. Should be smaller than confirmationByOthersAfterSeconds (e.g. less than 1 hour).
         // rate-limited
-        uint64 __announcedUnderlyingConfirmationMinSeconds;
+        uint64 __announcedUnderlyingConfirmationMinSeconds; // only storage placeholder
         // Minimum time from the moment token is deprecated to when it becomes invalid and agents still using
         // it as vault collateral get liquidated.
         // timelocked
-        uint64 tokenInvalidationTimeMinSeconds;
+        uint64 __tokenInvalidationTimeMinSeconds; // only storage placeholder
         // On some rare occasions (stuck minting), the agent has to unlock collateral.
         // For this, part of collateral corresponding to FTSO asset value is burned and the rest is released.
         // However, we cannot burn typical vault collateral (stablecoins), so the agent must buy them for NAT

coston/data/CollateralType.sol

@@ -18,7 +18,7 @@ library CollateralType {
         IERC20 token;
         // Same as token.decimals(), when that exists.
         uint256 decimals;
-        // Token invalidation time. Must be 0 on creation.
+        // Token invalidation time. Should always be 0 since token invalidation is deprecated.
         uint256 validUntil;
         // When `true`, the FTSO with symbol `assetFtsoSymbol` returns asset price relative to this token
         // (such FTSO's will probably exist for major stablecoins).

coston/data/EmergencyPause.sol

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.7.6 <0.9;
+
+library EmergencyPause {
+    enum Level {
+        // Pause is not active.
+        NONE,
+        // Prevent starting mint, redeem, liquidation and core vault transfer/return.
+        START_OPERATIONS,
+        // Everything from START_OPERATIONS, plus prevent finishing or defulating already started mints and redeems.
+        FULL,
+        // Everything from FULL, plus prevent FAsset transfers.
+        FULL_AND_TRANSFER
+    }
+}

coston2/IAssetManager.sol

@@ -12,6 +12,7 @@ import {AvailableAgentInfo} from "./data/AvailableAgentInfo.sol";
 import {RedemptionTicketInfo} from "./data/RedemptionTicketInfo.sol";
 import {RedemptionRequestInfo} from "./data/RedemptionRequestInfo.sol";
 import {CollateralReservationInfo} from "./data/CollateralReservationInfo.sol";
+import {EmergencyPause} from "./data/EmergencyPause.sol";
 import {IAssetManagerEvents} from "./IAssetManagerEvents.sol";
 import {IAgentPing} from "./IAgentPing.sol";
 import {IRedemptionTimeExtension} from "./IRedemptionTimeExtension.sol";
@@ -96,22 +97,18 @@ interface IAssetManager is
     function emergencyPaused() external view returns (bool);
 
     /**
-     * The time when emergency pause mode will end automatically.
-     */
-    function emergencyPausedUntil() external view returns (uint256);
-
-    ////////////////////////////////////////////////////////////////////////////////////
-    // Emergency pause transfers
-
-    /**
-     * If true, the system is in emergency pause mode and most operations (mint, redeem, liquidate) are disabled.
+     * Emergency pause level defines which operations are paused:
+     * NONE - pause is not active,
+     * START_OPERATIONS - prevent starting mint, redeem, liquidation (start/liquidate) and core vault transfer/return,
+     * FULL - everything from START_OPERATIONS, plus prevent finishing or defulating already started mints and redeems,
+     * FULL_AND_TRANSFER - everything from FULL, plus prevent FAsset transfers.
      */
-    function transfersEmergencyPaused() external view returns (bool);
+    function emergencyPauseLevel() external view returns (EmergencyPause.Level);
 
     /**
      * The time when emergency pause mode will end automatically.
      */
-    function transfersEmergencyPausedUntil() external view returns (uint256);
+    function emergencyPausedUntil() external view returns (uint256);
 
     ////////////////////////////////////////////////////////////////////////////////////
     // Asset manager upgrading state
@@ -264,13 +261,6 @@ interface IAssetManager is
         string memory _name
     ) external;
 
-    /**
-     * If the current agent's vault collateral token gets deprecated, the agent must switch with this method.
-     * NOTE: may only be called by the agent vault owner.
-     * NOTE: at the time of switch, the agent must have enough of both collaterals in the vault.
-     */
-    function switchVaultCollateral(address _agentVault, IERC20 _token) external;
-
     /**
      * When current pool collateral token contract (WNat) is replaced by the method setPoolWNatCollateralType,
      * pools don't switch automatically. Instead, the agent must call this method that swaps old WNat tokens for
@@ -808,7 +798,7 @@ interface IAssetManager is
         );
 
     ////////////////////////////////////////////////////////////////////////////////////
-    // Dust
+    // Dust and small ticket management
 
     /**
      * Due to the minting pool fees or after a lot size change by the governance,
@@ -824,6 +814,20 @@ interface IAssetManager is
      */
     function convertDustToTicket(address _agentVault) external;
 
+    /**
+     * If lot size is increased, there may be many tickets less than one lot in the queue.
+     * In extreme cases, this could prevent redemptions, if there weren't any tickets above 1 lot
+     * among the first `maxRedeemedTickets` tickets.
+     * To fix this, call this method. It converts small tickets to dust and when the dust exceeds one lot
+     * adds it to the ticket.
+     * Since the method just cleans the redemption queue it can be called by anybody.
+     * @param _firstTicketId if nonzero, the ticket id of starting ticket; if zero, the starting ticket will
+     *   be the redemption queue's first ticket id.
+     *   When the method finishes, it emits RedemptionTicketsConsolidated event with the nextTicketId
+     *   parameter. If it is nonzero, the method should be invoked again with this value as _firstTicketId.
+     */
+    function consolidateSmallTickets(uint256 _firstTicketId) external;
+
     ////////////////////////////////////////////////////////////////////////////////////
     // Liquidation
 

coston2/IAssetManagerEvents.sol

@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: MIT
 pragma solidity >=0.7.6 <0.9;
 
+import {EmergencyPause} from "./data/EmergencyPause.sol";
+
 /**
  * All asset manager events.
  */
@@ -337,6 +339,16 @@ interface IAssetManagerEvents {
         uint256 indexed redemptionTicketId
     );
 
+    /**
+     * Method `consolidateSmallTickets` has finished.
+     * @param firstTicketId first handled ticket id (different from the method param _firstTicketId if it was 0).
+     * @param nextTicketId the first remaining (not handled) ticket id, or 0 if the end of queue was reached.
+     */
+    event RedemptionTicketsConsolidated(
+        uint256 firstTicketId,
+        uint256 nextTicketId
+    );
+
     /**
      * Due to lot size change, some dust was created for this agent during
      * redemption. Value `dustUBA` is the new amount of dust. Dust cannot be directly redeemed,
@@ -512,33 +524,18 @@ interface IAssetManagerEvents {
         uint256 safetyMinCollateralRatioBIPS
     );
 
-    /**
-     * Collateral token has been marked as deprecated. After the timestamp `validUntil` passes, it will be
-     * considered invalid and the agents who haven't switched their collateral before will be liquidated.
-     */
-    event CollateralTypeDeprecated(
-        uint8 collateralClass,
-        address collateralToken,
-        uint256 validUntil
-    );
-
     /**
      * Emergency pause was triggered.
      */
-    event EmergencyPauseTriggered(uint256 pausedUntil);
+    event EmergencyPauseTriggered(
+        EmergencyPause.Level externalLevel,
+        uint256 externalPausedUntil,
+        EmergencyPause.Level governanceLevel,
+        uint256 governancePausedUntil
+    );
 
     /**
      * Emergency pause was canceled.
      */
     event EmergencyPauseCanceled();
-
-    /**
-     * Emergency pause transfers was triggered.
-     */
-    event EmergencyPauseTransfersTriggered(uint256 pausedUntil);
-
-    /**
-     * Emergency pause transfers was canceled.
-     */
-    event EmergencyPauseTransfersCanceled();
 }

coston2/data/AssetManagerSettings.sol

@@ -170,11 +170,11 @@ library AssetManagerSettings {
         // Shouldn't be much bigger than Flare data connector response time, so that payments can be confirmed without
         // extra wait. Should be smaller than confirmationByOthersAfterSeconds (e.g. less than 1 hour).
         // rate-limited
-        uint64 __announcedUnderlyingConfirmationMinSeconds;
+        uint64 __announcedUnderlyingConfirmationMinSeconds; // only storage placeholder
         // Minimum time from the moment token is deprecated to when it becomes invalid and agents still using
         // it as vault collateral get liquidated.
         // timelocked
-        uint64 tokenInvalidationTimeMinSeconds;
+        uint64 __tokenInvalidationTimeMinSeconds; // only storage placeholder
         // On some rare occasions (stuck minting), the agent has to unlock collateral.
         // For this, part of collateral corresponding to FTSO asset value is burned and the rest is released.
         // However, we cannot burn typical vault collateral (stablecoins), so the agent must buy them for NAT

coston2/data/CollateralType.sol

@@ -18,7 +18,7 @@ library CollateralType {
         IERC20 token;
         // Same as token.decimals(), when that exists.
         uint256 decimals;
-        // Token invalidation time. Must be 0 on creation.
+        // Token invalidation time. Should always be 0 since token invalidation is deprecated.
         uint256 validUntil;
         // When `true`, the FTSO with symbol `assetFtsoSymbol` returns asset price relative to this token
         // (such FTSO's will probably exist for major stablecoins).

coston2/data/EmergencyPause.sol

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.7.6 <0.9;
+
+library EmergencyPause {
+    enum Level {
+        // Pause is not active.
+        NONE,
+        // Prevent starting mint, redeem, liquidation and core vault transfer/return.
+        START_OPERATIONS,
+        // Everything from START_OPERATIONS, plus prevent finishing or defulating already started mints and redeems.
+        FULL,
+        // Everything from FULL, plus prevent FAsset transfers.
+        FULL_AND_TRANSFER
+    }
+}