Revert "feat: remove maxTimestampSpread and only rely on expiry" (#504)

This reverts commit ac1c5406441c01119eaf9c0de54512f7cfe1ff19.

### Description

Brings back the maxTimestampSpread setting. A visual explanation here:

<img width="918" alt="image"
src="https://github.com/user-attachments/assets/02dfaadb-f029-4f38-8bd5-965644b4a4b5">

We need it because CELO/USD has a heartbeat of 24hr and PHP/USD
5minutes, therefore we could be in a situation where the spread between
reports is quite large, and if we rely only on max timestamp spread we
could be reporting with stale data. The rule of thumb is:
- Set `maxTimestampSpread` by considering the largest heartbeat
frequency.
- Set `tokenExpiry` in SortedOracles by considering the shortest
heartbeat frequency.

### Other changes

N/A

### Tested

Yup

### Related issues

N/A

### Backwards compatibility

N/A

### Documentation

N/A

---------

Co-authored-by: chapati <[email protected]>
Co-authored-by: philbow61 <[email protected]>

Author: 3 people

contracts/interfaces/IChainlinkRelayer.sol

@@ -21,5 +21,7 @@ interface IChainlinkRelayer {
 
   function getAggregators() external returns (ChainlinkAggregator[] memory);
 
+  function maxTimestampSpread() external returns (uint256);
+
   function relay() external;
 }

contracts/interfaces/IChainlinkRelayerFactory.sol

@@ -44,6 +44,7 @@ interface IChainlinkRelayerFactory {
   function deployRelayer(
     address rateFeedId,
     string calldata rateFeedDescription,
+    uint256 maxTimestampSpread,
     IChainlinkRelayer.ChainlinkAggregator[] calldata aggregators
   ) external returns (address);
 
@@ -52,6 +53,7 @@ interface IChainlinkRelayerFactory {
   function redeployRelayer(
     address rateFeedId,
     string calldata rateFeedDescription,
+    uint256 maxTimestampSpread,
     IChainlinkRelayer.ChainlinkAggregator[] calldata aggregators
   ) external returns (address);
 
@@ -62,6 +64,7 @@ interface IChainlinkRelayerFactory {
   function computedRelayerAddress(
     address rateFeedId,
     string calldata rateFeedDescription,
+    uint256 maxTimestampSpread,
     IChainlinkRelayer.ChainlinkAggregator[] calldata aggregators
   ) external returns (address);
 }

contracts/oracles/ChainlinkRelayerFactory.sol

@@ -105,6 +105,8 @@ contract ChainlinkRelayerFactory is IChainlinkRelayerFactory, OwnableUpgradeable
    * @notice Deploys a new relayer contract.
    * @param rateFeedId The rate feed ID for which the relayer will report.
    * @param rateFeedDescription Human-readable rate feed, which the relayer will report on, i.e. "CELO/USD".
+   * @param maxTimestampSpread Max difference in milliseconds between the earliest and
+   *        latest timestamp of all aggregators in the price path.
    * @param aggregators Array of ChainlinkAggregator structs defining the price path.
    *        See contract-level @dev comment in the ChainlinkRelayerV1 contract,
    *        for an explanation on price paths.
@@ -113,13 +115,14 @@ contract ChainlinkRelayerFactory is IChainlinkRelayerFactory, OwnableUpgradeable
   function deployRelayer(
     address rateFeedId,
     string calldata rateFeedDescription,
+    uint256 maxTimestampSpread,
     IChainlinkRelayer.ChainlinkAggregator[] calldata aggregators
   ) public onlyDeployer returns (address relayerAddress) {
     if (address(deployedRelayers[rateFeedId]) != address(0)) {
       revert RelayerForFeedExists(rateFeedId);
     }
 
-    address expectedAddress = computedRelayerAddress(rateFeedId, rateFeedDescription, aggregators);
+    address expectedAddress = computedRelayerAddress(rateFeedId, rateFeedDescription, maxTimestampSpread, aggregators);
     if (expectedAddress.code.length > 0) {
       revert ContractAlreadyExists(expectedAddress, rateFeedId);
     }
@@ -129,6 +132,7 @@ contract ChainlinkRelayerFactory is IChainlinkRelayerFactory, OwnableUpgradeable
       rateFeedId,
       rateFeedDescription,
       sortedOracles,
+      maxTimestampSpread,
       aggregators
     );
 
@@ -176,16 +180,19 @@ contract ChainlinkRelayerFactory is IChainlinkRelayerFactory, OwnableUpgradeable
    *         has been upgraded since the last deployment of the relayer).
    * @param rateFeedId The rate feed ID for which the relayer will report.
    * @param rateFeedDescription Human-readable rate feed, which the relayer will report on, i.e. "CELO/USD".
+   * @param maxTimestampSpread Max difference in milliseconds between the earliest and
+   *        latest timestamp of all aggregators in the price path.
    * @param aggregators Array of ChainlinkAggregator structs defining the price path.
    * @return relayerAddress The address of the newly deployed relayer contract.
    */
   function redeployRelayer(
     address rateFeedId,
     string calldata rateFeedDescription,
+    uint256 maxTimestampSpread,
     IChainlinkRelayer.ChainlinkAggregator[] calldata aggregators
   ) external onlyDeployer returns (address relayerAddress) {
     removeRelayer(rateFeedId);
-    return deployRelayer(rateFeedId, rateFeedDescription, aggregators);
+    return deployRelayer(rateFeedId, rateFeedDescription, maxTimestampSpread, aggregators);
   }
 
   /**
@@ -224,12 +231,15 @@ contract ChainlinkRelayerFactory is IChainlinkRelayerFactory, OwnableUpgradeable
    * @notice Computes the expected CREATE2 address for given relayer parameters.
    * @param rateFeedId The rate feed ID.
    * @param rateFeedDescription The human readable description of the reported rate feed.
+   * @param maxTimestampSpread Max difference in milliseconds between the earliest and
+   *        latest timestamp of all aggregators in the price path.
    * @param aggregators Array of ChainlinkAggregator structs defining the price path.
    * @dev See https://eips.ethereum.org/EIPS/eip-1014.
    */
   function computedRelayerAddress(
     address rateFeedId,
     string calldata rateFeedDescription,
+    uint256 maxTimestampSpread,
     IChainlinkRelayer.ChainlinkAggregator[] calldata aggregators
   ) public view returns (address) {
     bytes32 salt = _getSalt();
@@ -245,7 +255,7 @@ contract ChainlinkRelayerFactory is IChainlinkRelayerFactory, OwnableUpgradeable
                 keccak256(
                   abi.encodePacked(
                     type(ChainlinkRelayerV1).creationCode,
-                    abi.encode(rateFeedId, rateFeedDescription, sortedOracles, aggregators)
+                    abi.encode(rateFeedId, rateFeedDescription, sortedOracles, maxTimestampSpread, aggregators)
                   )
                 )
               )

contracts/oracles/ChainlinkRelayerV1.sol

@@ -89,6 +89,13 @@ contract ChainlinkRelayerV1 is IChainlinkRelayer {
   /// @notice The number of aggregators provided during construction 1 <= aggregatorCount <= 4.
   uint256 private immutable aggregatorCount;
 
+  /**
+   * @notice Maximum timestamp deviation allowed between all report timestamps pulled
+   * from the Chainlink aggregators.
+   * @dev Only relevant when aggregatorCount > 1.
+   */
+  uint256 public immutable maxTimestampSpread;
+
   /**
    * @notice Human-readable description of the rate feed.
    * @dev Should only be used off-chain for easier debugging / UI generation,
@@ -102,6 +109,10 @@ contract ChainlinkRelayerV1 is IChainlinkRelayer {
   /// @notice Used when more than four aggregators are passed into the constructor.
   error TooManyAggregators();
 
+  /// @notice Used when a) there is more than 1 aggregator and the maxTimestampSpread is 0,
+  /// OR b) when there is only 1 aggregator and the maxTimestampSpread is not 0.
+  error InvalidMaxTimestampSpread();
+
   /// @notice Used when a new price's timestamp is not newer than the most recent SortedOracles timestamp.
   error TimestampNotNew();
 
@@ -110,7 +121,11 @@ contract ChainlinkRelayerV1 is IChainlinkRelayer {
 
   /// @notice Used when a negative or zero price is returned by the Chainlink aggregator.
   error InvalidPrice();
-
+  /**
+   * @notice Used when the spread between the earliest and latest timestamp
+   * of the aggregators is above the maximum allowed.
+   */
+  error TimestampSpreadTooHigh();
   /**
    * @notice Used when trying to recover from a lesser/greater revert and there are
    * too many existing reports in SortedOracles.
@@ -128,16 +143,20 @@ contract ChainlinkRelayerV1 is IChainlinkRelayer {
    * @param _rateFeedId ID of the rate feed this relayer instance relays for.
    * @param _rateFeedDescription The human-readable description of the reported rate feed.
    * @param _sortedOracles Address of the SortedOracles contract to relay to.
+   * @param _maxTimestampSpread Max difference in milliseconds between the earliest and
+   *        latest timestamp of all aggregators in the price path.
    * @param _aggregators Array of ChainlinkAggregator structs defining the price path.
    */
   constructor(
     address _rateFeedId,
     string memory _rateFeedDescription,
     address _sortedOracles,
+    uint256 _maxTimestampSpread,
     ChainlinkAggregator[] memory _aggregators
   ) {
     rateFeedId = _rateFeedId;
     sortedOracles = _sortedOracles;
+    maxTimestampSpread = _maxTimestampSpread;
     rateFeedDescription = _rateFeedDescription;
 
     aggregatorCount = _aggregators.length;
@@ -149,6 +168,10 @@ contract ChainlinkRelayerV1 is IChainlinkRelayer {
       revert TooManyAggregators();
     }
 
+    if ((aggregatorCount > 1 && _maxTimestampSpread == 0) || (aggregatorCount == 1 && _maxTimestampSpread != 0)) {
+      revert InvalidMaxTimestampSpread();
+    }
+
     ChainlinkAggregator[] memory aggregators = new ChainlinkAggregator[](4);
     for (uint256 i = 0; i < _aggregators.length; i++) {
       if (_aggregators[i].aggregator == address(0)) {
@@ -183,7 +206,8 @@ contract ChainlinkRelayerV1 is IChainlinkRelayer {
    * @dev Performs checks on the timestamp, will revert if any fails:
    *      - The most recent Chainlink timestamp should be strictly newer than the most
    *        recent timestamp in SortedOracles.
-   *      - The oldest Chainlink timestamp should not be considered expired by SortedOracles.
+   *      - The most recent Chainlink timestamp should not be considered expired by SortedOracles.
+   *      - The spread between aggregator timestamps is less than the maxTimestampSpread.
    */
   function relay() external {
     ISortedOraclesMin _sortedOracles = ISortedOraclesMin(sortedOracles);
@@ -201,13 +225,17 @@ contract ChainlinkRelayerV1 is IChainlinkRelayer {
       newestChainlinkTs = timestamp > newestChainlinkTs ? timestamp : newestChainlinkTs;
     }
 
+    if (newestChainlinkTs - oldestChainlinkTs > maxTimestampSpread) {
+      revert TimestampSpreadTooHigh();
+    }
+
     uint256 lastReportTs = _sortedOracles.medianTimestamp(rateFeedId);
 
     if (lastReportTs > 0 && newestChainlinkTs <= lastReportTs) {
       revert TimestampNotNew();
     }
 
-    if (isTimestampExpired(oldestChainlinkTs)) {
+    if (isTimestampExpired(newestChainlinkTs)) {
       revert ExpiredTimestamp();
     }
 

test/integration/ChainlinkRelayerIntegration.t.sol

@@ -108,7 +108,7 @@ contract ChainlinkRelayerIntegration_ReportAfterRedeploy is ChainlinkRelayerInte
 
     vm.prank(owner);
     IChainlinkRelayer chainlinkRelayer0 = IChainlinkRelayer(
-      relayerFactory.deployRelayer(rateFeedId, "cUSD/FOO", aggregatorList0)
+      relayerFactory.deployRelayer(rateFeedId, "cUSD/FOO", 0, aggregatorList0)
     );
 
     vm.prank(deployer);
@@ -121,7 +121,7 @@ contract ChainlinkRelayerIntegration_ReportAfterRedeploy is ChainlinkRelayerInte
 
     vm.prank(owner);
     IChainlinkRelayer chainlinkRelayer1 = IChainlinkRelayer(
-      relayerFactory.redeployRelayer(rateFeedId, "cUSD/FOO", aggregatorList1)
+      relayerFactory.redeployRelayer(rateFeedId, "cUSD/FOO", 0, aggregatorList1)
     );
 
     vm.prank(deployer);
@@ -158,7 +158,7 @@ contract ChainlinkRelayerIntegration_CircuitBreakerInteraction is ChainlinkRelay
     IChainlinkRelayer.ChainlinkAggregator[] memory aggregators = new IChainlinkRelayer.ChainlinkAggregator[](1);
     aggregators[0] = IChainlinkRelayer.ChainlinkAggregator(address(chainlinkAggregator), false);
     vm.prank(owner);
-    chainlinkRelayer = IChainlinkRelayer(relayerFactory.deployRelayer(rateFeedId, "CELO/USD", aggregators));
+    chainlinkRelayer = IChainlinkRelayer(relayerFactory.deployRelayer(rateFeedId, "CELO/USD", 0, aggregators));
 
     vm.prank(deployer);
     sortedOracles.addOracle(rateFeedId, address(chainlinkRelayer));