receiver/offramp

Author: RensR

chains/evm/contracts/applications/CCIPClientExampleWithCCVs.sol

@@ -104,11 +104,11 @@ contract CCIPClientExampleWithCCVs is CCIPClientExample {
     }
   }
 
-  /// @notice Provides the required and optional CCVs and min block confirmations for a source chain.
+  /// @notice Provides the required and optional CCVs and allowed finality config for a source chain.
   /// @dev OffRamp will apply the defaults for the lane if no CCVs are defined for a source chain.
-  /// @dev WARNING: minBlockConfirmations must be used carefully, when in doubt it's safer to require finality (minBlockConfirmations = 0) than
+  /// @dev WARNING: allowedFinalityConfig must be used carefully, when in doubt it's safer to require finality (allowedFinalityConfig = bytes2(0)) than
   /// to allow FTF messages (any non-zero value) as FTF messages can be reorged.
-  function getCCVsAndMinBlockConfirmations(
+  function getCCVsAndFinalityConfig(
     uint64 sourceChainSelector,
     bytes calldata
   )
@@ -120,14 +120,14 @@ contract CCIPClientExampleWithCCVs is CCIPClientExample {
       address[] memory requiredCCVs,
       address[] memory optionalCCVs,
       uint8 optionalThreshold,
-      uint16 minBlockConfirmations
+      bytes2 allowedFinalityConfig
     )
   {
     CCVConfig memory config = s_ccvConfigs[sourceChainSelector];
-    // If allowFasterThanFinality is true, minBlockConfirmations = 1 (allow any FTF level) - WARNING only use a finality of 1 when
+    // If allowFasterThanFinality is true, allowedFinalityConfig = bytes2(uint16(1)) (allow any FTF level) - WARNING only use a finality of 1 when
     // you use a trusted sender on the source chain that manages the finality risk when sending messages.
-    // If allowFasterThanFinality is false, minBlockConfirmations = 0 (require finality).
-    minBlockConfirmations = config.allowFasterThanFinality ? 1 : 0;
-    return (config.requiredCCVs, config.optionalCCVs, config.optionalThreshold, minBlockConfirmations);
+    // If allowFasterThanFinality is false, allowedFinalityConfig = bytes2(0) (require finality).
+    allowedFinalityConfig = config.allowFasterThanFinality ? bytes2(uint16(1)) : bytes2(0);
+    return (config.requiredCCVs, config.optionalCCVs, config.optionalThreshold, allowedFinalityConfig);
   }
 }

chains/evm/contracts/applications/CCIPReceiver.sol

@@ -55,10 +55,10 @@ abstract contract CCIPReceiver is IAny2EVMMessageReceiverV2, IERC165 {
     return address(i_ccipRouter);
   }
 
-  /// @notice Return the CCVs required/optional and min block confirmations for a source chain.
+  /// @notice Return the CCVs required/optional and allowed finality config for a source chain.
   /// @dev This can be overridden to specify different CCVs per source chain. The current implementation means the
-  /// default CCV is used and finality is required (minBlockConfirmations = 0).
-  function getCCVsAndMinBlockConfirmations(
+  /// default CCV is used and finality is required (allowedFinalityConfig = bytes2(0)).
+  function getCCVsAndFinalityConfig(
     uint64,
     bytes calldata
   )
@@ -69,12 +69,12 @@ abstract contract CCIPReceiver is IAny2EVMMessageReceiverV2, IERC165 {
       address[] memory requiredCCVs,
       address[] memory optionalCCVs,
       uint8 optionalThreshold,
-      uint16 minBlockConfirmations
+      bytes2 allowedFinalityConfig
     )
   {
     // By default no specific CCVs are required or optional. This means the default CCV is chosen.
-    // minBlockConfirmations = 0 means finality is required.
-    return (new address[](0), new address[](0), 0, 0);
+    // allowedFinalityConfig = bytes2(0) means finality is required.
+    return (new address[](0), new address[](0), 0, bytes2(0));
   }
 
   error InvalidRouter(address router);

chains/evm/contracts/interfaces/IAny2EVMMessageReceiverV2.sol

@@ -5,23 +5,22 @@ import {IAny2EVMMessageReceiver} from "./IAny2EVMMessageReceiver.sol";
 
 interface IAny2EVMMessageReceiverV2 is IAny2EVMMessageReceiver {
   /// @notice Get the CCV configuration & minimum accepted block confirmations for a source chain and sender.
-  /// @dev Implementations must return an appropriate minBlockConfirmations value. Returning 0 signals that only fully finalized
-  /// messages are accepted. Returning a non-zero value allows faster-than-finality (FTF) messages whose requested block
-  /// depth is at least minBlockConfirmations. If a suitable minBlockConfirmations is not returned, anyone will be able to send messages
-  /// with any level of finality to the receiver. In most cases, the receiver will want to require a certain level of
-  /// finality. When a trusted sender is used (and verified by the receiver), this is less critical as the trusted sender
+  /// @dev Implementations must return an appropriate allowedFinalityConfig value. Returning bytes2(0) signals that only fully finalized
+  /// messages are accepted. Returning a non-zero value allows faster-than-finality (FTF) messages whose requested
+  /// finality is permitted by the allowedFinalityConfig (see `FinalityCodec._ensureRequestedFinalityAllowed`).
+  /// When a trusted sender is used (and verified by the receiver), this is less critical as the trusted sender
   /// will only send messages with a certain level of finality. The simplest way to implement this is to either allow FTF
   /// messages when sender-verification is used, or require finality for all messages. That means the config can be a
   /// simple boolean instead of n^2 config where for each source, some safe block confirmations must be chosen.
   ///
   /// A few methods to check the block confirmations requirement are:
-  /// - Only allow trusted senders, always return `1` to signal any level of FTF
-  /// - Return a single threshold (e.g. 10 blocks) for all chains
-  /// - Return a threshold specific to the source chain (e.g. 10 blocks for chain A, 20 blocks for chain B)
-  /// - Do not allow FTF messages at all, always return `0`
+  /// - Only allow trusted senders, allow FTF broadly as the senders will decide on the final value
+  /// - Return a single config for all chains
+  /// - Return a config specific to the source chain (e.g. 10 blocks for chain A, 20 blocks for chain B)
+  /// - Do not allow FTF messages at all, always return the WAIT_FOR_FINALITY_FLAG.
   ///
   /// @param sourceChainSelector The source chain selector of the incoming message. This can be used to specify
-  /// different CCV requirements for different source chains, and provides context for the blockConfirmationsRequested parameter.
+  /// different CCV requirements for different source chains, and provides context for the allowed finality config.
   /// @param sender The sender of the message on the source chain. This can be used to implement sender-specific
   /// security policies, such as allowing FTF only for trusted senders.
   /// @dev Messages are executable when either the required block confirmations has been reached, or the chain has marked the
@@ -33,10 +32,9 @@ interface IAny2EVMMessageReceiverV2 is IAny2EVMMessageReceiver {
   /// included, the optionalThreshold parameter must also be set to indicate how many of the optional CCVs must pass
   /// verification for a message to be accepted.
   /// @return optionalThreshold The number of optional CCVs that must pass verification for a message to be accepted.
-  /// @return minBlockConfirmations The minimum block confirmations the receiver requires for FTF messages. A value of 0 means only
-  /// finalized messages are accepted. A non-zero value allows FTF messages whose requested block confirmations meets or
-  /// exceeds this threshold.
-  function getCCVsAndMinBlockConfirmations(
+  /// @return allowedFinalityConfig The allowed finality config, encoded according to the `FinalityCodec`. This allows
+  /// the receiver to specify which finality configs are accepted for messages from this source chain.
+  function getCCVsAndFinalityConfig(
     uint64 sourceChainSelector,
     bytes calldata sender
   )
@@ -46,6 +44,6 @@ interface IAny2EVMMessageReceiverV2 is IAny2EVMMessageReceiver {
       address[] memory requiredCCVs,
       address[] memory optionalCCVs,
       uint8 optionalThreshold,
-      uint16 minBlockConfirmations
+      bytes2 allowedFinalityConfig
     );
 }

chains/evm/contracts/offRamp/OffRamp.sol

@@ -5,24 +5,25 @@ import {IAny2EVMMessageReceiver} from "../interfaces/IAny2EVMMessageReceiver.sol
 import {IAny2EVMMessageReceiverV2} from "../interfaces/IAny2EVMMessageReceiverV2.sol";
 import {ICrossChainVerifierResolver} from "../interfaces/ICrossChainVerifierResolver.sol";
 import {ICrossChainVerifierV1} from "../interfaces/ICrossChainVerifierV1.sol";
+import {CCVConfigValidation} from "../libraries/CCVConfigValidation.sol";
+import {Client} from "../libraries/Client.sol";
+import {ERC165CheckerReverting} from "../libraries/ERC165CheckerReverting.sol";
+import "../libraries/FinalityCodec.sol";
+import {IERC20} from "@openzeppelin/contracts@5.3.0/token/ERC20/IERC20.sol";
+import {EnumerableSet} from "@openzeppelin/contracts@5.3.0/utils/structs/EnumerableSet.sol";
+
 import {IPoolV1} from "../interfaces/IPool.sol";
 import {IPoolV2} from "../interfaces/IPoolV2.sol";
 import {IRMNRemote} from "../interfaces/IRMNRemote.sol";
 import {IRouter} from "../interfaces/IRouter.sol";
 import {ITokenAdminRegistry} from "../interfaces/ITokenAdminRegistry.sol";
+import {Internal} from "../libraries/Internal.sol";
 import {ITypeAndVersion} from "@chainlink/contracts/src/v0.8/shared/interfaces/ITypeAndVersion.sol";
 
-import {CCVConfigValidation} from "../libraries/CCVConfigValidation.sol";
-import {Client} from "../libraries/Client.sol";
-import {ERC165CheckerReverting} from "../libraries/ERC165CheckerReverting.sol";
-import {Internal} from "../libraries/Internal.sol";
 import {MessageV1Codec} from "../libraries/MessageV1Codec.sol";
 import {Pool} from "../libraries/Pool.sol";
 import {Ownable2StepMsgSender} from "@chainlink/contracts/src/v0.8/shared/access/Ownable2StepMsgSender.sol";
 
-import {IERC20} from "@openzeppelin/contracts@5.3.0/token/ERC20/IERC20.sol";
-import {EnumerableSet} from "@openzeppelin/contracts@5.3.0/utils/structs/EnumerableSet.sol";
-
 contract OffRamp is ITypeAndVersion, Ownable2StepMsgSender {
   using ERC165CheckerReverting for address;
   using EnumerableSet for EnumerableSet.UintSet;
@@ -44,7 +45,6 @@ contract OffRamp is ITypeAndVersion, Ownable2StepMsgSender {
   error SkippedAlreadyExecutedMessage(bytes32 messageId, uint64 sourceChainSelector, uint64 messageNumber);
   error ReentrancyGuardReentrantCall();
   error RequiredCCVMissing(address requiredCCV);
-  error InvalidFinalityForReceiver(address receiver, uint16 msgBlockDepth, uint16 requiredBlockDepth);
   error InvalidNumberOfTokens(uint256 numTokens);
   error InvalidOnRamp(bytes got);
   error InvalidOffRamp(address expected, bytes got);
@@ -693,16 +693,16 @@ contract OffRamp is ITypeAndVersion, Ownable2StepMsgSender {
     bytes memory sender,
     bytes2 messageRequestedFinality
   ) internal view returns (address[] memory requiredCCV, address[] memory optionalCCVs, uint8 optionalThreshold) {
-    // Default block confirmations requirement is 0, which means "wait for finality". A receiver implementing
-    // IAny2EVMMessageReceiverV2 can return a different value.
+    // Default finality config is 0, which means "wait for finality". A receiver implementing IAny2EVMMessageReceiverV2
+    // can return a different value.
     // If the receiver does not support the V2 interface it cannot support FTF. This is to protect anyone not
     // explicitly opting in to support FTF from accidentally allowing messages with FTF finality to be executed.
-    uint16 minBlockConfirmations;
+    bytes2 receiverFinalityConfig = bytes2(0);
 
     // Only query for custom CCVs if the receiver supports the interface.
     if (receiver._supportsInterfaceReverting(type(IAny2EVMMessageReceiverV2).interfaceId)) {
-      (requiredCCV, optionalCCVs, optionalThreshold, minBlockConfirmations) =
-        IAny2EVMMessageReceiverV2(receiver).getCCVsAndMinBlockConfirmations(sourceChainSelector, sender);
+      (requiredCCV, optionalCCVs, optionalThreshold, receiverFinalityConfig) =
+        IAny2EVMMessageReceiverV2(receiver).getCCVsAndFinalityConfig(sourceChainSelector, sender);
 
       CCVConfigValidation._assertNoDuplicates(requiredCCV);
       CCVConfigValidation._assertNoDuplicates(optionalCCVs);
@@ -713,18 +713,8 @@ contract OffRamp is ITypeAndVersion, Ownable2StepMsgSender {
       }
     }
 
-    // If non-zero it means FTF is enabled. Ensure it follows the min requirements from the receiver.
-    uint16 requestedWire = uint16(messageRequestedFinality);
-    if (requestedWire != 0) {
-      // If the receiver requires finality, but the msg is FTF, revert.
-      if (minBlockConfirmations == 0) {
-        revert InvalidFinalityForReceiver(receiver, requestedWire, minBlockConfirmations);
-      }
-      // If the receiver specified a minBlockConfirmations that is higher than the message requested block confirmations, revert.
-      if (minBlockConfirmations > requestedWire) {
-        revert InvalidFinalityForReceiver(receiver, requestedWire, minBlockConfirmations);
-      }
-    }
+    // Check the finality requirement of the message against the allowed finality for the receiver.
+    FinalityCodec._ensureRequestedFinalityAllowed(messageRequestedFinality, receiverFinalityConfig);
 
     // If the receiver specified empty required and optional CCVs, we fall back to the default CCVs.
     // If they did specify something, we use what they specified.
@@ -742,6 +732,7 @@ contract OffRamp is ITypeAndVersion, Ownable2StepMsgSender {
   /// @param localToken The local token address.
   /// @param sourceChainSelector The source chain selector.
   /// @param amount The amount of the token to be released/minted.
+  /// @param finality The finality requirement of the message (see `FinalityCodec`).
   /// @param extraData The extra data for the pool.
   /// @return requiredCCV The required CCVs.
   function _getCCVsFromPool(

chains/evm/contracts/onRamp/OnRamp.sol

@@ -47,7 +47,7 @@ contract OnRamp is IEVM2AnyOnRampClient, ITypeAndVersion, Ownable2StepMsgSender
   error ReentrancyGuardReentrantCall();
   error DestinationChainNotSupported(uint64 destChainSelector);
   error InvalidDestChainAddress(bytes destChainAddress);
-  error CustomBlockConfirmationsNotSupportedOnPoolV1();
+  error FTFNotSupportedOnPoolV1();
   error TokenArgsNotSupportedOnPoolV1();
   error InsufficientFeeTokenAmount();
   error TokenReceiverNotAllowed(uint64 destChainSelector);
@@ -756,7 +756,7 @@ contract OnRamp is IEVM2AnyOnRampClient, ITypeAndVersion, Ownable2StepMsgSender
         // V1 pools don't understand `finalityConfig`/`tokenArgs`.
         // We enforce default finality and no `tokenArgs` to avoid silent mis-interpretation.
         if (finalityConfig != bytes2(0)) {
-          revert CustomBlockConfirmationsNotSupportedOnPoolV1();
+          revert FTFNotSupportedOnPoolV1();
         }
         if (tokenArgs.length != 0) {
           revert TokenArgsNotSupportedOnPoolV1();

chains/evm/contracts/test/applications/CCIPClientExampleWithCCVs/CCIPClientExampleWithCCVs.applyCCVConfigUpdates.t.sol

@@ -44,12 +44,12 @@ contract CCIPClientExampleWithCCVs_applyCCVConfigUpdates is RouterSetup {
       address[] memory retRequiredCCVs,
       address[] memory retOptionalCCVs,
       uint8 retOptionalThreshold,
-      uint16 minBlockConfirmations
-    ) = s_client.getCCVsAndMinBlockConfirmations(SOURCE_CHAIN_SELECTOR, sender);
+      bytes2 allowedFinalityConfig
+    ) = s_client.getCCVsAndFinalityConfig(SOURCE_CHAIN_SELECTOR, sender);
     assertEq(retRequiredCCVs.length, requiredCCVs.length);
     assertEq(retOptionalCCVs.length, optionalCCVs.length);
     assertEq(retOptionalThreshold, optionalThreshold);
-    assertEq(minBlockConfirmations, 1);
+    assertEq(allowedFinalityConfig, bytes2(uint16(1)));
     for (uint256 i = 0; i < requiredCCVs.length; ++i) {
       assertEq(retRequiredCCVs[i], requiredCCVs[i]);
     }
@@ -153,7 +153,7 @@ contract CCIPClientExampleWithCCVs_applyCCVConfigUpdates is RouterSetup {
     s_client.applyCCVConfigUpdates(args);
   }
 
-  function test_getCCVsAndMinBlockConfirmations_RequireFinality_ReturnsZeroMinBlockConfirmations() public {
+  function test_getCCVsAndFinalityConfig_RequireFinality_ReturnsZeroAllowedFinalityConfig() public {
     address[] memory requiredCCVs = new address[](1);
     requiredCCVs[0] = address(0x1);
 
@@ -170,14 +170,14 @@ contract CCIPClientExampleWithCCVs_applyCCVConfigUpdates is RouterSetup {
 
     bytes memory sender = abi.encodePacked(makeAddr("sender"));
 
-    (address[] memory retRequired,,, uint16 minBlockConfirmations) =
-      s_client.getCCVsAndMinBlockConfirmations(SOURCE_CHAIN_SELECTOR, sender);
+    (address[] memory retRequired,,, bytes2 allowedFinalityConfig) =
+      s_client.getCCVsAndFinalityConfig(SOURCE_CHAIN_SELECTOR, sender);
     assertEq(retRequired.length, 1);
     assertEq(retRequired[0], address(0x1));
-    assertEq(minBlockConfirmations, 0);
+    assertEq(allowedFinalityConfig, bytes2(0));
   }
 
-  function test_getCCVsAndMinBlockConfirmations_NoRequireFinality_ReturnsNonZeroMinBlockConfirmations() public {
+  function test_getCCVsAndFinalityConfig_NoRequireFinality_ReturnsNonZeroAllowedFinalityConfig() public {
     address[] memory requiredCCVs = new address[](1);
     requiredCCVs[0] = address(0x1);
 
@@ -194,10 +194,10 @@ contract CCIPClientExampleWithCCVs_applyCCVConfigUpdates is RouterSetup {
 
     bytes memory sender = abi.encodePacked(makeAddr("sender"));
 
-    (address[] memory retRequired,,, uint16 minBlockConfirmations) =
-      s_client.getCCVsAndMinBlockConfirmations(SOURCE_CHAIN_SELECTOR, sender);
+    (address[] memory retRequired,,, bytes2 allowedFinalityConfig) =
+      s_client.getCCVsAndFinalityConfig(SOURCE_CHAIN_SELECTOR, sender);
     assertEq(retRequired.length, 1);
     assertEq(retRequired[0], address(0x1));
-    assertEq(minBlockConfirmations, 1);
+    assertEq(allowedFinalityConfig, bytes2(uint16(1)));
   }
 }

chains/evm/contracts/test/mocks/MockReceiverV2.sol

@@ -10,7 +10,7 @@ contract MockReceiverV2 is IAny2EVMMessageReceiverV2, IERC165 {
   address[] internal s_required;
   address[] internal s_optional;
   uint8 internal s_threshold;
-  uint16 internal s_minBlockConfirmations;
+  bytes2 internal s_allowedFinalityConfig;
 
   constructor(
     address[] memory required,
@@ -22,10 +22,10 @@ contract MockReceiverV2 is IAny2EVMMessageReceiverV2, IERC165 {
     s_threshold = threshold;
   }
 
-  function setMinBlockConfirmations(
-    uint16 minBlockConfirmations
+  function setAllowedFinalityConfig(
+    bytes2 allowedFinalityConfig
   ) external {
-    s_minBlockConfirmations = minBlockConfirmations;
+    s_allowedFinalityConfig = allowedFinalityConfig;
   }
 
   // From IAny2EVMMessageReceiver
@@ -34,7 +34,7 @@ contract MockReceiverV2 is IAny2EVMMessageReceiverV2, IERC165 {
   ) external {}
 
   // From IAny2EVMMessageReceiverV2
-  function getCCVsAndMinBlockConfirmations(
+  function getCCVsAndFinalityConfig(
     uint64, // sourceChainSelector
     bytes calldata // sender
   )
@@ -44,10 +44,10 @@ contract MockReceiverV2 is IAny2EVMMessageReceiverV2, IERC165 {
       address[] memory requiredVerifier,
       address[] memory optionalVerifiers,
       uint8 threshold,
-      uint16 minBlockDepth
+      bytes2 allowedFinalityConfig
     )
   {
-    return (s_required, s_optional, s_threshold, s_minBlockConfirmations);
+    return (s_required, s_optional, s_threshold, s_allowedFinalityConfig);
   }
 
   function supportsInterface(