feat(contracts-rfq): relayer exclusivity [SLT-187]

packages/contracts-rfq/contracts/FastBridgeV2.sol

@@ -71,59 +71,87 @@
 
     /// @inheritdoc IFastBridge
     function getBridgeTransaction(bytes memory request) public pure returns (BridgeTransaction memory) {
+        // Note: when passing V2 request, this will decode the V1 fields correctly since the new fields were
+        // added as the last fields of the struct and hence the ABI decoder will simply ignore the extra data.
         return abi.decode(request, (BridgeTransaction));
     }
 
+    /// @inheritdoc IFastBridgeV2
+    function getBridgeTransactionV2(bytes memory request) public pure returns (BridgeTransactionV2 memory) {
+        return abi.decode(request, (BridgeTransactionV2));
+    }
+
     /// @inheritdoc IFastBridge
     function bridge(BridgeParams memory params) external payable {
+        BridgeParamsV2 memory defaultParamsV2 =
+            BridgeParamsV2({quoteRelayer: address(0), quoteExclusivitySeconds: 0, quoteId: bytes("")});
+        bridge(params, defaultParamsV2);
+    }
+
+    /// @inheritdoc IFastBridgeV2
+    // TODO: reduce cyclomatic complexity alongside arbitrary call
+    // solhint-disable-next-line code-complexity
+    function bridge(BridgeParams memory params, BridgeParamsV2 memory paramsV2) public payable {
         // check bridge params
         if (params.dstChainId == block.chainid) revert ChainIncorrect();
         if (params.originAmount == 0 || params.destAmount == 0) revert AmountIncorrect();
         if (params.sender == address(0) || params.to == address(0)) revert ZeroAddress();
         if (params.originToken == address(0) || params.destToken == address(0)) revert ZeroAddress();
         if (params.deadline < block.timestamp + MIN_DEADLINE_PERIOD) revert DeadlineTooShort();
+        // quoteRelayer and quoteExclusivitySeconds must be both set or both not set
+        if ((paramsV2.quoteRelayer == address(0)) != (paramsV2.quoteExclusivitySeconds == 0)) {
+            revert ExclusivityParamsIncorrect();
+        }
 
         // transfer tokens to bridge contract
         // @dev use returned originAmount in request in case of transfer fees
         uint256 originAmount = _pullToken(address(this), params.originToken, params.originAmount);
 
         // track amount of origin token owed to protocol
         uint256 originFeeAmount;
         if (protocolFeeRate > 0) originFeeAmount = (originAmount * protocolFeeRate) / FEE_BPS;
         originAmount -= originFeeAmount; // remove from amount used in request as not relevant for relayers
 
+        // Calculate exclusivity end time only if exclusivity params are set
+        uint256 exclusivityEndTime =
+            paramsV2.quoteExclusivitySeconds == 0 ? 0 : block.timestamp + paramsV2.quoteExclusivitySeconds;
         // set status to requested
         bytes memory request = abi.encode(
-            BridgeTransaction({
-                originChainId: uint32(block.chainid),
-                destChainId: params.dstChainId,
-                originSender: params.sender,
-                destRecipient: params.to,
-                originToken: params.originToken,
-                destToken: params.destToken,
-                originAmount: originAmount,
-                destAmount: params.destAmount,
-                originFeeAmount: originFeeAmount,
-                sendChainGas: params.sendChainGas,
-                deadline: params.deadline,
-                nonce: nonce++ // increment nonce on every bridge
+            BridgeTransactionV2({
+                txV1: BridgeTransaction({
+                    originChainId: uint32(block.chainid),
+                    destChainId: params.dstChainId,
+                    originSender: params.sender,
+                    destRecipient: params.to,
+                    originToken: params.originToken,
+                    destToken: params.destToken,
+                    originAmount: originAmount,
+                    destAmount: params.destAmount,
+                    originFeeAmount: originFeeAmount,
+                    sendChainGas: params.sendChainGas,
+                    deadline: params.deadline,
+                    nonce: nonce++ // increment nonce on every bridge
+                }),
+                exclusivityRelayer: paramsV2.quoteRelayer,
+                exclusivityEndTime: exclusivityEndTime
             })
         );
         bytes32 transactionId = keccak256(request);
         bridgeTxDetails[transactionId].status = BridgeStatus.REQUESTED;
 
         emit BridgeRequested(
             transactionId,
             params.sender,
             request,
             params.dstChainId,
             params.originToken,
             params.destToken,
             originAmount,
             params.destAmount,
             params.sendChainGas
         );
+        emit BridgeRequestedV2(transactionId, paramsV2.quoteId);
     }
 
     /// @inheritdoc IFastBridge
     function relay(bytes memory request) external payable {
@@ -131,28 +159,33 @@
     }
 
     /// @inheritdoc IFastBridgeV2
+    // TODO: reduce cyclomatic complexity alongside arbitrary call
+    // solhint-disable-next-line code-complexity
     function relay(bytes memory request, address relayer) public payable {
         if (relayer == address(0)) revert ZeroAddress();
+        // Check if the transaction has already been relayed
         bytes32 transactionId = keccak256(request);
-        BridgeTransaction memory transaction = getBridgeTransaction(request);
-        if (transaction.destChainId != uint32(block.chainid)) revert ChainIncorrect();
-
-        // check haven't exceeded deadline for relay to happen
-        if (block.timestamp > transaction.deadline) revert DeadlineExceeded();
-
-        if (bridgeRelayDetails[transactionId].relayer != address(0)) revert TransactionRelayed();
-
+        if (bridgeRelays(transactionId)) revert TransactionRelayed();
+        // Decode the transaction and check that it could be relayed on this chain
+        BridgeTransactionV2 memory transaction = getBridgeTransactionV2(request);
+        if (transaction.txV1.destChainId != uint32(block.chainid)) revert ChainIncorrect();
+        // Check the deadline for relay to happen
+        if (block.timestamp > transaction.txV1.deadline) revert DeadlineExceeded();
+        // Check the exclusivity period, if it is still ongoing
+        if (block.timestamp <= transaction.exclusivityEndTime && relayer != transaction.exclusivityRelayer) {
+            revert ExclusivityPeriodNotPassed();
+        }
         // mark bridge transaction as relayed
         bridgeRelayDetails[transactionId] =
             BridgeRelay({blockNumber: uint48(block.number), blockTimestamp: uint48(block.timestamp), relayer: relayer});
 
         // transfer tokens to recipient on destination chain and gas rebate if requested
-        address to = transaction.destRecipient;
-        address token = transaction.destToken;
-        uint256 amount = transaction.destAmount;
+        address to = transaction.txV1.destRecipient;
+        address token = transaction.txV1.destToken;
+        uint256 amount = transaction.txV1.destAmount;
 
         uint256 rebate = chainGasAmount;
-        if (!transaction.sendChainGas) {
+        if (!transaction.txV1.sendChainGas) {
             // forward erc20
             rebate = 0;
             _pullToken(to, token, amount);
@@ -169,11 +202,11 @@
             transactionId,
             relayer,
             to,
-            transaction.originChainId,
-            transaction.originToken,
-            transaction.destToken,
-            transaction.originAmount,
-            transaction.destAmount,
+            transaction.txV1.originChainId,
+            transaction.txV1.originToken,
+            transaction.txV1.destToken,
+            transaction.txV1.originAmount,
+            transaction.txV1.destAmount,
             rebate
         );
     }
@@ -229,7 +262,7 @@
     /// @inheritdoc IFastBridge
     function claim(bytes memory request, address to) public {
         bytes32 transactionId = keccak256(request);
-        BridgeTransaction memory transaction = getBridgeTransaction(request);
+        BridgeTransaction memory transaction = getBridgeTransactionV2(request).txV1;
 
         // update bridge tx status if able to claim origin collateral
         if (bridgeTxDetails[transactionId].status != BridgeStatus.RELAYER_PROVED) revert StatusIncorrect();
@@ -278,7 +311,7 @@
     function refund(bytes memory request) external {
         bytes32 transactionId = keccak256(request);
 
-        BridgeTransaction memory transaction = getBridgeTransaction(request);
+        BridgeTransaction memory transaction = getBridgeTransactionV2(request).txV1;
 
         if (bridgeTxDetails[transactionId].status != BridgeStatus.REQUESTED) revert StatusIncorrect();
 

packages/contracts-rfq/contracts/interfaces/IFastBridgeV2.sol

@@ -25,6 +25,37 @@ interface IFastBridgeV2 is IFastBridge {
         address relayer;
     }
 
+    /// @notice New params introduced in the FastBridgeV2.
+    /// We are passing fields from the older BridgeParams struct outside of this struct
+    /// for backwards compatibility.
+    /// Note: quoteRelayer and quoteExclusivitySeconds are either both zero (indicating no exclusivity)
+    /// or both non-zero (indicating exclusivity for the given period).
+    /// @param quoteRelayer             Relayer that provided the quote for the transaction
+    /// @param quoteExclusivitySeconds  Period of time the quote relayer is guaranteed exclusivity after user's deposit
+    /// @param quoteId                  Unique quote identifier used for tracking the quote
+    struct BridgeParamsV2 {
+        address quoteRelayer;
+        uint256 quoteExclusivitySeconds;
+        bytes quoteId;
+    }
+
+    /// @notice Updated bridge transaction struct to include parameters introduced in FastBridgeV2.
+    /// Note: only `exclusivityRelayer` can fill such a transaction until `exclusivityEndTime`.
+    /// TODO: consider changing the encoding scheme to prevent spending extra gas on decoding.
+    struct BridgeTransactionV2 {
+        BridgeTransaction txV1;
+        address exclusivityRelayer;
+        uint256 exclusivityEndTime;
+    }
+
+    event BridgeRequestedV2(bytes32 indexed transactionId, bytes quoteId);
+
+    /// @notice Initiates bridge on origin chain to be relayed by off-chain relayer, with the ability
+    /// to provide temporary exclusivity fill rights for the quote relayer.
+    /// @param params   The parameters required to bridge
+    /// @param paramsV2 The parameters for exclusivity fill rights (optional, could be left empty)
+    function bridge(BridgeParams memory params, BridgeParamsV2 memory paramsV2) external payable;
+
     /// @notice Relays destination side of bridge transaction by off-chain relayer
     /// @param request The encoded bridge transaction to relay on destination chain
     /// @param relayer The address of the relaying entity which should have control of the origin funds when claimed
@@ -55,4 +86,8 @@ interface IFastBridgeV2 is IFastBridge {
     /// @return timestamp The timestamp of the bridge proof
     /// @return relayer The relayer address of the bridge proof
     function bridgeProofs(bytes32 transactionId) external view returns (uint96 timestamp, address relayer);
+
+    /// @notice Decodes bridge request into a bridge transaction V2 struct used by FastBridgeV2
+    /// @param request The bridge request to decode
+    function getBridgeTransactionV2(bytes memory request) external view returns (BridgeTransactionV2 memory);
 }

packages/contracts-rfq/contracts/interfaces/IFastBridgeV2Errors.sol

@@ -4,6 +4,7 @@ pragma solidity ^0.8.0;
 interface IFastBridgeV2Errors {
     error AmountIncorrect();
     error ChainIncorrect();
+    error ExclusivityParamsIncorrect();
     error MsgValueIncorrect();
     error SenderIncorrect();
     error StatusIncorrect();
@@ -14,6 +15,7 @@ interface IFastBridgeV2Errors {
     error DeadlineTooShort();
     error DisputePeriodNotPassed();
     error DisputePeriodPassed();
+    error ExclusivityPeriodNotPassed();
 
     error TransactionRelayed();
 }

packages/contracts-rfq/test/FastBridgeV2.Dst.Base.t.sol

@@ -1,13 +1,13 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.20;
 
-import {FastBridgeV2, FastBridgeV2Test, IFastBridge} from "./FastBridgeV2.t.sol";
+import {FastBridgeV2, FastBridgeV2Test, IFastBridgeV2} from "./FastBridgeV2.t.sol";
 
 // solhint-disable func-name-mixedcase, ordering
 contract FastBridgeV2DstBaseTest is FastBridgeV2Test {
     uint256 public constant LEFTOVER_BALANCE = 1 ether;
 
-    function setUp() public override {
+    function setUp() public virtual override {
         vm.chainId(DST_CHAIN_ID);
         super.setUp();
     }
@@ -29,7 +29,7 @@ contract FastBridgeV2DstBaseTest is FastBridgeV2Test {
 
     // ══════════════════════════════════════════════════ HELPERS ══════════════════════════════════════════════════════
 
-    function relay(address caller, uint256 msgValue, IFastBridge.BridgeTransaction memory bridgeTx) public {
+    function relay(address caller, uint256 msgValue, IFastBridgeV2.BridgeTransactionV2 memory bridgeTx) public {
         bytes memory request = abi.encode(bridgeTx);
         vm.prank({msgSender: caller, txOrigin: caller});
         fastBridge.relay{value: msgValue}(request);
@@ -39,7 +39,7 @@ contract FastBridgeV2DstBaseTest is FastBridgeV2Test {
         address caller,
         address relayer,
         uint256 msgValue,
-        IFastBridge.BridgeTransaction memory bridgeTx
+        IFastBridgeV2.BridgeTransactionV2 memory bridgeTx
     )
         public
     {