PurchaseEscrow

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

/**
 * @title IPurchaseEscrow
 * @dev Interface for managing purchase transactions in an escrow system.
 */
interface IPurchaseEscrow {

    /**
     * @dev Struct representing a purchase transaction.
     * @param exists Indicates if the purchase exists.
     * @param purchaseId The unique identifier for the purchase.
     * @param productId The unique identifier for the product being purchased.
     * @param quantity The quantity of the product being purchased.
     * @param buyer The address of the buyer.
     * @param seller The address of the seller.
     * @param validator The address of the validator.
     * @param amount The amount of the purchase in wei.
     * @param isDisputed Indicates if the purchase is disputed.
     * @param isFinalized Indicates if the purchase is finalized.
     */
    struct Purchase {
        bool exists;
        uint256 purchaseId;
        uint256 productId;
        uint256 quantity;
        address payable buyer;
        address payable seller;
        address payable validator;
        uint256 amount;
        bool isDisputed;
        bool isFinalized;
    }

    struct InitiatePurchaseInput {
        uint256 productId;
        uint256 quantity;
        address payable buyer; 
        address payable seller; 
        address payable validator;
    }

    struct InitiateCartCheckoutInput {
        uint256[] productIds;
        uint256[] quantities;
        address payable buyer;
        address payable validator;
    }

    /**
     * @dev Emitted when a new purchase is initiated.
     * @param productId The unique identifier for the product.
     * @param buyer The address of the buyer.
     * @param seller The address of the seller.
     */
    event PurchaseInitiated(uint256 indexed productId, address indexed buyer, address indexed seller);

    /**
     * @dev Emitted when a validator is assigned to a purchase.
     * @param purchaseId The unique identifier for the purchase.
     * @param validator The address of the validator.
     */
    event ValidatorAssignedToPurchase(uint256 indexed purchaseId, address indexed validator);

    /**
     * @dev Emitted when a cart checkout is initiated.
     * @param purchaseIds The unique identifiers for the purchases.
     * @param productIds The unique identifiers for the products.
     * @param buyer The address of the buyer.
     * @param validator The address of the validator.
     * @param amount The total amount of the purchases in wei.
     */
    event CheckoutPurchaseInitiated(uint256[] indexed purchaseIds, uint256[] indexed productIds, address indexed buyer, address validator, uint256 amount);

    /**
     * @dev Emitted when a validator is assigned to multiple purchases.
     * @param purchaseIds The unique identifiers for the purchases.
     * @param validator The address of the validator.
     */
    event ValidatorAssignedToPurchases(uint256[] indexed purchaseIds, address indexed validator);

    /**
     * @dev Emitted when a dispute is initiated for a purchase.
     * @param purchaseId The unique identifier for the purchase.
     */
    event DisputeInitiated(uint256 indexed purchaseId);

    /**
     * @dev Emitted when a purchase is finalized.
     * @param purchaseId The unique identifier for the purchase.
     */
    event PurchaseFinalized(uint256 indexed purchaseId);

    /**
     * @dev Emitted when the rewards address is updated.
     * @param newAddress The new rewards address.
     */
    event RewardsAddressUpdated(address indexed newAddress);

    /**
     * @dev Emitted when funds are released from escrow.
     * @param purchaseId The unique identifier for the purchase.
     * @param seller The address of the seller.
     * @param toBuyer Indicates if the funds were released to the seller.
     */
    event FundsReleased(uint256 indexed purchaseId, address indexed seller, bool indexed toBuyer);

    /**
     * @notice Retrieves the details of a purchase by its unique identifier.
     * @param purchaseId The unique identifier of the purchase.
     * @return purchase The details of the purchase.
     */
    function getPurchase(uint256 purchaseId) external view returns (Purchase memory);

    /**
     * @notice Retrieves the details of a purchase by the product's unique identifier.
     * @param productId The unique identifier of the product.
     * @return purchase The details of the purchase.
     */
    function getPurchaseByProductId(uint256 productId) external view returns (Purchase memory);

    /**
     * @notice Checks if a buyer has purchased from a seller.
     * @param buyer The address of the buyer.
     * @param seller The address of the seller.
     * @return hasPurchased True if the buyer has purchased from the seller, otherwise false.
     */
    function hasPurchased(address buyer, address seller) external view returns (bool);

    /**
     * @notice Initiates a new purchase.
     * @param input The struct containing all input parameters.
     */
    function initiatePurchase(InitiatePurchaseInput calldata input) external payable;

    /**
     * @notice Initiates a cart checkout with multiple products.
     * @param input The struct containing all input parameters.
     */
    function initiateCartCheckout(InitiateCartCheckoutInput calldata input) external payable;

    /**
     * @notice Initiates a dispute for a purchase.
     * @param purchaseId The unique identifier of the purchase.
     */
    function initiateDispute(uint256 purchaseId) external;

    /**
     * @notice Resolves a dispute for a purchase.
     * @param purchaseId The unique identifier of the purchase.
     * @param approveBuyerRefund Indicates if the release of funds is approved.
     */
    function resolveDispute(uint256 purchaseId, bool approveBuyerRefund) external;

    /**
     * @notice Finalizes a purchase, confirming receipt or satisfactory product condition.
     * @param purchaseId The unique identifier of the purchase.
     */
    function finalizePurchase(uint256 purchaseId) external;

    /**
     * @notice Updates the rewards address.
     * @param newAddress The new rewards address.
     */
    function updateRewardsAddress(address newAddress) external;
}