feat: Enable deposit and match orders in a single tx

abis/contracts/facets/IexecEscrowTokenFacet.json

@@ -227,7 +227,7 @@
       },
       {
         "internalType": "bytes",
-        "name": "",
+        "name": "data",
         "type": "bytes"
       }
     ],

contracts/facets/IexecEscrowTokenFacet.sol

@@ -7,6 +7,8 @@ import {IexecERC20Core} from "./IexecERC20Core.sol";
 import {FacetBase} from "./FacetBase.sol";
 import {IexecEscrowToken} from "../interfaces/IexecEscrowToken.sol";
 import {IexecTokenSpender} from "../interfaces/IexecTokenSpender.sol";
+import {IexecPoco1} from "../interfaces/IexecPoco1.sol";
+import {IexecLibOrders_v5} from "../libs/IexecLibOrders_v5.sol";
 import {PocoStorageLib} from "../libs/PocoStorageLib.sol";
 
 contract IexecEscrowTokenFacet is IexecEscrowToken, IexecTokenSpender, FacetBase, IexecERC20Core {
@@ -64,23 +66,131 @@ contract IexecEscrowTokenFacet is IexecEscrowToken, IexecTokenSpender, FacetBase
         return delta;
     }
 
-    // Token Spender (endpoint for approveAndCallback calls to the proxy)
+    /***************************************************************************
+     *            Token Spender: Atomic Approve+Deposit+Match                  *
+     ***************************************************************************/
+
+    /**
+     * @notice Receives approval and optionally matches orders in one transaction
+     *
+     * Usage patterns:
+     * 1. Simple deposit: RLC.approveAndCall(escrow, amount, "")
+     * 2. Deposit + match: RLC.approveAndCall(escrow, amount, encodedOrders)
+     *
+     * The `data` parameter should be ABI-encoded orders if matching is desired:
+     * abi.encode(appOrder, datasetOrder, workerpoolOrder, requestOrder)
+     *
+     * @dev Important notes:
+     * - Match orders sponsoring is NOT supported. The requester (sender) always pays for the deal.
+     * - Clients must compute the exact deal cost and deposit the right amount for the deal to be matched.
+     *   The deal cost = (appPrice + datasetPrice + workerpoolPrice) * volume.
+     * - If insufficient funds are deposited, the match will fail.
+     *
+     * @param sender The address that approved tokens (must be requester if matching)
+     * @param amount Amount of tokens approved and to be deposited
+     * @param token Address of the token (must be RLC)
+     * @param data Optional: ABI-encoded orders for matching
+     * @return success True if operation succeeded
+     *
+     *
+     * @custom:example
+     * ```solidity
+     * // Compute deal cost
+     * uint256 dealCost = (appPrice + datasetPrice + workerpoolPrice) * volume;
+     *
+     * // Encode orders
+     * bytes memory data = abi.encode(appOrder, datasetOrder, workerpoolOrder, requestOrder);
+     *
+     * // One transaction does it all
+     * RLC(token).approveAndCall(iexecProxy, dealCost, data);
+     * ```
+     */
     function receiveApproval(
         address sender,
         uint256 amount,
         address token,
-        bytes calldata
+        bytes calldata data
     ) external override returns (bool) {
         PocoStorageLib.PocoStorage storage $ = PocoStorageLib.getPocoStorage();
         require(token == address($.m_baseToken), "wrong-token");
         _deposit(sender, amount);
         _mint(sender, amount);
+        bytes32 dealId = bytes32(0);
+        if (data.length > 0) {
+            dealId = _decodeDataAndMatchOrders(sender, data);
+        }
         return true;
     }
 
+    /******************************************************************************
+     *        Token Spender: Atomic Deposit+Match if used with RLC.approveAndCall *
+     *****************************************************************************/
+
+    /**
+     * @dev Internal function to match orders after deposit
+     * @param sender The user who deposited (must be the requester)
+     * @param data ABI-encoded orders
+     * @return dealId The deal ID of the matched deal
+     */
+    function _decodeDataAndMatchOrders(
+        address sender,
+        bytes calldata data
+    ) internal returns (bytes32 dealId) {
+        // Decode the orders from calldata
+        (
+            IexecLibOrders_v5.AppOrder memory apporder,
+            IexecLibOrders_v5.DatasetOrder memory datasetorder,
+            IexecLibOrders_v5.WorkerpoolOrder memory workerpoolorder,
+            IexecLibOrders_v5.RequestOrder memory requestorder
+        ) = abi.decode(
+                data,
+                (
+                    IexecLibOrders_v5.AppOrder,
+                    IexecLibOrders_v5.DatasetOrder,
+                    IexecLibOrders_v5.WorkerpoolOrder,
+                    IexecLibOrders_v5.RequestOrder
+                )
+            );
+
+        // Validate that sender is the requester
+        if (requestorder.requester != sender) revert("caller-must-be-requester");
+
+        // Call matchOrders on the IexecPoco1 facet through the diamond
+        // Using delegatecall for safety: preserves msg.sender context
+        // Note: matchOrders doesn't use msg.sender, but delegatecall is safer
+        // in case the implementation changes in the future
+        (bool success, bytes memory result) = address(this).delegatecall(
+            abi.encodeWithSelector(
+                IexecPoco1.matchOrders.selector,
+                apporder,
+                datasetorder,
+                workerpoolorder,
+                requestorder
+            )
+        );
+
+        // Handle failure and bubble up revert reason
+        if (!success) {
+            if (result.length > 0) {
+                // Decode and revert with the original error
+                assembly {
+                    let returndata_size := mload(result)
+                    revert(add(result, 32), returndata_size)
+                }
+            } else {
+                revert("receive-approval-failed");
+            }
+        }
+
+        // Decode the dealId from successful call
+        dealId = abi.decode(result, (bytes32));
+
+        return dealId;
+    }
+
     function _deposit(address from, uint256 amount) internal {
         PocoStorageLib.PocoStorage storage $ = PocoStorageLib.getPocoStorage();
-        require($.m_baseToken.transferFrom(from, address(this), amount), "failled-transferFrom");
+        require($.m_baseToken.transferFrom(from, address(this), amount), "failed-transferFrom");
     }
 
     function _withdraw(address to, uint256 amount) internal {

contracts/facets/IexecPoco1Facet.sol

@@ -140,6 +140,11 @@ contract IexecPoco1Facet is
     /**
      * Match orders. The requester gets debited.
      *
+     * @notice This function does not use `msg.sender` to determine who pays for the deal.
+     * The sponsor is always set to `_requestorder.requester`, regardless of who calls this function.
+     * This design allows the function to be safely called via delegatecall from other facets
+     * (e.g., IexecEscrowTokenFacet.receiveApproval) without security concerns.
+     *
      * @param _apporder The app order.
      * @param _datasetorder The dataset order.
      * @param _workerpoolorder The workerpool order.

contracts/interfaces/IexecEscrowToken.sol

@@ -6,7 +6,6 @@ pragma solidity ^0.8.0;
 interface IexecEscrowToken {
     receive() external payable;
     fallback() external payable;
-
     function deposit(uint256) external returns (bool);
     function depositFor(uint256, address) external returns (bool);
     function depositForArray(uint256[] calldata, address[] calldata) external returns (bool);

docs/solidity/index.md

@@ -247,9 +247,33 @@ function recover() external returns (uint256)
 ### receiveApproval
 
 ```solidity
-function receiveApproval(address sender, uint256 amount, address token, bytes) external returns (bool)
+function receiveApproval(address sender, uint256 amount, address token, bytes data) external returns (bool)
 ```
 
+Receives approval and optionally matches orders in one transaction
+
+Usage patterns:
+1. Simple deposit: RLC.approveAndCall(escrow, amount, "")
+2. Deposit + match: RLC.approveAndCall(escrow, amount, encodedOrders)
+
+The `data` parameter should be ABI-encoded orders if matching is desired:
+abi.encode(appOrder, datasetOrder, workerpoolOrder, requestOrder)
+
+#### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| sender | address | The address that approved tokens (must be requester if matching) |
+| amount | uint256 | Amount of tokens approved and to be deposited |
+| token | address | Address of the token (must be RLC) |
+| data | bytes | Optional: ABI-encoded orders for matching |
+
+#### Return Values
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| [0] | bool | success True if operation succeeded @custom:example ```solidity // Encode orders bytes memory data = abi.encode(appOrder, datasetOrder, workerpoolOrder, requestOrder); // One transaction does it all RLC(token).approveAndCall(iexecProxy, dealCost, data); ``` |
+
 ## IexecOrderManagementFacet
 
 ### manageAppOrder
@@ -343,6 +367,11 @@ function matchOrders(struct IexecLibOrders_v5.AppOrder _apporder, struct IexecLi
 
 Match orders. The requester gets debited.
 
+This function does not use `msg.sender` to determine who pays for the deal.
+The sponsor is always set to `_requestorder.requester`, regardless of who calls this function.
+This design allows the function to be safely called via delegatecall from other facets
+(e.g., IexecEscrowTokenFacet.receiveApproval) without security concerns.
+
 #### Parameters
 
 | Name | Type | Description |