Merge pull request #7 from flare-foundation:0.1.41

Update version to 0.1.41

Author: fassko

foundry.toml

@@ -1,6 +1,6 @@
 [package]
 name = "flare-periphery"
-version = "0.1.40"
+version = "0.1.41"
 
 [profile.default]
 src = "src"

src/coston/IAssetManager.sol

@@ -154,6 +154,12 @@ interface IAssetManager is
      * to prevent current block being too outdated, which gives too short time for
      * minting or redemption payment.
      * NOTE: anybody can call.
+     * NOTE: the block/timestamp will only be updated if it is strictly higher than the current value.
+     * For mintings and redemptions we also add the duration from the last update (on this chain) to compensate
+     * for the time that passed since the last update. This mechanism can be abused by providing old block proof
+     * as fresh, which will distort the compensation accounting. Due to monotonicity such an attack will only work
+     * if there was no block update for some time. Therefore it is enough to have at least one honest
+     * current block updater regularly providing updates to avoid this issue.
      * @param _proof proof that a block with given number and timestamp exists
      */
     function updateCurrentBlock(
@@ -304,17 +310,18 @@ interface IAssetManager is
         returns (uint256 _withdrawalAllowedAt);
 
     /**
-     * The agent is going to redeem `_valueWei` collateral pool tokens in the agent vault.
-     * This has to be announced and the agent must then wait `withdrawalWaitMinSeconds` time.
-     * After that time, the agent can call `redeemCollateralPoolTokens(_valueNATWei)` on the agent vault.
+     * Agent is going to withdraw `_valuePoolTokenWei` of pool tokens from the agent vault
+     * and redeem them for NAT from the collateral pool.
+     * This has to be announced and the agent must then wait `withdrawalWaitMinSeconds`.
+     * After that time, the agent can call redeemCollateralPoolTokens(_valuePoolTokenWei) on agent vault.
      * NOTE: may only be called by the agent vault owner.
      * @param _agentVault agent vault address
-     * @param _valueNATWei the amount to be withdrawn
+     * @param _valuePoolTokenWei the amount to be withdrawn
      * @return _redemptionAllowedAt the timestamp when the redemption can be made
      */
     function announceAgentPoolTokenRedemption(
         address _agentVault,
-        uint256 _valueNATWei
+        uint256 _valuePoolTokenWei
     ) external
         returns (uint256 _redemptionAllowedAt);
 
@@ -379,7 +386,7 @@ interface IAssetManager is
     // Agent information
 
     /**
-     * Get (a part of) the list of all agents.
+     * Get (a part of) the list of all active (not destroyed) agents.
      * The list must be retrieved in parts since retrieving the whole list can consume too much gas for one block.
      * @param _start first index to return from the available agent's list
      * @param _end end index (one above last) to return from the available agent's list
@@ -540,6 +547,9 @@ interface IAssetManager is
      * If the minter pays the underlying amount, minter obtains f-assets.
      * The collateral reservation fee is split between the agent and the collateral pool.
      * NOTE: the owner of the agent vault must be in the AgentOwnerRegistry.
+     * NOTE: if the underlying block isn't updated regularly, it can happen that there is not enough time for
+     * the underlying payment. Therefore minters have to verify the current underlying before minting and,
+     * if needed, update it by calling `updateCurrentBlock`.
      * @param _agentVault agent vault address
      * @param _lots the number of lots for which to reserve collateral
      * @param _maxMintingFeeBIPS maximum minting fee (BIPS) that can be charged by the agent - best is just to
@@ -687,6 +697,9 @@ interface IAssetManager is
      * of remaining lots.
      * Agent receives redemption request id and instructions for underlying payment in
      * RedemptionRequested event and has to pay `value - fee` and use the provided payment reference.
+     * NOTE: if the underlying block isn't updated regularly, it can happen that there is no time for underlying
+     * payment. Since the agents cannot know when the next redemption will happen, they should regularly update the
+     * underlying time by obtaining fresh proof of latest underlying block and calling `updateCurrentBlock`.
      * @param _lots number of lots to redeem
      * @param _redeemerUnderlyingAddressString the address to which the agent must transfer underlying amount
      * @param _executor the account that is allowed to execute redemption default (besides redeemer and agent)
@@ -850,7 +863,7 @@ interface IAssetManager is
      * 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.
+     * NOTE: this method can be called by the governance or its executor.
      * @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

src/coston/IAssetManagerController.sol

@@ -5,6 +5,9 @@ import {IAssetManager} from "./IAssetManager.sol";
 
 
 interface IAssetManagerController {
+    event AssetManagerAdded(address assetManager);
+    event AssetManagerRemoved(address assetManager);
+
     /**
      * Return the list of all asset managers managed by this controller.
      */

src/coston/IAssetManagerEvents.sol

@@ -525,4 +525,14 @@ interface IAssetManagerEvents {
      * Emergency pause was canceled.
      */
     event EmergencyPauseCanceled();
+
+    /**
+     * Emergency pause total duration was reset by the governance.
+     */
+    event EmergencyPauseTotalDurationReset();
+
+    /**
+     * Minting was paused/unpaused by the governance.
+     */
+    event MintingPaused(bool paused);
 }

src/coston2/IAssetManager.sol

@@ -154,6 +154,12 @@ interface IAssetManager is
      * to prevent current block being too outdated, which gives too short time for
      * minting or redemption payment.
      * NOTE: anybody can call.
+     * NOTE: the block/timestamp will only be updated if it is strictly higher than the current value.
+     * For mintings and redemptions we also add the duration from the last update (on this chain) to compensate
+     * for the time that passed since the last update. This mechanism can be abused by providing old block proof
+     * as fresh, which will distort the compensation accounting. Due to monotonicity such an attack will only work
+     * if there was no block update for some time. Therefore it is enough to have at least one honest
+     * current block updater regularly providing updates to avoid this issue.
      * @param _proof proof that a block with given number and timestamp exists
      */
     function updateCurrentBlock(
@@ -304,17 +310,18 @@ interface IAssetManager is
         returns (uint256 _withdrawalAllowedAt);
 
     /**
-     * The agent is going to redeem `_valueWei` collateral pool tokens in the agent vault.
-     * This has to be announced and the agent must then wait `withdrawalWaitMinSeconds` time.
-     * After that time, the agent can call `redeemCollateralPoolTokens(_valueNATWei)` on the agent vault.
+     * Agent is going to withdraw `_valuePoolTokenWei` of pool tokens from the agent vault
+     * and redeem them for NAT from the collateral pool.
+     * This has to be announced and the agent must then wait `withdrawalWaitMinSeconds`.
+     * After that time, the agent can call redeemCollateralPoolTokens(_valuePoolTokenWei) on agent vault.
      * NOTE: may only be called by the agent vault owner.
      * @param _agentVault agent vault address
-     * @param _valueNATWei the amount to be withdrawn
+     * @param _valuePoolTokenWei the amount to be withdrawn
      * @return _redemptionAllowedAt the timestamp when the redemption can be made
      */
     function announceAgentPoolTokenRedemption(
         address _agentVault,
-        uint256 _valueNATWei
+        uint256 _valuePoolTokenWei
     ) external
         returns (uint256 _redemptionAllowedAt);
 
@@ -379,7 +386,7 @@ interface IAssetManager is
     // Agent information
 
     /**
-     * Get (a part of) the list of all agents.
+     * Get (a part of) the list of all active (not destroyed) agents.
      * The list must be retrieved in parts since retrieving the whole list can consume too much gas for one block.
      * @param _start first index to return from the available agent's list
      * @param _end end index (one above last) to return from the available agent's list
@@ -540,6 +547,9 @@ interface IAssetManager is
      * If the minter pays the underlying amount, minter obtains f-assets.
      * The collateral reservation fee is split between the agent and the collateral pool.
      * NOTE: the owner of the agent vault must be in the AgentOwnerRegistry.
+     * NOTE: if the underlying block isn't updated regularly, it can happen that there is not enough time for
+     * the underlying payment. Therefore minters have to verify the current underlying before minting and,
+     * if needed, update it by calling `updateCurrentBlock`.
      * @param _agentVault agent vault address
      * @param _lots the number of lots for which to reserve collateral
      * @param _maxMintingFeeBIPS maximum minting fee (BIPS) that can be charged by the agent - best is just to
@@ -687,6 +697,9 @@ interface IAssetManager is
      * of remaining lots.
      * Agent receives redemption request id and instructions for underlying payment in
      * RedemptionRequested event and has to pay `value - fee` and use the provided payment reference.
+     * NOTE: if the underlying block isn't updated regularly, it can happen that there is no time for underlying
+     * payment. Since the agents cannot know when the next redemption will happen, they should regularly update the
+     * underlying time by obtaining fresh proof of latest underlying block and calling `updateCurrentBlock`.
      * @param _lots number of lots to redeem
      * @param _redeemerUnderlyingAddressString the address to which the agent must transfer underlying amount
      * @param _executor the account that is allowed to execute redemption default (besides redeemer and agent)
@@ -850,7 +863,7 @@ interface IAssetManager is
      * 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.
+     * NOTE: this method can be called by the governance or its executor.
      * @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

src/coston2/IAssetManagerController.sol

@@ -5,6 +5,9 @@ import {IAssetManager} from "./IAssetManager.sol";
 
 
 interface IAssetManagerController {
+    event AssetManagerAdded(address assetManager);
+    event AssetManagerRemoved(address assetManager);
+
     /**
      * Return the list of all asset managers managed by this controller.
      */

src/coston2/IAssetManagerEvents.sol

@@ -525,4 +525,14 @@ interface IAssetManagerEvents {
      * Emergency pause was canceled.
      */
     event EmergencyPauseCanceled();
+
+    /**
+     * Emergency pause total duration was reset by the governance.
+     */
+    event EmergencyPauseTotalDurationReset();
+
+    /**
+     * Minting was paused/unpaused by the governance.
+     */
+    event MintingPaused(bool paused);
 }

src/coston2/ICustomInstructionsFacet.sol

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.8.4 <0.9;
+
+/**
+ * @title ICustomInstructionsFacet
+ * @notice Interface for the CustomInstructionsFacet contract.
+ */
+interface ICustomInstructionsFacet {
+
+    /// @notice Struct containing custom call information
+    struct CustomCall {
+        /// @notice Target contract address
+        address targetContract;
+        /// @notice value (in wei) to send with the call
+        uint256 value;
+        /// @notice Call data
+        bytes data;
+    }
+
+    /**
+     * @notice Emitted when a custom instruction is registered.
+     * @param customInstructionHash The hash representing the registered instructions.
+     */
+    event CustomInstructionRegistered(bytes32 indexed customInstructionHash);
+
+    /**
+     * @notice Emitted when a custom instruction is already registered.
+     * @param customInstructionHash The hash representing the already registered instructions.
+     */
+    event CustomInstructionAlreadyRegistered(bytes32 indexed customInstructionHash);
+
+    /**
+     * @notice Reverts if the custom instruction is empty (zero custom calls).
+     */
+    error EmptyCustomInstruction();
+
+    /**
+     * @notice Reverts if the target address of a custom call is zero.
+     */
+    error TargetAddressZero();
+
+    /**
+     * @notice Reverts if the target address of a custom call is not a contract.
+     * @param target The target address.
+     */
+    error TargetNotAContract(address target);
+
+    /**
+     * @notice Register custom instruction and return the call hash.
+     * @param _customInstruction Custom instruction (array of custom calls) to register.
+     * @return _customInstructionHash The hash representing the registered custom instruction.
+     */
+    function registerCustomInstruction(
+        CustomCall[] memory _customInstruction
+    ) external returns (bytes32 _customInstructionHash);
+
+    /**
+     * @notice Get a custom instruction for a given call hash.
+     * @param _customInstructionHash The hash representing the custom instruction.
+     * @return _customInstruction Custom instruction (array of custom calls) for the hash.
+     */
+    function getCustomInstruction(
+        bytes32 _customInstructionHash
+    ) external view returns (CustomCall[] memory _customInstruction);
+    /**
+     * @notice Get paginated custom instruction hashes.
+     * @param _start The starting index.
+     * @param _end The ending index.
+     * @return _customInstructionHashes Array of custom instruction hashes for the requested page.
+     * @return _totalLength The total number of custom instruction hashes.
+     */
+    function getCustomInstructionHashes(
+        uint256 _start,
+        uint256 _end
+    ) external view returns (bytes32[] memory _customInstructionHashes, uint256 _totalLength);
+
+    /**
+     * @notice Encode a custom instruction to get its call hash.
+     * @param _customInstruction Custom instruction (array of custom calls) to encode.
+     * @return _customInstructionHash The hash representing the custom instruction.
+     */
+    function encodeCustomInstruction(
+        CustomCall[] memory _customInstruction
+    ) external pure returns (bytes32 _customInstructionHash);
+}

src/coston2/IInstructionsFacet.sol

@@ -2,6 +2,7 @@
 pragma solidity >=0.8.4 <0.9;
 
 import {IPayment} from "./IPayment.sol";
+import {ICustomInstructionsFacet} from "./ICustomInstructionsFacet.sol";
 
 /**
  * @title IInstructionsFacet
@@ -173,6 +174,18 @@ interface IInstructionsFacet {
         uint256 amount
     );
 
+    /**
+     * @notice Emitted when a custom instruction is executed.
+     * @param personalAccount The personal account address.
+     * @param callHash The call hash of the custom instruction.
+     * @param customInstruction The custom instruction.
+     */
+    event CustomInstructionExecuted(
+        address indexed personalAccount,
+        bytes32 indexed callHash,
+        ICustomInstructionsFacet.CustomCall[] customInstruction
+    );
+
     /**
      * @notice Reverts if the payment amount is invalid.
      * @param requiredAmount The required payment amount.
@@ -239,6 +252,11 @@ interface IInstructionsFacet {
      */
     error InvalidMinter();
 
+    /**
+     * @notice Reverts if the provided custom instruction hash is invalid (not registered).
+     */
+    error InvalidCustomInstructionHash();
+
     /**
      * @notice Reserve collateral for minting operation.
      * @param _xrplAddress The XRPL address requesting the collateral reservation.

src/coston2/IMasterAccountController.sol

@@ -16,6 +16,7 @@ import {ISwapFacet} from "./ISwapFacet.sol";
 import {ITimelockFacet} from "./ITimelockFacet.sol";
 import {IVaultsFacet} from "./IVaultsFacet.sol";
 import {IXrplProviderWalletsFacet} from "./IXrplProviderWalletsFacet.sol";
+import {ICustomInstructionsFacet} from "./ICustomInstructionsFacet.sol";
 
 /**
  * @title IMasterAccountController
@@ -36,5 +37,6 @@ interface IMasterAccountController is
     ISwapFacet,
     ITimelockFacet,
     IVaultsFacet,
-    IXrplProviderWalletsFacet
+    IXrplProviderWalletsFacet,
+    ICustomInstructionsFacet
 {}