@sudobility/auctions_contracts 0.1.3

package/contracts/core/AuctionRegistryStorage.sol

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import "../interfaces/IAuctionTypes.sol";
+
+/**
+ * @title AuctionRegistryStorage
+ * @notice Storage layout for the AuctionRegistry contract
+ * @dev This contract defines storage variables for UUPS proxy safety
+ */
+abstract contract AuctionRegistryStorage is IAuctionTypes {
+    // ============ Core Auction Storage ============
+
+    /// @notice Mapping from auction ID to core auction data
+    mapping(uint256 => AuctionCore) internal _auctions;
+
+    /// @notice Mapping from auction ID to Traditional auction parameters
+    mapping(uint256 => TraditionalParams) internal _traditionalParams;
+
+    /// @notice Mapping from auction ID to Dutch auction parameters
+    mapping(uint256 => DutchParams) internal _dutchParams;
+
+    /// @notice Mapping from auction ID to Penny auction parameters
+    mapping(uint256 => PennyParams) internal _pennyParams;
+
+    /// @notice Mapping from auction ID to array of items
+    mapping(uint256 => AuctionItem[]) internal _auctionItems;
+
+    /// @notice Counter for auction IDs
+    uint256 internal _nextAuctionId;
+
+    // ============ Access Control Storage ============
+
+    /// @notice Contract owner
+    address internal _owner;
+
+    /// @notice Pending owner for 2-step transfer
+    address internal _pendingOwner;
+
+    /// @notice Whether the contract is paused
+    bool internal _paused;
+
+    // ============ Fee Storage ============
+
+    /// @notice Fee rate in basis points (50 = 0.5%)
+    uint16 internal _feeRate;
+
+    /// @notice Fee recipient address
+    address internal _feeRecipient;
+
+    /// @notice Accumulated fees per token
+    mapping(address => uint256) internal _accumulatedFees;
+
+    // ============ Reentrancy Guard ============
+
+    /// @notice Reentrancy status
+    uint256 internal _reentrancyStatus;
+
+    /// @notice Not entered constant
+    uint256 internal constant _NOT_ENTERED = 1;
+
+    /// @notice Entered constant
+    uint256 internal constant _ENTERED = 2;
+
+    // ============ Time Constants ============
+
+    /// @notice 24 hours in seconds for dealer acceptance window
+    uint256 internal constant ACCEPTANCE_PERIOD = 24 hours;
+
+    /// @notice 5 minutes in seconds for Penny auction timer
+    uint64 internal constant PENNY_TIMER_DURATION = 5 minutes;
+
+    // ============ Storage Gap ============
+
+    /// @notice Storage gap for future upgrades
+    uint256[50] private __gap;
+}

package/contracts/interfaces/IAuctionEvents.sol

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import "./IAuctionTypes.sol";
+
+/**
+ * @title IAuctionEvents
+ * @notice Events emitted by the auction system
+ */
+interface IAuctionEvents {
+    // ============ Auction Lifecycle Events ============
+
+    /// @notice Emitted when a new auction is created
+    event AuctionCreated(
+        uint256 indexed auctionId,
+        address indexed dealer,
+        IAuctionTypes.AuctionType auctionType,
+        address paymentToken,
+        uint96 deadline
+    );
+
+    /// @notice Emitted when an item is deposited into an auction
+    event ItemDeposited(
+        uint256 indexed auctionId,
+        address indexed tokenAddress,
+        IAuctionTypes.ItemType itemType,
+        uint256 tokenId,
+        uint256 amount
+    );
+
+    // ============ Bidding Events ============
+
+    /// @notice Emitted when a bid is placed on a Traditional auction
+    event BidPlaced(
+        uint256 indexed auctionId,
+        address indexed bidder,
+        uint128 amount,
+        uint128 previousBid
+    );
+
+    /// @notice Emitted when a previous bidder is refunded
+    event BidRefunded(
+        uint256 indexed auctionId,
+        address indexed bidder,
+        uint128 amount
+    );
+
+    /// @notice Emitted when someone purchases in a Dutch auction
+    event DutchPurchase(
+        uint256 indexed auctionId,
+        address indexed buyer,
+        uint128 price
+    );
+
+    /// @notice Emitted when a bid is placed on a Penny auction
+    event PennyBidPlaced(
+        uint256 indexed auctionId,
+        address indexed bidder,
+        uint128 incrementPaid,
+        uint128 totalPaid,
+        uint64 newDeadline
+    );
+
+    // ============ Finalization Events ============
+
+    /// @notice Emitted when an auction is successfully finalized
+    event AuctionFinalized(
+        uint256 indexed auctionId,
+        address indexed winner,
+        uint128 finalPrice,
+        uint128 feeAmount
+    );
+
+    /// @notice Emitted when a Traditional auction expires below reserve
+    event AuctionExpired(
+        uint256 indexed auctionId,
+        uint96 acceptanceDeadline
+    );
+
+    /// @notice Emitted when dealer accepts a bid below reserve
+    event DealerAccepted(
+        uint256 indexed auctionId,
+        uint128 acceptedBid
+    );
+
+    /// @notice Emitted when an auction is refunded (items to dealer, payment to bidder)
+    event AuctionRefunded(
+        uint256 indexed auctionId,
+        address indexed dealer,
+        address indexed bidder
+    );
+
+    // ============ Admin Events ============
+
+    /// @notice Emitted when the contract is paused
+    event Paused(address indexed by);
+
+    /// @notice Emitted when the contract is unpaused
+    event Unpaused(address indexed by);
+
+    /// @notice Emitted when the fee rate is updated
+    event FeeRateUpdated(uint16 oldRate, uint16 newRate);
+
+    /// @notice Emitted when the fee recipient is updated
+    event FeeRecipientUpdated(address indexed oldRecipient, address indexed newRecipient);
+
+    /// @notice Emitted when fees are claimed
+    event FeesClaimed(address indexed token, address indexed recipient, uint256 amount);
+
+    /// @notice Emitted when ownership is transferred
+    event OwnershipTransferStarted(address indexed previousOwner, address indexed newOwner);
+
+    /// @notice Emitted when ownership transfer is accepted
+    event OwnershipTransferred(address indexed previousOwner, address indexed newOwner);
+}

package/contracts/interfaces/IAuctionRegistry.sol

@@ -0,0 +1,230 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import "./IAuctionTypes.sol";
+
+/**
+ * @title IAuctionRegistry
+ * @notice Interface for the main auction registry contract
+ */
+interface IAuctionRegistry is IAuctionTypes {
+    // ============ Auction Creation ============
+
+    /**
+     * @notice Create a Traditional auction
+     * @param items Array of items to auction
+     * @param paymentToken ERC-20 token for payments
+     * @param startAmount Minimum first bid
+     * @param increment Minimum bid increase
+     * @param reservePrice Minimum price to auto-finalize
+     * @param deadline Auction end timestamp
+     * @return auctionId The ID of the created auction
+     */
+    function createTraditionalAuction(
+        AuctionItem[] calldata items,
+        address paymentToken,
+        uint128 startAmount,
+        uint128 increment,
+        uint128 reservePrice,
+        uint96 deadline
+    ) external returns (uint256 auctionId);
+
+    /**
+     * @notice Create a Dutch auction
+     * @param items Array of items to auction
+     * @param paymentToken ERC-20 token for payments
+     * @param startPrice Initial price
+     * @param decreaseAmount Price decrease per interval
+     * @param decreaseInterval Seconds between decreases
+     * @param minimumPrice Floor price
+     * @param deadline Auction end timestamp
+     * @return auctionId The ID of the created auction
+     */
+    function createDutchAuction(
+        AuctionItem[] calldata items,
+        address paymentToken,
+        uint128 startPrice,
+        uint128 decreaseAmount,
+        uint64 decreaseInterval,
+        uint128 minimumPrice,
+        uint96 deadline
+    ) external returns (uint256 auctionId);
+
+    /**
+     * @notice Create a Penny auction
+     * @param items Array of items to auction
+     * @param paymentToken ERC-20 token for payments
+     * @param incrementAmount Fixed bid increment amount
+     * @return auctionId The ID of the created auction
+     */
+    function createPennyAuction(
+        AuctionItem[] calldata items,
+        address paymentToken,
+        uint128 incrementAmount
+    ) external returns (uint256 auctionId);
+
+    // ============ Bidding ============
+
+    /**
+     * @notice Place a bid on a Traditional auction
+     * @param auctionId The auction ID
+     * @param amount The bid amount
+     */
+    function bidTraditional(uint256 auctionId, uint128 amount) external;
+
+    /**
+     * @notice Buy at current price in a Dutch auction
+     * @param auctionId The auction ID
+     */
+    function buyDutch(uint256 auctionId) external;
+
+    /**
+     * @notice Place a bid on a Penny auction
+     * @param auctionId The auction ID
+     */
+    function bidPenny(uint256 auctionId) external;
+
+    // ============ Finalization ============
+
+    /**
+     * @notice Finalize an auction
+     * @dev Can be called by anyone when conditions are met
+     * @param auctionId The auction ID
+     */
+    function finalizeAuction(uint256 auctionId) external;
+
+    /**
+     * @notice Dealer accepts bid below reserve price (Traditional only)
+     * @param auctionId The auction ID
+     */
+    function dealerAcceptBid(uint256 auctionId) external;
+
+    // ============ View Functions ============
+
+    /**
+     * @notice Get auction core data and items
+     * @param auctionId The auction ID
+     * @return core The core auction data
+     * @return items The auction items
+     */
+    function getAuction(uint256 auctionId)
+        external
+        view
+        returns (AuctionCore memory core, AuctionItem[] memory items);
+
+    /**
+     * @notice Get Traditional auction parameters
+     * @param auctionId The auction ID
+     * @return params The Traditional auction parameters
+     */
+    function getTraditionalParams(uint256 auctionId)
+        external
+        view
+        returns (TraditionalParams memory params);
+
+    /**
+     * @notice Get Dutch auction parameters
+     * @param auctionId The auction ID
+     * @return params The Dutch auction parameters
+     */
+    function getDutchParams(uint256 auctionId)
+        external
+        view
+        returns (DutchParams memory params);
+
+    /**
+     * @notice Get current price for a Dutch auction
+     * @param auctionId The auction ID
+     * @return currentPrice The current price
+     */
+    function getDutchCurrentPrice(uint256 auctionId)
+        external
+        view
+        returns (uint128 currentPrice);
+
+    /**
+     * @notice Get Penny auction parameters
+     * @param auctionId The auction ID
+     * @return params The Penny auction parameters
+     */
+    function getPennyParams(uint256 auctionId)
+        external
+        view
+        returns (PennyParams memory params);
+
+    /**
+     * @notice Get effective deadline for a Penny auction
+     * @param auctionId The auction ID
+     * @return effectiveDeadline The effective deadline (lastBidTime + timerDuration)
+     */
+    function getPennyDeadline(uint256 auctionId)
+        external
+        view
+        returns (uint256 effectiveDeadline);
+
+    /**
+     * @notice Get the next auction ID
+     * @return The next auction ID that will be assigned
+     */
+    function nextAuctionId() external view returns (uint256);
+
+    /**
+     * @notice Check if the contract is paused
+     * @return True if paused
+     */
+    function paused() external view returns (bool);
+
+    /**
+     * @notice Get the fee rate in basis points
+     * @return The fee rate (50 = 0.5%)
+     */
+    function feeRate() external view returns (uint16);
+
+    /**
+     * @notice Get accumulated fees for a token
+     * @param token The token address
+     * @return The accumulated fee amount
+     */
+    function accumulatedFees(address token) external view returns (uint256);
+
+    // ============ Admin Functions ============
+
+    /**
+     * @notice Pause the contract
+     */
+    function pause() external;
+
+    /**
+     * @notice Unpause the contract
+     */
+    function unpause() external;
+
+    /**
+     * @notice Set the fee rate
+     * @param newRate New fee rate in basis points (max 1000 = 10%)
+     */
+    function setFeeRate(uint16 newRate) external;
+
+    /**
+     * @notice Set the fee recipient
+     * @param newRecipient New fee recipient address
+     */
+    function setFeeRecipient(address newRecipient) external;
+
+    /**
+     * @notice Claim accumulated fees for a token
+     * @param token The token address to claim fees for
+     */
+    function claimFees(address token) external;
+
+    /**
+     * @notice Start ownership transfer
+     * @param newOwner The new owner address
+     */
+    function transferOwnership(address newOwner) external;
+
+    /**
+     * @notice Accept ownership transfer
+     */
+    function acceptOwnership() external;
+}

package/contracts/interfaces/IAuctionTypes.sol

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+/**
+ * @title IAuctionTypes
+ * @notice Shared types for the auction system
+ */
+interface IAuctionTypes {
+    /// @notice Types of auctions supported
+    enum AuctionType {
+        Traditional,  // 0 - English auction with reserve price
+        Dutch,        // 1 - Descending price auction
+        Penny         // 2 - Incremental bid auction with timer reset
+    }
+
+    /// @notice Status of an auction
+    enum AuctionStatus {
+        Active,       // 0 - Auction is live and accepting bids
+        Expired,      // 1 - Deadline passed, pending finalization
+        Finalized,    // 2 - Successfully completed
+        Refunded      // 3 - Items returned to dealer, bidder refunded
+    }
+
+    /// @notice Types of tokens that can be auctioned
+    enum ItemType {
+        ERC20,        // 0 - Fungible tokens
+        ERC721,       // 1 - Non-fungible tokens
+        ERC1155       // 2 - Semi-fungible tokens
+    }
+
+    /// @notice Represents an item in an auction
+    /// @dev Supports ERC-20, ERC-721, and ERC-1155 tokens
+    struct AuctionItem {
+        address tokenAddress;  // Token contract address
+        ItemType itemType;     // Type of token
+        uint256 tokenId;       // Token ID (0 for ERC-20)
+        uint256 amount;        // Quantity (1 for ERC-721)
+    }
+
+    /// @notice Core auction data shared across all auction types
+    /// @dev Packed for storage efficiency
+    struct AuctionCore {
+        address dealer;           // Auction creator
+        AuctionType auctionType;  // Type of auction
+        AuctionStatus status;     // Current status
+        address paymentToken;     // ERC-20 token for payments
+        uint96 deadline;          // Auction end timestamp
+        address highBidder;       // Current highest bidder / buyer
+        uint128 currentBid;       // Current bid amount
+        uint64 createdAt;         // Creation timestamp
+    }
+
+    /// @notice Parameters specific to Traditional auctions
+    struct TraditionalParams {
+        uint128 startAmount;           // Minimum first bid
+        uint128 increment;             // Minimum bid increase
+        uint128 reservePrice;          // Minimum price to auto-finalize
+        uint96 acceptanceDeadline;     // Dealer acceptance deadline (24h after auction end)
+        bool reserveMet;               // Whether reserve price was met
+    }
+
+    /// @notice Parameters specific to Dutch auctions
+    struct DutchParams {
+        uint128 startPrice;       // Initial price
+        uint128 decreaseAmount;   // Price decrease per interval
+        uint64 decreaseInterval;  // Seconds between decreases
+        uint128 minimumPrice;     // Floor price
+        uint64 startTime;         // When price starts decreasing
+    }
+
+    /// @notice Parameters specific to Penny auctions
+    struct PennyParams {
+        uint128 incrementAmount;  // Fixed bid increment (paid to dealer)
+        uint128 totalPaid;        // Total payments received
+        uint64 lastBidTime;       // Timestamp of last bid
+        uint64 timerDuration;     // Timer reset duration (5 minutes)
+    }
+}

package/contracts/libraries/FeeLib.sol

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+/**
+ * @title FeeLib
+ * @notice Library for fee calculations
+ */
+library FeeLib {
+    /// @notice Maximum fee rate (10%)
+    uint16 internal constant MAX_FEE_RATE = 1000;
+
+    /// @notice Fee denominator (basis points)
+    uint16 internal constant FEE_DENOMINATOR = 10000;
+
+    /// @notice Default fee rate (0.5%)
+    uint16 internal constant DEFAULT_FEE_RATE = 50;
+
+    /**
+     * @notice Calculate fee and net amount from a total amount
+     * @param amount The total amount
+     * @param feeRate The fee rate in basis points
+     * @return fee The fee amount
+     * @return netAmount The amount after fee deduction
+     */
+    function calculateFee(
+        uint256 amount,
+        uint16 feeRate
+    ) internal pure returns (uint256 fee, uint256 netAmount) {
+        fee = (amount * feeRate) / FEE_DENOMINATOR;
+        netAmount = amount - fee;
+    }
+
+    /**
+     * @notice Validate that a fee rate is within acceptable bounds
+     * @param feeRate The fee rate to validate
+     */
+    function validateFeeRate(uint16 feeRate) internal pure {
+        require(feeRate <= MAX_FEE_RATE, "FeeLib: fee rate too high");
+    }
+}

package/contracts/libraries/TokenTransferLib.sol

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import "@openzeppelin/contracts/token/ERC721/IERC721.sol";
+import "@openzeppelin/contracts/token/ERC1155/IERC1155.sol";
+import "../interfaces/IAuctionTypes.sol";
+
+/**
+ * @title TokenTransferLib
+ * @notice Library for safe token transfers across ERC-20, ERC-721, and ERC-1155
+ */
+library TokenTransferLib {
+    using SafeERC20 for IERC20;
+
+    /**
+     * @notice Transfer ERC-20 tokens safely
+     * @param token The token contract address
+     * @param from The sender address
+     * @param to The recipient address
+     * @param amount The amount to transfer
+     */
+    function safeTransferERC20(
+        address token,
+        address from,
+        address to,
+        uint256 amount
+    ) internal {
+        if (from == address(this)) {
+            IERC20(token).safeTransfer(to, amount);
+        } else {
+            IERC20(token).safeTransferFrom(from, to, amount);
+        }
+    }
+
+    /**
+     * @notice Transfer ERC-721 token safely
+     * @param token The token contract address
+     * @param from The sender address
+     * @param to The recipient address
+     * @param tokenId The token ID to transfer
+     */
+    function safeTransferERC721(
+        address token,
+        address from,
+        address to,
+        uint256 tokenId
+    ) internal {
+        IERC721(token).safeTransferFrom(from, to, tokenId);
+    }
+
+    /**
+     * @notice Transfer ERC-1155 token safely
+     * @param token The token contract address
+     * @param from The sender address
+     * @param to The recipient address
+     * @param tokenId The token ID to transfer
+     * @param amount The amount to transfer
+     */
+    function safeTransferERC1155(
+        address token,
+        address from,
+        address to,
+        uint256 tokenId,
+        uint256 amount
+    ) internal {
+        IERC1155(token).safeTransferFrom(from, to, tokenId, amount, "");
+    }
+
+    /**
+     * @notice Transfer an auction item based on its type
+     * @param item The auction item to transfer
+     * @param from The sender address
+     * @param to The recipient address
+     */
+    function transferItem(
+        IAuctionTypes.AuctionItem memory item,
+        address from,
+        address to
+    ) internal {
+        if (item.itemType == IAuctionTypes.ItemType.ERC20) {
+            safeTransferERC20(item.tokenAddress, from, to, item.amount);
+        } else if (item.itemType == IAuctionTypes.ItemType.ERC721) {
+            safeTransferERC721(item.tokenAddress, from, to, item.tokenId);
+        } else if (item.itemType == IAuctionTypes.ItemType.ERC1155) {
+            safeTransferERC1155(item.tokenAddress, from, to, item.tokenId, item.amount);
+        }
+    }
+
+    /**
+     * @notice Transfer multiple auction items
+     * @param items Array of auction items to transfer
+     * @param from The sender address
+     * @param to The recipient address
+     */
+    function transferItems(
+        IAuctionTypes.AuctionItem[] memory items,
+        address from,
+        address to
+    ) internal {
+        uint256 length = items.length;
+        for (uint256 i = 0; i < length; ) {
+            transferItem(items[i], from, to);
+            unchecked { ++i; }
+        }
+    }
+
+    /**
+     * @notice Validate that a token address is a contract
+     * @param token The token address to validate
+     */
+    function validateTokenAddress(address token) internal view {
+        require(token != address(0), "TokenTransferLib: zero address");
+        require(token.code.length > 0, "TokenTransferLib: not a contract");
+    }
+}

package/contracts/test/mocks/MockERC1155.sol

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import "@openzeppelin/contracts/token/ERC1155/ERC1155.sol";
+
+/**
+ * @title MockERC1155
+ * @notice Mock ERC-1155 token for testing
+ */
+contract MockERC1155 is ERC1155 {
+    constructor(string memory uri_) ERC1155(uri_) {}
+
+    function mint(
+        address to,
+        uint256 id,
+        uint256 amount
+    ) external {
+        _mint(to, id, amount, "");
+    }
+
+    function mintBatch(
+        address to,
+        uint256[] memory ids,
+        uint256[] memory amounts
+    ) external {
+        _mintBatch(to, ids, amounts, "");
+    }
+
+    function burn(
+        address from,
+        uint256 id,
+        uint256 amount
+    ) external {
+        _burn(from, id, amount);
+    }
+}