PacksInitializable

{{
  "language": "Solidity",
  "sources": {
    "src/packs/PacksInitializable.sol": {
      "content": "// SPDX-License-Identifier: MIT
pragma solidity 0.8.28;

import {Packs} from "./Packs.sol";
import {UUPSUpgradeable} from "@openzeppelin/contracts/proxy/utils/UUPSUpgradeable.sol";
import {IPRNG} from "../common/interfaces/IPRNG.sol";

contract PacksInitializable is Packs, UUPSUpgradeable {
    error InvalidZeroAddress();

    /// @dev Disables initializers for the implementation contract.
    constructor() Packs(0, 0, address(0x2), address(0x3), address(0x4)) {
        _disableInitializers();
    }

    /// @notice Initializes the contract and handles any pre-existing balance
    /// @dev Sets up EIP712 domain separator and deposits any ETH sent during deployment
    function initialize(
        uint256 protocolFee_,
        uint256 flatFee_,
        address initialOwner_,
        address fundsReceiver_,
        address prng_,
        address fundsReceiverManager_
    ) public initializer {
        if (initialOwner_ == address(0)) revert InvalidZeroAddress();

        __ReentrancyGuard_init();
        __MEAccessControl_init();
        __Pausable_init();
        __PacksSignatureVerifier_init("Packs", "1");

        uint256 existingBalance = address(this).balance;
        if (existingBalance > 0) {
            _depositTreasury(existingBalance);
        }

        _setProtocolFee(protocolFee_);
        _setFlatFee(flatFee_);
        _setFundsReceiver(fundsReceiver_);
        PRNG = IPRNG(prng_);
        _grantRole(FUNDS_RECEIVER_MANAGER_ROLE, fundsReceiverManager_);

        // Initialize reward limits
        minReward = 0.01 ether;
        maxReward = 5 ether;

        minPackPrice = 0.01 ether;
        maxPackPrice = 0.25 ether;

        // Initialize expiries
        commitCancellableTime = 1 days;
        nftFulfillmentExpiryTime = 10 minutes;

        // Grant roles to initial owner
        _grantRole(DEFAULT_ADMIN_ROLE, initialOwner_);
        _grantRole(OPS_ROLE, initialOwner_);
        _grantRole(RESCUE_ROLE, initialOwner_);
    }

    /// @dev Overriden to prevent unauthorized upgrades.
    function _authorizeUpgrade(
        address newImplementation
    ) internal override onlyRole(DEFAULT_ADMIN_ROLE) {
        if (newImplementation == address(0))
            revert InvalidZeroAddress();
    }
}

"
    },
    "src/packs/Packs.sol": {
      "content": "// SPDX-License-Identifier: MIT
pragma solidity 0.8.28;

import {Errors} from "../common/Errors.sol";

import "./base/PacksCommit.sol";
import "./base/PacksFulfill.sol";
import "./base/PacksAdmin.sol";

contract Packs is
    PacksAdmin,
    PacksCommit,
    PacksFulfill
{
    // ============================================================
    // MODIFIERS
    // ============================================================

    modifier onlyCommitOwnerOrCosigner(uint256 commitId_) {
        if (packs[commitId_].receiver != msg.sender && packs[commitId_].cosigner != msg.sender) {
            revert Errors.InvalidCommitOwner();
        }
        _;
    }

    // ============================================================
    // CONSTRUCTOR
    // ============================================================

    constructor(uint256 protocolFee_,uint256 flatFee_,address fundsReceiver_, address prng_, address fundsReceiverManager_) initializer {
        __MEAccessControl_init();
        __Pausable_init();
        __PacksSignatureVerifier_init("Packs", "1");
        __ReentrancyGuard_init();

        uint256 existingBalance = address(this).balance;
        if (existingBalance > 0) {
            _depositTreasury(existingBalance);
        }

        _setProtocolFee(protocolFee_);
        _setFlatFee(flatFee_);
        _setFundsReceiver(fundsReceiver_);
        PRNG = IPRNG(prng_);
        _grantRole(FUNDS_RECEIVER_MANAGER_ROLE, fundsReceiverManager_);

        // Initialize reward limits
        minReward = 0.01 ether;
        maxReward = 5 ether;

        minPackPrice = 0.01 ether;
        maxPackPrice = 0.25 ether;

        // Initialize expiries
        commitCancellableTime = 1 hours;
        nftFulfillmentExpiryTime = 10 minutes;
    }

    // ============================================================
    // CORE BUSINESS LOGIC
    // ============================================================

    function commit(
        address receiver_,
        address cosigner_,
        uint256 seed_,
        PackType packType_,
        BucketData[] memory buckets_,
        bytes memory signature_
    ) external payable whenNotPaused returns (uint256) {
        return _commit(receiver_, cosigner_, seed_, packType_, buckets_, signature_);
    }

    function fulfill(
        uint256 commitId_,
        address marketplace_,
        bytes calldata orderData_,
        uint256 orderAmount_,
        address token_,
        uint256 tokenId_,
        uint256 payoutAmount_,
        bytes calldata commitSignature_,
        bytes calldata fulfillmentSignature_,
        FulfillmentOption choice_
    ) public payable whenNotPaused {
        _fulfill(
            commitId_,
            marketplace_,
            orderData_,
            orderAmount_,
            token_,
            tokenId_,
            payoutAmount_,
            commitSignature_,
            fulfillmentSignature_,
            choice_
        );
    }

    function fulfillByDigest(
        bytes32 commitDigest_,
        address marketplace_,
        bytes calldata orderData_,
        uint256 orderAmount_,
        address token_,
        uint256 tokenId_,
        uint256 payoutAmount_,
        bytes calldata commitSignature_,
        bytes calldata fulfillmentSignature_,
        FulfillmentOption choice_
    ) external payable whenNotPaused {
        return fulfill(
            commitIdByDigest[commitDigest_],
            marketplace_,
            orderData_,
            orderAmount_,
            token_,
            tokenId_,
            payoutAmount_,
            commitSignature_,
            fulfillmentSignature_,
            choice_
        );
    }

    function cancel(uint256 commitId_) external nonReentrant onlyCommitOwnerOrCosigner(commitId_) {
        _cancel(commitId_);
    }

    // ============================================================
    // TREASURY MANAGEMENT
    // ============================================================

    function withdrawTreasury(uint256 amount) external nonReentrant onlyRole(DEFAULT_ADMIN_ROLE) {
        _withdrawTreasury(amount);
    }

    function emergencyWithdraw() external nonReentrant onlyRole(DEFAULT_ADMIN_ROLE) {
        _emergencyWithdraw();
    }

    receive() external payable {
        _depositTreasury(msg.value);
    }

    // ============================================================
    // ADMIN CONFIGURATION
    // ============================================================

    function addCosigner(address cosigner_) external onlyRole(DEFAULT_ADMIN_ROLE) {
        _addCosigner(cosigner_);
    }

    function removeCosigner(address cosigner_) external onlyRole(DEFAULT_ADMIN_ROLE) {
        _removeCosigner(cosigner_);
    }

    function setCommitCancellableTime(uint256 commitCancellableTime_) external onlyRole(DEFAULT_ADMIN_ROLE) {
        _updateCommitCancellableTime(commitCancellableTime_);
    }

    function setNftFulfillmentExpiryTime(uint256 nftFulfillmentExpiryTime_) external onlyRole(DEFAULT_ADMIN_ROLE) {
        _updateNftFulfillmentExpiryTime(nftFulfillmentExpiryTime_);
    }

    function setMinReward(uint256 minReward_) external onlyRole(DEFAULT_ADMIN_ROLE) {
        _updateMinReward(minReward_);
    }

    function setMaxReward(uint256 maxReward_) external onlyRole(DEFAULT_ADMIN_ROLE) {
        _updateMaxReward(maxReward_);
    }

    function setMinPackPrice(uint256 minPackPrice_) external onlyRole(DEFAULT_ADMIN_ROLE) {
        _updateMinPackPrice(minPackPrice_);
    }

    function setMaxPackPrice(uint256 maxPackPrice_) external onlyRole(DEFAULT_ADMIN_ROLE) {
        _updateMaxPackPrice(maxPackPrice_);
    }

    function setProtocolFee(uint256 protocolFee_) external onlyRole(OPS_ROLE) {
        _setProtocolFee(protocolFee_);
    }

    function setFlatFee(uint256 flatFee_) external onlyRole(OPS_ROLE) {
        _setFlatFee(flatFee_);
    }

    function setFundsReceiver(address fundsReceiver_) external onlyRole(FUNDS_RECEIVER_MANAGER_ROLE) {
        _setFundsReceiver(fundsReceiver_);
    }

    function transferFundsReceiverManager(address newFundsReceiverManager_)
        external
        onlyRole(FUNDS_RECEIVER_MANAGER_ROLE)
    {
        if (newFundsReceiverManager_ == address(0)) {
            revert Errors.InvalidFundsReceiverManager();
        }
        _transferFundsReceiverManager(newFundsReceiverManager_);
    }

    function pause() external onlyRole(DEFAULT_ADMIN_ROLE) {
        _pause();
    }

    function unpause() external onlyRole(DEFAULT_ADMIN_ROLE) {
        _unpause();
    }

    // ============================================================
    // VIEW FUNCTIONS & UTILITIES
    // ============================================================

    function getPacksLength() external view returns (uint256) {
        return packs.length;
    }
    
    // ============================================================
    // INTERNAL OVERRIDES
    // ============================================================

    function _transferFundsReceiverManager(address newFundsReceiverManager_) internal override {
        _revokeRole(FUNDS_RECEIVER_MANAGER_ROLE, msg.sender);
        _grantRole(FUNDS_RECEIVER_MANAGER_ROLE, newFundsReceiverManager_);
        emit FundsReceiverManagerTransferred(msg.sender, newFundsReceiverManager_);
    }
}
"
    },
    "lib/openzeppelin-contracts/contracts/proxy/utils/UUPSUpgradeable.sol": {
      "content": "// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.2.0) (proxy/utils/UUPSUpgradeable.sol)

pragma solidity ^0.8.22;

import {IERC1822Proxiable} from "../../interfaces/draft-IERC1822.sol";
import {ERC1967Utils} from "../ERC1967/ERC1967Utils.sol";

/**
 * @dev An upgradeability mechanism designed for UUPS proxies. The functions included here can perform an upgrade of an
 * {ERC1967Proxy}, when this contract is set as the implementation behind such a proxy.
 *
 * A security mechanism ensures that an upgrade does not turn off upgradeability accidentally, although this risk is
 * reinstated if the upgrade retains upgradeability but removes the security mechanism, e.g. by replacing
 * `UUPSUpgradeable` with a custom implementation of upgrades.
 *
 * The {_authorizeUpgrade} function must be overridden to include access restriction to the upgrade mechanism.
 */
abstract contract UUPSUpgradeable is IERC1822Proxiable {
    /// @custom:oz-upgrades-unsafe-allow state-variable-immutable
    address private immutable __self = address(this);

    /**
     * @dev The version of the upgrade interface of the contract. If this getter is missing, both `upgradeTo(address)`
     * and `upgradeToAndCall(address,bytes)` are present, and `upgradeTo` must be used if no function should be called,
     * while `upgradeToAndCall` will invoke the `receive` function if the second argument is the empty byte string.
     * If the getter returns `"5.0.0"`, only `upgradeToAndCall(address,bytes)` is present, and the second argument must
     * be the empty byte string if no function should be called, making it impossible to invoke the `receive` function
     * during an upgrade.
     */
    string public constant UPGRADE_INTERFACE_VERSION = "5.0.0";

    /**
     * @dev The call is from an unauthorized context.
     */
    error UUPSUnauthorizedCallContext();

    /**
     * @dev The storage `slot` is unsupported as a UUID.
     */
    error UUPSUnsupportedProxiableUUID(bytes32 slot);

    /**
     * @dev Check that the execution is being performed through a delegatecall call and that the execution context is
     * a proxy contract with an implementation (as defined in ERC-1967) pointing to self. This should only be the case
     * for UUPS and transparent proxies that are using the current contract as their implementation. Execution of a
     * function through ERC-1167 minimal proxies (clones) would not normally pass this test, but is not guaranteed to
     * fail.
     */
    modifier onlyProxy() {
        _checkProxy();
        _;
    }

    /**
     * @dev Check that the execution is not being performed through a delegate call. This allows a function to be
     * callable on the implementing contract but not through proxies.
     */
    modifier notDelegated() {
        _checkNotDelegated();
        _;
    }

    /**
     * @dev Implementation of the ERC-1822 {proxiableUUID} function. This returns the storage slot used by the
     * implementation. It is used to validate the implementation's compatibility when performing an upgrade.
     *
     * IMPORTANT: A proxy pointing at a proxiable contract should not be considered proxiable itself, because this risks
     * bricking a proxy that upgrades to it, by delegating to itself until out of gas. Thus it is critical that this
     * function revert if invoked through a proxy. This is guaranteed by the `notDelegated` modifier.
     */
    function proxiableUUID() external view virtual notDelegated returns (bytes32) {
        return ERC1967Utils.IMPLEMENTATION_SLOT;
    }

    /**
     * @dev Upgrade the implementation of the proxy to `newImplementation`, and subsequently execute the function call
     * encoded in `data`.
     *
     * Calls {_authorizeUpgrade}.
     *
     * Emits an {Upgraded} event.
     *
     * @custom:oz-upgrades-unsafe-allow-reachable delegatecall
     */
    function upgradeToAndCall(address newImplementation, bytes memory data) public payable virtual onlyProxy {
        _authorizeUpgrade(newImplementation);
        _upgradeToAndCallUUPS(newImplementation, data);
    }

    /**
     * @dev Reverts if the execution is not performed via delegatecall or the execution
     * context is not of a proxy with an ERC-1967 compliant implementation pointing to self.
     * See {_onlyProxy}.
     */
    function _checkProxy() internal view virtual {
        if (
            address(this) == __self || // Must be called through delegatecall
            ERC1967Utils.getImplementation() != __self // Must be called through an active proxy
        ) {
            revert UUPSUnauthorizedCallContext();
        }
    }

    /**
     * @dev Reverts if the execution is performed via delegatecall.
     * See {notDelegated}.
     */
    function _checkNotDelegated() internal view virtual {
        if (address(this) != __self) {
            // Must not be called through delegatecall
            revert UUPSUnauthorizedCallContext();
        }
    }

    /**
     * @dev Function that should revert when `msg.sender` is not authorized to upgrade the contract. Called by
     * {upgradeToAndCall}.
     *
     * Normally, this function will use an xref:access.adoc[access control] modifier such as {Ownable-onlyOwner}.
     *
     * ```solidity
     * function _authorizeUpgrade(address) internal onlyOwner {}
     * ```
     */
    function _authorizeUpgrade(address newImplementation) internal virtual;

    /**
     * @dev Performs an implementation upgrade with a security check for UUPS proxies, and additional setup call.
     *
     * As a security check, {proxiableUUID} is invoked in the new implementation, and the return value
     * is expected to be the implementation slot in ERC-1967.
     *
     * Emits an {IERC1967-Upgraded} event.
     */
    function _upgradeToAndCallUUPS(address newImplementation, bytes memory data) private {
        try IERC1822Proxiable(newImplementation).proxiableUUID() returns (bytes32 slot) {
            if (slot != ERC1967Utils.IMPLEMENTATION_SLOT) {
                revert UUPSUnsupportedProxiableUUID(slot);
            }
            ERC1967Utils.upgradeToAndCall(newImplementation, data);
        } catch {
            // The implementation is not UUPS
            revert ERC1967Utils.ERC1967InvalidImplementation(newImplementation);
        }
    }
}
"
    },
    "src/common/interfaces/IPRNG.sol": {
      "content": "// SPDX-License-Identifier: MIT
pragma solidity 0.8.28;

/// @title IPRNG
/// @notice Interface for the PRNG contract that provides pseudo-random number generation
interface IPRNG {
    /// @notice Base points for percentage calculations (100.00%)
    function BASE_POINTS() external view returns (uint256);

    /// @notice Maximum CRC32 hash value adjusted to prevent modulo bias
    function MAX_CRC32_HASH_VALUE() external view returns (uint32);

    /// @notice Generates a pseudo-random number between 0 and BASE_POINTS
    /// @param signature The input signature bytes to use as entropy source
    /// @return A pseudo-random number between 0 and BASE_POINTS (0-10000)
    function rng(bytes calldata signature) external view returns (uint32);
}
"
    },
    "src/common/Errors.sol": {
      "content": "// SPDX-License-Identifier: MIT
pragma solidity ^0.8.13;

/// @title Shared Errors
/// @notice Common error definitions used across multiple contracts
library Errors {
    // Generic errors (deprecated - use specific errors below)
    error InvalidAddress();
    error TransferFailed();
    error InvalidAmount();
    error InsufficientBalance();
    error ArrayLengthMismatch();
    error Unauthorized();
    
    // Specific amount errors
    error WithdrawAmountZero();
    error WithdrawAmountExceedsTreasury();
    error CommitAmountZero();
    error CommitAmountTooLowForFlatFee();
    error PackPriceBelowMinimum();
    error PackPriceAboveMaximum();
    error PayoutExceedsOrderAmount();
    error OrderAmountBelowBucketMin();
    error OrderAmountAboveBucketMax();
    error PayoutAmountBelowBucketMin();
    error PayoutAmountAboveBucketMax();
    
    // Specific balance errors
    error InsufficientTreasuryBalance();
    
    // Specific address errors
    error CosignerAddressZero();
    error NotActiveCosigner();
    error ReceiverAddressZero();
    error CosignerAddressZeroInCommit();
    error CosignerNotActive();
    error PackSignerMismatch();
    error PackSignerNotCosigner();
    error MarketplaceAddressZero();
    error CommitSignerMismatch();
    error CommitSignerNotCosigner();
    error FulfillmentSignerMismatch();
    error FulfillmentSignerNotCosigner();
    error FundsReceiverAddressZero();
    
    // Specific authorization errors
    error OnlyCosignerCanFulfill();
    
    // Packs contract-specific errors
    error AlreadyCosigner();
    error AlreadyFulfilled();
    error InvalidCommitOwner();
    error InvalidBuckets();
    error InvalidReward();
    error InvalidPackPrice();
    error InvalidCommitId();
    error WithdrawalFailed();
    error InvalidCommitCancellableTime();
    error InvalidNftFulfillmentExpiryTime();
    error CommitIsCancelled();
    error CommitNotCancellable();
    error InvalidFundsReceiverManager();
    error BucketSelectionFailed();
    error InvalidProtocolFee();
}
"
    },
    "src/packs/base/PacksCommit.sol": {
      "content": "// SPDX-License-Identifier: MIT
pragma solidity 0.8.28;

import "./PacksStorage.sol";
import {Errors} from "../../common/Errors.sol";

/// @title PacksCommit
/// @notice Handles commit flow logic for Packs contract
/// @dev Abstract contract with commit helpers - storage accessed from PacksStorage
abstract contract PacksCommit is PacksStorage {
    
    // ============================================================
    // EVENTS
    // ============================================================
    
    event Commit(
        address indexed sender,
        uint256 indexed commitId,
        address indexed receiver,
        address cosigner,
        uint256 seed,
        uint256 counter,
        uint256 packPrice,
        bytes32 packHash,
        bytes32 digest,
        uint256 protocolFee,
        uint256 flatFee
    );    
    event CommitCancelled(uint256 indexed commitId, bytes32 digest);
    event CancellationRefundFailed(uint256 indexed commitId, address indexed receiver, uint256 amount, bytes32 digest);
    
    // ============================================================
    // COMMIT LOGIC
    // ============================================================
    
    /// @notice Calculate contribution amount with custom fee rate
    function calculateContributionWithoutFee(
        uint256 amount,
        uint256 feeRate
    ) public pure returns (uint256) {
        return (amount * BASE_POINTS) / (BASE_POINTS + feeRate);
    }
    
    function _commit(
        address receiver_,
        address cosigner_,
        uint256 seed_,
        PackType packType_,
        BucketData[] memory buckets_,
        bytes memory signature_
    ) internal returns (uint256) {
        uint256 packPrice = _validateAndCalculatePackPrice(msg.value);
        _validateCommitAddresses(receiver_, cosigner_);
        _validateBuckets(buckets_, packPrice);
        bytes32 packHash = _verifyPackSignature(packType_, packPrice, buckets_, signature_, cosigner_);
        uint256 commitId = _createCommit(receiver_, cosigner_, seed_, packPrice, buckets_, packHash);
        _processCommitFees(commitId, packPrice);
        _setCommitExpiryTimes(commitId);
        
        bytes32 digest = hashCommit(packs[commitId]);
        commitIdByDigest[digest] = commitId;
        
        emit Commit(
            msg.sender, commitId, receiver_, cosigner_, seed_, 
            packs[commitId].counter, packPrice, packHash, digest, 
            feesPaid[commitId], flatFee
        );
        
        return commitId;
    }
    
    function _validateAndCalculatePackPrice(uint256 totalAmount) internal view returns (uint256) {
        if (totalAmount == 0) revert Errors.CommitAmountZero();
        if (totalAmount <= flatFee) revert Errors.CommitAmountTooLowForFlatFee();
        
        uint256 packPrice = calculateContributionWithoutFee(totalAmount, protocolFee) - flatFee;
        
        if (packPrice < minPackPrice) revert Errors.PackPriceBelowMinimum();
        if (packPrice > maxPackPrice) revert Errors.PackPriceAboveMaximum();
        
        return packPrice;
    }
    
    function _validateCommitAddresses(address receiver_, address cosigner_) internal view {
        if (receiver_ == address(0)) revert Errors.ReceiverAddressZero();
        if (cosigner_ == address(0)) revert Errors.CosignerAddressZeroInCommit();
        if (!isCosigner[cosigner_]) revert Errors.CosignerNotActive();
    }
    
    function _validateBuckets(BucketData[] memory buckets_, uint256 packPrice) internal view {
        if (buckets_.length < MIN_BUCKETS) revert Errors.InvalidBuckets();
        if (buckets_.length > MAX_BUCKETS) revert Errors.InvalidBuckets();

        uint256 totalOdds = 0;
        for (uint256 i = 0; i < buckets_.length; i++) {
            _validateBucketValues(buckets_[i], packPrice);
            _validateBucketOdds(buckets_[i]);
            
            if (i < buckets_.length - 1 && buckets_[i].maxValue > buckets_[i + 1].minValue) {
                revert Errors.InvalidBuckets();
            }
            
            totalOdds += buckets_[i].oddsBps;
        }

        if (totalOdds != BASE_POINTS) revert Errors.InvalidBuckets();
    }
    
    function _validateBucketValues(BucketData memory bucket, uint256 packPrice) internal view {
        if (bucket.minValue == 0) revert Errors.InvalidReward();
        if (bucket.maxValue == 0) revert Errors.InvalidReward();
        if (bucket.minValue > bucket.maxValue) revert Errors.InvalidReward();
        if (bucket.minValue < minReward) revert Errors.InvalidReward();
        if (bucket.maxValue > maxReward) revert Errors.InvalidReward();
        
    }
    
    function _validateBucketOdds(BucketData memory bucket) internal pure {
        if (bucket.oddsBps == 0) revert Errors.InvalidBuckets();
        if (bucket.oddsBps > 10000) revert Errors.InvalidBuckets();
    }
    
    function _verifyPackSignature(
        PackType packType_,
        uint256 packPrice,
        BucketData[] memory buckets_,
        bytes memory signature_,
        address expectedCosigner
    ) internal view returns (bytes32) {
        bytes32 packHash = hashPack(packType_, packPrice, buckets_);
        address signer = verifyHash(packHash, signature_);
        
        if (signer != expectedCosigner) revert Errors.PackSignerMismatch();
        if (!isCosigner[signer]) revert Errors.PackSignerNotCosigner();
        
        return packHash;
    }
    
    function _createCommit(
        address receiver_,
        address cosigner_,
        uint256 seed_,
        uint256 packPrice,
        BucketData[] memory buckets_,
        bytes32 packHash
    ) internal returns (uint256) {
        uint256 commitId = packs.length;
        uint256 userCounter = packCount[receiver_]++;

        packs.push(CommitData({
            id: commitId,
            receiver: receiver_,
            cosigner: cosigner_,
            seed: seed_,
            counter: userCounter,
            packPrice: packPrice,
            buckets: buckets_,
            packHash: packHash
        }));
        
        return commitId;
    }
    
    function _processCommitFees(uint256 commitId, uint256 packPrice) internal {
        feesPaid[commitId] = msg.value - packPrice;
        protocolBalance += feesPaid[commitId];
        _handleFlatFeePayment();
        commitBalance += packPrice;
    }
    
    function _setCommitExpiryTimes(uint256 commitId) internal {
        commitCancellableAt[commitId] = block.timestamp + commitCancellableTime;
        nftFulfillmentExpiresAt[commitId] = block.timestamp + nftFulfillmentExpiryTime;
    }
    
    function _handleFlatFeePayment() internal {
        if (flatFee > 0 && fundsReceiver != address(0)) {
            (bool success, ) = fundsReceiver.call{value: flatFee}("");
            if (!success) {
                treasuryBalance += flatFee;
            }
        } else if (flatFee > 0) {
            treasuryBalance += flatFee;
        }
    }

    // ============================================================
    // CANCEL LOGIC
    // ============================================================
    
    function _cancel(uint256 commitId_) internal {
        _validateCancellationRequest(commitId_);
        isCancelled[commitId_] = true;
        CommitData memory commitData = packs[commitId_];
        uint256 totalRefund = _calculateAndUpdateRefund(commitId_, commitData.packPrice);
        _processRefund(commitId_, commitData.receiver, totalRefund, commitData);
        emit CommitCancelled(commitId_, hashCommit(commitData));
    }
    
    function _validateCancellationRequest(uint256 commitId_) internal view {
        if (commitId_ >= packs.length) revert Errors.InvalidCommitId();
        if (isFulfilled[commitId_]) revert Errors.AlreadyFulfilled();
        if (isCancelled[commitId_]) revert Errors.CommitIsCancelled();
        if (block.timestamp < commitCancellableAt[commitId_]) {
            revert Errors.CommitNotCancellable();
        }
    }
    
    function _calculateAndUpdateRefund(uint256 commitId_, uint256 packPrice) internal returns (uint256 totalRefund) {
        commitBalance -= packPrice;
        uint256 protocolFeesPaid = feesPaid[commitId_];
        protocolBalance -= protocolFeesPaid;
        totalRefund = packPrice + protocolFeesPaid;
    }
    
    function _processRefund(uint256 commitId_, address receiver, uint256 amount, CommitData memory commitData) internal {
        (bool success,) = payable(receiver).call{value: amount}("");
        if (!success) {
            treasuryBalance += amount;
            emit CancellationRefundFailed(commitId_, receiver, amount, hashCommit(commitData));
        }
    }
}
"
    },
    "src/packs/base/PacksFulfill.sol": {
      "content": "// SPDX-License-Identifier: MIT
pragma solidity 0.8.28;

import "./PacksStorage.sol";
import {Errors} from "../../common/Errors.sol";

/// @title PacksFulfill
/// @notice Handles fulfillment flow logic for Packs contract
/// @dev Abstract contract with fulfillment helpers - storage accessed from PacksStorage
abstract contract PacksFulfill is PacksStorage {
    
    // ============================================================
    // EVENTS
    // ============================================================
    
    event Fulfillment(
        address indexed sender,
        uint256 indexed commitId,
        uint256 rng,
        uint256 odds,
        uint256 bucketIndex,
        uint256 payout,
        address token,
        uint256 tokenId,
        uint256 amount,
        address receiver,
        FulfillmentOption choice,
        FulfillmentOption fulfillmentType,
        bytes32 digest
    );
    
    event FulfillmentPayoutFailed(uint256 indexed commitId, address indexed receiver, uint256 amount, bytes32 digest);
    event TreasuryDeposit(address indexed sender, uint256 amount);
    
    // ============================================================
    // FULFILLMENT LOGIC
    // ============================================================
    
    function _fulfill(
        uint256 commitId_,
        address marketplace_,
        bytes calldata orderData_,
        uint256 orderAmount_,
        address token_,
        uint256 tokenId_,
        uint256 payoutAmount_,
        bytes calldata commitSignature_,
        bytes calldata fulfillmentSignature_,
        FulfillmentOption choice_
    ) internal {
        CommitData memory commitData = _validateFulfillmentRequest(commitId_, marketplace_, orderAmount_, payoutAmount_);
        (uint256 rng, bytes32 digest) = _verifyFulfillmentSignatures(
            commitData, commitSignature_, fulfillmentSignature_, marketplace_,
            orderData_, orderAmount_, token_, tokenId_, payoutAmount_, choice_
        );
        (uint256 bucketIndex, BucketData memory bucket) = _determineOutcomeAndValidate(
            rng, commitData.buckets, orderAmount_, payoutAmount_
        );
        FulfillmentOption fulfillmentType = _determineFulfillmentType(commitId_, choice_);
        _markFulfilledAndUpdateBalances(commitId_, commitData.packPrice);
        _executeFulfillment(
            commitId_, commitData, marketplace_, orderData_, orderAmount_,
            token_, tokenId_, payoutAmount_, rng, bucket, bucketIndex,
            choice_, fulfillmentType, digest
        );
    }
    
    function _validateFulfillmentRequest(
        uint256 commitId_,
        address marketplace_,
        uint256 orderAmount_,
        uint256 payoutAmount_
    ) internal returns (CommitData memory) {
        if (commitId_ >= packs.length) revert Errors.InvalidCommitId();
        if (msg.sender != packs[commitId_].cosigner) revert Errors.OnlyCosignerCanFulfill();
        if (marketplace_ == address(0)) revert Errors.MarketplaceAddressZero();
        if (msg.value > 0) _depositTreasury(msg.value);
        if (orderAmount_ > treasuryBalance) revert Errors.InsufficientTreasuryBalance();
        if (isFulfilled[commitId_]) revert Errors.AlreadyFulfilled();
        if (isCancelled[commitId_]) revert Errors.CommitIsCancelled();
        if (payoutAmount_ > orderAmount_) revert Errors.PayoutExceedsOrderAmount();

        return packs[commitId_];
    }
    
    function _verifyFulfillmentSignatures(
        CommitData memory commitData,
        bytes calldata commitSignature_,
        bytes calldata fulfillmentSignature_,
        address marketplace_,
        bytes calldata orderData_,
        uint256 orderAmount_,
        address token_,
        uint256 tokenId_,
        uint256 payoutAmount_,
        FulfillmentOption choice_
    ) internal view returns (uint256 rng, bytes32 digest) {
        address commitCosigner = verifyCommit(commitData, commitSignature_);
        if (commitCosigner != commitData.cosigner) revert Errors.CommitSignerMismatch();
        if (!isCosigner[commitCosigner]) revert Errors.CommitSignerNotCosigner();

        rng = PRNG.rng(commitSignature_);
        digest = hashCommit(commitData);

        bytes32 fulfillmentHash = hashFulfillment(
            digest, marketplace_, orderAmount_, orderData_, 
            token_, tokenId_, payoutAmount_, choice_
        );
        address fulfillmentCosigner = verifyHash(fulfillmentHash, fulfillmentSignature_);
        if (fulfillmentCosigner != commitData.cosigner) revert Errors.FulfillmentSignerMismatch();
        if (!isCosigner[fulfillmentCosigner]) revert Errors.FulfillmentSignerNotCosigner();
    }
    
    function _determineOutcomeAndValidate(
        uint256 rng,
        BucketData[] memory buckets,
        uint256 orderAmount_,
        uint256 payoutAmount_
    ) internal pure returns (uint256 bucketIndex, BucketData memory bucket) {
        bucketIndex = _getBucketIndex(rng, buckets);
        bucket = buckets[bucketIndex];
        
        if (orderAmount_ < bucket.minValue) revert Errors.OrderAmountBelowBucketMin();
        if (orderAmount_ > bucket.maxValue) revert Errors.OrderAmountAboveBucketMax();
        if (payoutAmount_ < bucket.minValue) revert Errors.PayoutAmountBelowBucketMin();
        if (payoutAmount_ > bucket.maxValue) revert Errors.PayoutAmountAboveBucketMax();
    }
    
    function _getBucketIndex(uint256 rng, BucketData[] memory buckets) internal pure returns (uint256) {
        uint256 cumulativeOdds = 0;
        for (uint256 i = 0; i < buckets.length; i++) {
            cumulativeOdds += buckets[i].oddsBps;
            if (rng < cumulativeOdds) {
                return i;
            }
        }
        revert Errors.BucketSelectionFailed();
    }
    
    function _determineFulfillmentType(uint256 commitId_, FulfillmentOption choice_) internal view returns (FulfillmentOption) {
        if (choice_ == FulfillmentOption.NFT && block.timestamp > nftFulfillmentExpiresAt[commitId_]) {
            return FulfillmentOption.Payout;
        }
        return choice_;
    }
    
    function _markFulfilledAndUpdateBalances(uint256 commitId_, uint256 packPrice) internal {
        isFulfilled[commitId_] = true;
        commitBalance -= packPrice;
        treasuryBalance += packPrice;
        uint256 protocolFeesPaid = feesPaid[commitId_];
        protocolBalance -= protocolFeesPaid;
        treasuryBalance += protocolFeesPaid;
    }
    
    function _executeFulfillment(
        uint256 commitId_,
        CommitData memory commitData,
        address marketplace_,
        bytes calldata orderData_,
        uint256 orderAmount_,
        address token_,
        uint256 tokenId_,
        uint256 payoutAmount_,
        uint256 rng,
        BucketData memory bucket,
        uint256 bucketIndex,
        FulfillmentOption choice_,
        FulfillmentOption fulfillmentType,
        bytes32 digest
    ) internal {
        if (fulfillmentType == FulfillmentOption.NFT) {
            _executeNFTFulfillment(commitId_, commitData, marketplace_, orderData_, orderAmount_,
                token_, tokenId_, rng, bucket, bucketIndex, choice_, fulfillmentType, digest);
        } else {
            _executePayoutFulfillment(commitId_, commitData, payoutAmount_, rng, bucket,
                bucketIndex, choice_, fulfillmentType, digest);
        }
    }
    
    function _executeNFTFulfillment(
        uint256 commitId_,
        CommitData memory commitData,
        address marketplace_,
        bytes calldata orderData_,
        uint256 orderAmount_,
        address token_,
        uint256 tokenId_,
        uint256 rng,
        BucketData memory bucket,
        uint256 bucketIndex,
        FulfillmentOption choice_,
        FulfillmentOption fulfillmentType,
        bytes32 digest
    ) internal {
        (bool success,) = marketplace_.call{value: orderAmount_}(orderData_);   
        
        if (success) {
            treasuryBalance -= orderAmount_;
            emit Fulfillment(msg.sender, commitId_, rng, bucket.oddsBps, bucketIndex,
                0, token_, tokenId_, orderAmount_, commitData.receiver, choice_, fulfillmentType, digest);
        } else {
            (bool fallbackSuccess,) = commitData.receiver.call{value: orderAmount_}("");
            if (fallbackSuccess) {
                treasuryBalance -= orderAmount_;
            } else {
                emit FulfillmentPayoutFailed(commitData.id, commitData.receiver, orderAmount_, digest);
            }
            emit Fulfillment(msg.sender, commitId_, rng, bucket.oddsBps, bucketIndex,
                orderAmount_, address(0), 0, 0, commitData.receiver, choice_, fulfillmentType, digest);
        }
    }

    
    function _executePayoutFulfillment(
        uint256 commitId_,
        CommitData memory commitData,
        uint256 payoutAmount_,
        uint256 rng,
        BucketData memory bucket,
        uint256 bucketIndex,
        FulfillmentOption choice_,
        FulfillmentOption fulfillmentType,
        bytes32 digest
    ) internal {
        (bool success,) = commitData.receiver.call{value: payoutAmount_}("");
        if (success) {
            treasuryBalance -= payoutAmount_;
        } else {
            emit FulfillmentPayoutFailed(commitData.id, commitData.receiver, payoutAmount_, digest);
        }

        emit Fulfillment(msg.sender, commitId_, rng, bucket.oddsBps, bucketIndex,
            payoutAmount_, address(0), 0, 0, commitData.receiver, choice_, fulfillmentType, digest);
    }
    
    function _depositTreasury(uint256 amount) internal {
        treasuryBalance += amount;
        emit TreasuryDeposit(msg.sender, amount);
    }
}
"
    },
    "src/packs/base/PacksAdmin.sol": {
      "content": "// SPDX-License-Identifier: MIT
pragma solidity 0.8.28;

import "./PacksStorage.sol";
import {MEAccessControlUpgradeable} from "../../common/MEAccessControlUpgradeable.sol";
import {ReentrancyGuardUpgradeable} from "@openzeppelin/contracts-upgradeable/utils/ReentrancyGuardUpgradeable.sol";
import {PausableUpgradeable} from "@openzeppelin/contracts-upgradeable/utils/PausableUpgradeable.sol";

import {Errors} from "../../common/Errors.sol";
import {TokenRescuer} from "../../common/TokenRescuer.sol";

/// @title PacksAdmin
/// @notice Handles admin configuration, treasury management, pause controls, and token rescue for Packs contract
/// @dev Abstract contract with admin helpers - storage accessed from PacksStorage
abstract contract PacksAdmin is MEAccessControlUpgradeable, ReentrancyGuardUpgradeable, PausableUpgradeable, PacksStorage, TokenRescuer {
    
    // ============================================================
    // EVENTS
    // ============================================================
    
    event CosignerAdded(address indexed cosigner);
    event CosignerRemoved(address indexed cosigner);
    event MaxRewardUpdated(uint256 oldMaxReward, uint256 newMaxReward);
    event MaxPackPriceUpdated(uint256 oldMaxPackPrice, uint256 newMaxPackPrice);
    event MinRewardUpdated(uint256 oldMinReward, uint256 newMinReward);
    event MinPackPriceUpdated(uint256 oldMinPackPrice, uint256 newMinPackPrice);
    event CommitCancellableTimeUpdated(uint256 oldCommitCancellableTime, uint256 newCommitCancellableTime);
    event NftFulfillmentExpiryTimeUpdated(uint256 oldNftFulfillmentExpiryTime, uint256 newNftFulfillmentExpiryTime);
    event FundsReceiverUpdated(address indexed oldFundsReceiver, address indexed newFundsReceiver);
    event FundsReceiverManagerTransferred(
        address indexed oldFundsReceiverManager, address indexed newFundsReceiverManager
    );
    event ProtocolFeeUpdated(uint256 oldProtocolFee, uint256 newProtocolFee);
    event FlatFeeUpdated(uint256 oldFlatFee, uint256 newFlatFee);
    event TreasuryWithdrawal(address indexed sender, uint256 amount, address fundsReceiver);
    event EmergencyWithdrawal(address indexed sender, uint256 amount, address fundsReceiver);
    
    // ============================================================
    // ADMIN CONFIGURATION
    // ============================================================
    
    // ---------- Cosigner Management ----------
    
    function _addCosigner(address cosigner_) internal {
        if (cosigner_ == address(0)) revert Errors.CosignerAddressZero();
        if (isCosigner[cosigner_]) revert Errors.AlreadyCosigner();
        isCosigner[cosigner_] = true;
        emit CosignerAdded(cosigner_);
    }
    
    function _removeCosigner(address cosigner_) internal {
        if (!isCosigner[cosigner_]) revert Errors.NotActiveCosigner();
        isCosigner[cosigner_] = false;
        emit CosignerRemoved(cosigner_);
    }
    
    // ---------- Time Parameters ----------
    
    function _updateCommitCancellableTime(uint256 commitCancellableTime_) internal {
        if (commitCancellableTime_ < MIN_COMMIT_CANCELLABLE_TIME) {
            revert Errors.InvalidCommitCancellableTime();
        }
        uint256 oldCommitCancellableTime = commitCancellableTime;
        commitCancellableTime = commitCancellableTime_;
        emit CommitCancellableTimeUpdated(oldCommitCancellableTime, commitCancellableTime_);
    }
    
    function _updateNftFulfillmentExpiryTime(uint256 nftFulfillmentExpiryTime_) internal {
        if (nftFulfillmentExpiryTime_ < MIN_NFT_FULFILLMENT_EXPIRY_TIME) {
            revert Errors.InvalidNftFulfillmentExpiryTime();
        }
        uint256 oldNftFulfillmentExpiryTime = nftFulfillmentExpiryTime;
        nftFulfillmentExpiryTime = nftFulfillmentExpiryTime_;
        emit NftFulfillmentExpiryTimeUpdated(oldNftFulfillmentExpiryTime, nftFulfillmentExpiryTime_);
    }
    
    // ---------- Reward Limits ----------
    
    function _updateMinReward(uint256 minReward_) internal {
        if (minReward_ == 0) revert Errors.InvalidReward();
        if (minReward_ > maxReward) revert Errors.InvalidReward();
        uint256 oldMinReward = minReward;
        minReward = minReward_;
        emit MinRewardUpdated(oldMinReward, minReward_);
    }
    
    function _updateMaxReward(uint256 maxReward_) internal {
        if (maxReward_ == 0) revert Errors.InvalidReward();
        if (maxReward_ < minReward) revert Errors.InvalidReward();
        uint256 oldMaxReward = maxReward;
        maxReward = maxReward_;
        emit MaxRewardUpdated(oldMaxReward, maxReward_);
    }
    
    // ---------- Pack Price Limits ----------
    
    function _updateMinPackPrice(uint256 minPackPrice_) internal {
        if (minPackPrice_ == 0) revert Errors.InvalidPackPrice();
        if (minPackPrice_ > maxPackPrice) revert Errors.InvalidPackPrice();
        uint256 oldMinPackPrice = minPackPrice;
        minPackPrice = minPackPrice_;
        emit MinPackPriceUpdated(oldMinPackPrice, minPackPrice_);
    }
    
    function _updateMaxPackPrice(uint256 maxPackPrice_) internal {
        if (maxPackPrice_ == 0) revert Errors.InvalidPackPrice();
        if (maxPackPrice_ < minPackPrice) revert Errors.InvalidPackPrice();
        uint256 oldMaxPackPrice = maxPackPrice;
        maxPackPrice = maxPackPrice_;
        emit MaxPackPriceUpdated(oldMaxPackPrice, maxPackPrice_);
    }
        
    // ---------- Fees ----------
    
    function _setProtocolFee(uint256 protocolFee_) internal {
        if (protocolFee_ > BASE_POINTS) revert Errors.InvalidProtocolFee();
        uint256 oldProtocolFee = protocolFee;
        protocolFee = protocolFee_;
        emit ProtocolFeeUpdated(oldProtocolFee, protocolFee_);
    }
    
    function _setFlatFee(uint256 flatFee_) internal {
        uint256 oldFlatFee = flatFee;
        flatFee = flatFee_;
        emit FlatFeeUpdated(oldFlatFee, flatFee_);
    }
    
    // ---------- Funds Receiver ----------
    
    function _setFundsReceiver(address fundsReceiver_) internal virtual {
        if (fundsReceiver_ == address(0)) revert Errors.FundsReceiverAddressZero();
        if (hasRole(FUNDS_RECEIVER_MANAGER_ROLE, fundsReceiver_)) {
            revert Errors.InvalidFundsReceiverManager();
        }
        address oldFundsReceiver = fundsReceiver;
        fundsReceiver = payable(fundsReceiver_);
        emit FundsReceiverUpdated(oldFundsReceiver, fundsReceiver_);
    }

      // ============================================================
    // TREASURY LOGIC
    // ============================================================
    
    function _withdrawTreasury(uint256 amount) internal {
        if (amount == 0) revert Errors.WithdrawAmountZero();
        if (amount > treasuryBalance) revert Errors.WithdrawAmountExceedsTreasury();
        treasuryBalance -= amount;

        (bool success,) = payable(fundsReceiver).call{value: amount}("");
        if (!success) revert Errors.WithdrawalFailed();

        emit TreasuryWithdrawal(msg.sender, amount, fundsReceiver);
    }
    
    function _emergencyWithdraw() internal virtual {
        treasuryBalance = 0;
        commitBalance = 0;
        protocolBalance = 0;

        uint256 currentBalance = address(this).balance;
        _rescueETH(fundsReceiver, currentBalance);
        // Pause must be called by inheriting contract that has PausableUpgradeable
        _pause();
        emit EmergencyWithdrawal(msg.sender, currentBalance, fundsReceiver);
    }
    
    
    function _transferFundsReceiverManager(address newFundsReceiverManager_) internal virtual;
    
    // ============================================================
    // RESCUE FUNCTIONS (Token Recovery)
    // ============================================================

    function rescueERC20(address token, address to, uint256 amount) external {
        _checkRole(RESCUE_ROLE, msg.sender);
        address[] memory tokens = new address[](1);
        address[] memory tos = new address[](1);
        uint256[] memory amounts = new uint256[](1);

        tokens[0] = token;
        tos[0] = to;
        amounts[0] = amount;

        _rescueERC20Batch(tokens, tos, amounts);
    }

    function rescueERC721(address token, address to, uint256 tokenId) external {
        _checkRole(RESCUE_ROLE, msg.sender);
        address[] memory tokens = new address[](1);
        address[] memory tos = new address[](1);
        uint256[] memory tokenIds = new uint256[](1);

        tokens[0] = token;
        tos[0] = to;
        tokenIds[0] = tokenId;

        _rescueERC721Batch(tokens, tos, tokenIds);
    }

    function rescueERC1155(address token, address to, uint256 tokenId, uint256 amount) external {
        _checkRole(RESCUE_ROLE, msg.sender);
        address[] memory tokens = new address[](1);
        address[] memory tos = new address[](1);
        uint256[] memory tokenIds = new uint256[](1);
        uint256[] memory amounts = new uint256[](1);

        tokens[0] = token;
        tos[0] = to;
        tokenIds[0] = tokenId;
        amounts[0] = amount;

        _rescueERC1155Batch(tokens, tos, tokenIds, amounts);
    }

    function rescueERC20Batch(address[] calldata tokens, address[] calldata tos, uint256[] calldata amounts)
        external
    {
        _checkRole(RESCUE_ROLE, msg.sender);
        _rescueERC20Batch(tokens, tos, amounts);
    }

    function rescueERC721Batch(address[] calldata tokens, address[] calldata tos, uint256[] calldata tokenIds)
        external
    {
        _checkRole(RESCUE_ROLE, msg.sender);
        _rescueERC721Batch(tokens, tos, tokenIds);
    }

    function rescueERC1155Batch(
        address[] calldata tokens,
        address[] calldata tos,
        uint256[] calldata tokenIds,
        uint256[] calldata amounts
    ) external {
        _checkRole(RESCUE_ROLE, msg.sender);
        _rescueERC1155Batch(tokens, tos, tokenIds, amounts);
    }
}
"
    },
    "lib/openzeppelin-contracts/contracts/interfaces/draft-IERC1822.sol": {
      "content": "// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.1.0) (interfaces/draft-IERC1822.sol)

pragma solidity ^0.8.20;

/**
 * @dev ERC-1822: Universal Upgradeable Proxy Standard (UUPS) documents a method for upgradeability through a simplified
 * proxy whose upgrades are fully controlled by the current implementation.
 */
interface IERC1822Proxiable {
    /**
     * @dev Returns the storage slot that the proxiable contract assumes is being used to store the implementation
     * address.
     *
     * IMPORTANT: A proxy pointing at a proxiable contract should not be considered proxiable itself, because this risks
     * bricking a proxy that upgrades to it, by delegating to itself until out of gas. Thus it is critical that this
     * function revert if invoked through a proxy.
     */
    function proxiableUUID() external view returns (bytes32);
}
"
    },
    "lib/openzeppelin-contracts/contracts/proxy/ERC1967/ERC1967Utils.sol": {
      "content": "// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.2.0) (proxy/ERC1967/ERC1967Utils.sol)

pragma solidity ^0.8.22;

import {IBeacon} from "../beacon/IBeacon.sol";
import {IERC1967} from "../../interfaces/IERC1967.sol";
import {Address} from "../../utils/Address.sol";
import {StorageSlot} from "../../utils/StorageSlot.sol";

/**
 * @dev This library provides getters and event emitting update functions for
 * https://eips.ethereum.org/EIPS/eip-1967[ERC-1967] slots.
 */
library ERC1967Utils {
    /**
     * @dev Storage slot with the address of the current implementation.
     * This is the keccak-256 hash of "eip1967.proxy.implementation" subtracted by 1.
     */
    // solhint-disable-next-line private-vars-leading-underscore
    bytes32 internal constant IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;

    /**
     * @dev The `implementation` of the proxy is invalid.
     */
    error ERC1967InvalidImplementation(address implementation);

    /**
     * @dev The `admin` of the proxy is invalid.
     */
    error ERC1967InvalidAdmin(address admin);

    /**
     * @dev The `beacon` of the proxy is invalid.
     */
    error ERC1967InvalidBeacon(address beacon);

    /**
     * @dev An upgrade function sees `msg.value > 0` that may be lost.
     */
    error ERC1967NonPayable();

    /**
     * @dev Returns the current implementation address.
     */
    function getImplementation() internal view returns (address) {
        return StorageSlot.getAddressSlot(IMPLEMENTATION_SLOT).value;
    }

    /**
     * @dev Stores a new address in the ERC-1967 implementation slot.
     */
    function _setImplementation(address newImplementation) private {
        if (newImplementation.code.length == 0) {
            revert ERC1967InvalidImplementation(newImplementation);
        }
        StorageSlot.getAddressSlot(IMPLEMENTATION_SLOT).value = newImplementation;
    }

    /**
     * @dev Performs implementation upgrade with additional setup call if data is nonempty.
     * This function is payable only if the setup call is performed, otherwise `msg.value` is rejected
     * to avoid stuck value in the contract.
     *
     * Emits an {IERC1967-Upgraded} event.
     */
    function upgradeToAndCall(address newImplementation, bytes memory data) internal {
        _setImplementation(newImplementation);
        emit IERC1967.Upgraded(newImplementation);

        if (data.length > 0) {
            Address.functionDelegateCall(newImplementation, data);
        } else {
            _checkNonPayable();
        }
    }

    /**
     * @dev Storage slot with the admin of the contract.
     * This is the keccak-256 hash of "eip1967.proxy.admin" subtracted by 1.
     */
    // solhint-disable-next-line private-vars-leading-underscore
    bytes32 internal constant ADMIN_SLOT = 0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103;

    /**
     * @dev Returns the current admin.
     *
     * TIP: To get this value clients can read directly from the storage slot shown below (specified by ERC-1967) using
     * the https://eth.wiki/json-rpc/API#eth_getstorageat[`eth_getStorageAt`] RPC call.
     * `0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103`
     */
    function getAdmin() internal view returns (address) {
        return StorageSlot.getAddressSlot(ADMIN_SLOT).value;
    }

    /**
     * @dev Stores a new address in the ERC-1967 admin slot.
     */
    function _setAdmin(address newAdmin) private {
        if (newAdmin == address(0)) {
            revert ERC1967InvalidAdmin(address(0));
        }
        StorageSlot.getAddressSlot(ADMIN_SLOT).value = newAdmin;
    }

    /**
     * @dev Changes the admin of the proxy.
     *
     * Emits an {IERC1967-AdminChanged} event.
     */
    function changeAdmin(address newAdmin) internal {
        emit IERC1967.AdminChanged(getAdmin(), newAdmin);
        _setAdmin(newAdmin);
    }

    /**
     * @dev The storage slot of the UpgradeableBeacon contract which defines the implementation for this proxy.
     * This is the keccak-256 hash of "eip1967.proxy.beacon" subtracted by 1.
     */
    // solhint-disable-next-line private-vars-leading-underscore
    bytes32 internal constant BEACON_SLOT = 0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50;

    /**
     * @dev Returns the current beacon.
     */
    function getBeacon() internal view returns (address) {
        return StorageSlot.getAddressSlot(BEACON_SLOT).value;
    }

    /**
     * @dev Stores a new beacon in the ERC-1967 beacon slot.
     */
    function _setBeacon(address newBeacon) private {
        if (newBeacon.code.length == 0) {
            revert ERC1967InvalidBeacon(newBeacon);
        }

        StorageSlot.getAddressSlot(BEACON_SLOT).value = newBeacon;

        address beaconImplementation = IBeacon(newBeacon).implementation();
        if (beaconImplementation.code.length == 0) {
            revert ERC1967InvalidImplementation(beaconImplementation);
        }
    }

    /**
     * @dev Change the beacon and trigger a setup call if data is nonempty.
     * This function is payable only if the setup call is performed, otherwise `msg.value` is rejected
     * to avoid stuck value in the contract.
     *
     * Emits an {IERC1967-BeaconUpgraded} event.
     *
     * CAUTION: Invoking this function has no effect on an instance of {BeaconProxy} since v5, since
     * it uses an immutable beacon without looking at the value of the ERC-1967 beacon slot for
     * efficiency.
     */
    function upgradeBeaconToAndCall(address newBeacon, bytes memory data) internal {
        _setBeacon(newBeacon);
        emit IERC1967.BeaconUpgraded(newBeacon);

        if (data.length > 0) {
            Address.functionDelegateCall(IBeacon(newBeacon).implementation(), data);
        } else {
            _checkNonPayable();
        }
    }

    /**
     * @dev Reverts if `msg.value` is not zero. It can be used to avoid `msg.value` stuck in the contract
     * if an upgrade doesn't perform an initialization call.
     */
    function _checkNonPayable() private {
        if (msg.value > 0) {
            revert ERC1967NonPayable();
        }
    }
}
"
    },
    "src/packs/base/PacksStorage.sol": {
      "content": "// SPDX-License-Identifier: MIT
pragma solidity 0.8.28;

import {PacksSignatureVerifierUpgradeable} from "../../common/SignatureVerifier/PacksSignatureVerifierUpgradeable.sol";
import {IPRNG} from "../../common/interfaces/IPRNG.sol";

/* Do not remove any storage variables from this contract. Always add new variables to the end. */

/// @title PacksStorage
/// @notice Storage layout for Packs contract
/// @dev All storage variables and events for Packs
abstract contract PacksStorage is PacksSignatureVerifierUpgradeable {
    // ============================================================
    // STORAGE
    // ============================================================

    IPRNG public PRNG;
    address payable public fundsReceiver;

    CommitData[] public packs;
    mapping(bytes32 commitDigest => uint256 commitId) public commitIdByDigest;

    uint256 public treasuryBalance;
    uint256 public commitBalance;

    uint256 public constant MIN_COMMIT_CANCELLABLE_TIME = 1 minutes;
    uint256 public commitCancellableTime;
    mapping(uint256 commitId => uint256 cancellableAt) public commitCancellableAt;

    uint256 public constant MIN_NFT_FULFILLMENT_EXPIRY_TIME = 30 seconds;
    uint256 public nftFulfillmentExpiryTime;
    mapping(uint256 commitId => uint256 expiresAt) public nftFulfillmentExpiresAt;

    bytes32 public constant FUNDS_RECEIVER_MANAGER_ROLE = keccak256("FUNDS_RECEIVER_MANAGER_ROLE");

    mapping(address cosigner => bool active) public isCosigner;
    mapping(address receiver => uint256 counter) public packCount;
    mapping(uint256 commitId => bool fulfilled) public isFulfilled;
    mapping(uint256 commitId => bool cancelled) public isCancelled;

    uint256 public minReward;
    uint256 public maxReward;
    uint256 public minPackPrice;
    uint256 public maxPackPrice;

    uint256 public minPackRewardMultiplier; // deprecated. These slots are unused but have to remain here. 
    uint256 public maxPackRewardMultiplier; // deprecated. These slots are unused but have to remain here. 

    uint256 public constant MIN_BUCKETS = 1;
    uint256 public constant MAX_BUCKETS = 6;

    uint256 public constant BASE_POINTS = 10000;

    uint256 public protocolFee = 0;
    uint256 public protocolBalance = 0;
    mapping(uint256 commitId => uint256 protocolFee) public feesPaid;
    uint256 public flatFee = 0;
}

"
    },
    "src/common/MEAccessControlUpgradeable.sol": {
      "content": "// SPDX-License-Identifier: MIT
pragma solidity 0.8.28;

import "@openzeppelin/contracts-upgradeable/access/AccessControlUpgradeable.sol";

/**
 * @title MEAccessControlUpgradeable
 * @dev Contract that inherits from OpenZeppelin's AccessControlUpgradeable and exposes role management
 * functions at the top level for improved developer experience.
 */
contract MEAccessControlUpgradeable is AccessControlUpgradeable {
    bytes32 public constant OPS_ROLE = keccak256("OPS_ROLE");
    bytes32 public constant RESCUE_ROLE = keccak256("RESCUE_ROLE");

    error InvalidOwner();

    function __MEAccessControl_init() internal {
        __AccessControl_init();
        _grantRole(DEFAULT_ADMIN_ROLE, msg.sender);
        _grantRole(OPS_ROLE, msg.sender);
        _grantRole(RESCUE_ROLE, msg.sender);
    }

    /// @notice Transfers admin rights to a new address. Admin functions are intentionally not paused
    /// @param newAdmin Address of the new admin
    function transferAdmin(
        address newAdmin
    ) public onlyRole(DEFAULT_ADMIN_ROLE) {
        if (newAdmin == address(0)) revert InvalidOwner();

        // Grant new admin the default admin role
        _grantRole(DEFAULT_ADMIN_ROLE, newAdmin);
        _grantRole(OPS_ROLE, newAdmin);

        // Revoke old admin's roles
        _revokeRole(DEFAULT_ADMIN_ROLE, msg.sender);
        _revokeRole(OPS_ROLE, msg.sender);
    }
    /// @notice Adds a new operations user
    /// @param user Address to grant operations role to
    function addOpsUser(address user) public onlyRole(DEFAULT_ADMIN_ROLE) {
        _grantRole(OPS_ROLE, user);
    }

    /// @notice Removes an operations user
    /// @param user Address to revoke operations role from
    function removeOpsUser(address user) public onlyRole(DEFAULT_ADMIN_ROLE) {
        _revokeRole(OPS_ROLE, user);
    }

    /// @notice Adds a new rescue user
    /// @param user Address to grant rescue role to
    function addRescueUser(address user) public onlyRole(DEFAULT_ADMIN_ROLE) {
        _grantRole(RESCUE_ROLE, user);
    }

    /// @notice Removes a rescue user
    /// @param user Address to revoke rescue role from
    function removeRescueUser(
        address user
    ) public onlyRole(DEFAULT_ADMIN_ROLE) {
        _revokeRole(RESCUE_ROLE, user);
    }

    /**
     * @notice Explicitly re-expose the inherited functions to make them more discoverable
     * in developer tools and documentation.
     */

    // Just uncomment any methods you want to make obviously available:

    /**
     * @dev Modifier that checks that an account has a specific role. Reverts
     * with an {AccessControlUnauthorizedAccount} error including the required role.
     */
    // modifier onlyRole(bytes32 role) {
    //     _checkRole(role);
    //     _;
    // }

    /**
     * @dev Makes `hasRole` visible at the top level of our contract.
     * @param role The role to check
     * @param account The account to check the role for
     * @return bool True if account has the role
     */
    // function hasRole(bytes32 role, address account) public view override returns (bool) {
    //     return super.hasRole(role, account);
    // }

    /**
     * @dev Makes `getRoleAdmin` visible at the top level of our contract.
     * @param role The role to get the admin role for
     * @return bytes32 The admin role
     */
    // function getRoleAdmin(bytes32 role) public view override returns (bytes32) {
    //     return super.getRoleAdmin(role);
    // }

    /**
     * @dev Makes `grantRole` visible at the top level of our contract.
     * @param role The role to grant
     * @param account The account to grant the role to
     */
    // function grantRole(bytes32 role, address account) public override {
    //     super.grantRole(role, account);
    // }

    /**
     * @dev Makes `revokeRole` visible at the top level of our contract.
     * @param role The role to revoke
     * @param account The account to revoke the role from
     */
    // function revokeRole(bytes32 role, address account) public override {
    //     super.revokeRole(role, account);
    // }

    /**
     * @dev Makes `renounceRole` visible at the top level of our contract.
     * @param role The role to renounce
     * @param callerConfirmation The confirmation address (must be the sender)
     */
    // function renounceRole(bytes32 role, address callerConfirmation) public override {
    //     super.renounceRole(role, callerConfirmation);
    // }
}"
    },
    "lib/openzeppelin-contracts-upgradeable/contracts/utils/ReentrancyGuardUpgradeable.sol": {
      "content": "// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.1.0) (utils/ReentrancyGuard.sol)

pragma solidity ^0.8.20;
import {Initializable} from "../proxy/utils/Initializable.sol";

/**
 * @dev Contract module that helps prevent reentrant calls to a function.
 *
 * Inheriting from `ReentrancyGuard` will make the {nonReentrant} modifier
 * available, which can be applied to functions to make sure there are no nested
 * (reentrant) calls to them.
 *
 * Note that because there is a single `nonReentrant` guard, functions marked as
 * `nonReentrant` may not call one another. This can be worked around by making
 * those functions `private`, and then adding `external` `nonReentrant` entry
 * points to them.
 *
 * TIP: If EIP-1153 (transient storage) is available on the chain you're deploying at,
 * consider using {ReentrancyGuardTransient} instead.
 *
 * TIP: If you would like to learn more about reentrancy and alternative ways
 * to protect against it, check out our blog post
 * https://blog.openzeppelin.com/reentrancy-after-istanbul/[Reentrancy After Istanbul].
 */
abstract contract ReentrancyGuardUpgradeable is Initializable {
    // Booleans are more expensive than uint256 or any type that takes up a full
    // word because each write operation emits an extra SLOAD to first read the
    // slot's contents, replace the bits taken up by the boolean, and then write
    // back. This is the compiler's defense against contract upgrades and
    // pointer aliasing, and it cannot be disabled.

    // The values being non-zero value makes deployment a bit more expensive,
    // but in exchange the refund on every call to nonReentrant will be lower in
    // amount. Since refunds are capped to a percentage of the total
    // transac