@artblocks/contracts 1.0.4 → 1.1.0

package/contracts/libs/v0.8.x/minter-libs/SEALib.sol

@@ -3,7 +3,14 @@
 
 pragma solidity ^0.8.0;
 
-import "@openzeppelin-4.7/contracts/utils/math/SafeCast.sol";
+import {IMinterFilterV1} from "../../../interfaces/v0.8.x/IMinterFilterV1.sol";
+
+import {ABHelpers} from "../ABHelpers.sol";
+import {SplitFundsLib} from "./SplitFundsLib.sol";
+import {MaxInvocationsLib} from "./MaxInvocationsLib.sol";
+
+import {IERC721} from "@openzeppelin-4.7/contracts/token/ERC721/IERC721.sol";
+import {SafeCast} from "@openzeppelin-4.7/contracts/utils/math/SafeCast.sol";
 
 /**
  * @title Art Blocks SEA Minter Library
@@ -14,6 +21,135 @@ import "@openzeppelin-4.7/contracts/utils/math/SafeCast.sol";
 
 library SEALib {
     using SafeCast for uint256;
+    /**
+     * @notice Minimum auction length, in seconds, was updated to be the
+     * provided value.
+     * @param minAuctionDurationSeconds Minimum auction length, in seconds
+     */
+    event MinAuctionDurationSecondsUpdated(uint256 minAuctionDurationSeconds);
+
+    /**
+     * @notice Admin-controlled time buffer updated
+     * @param minterTimeBufferSeconds Time buffer, in seconds
+     */
+    event MinterTimeBufferUpdated(uint32 minterTimeBufferSeconds);
+
+    /**
+     * @notice Admin-controlled refund gas limit updated
+     * @param refundGasLimit Gas limit to use when refunding the previous
+     * highest bidder, prior to using fallback force-send to refund
+     */
+    event MinterRefundGasLimitUpdated(uint24 refundGasLimit);
+
+    /**
+     * @notice Future auctions for project `projectId` on core contract
+     * `coreContract` configured.
+     * @param projectId Project Id configured
+     * @param coreContract Core contract address configured
+     * @param timestampStart Start timestamp after which future auctions may be
+     * started. If zero, auctions can start immediately.
+     * @param auctionDurationSeconds Duration of each new auction, before any
+     * extensions due to late bids
+     * @param basePrice Minimum bid price for the token auctions
+     * @param minBidIncrementPercentage Minimum bid increment percentage. Each
+     * subsequent bid must be at least this percentage greater than the
+     * previous bid. The value is expressed as a whole percentage, e.g. 5% is
+     * 5, 10% is 10, etc.
+     */
+    event ConfiguredFutureAuctions(
+        uint256 indexed projectId,
+        address indexed coreContract,
+        uint64 timestampStart,
+        uint32 auctionDurationSeconds,
+        uint256 basePrice,
+        uint8 minBidIncrementPercentage
+    );
+
+    /**
+     * @notice New token auction created, token created and sent to minter
+     * @param tokenId Token Id for which auction was created
+     * @param coreContract Core contract address for the given token
+     * @param bidder Bidder's address who initialized the auction
+     * @param bidAmount Bid amount
+     * @param endTime Auction end time
+     * @param minBidIncrementPercentage Minimum bid increment percentage. Each
+     * subsequent bid must be at least this percentage greater than the
+     * previous bid. The value is expressed as a whole percentage, e.g. 5% is
+     * 5, 10% is 10, etc.
+     */
+    event AuctionInitialized(
+        uint256 indexed tokenId,
+        address indexed coreContract,
+        address indexed bidder,
+        uint256 bidAmount,
+        uint64 endTime,
+        uint8 minBidIncrementPercentage
+    );
+
+    /**
+     * @notice Successful bid placed on token auction
+     * @param tokenId Token Id of auction bid on
+     * @param coreContract Core contract address for the given token
+     * @param bidder Bidder's address who placed the bid
+     * @param bidAmount Bid amount
+     */
+    event AuctionBid(
+        uint256 indexed tokenId,
+        address indexed coreContract,
+        address indexed bidder,
+        uint256 bidAmount
+    );
+
+    /**
+     * @notice Token auction was settled (token distributed to winner)
+     * @param tokenId Token Id of auction settled
+     * @param coreContract Core contract address for the given token
+     * @param winner Winner's address
+     * @param price Winning bid amount
+     */
+    event AuctionSettled(
+        uint256 indexed tokenId,
+        address indexed coreContract,
+        address indexed winner,
+        uint256 price
+    );
+
+    /**
+     * @notice Future auction details for project `projectId` reset
+     * @param projectId Project Id that was reset
+     * @param coreContract Core contract address that was reset
+     */
+    event ResetAuctionDetails(
+        uint256 indexed projectId,
+        address indexed coreContract
+    );
+
+    /**
+     * @notice Next token ID for project `projectId` updated
+     * @param projectId Project Id of next token updated
+     * @param coreContract Core contract address of next token updated
+     * @param tokenId Token Id of next token updated
+     */
+    event ProjectNextTokenUpdated(
+        uint256 indexed projectId,
+        address indexed coreContract,
+        uint256 tokenId
+    );
+
+    /**
+     * @notice Next token ID for project `projectId` ejected from the minter
+     * and is no longer populated
+     * @param projectId Project Id of next token ejected
+     * @param coreContract Core contract address of next token ejected
+     */
+    event ProjectNextTokenEjected(
+        uint256 indexed projectId,
+        address indexed coreContract
+    );
+
+    // position of SEA Lib storage, using a diamond storage pattern
+    // for this library
+    bytes32 constant SEA_LIB_STORAGE_POSITION = keccak256("sealib.storage");
 
     uint256 constant ONE_MILLION = 1_000_000;
 
@@ -67,93 +203,436 @@ library SEALib {
         bool settled;
     }
 
+    // Diamond storage pattern is used in this library
+    struct SEALibStorage {
+        mapping(address coreContract => mapping(uint256 projectId => SEAProjectConfig)) SEAProjectConfigs;
+    }
+
     /**
      * @notice Updates the SEAProjectConfig to clear the current settings for
      * future auctions on the project. Values are reset to their default
      * initial values.
      * Current auction details are not cleared or affected.
-     * @param _SEAProjectConfig SEAProjectConfig to update
+     * @param projectId Project ID to reset
+     * @param coreContract Core contract address to reset
      */
     function resetFutureAuctionDetails(
-        SEAProjectConfig storage _SEAProjectConfig
+        uint256 projectId,
+        address coreContract
     ) internal {
+        SEAProjectConfig storage SEAProjectConfig_ = getSEAProjectConfig({
+            projectId: projectId,
+            coreContract: coreContract
+        });
         // reset future auction details
-        _SEAProjectConfig.auctionDurationSeconds = 0;
-        _SEAProjectConfig.minBidIncrementPercentage = 0;
-        _SEAProjectConfig.basePrice = 0;
-        _SEAProjectConfig.timestampStart = 0;
+        SEAProjectConfig_.auctionDurationSeconds = 0;
+        SEAProjectConfig_.minBidIncrementPercentage = 0;
+        SEAProjectConfig_.basePrice = 0;
+        SEAProjectConfig_.timestampStart = 0;
+
+        emit ResetAuctionDetails({
+            projectId: projectId,
+            coreContract: coreContract
+        });
     }
 
     /**
-     * Overwrite the active auction for a project with a new auction.
-     * @dev This function is used to initialize a new auction. Care must be
-     * taken to ensure that the existing auction is fully complete and settled.
-     * @param _SEAProjectConfig SEAProjectConfig to update
-     * @param _targetTokenId token ID to create the auction for
-     * @param _bidAmount initial bid amount
-     * @param _bidder initial bidder's payable address
-     * @return endTime end time of the newly created auction
+     * @notice Configures future auctions for project `projectId` on core
+     * contract `coreContract`.
+     * Reverts if `timestampStart` is in the past and not zero.
+     * @param projectId Project ID to configure
+     * @param coreContract Core contract address to configure
+     * @param timestampStart Timestamp to start future auctions at. If zero,
+     * auctions can start immediately.
+     * @param auctionDurationSeconds Duration of each new auction, before any
+     * extensions due to late bids
+     * @param basePrice Minimum bid price for the token auctions
+     * @param minBidIncrementPercentage Minimum bid increment percentage. Each
+     * subsequent bid must be at least this percentage greater than the
+     * previous bid. The value is expressed as a whole percentage, e.g. 5% is
+     * 5, 10% is 10, etc.
      */
-    function overwriteProjectActiveAuction(
-        SEAProjectConfig storage _SEAProjectConfig,
-        uint256 _targetTokenId,
-        uint256 _bidAmount,
-        address payable _bidder
-    ) internal returns (uint64 endTime) {
-        // calculate auction end time
-        endTime = (block.timestamp + _SEAProjectConfig.auctionDurationSeconds)
-            .toUint64();
-        // set active auction on SEAProjectConfig
-        _SEAProjectConfig.activeAuction = Auction({
-            tokenId: _targetTokenId,
-            currentBid: _bidAmount,
-            currentBidder: _bidder,
-            endTime: endTime,
-            minBidIncrementPercentage: _SEAProjectConfig
-                .minBidIncrementPercentage,
-            settled: false
+    function configureFutureAuctions(
+        uint256 projectId,
+        address coreContract,
+        uint256 timestampStart,
+        uint256 auctionDurationSeconds,
+        uint256 basePrice,
+        uint8 minBidIncrementPercentage
+    ) internal {
+        SEAProjectConfig storage SEAProjectConfig_ = getSEAProjectConfig({
+            projectId: projectId,
+            coreContract: coreContract
+        });
+        require(
+            timestampStart == 0 || block.timestamp < timestampStart,
+            "Only future start times or 0"
+        );
+        // EFFECTS
+        SEAProjectConfig_.timestampStart = timestampStart.toUint64(); // @dev rely on this safe-cast check in event emit below
+        SEAProjectConfig_.auctionDurationSeconds = auctionDurationSeconds
+            .toUint32();
+        SEAProjectConfig_.basePrice = basePrice;
+        SEAProjectConfig_.minBidIncrementPercentage = minBidIncrementPercentage;
+
+        emit ConfiguredFutureAuctions({
+            projectId: projectId,
+            coreContract: coreContract,
+            timestampStart: uint64(timestampStart), // @dev safe-casting already previously checked
+            auctionDurationSeconds: auctionDurationSeconds.toUint32(),
+            basePrice: basePrice,
+            minBidIncrementPercentage: minBidIncrementPercentage
         });
-        return endTime;
     }
 
     /**
      * @notice Updates the bid state of an Auction.
      * Note that the auction's end time is extended if the bid is placed within
-     * the last `_timeBufferSeconds` of the auction.
+     * the last `timeBufferSeconds` of the auction.
      * NOTE: This function does not check if the bid is valid. It is assumed
      * that the bid has already been checked for validity by the caller.
-     * @param _auction Auction to update
-     * @param _timeBufferSeconds Time buffer to extend the auction to if the
-     * bid is placed within the last `_timeBufferSeconds` of the auction.
-     * @param _bidAmount bid amount
-     * @param _bidder bidder's payable address
+     * @param auction Auction to update
+     * @param timeBufferSeconds Time buffer to extend the auction to if the
+     * bid is placed within the last `timeBufferSeconds` of the auction.
+     * @param bidAmount bid amount
+     * @param bidder bidder's payable address
      */
     function auctionUpdateBid(
-        Auction storage _auction,
-        uint256 _timeBufferSeconds,
-        uint256 _bidAmount,
-        address payable _bidder
+        Auction storage auction,
+        uint256 timeBufferSeconds,
+        uint256 bidAmount,
+        address payable bidder
     ) internal {
         // update auction state
-        _auction.currentBid = _bidAmount;
-        _auction.currentBidder = _bidder;
-        uint256 minEndTime = block.timestamp + _timeBufferSeconds;
-        if (_auction.endTime < minEndTime) {
-            _auction.endTime = minEndTime.toUint64();
+        auction.currentBid = bidAmount;
+        auction.currentBidder = bidder;
+        uint256 minEndTime = block.timestamp + timeBufferSeconds;
+        if (auction.endTime < minEndTime) {
+            auction.endTime = minEndTime.toUint64();
         }
     }
 
+    /**
+     * @notice Ejects a project's "next token" from the minter and sends it to
+     * the input `to` address.
+     * This function is only intended for use in the edge case where the minter
+     * has a "next token" assigned to a project, but the project has been reset
+     * via `resetAuctionDetails`, and the artist does not want an auction to be
+     * started for the "next token". This function also protects against the
+     * unforseen case where the minter is in an unexpected state where it has a
+     * "next token" assigned to a project, but for some reason the project is
+     * unable to begin a new auction due to a bug.
+     * @param projectId The project ID being ejected
+     * @param coreContract The core contract address being ejected
+     * @param to The address to send the ejected token to
+     */
+    function ejectNextTokenTo(
+        uint256 projectId,
+        address coreContract,
+        address to
+    ) internal {
+        SEAProjectConfig storage SEAProjectConfig_ = getSEAProjectConfig({
+            projectId: projectId,
+            coreContract: coreContract
+        });
+        // CHECKS
+        // only if project is not configured (i.e. artist called
+        // `resetAuctionDetails`)
+        require(
+            !projectIsConfigured({
+                projectId: projectId,
+                coreContract: coreContract
+            }),
+            "Only unconfigured projects"
+        );
+        // only if project has a next token assigned
+        require(
+            SEAProjectConfig_.nextTokenNumberIsPopulated == true,
+            "No next token"
+        );
+        // EFFECTS
+        SEAProjectConfig_.nextTokenNumberIsPopulated = false;
+        // INTERACTIONS
+        // @dev overflow automatically handled by Sol ^0.8.0
+        uint256 nextTokenId = ABHelpers.tokenIdFromProjectIdAndTokenNumber({
+            projectId: projectId,
+            tokenNumber: SEAProjectConfig_.nextTokenNumber
+        });
+        IERC721(coreContract).transferFrom({
+            from: address(this),
+            to: to,
+            tokenId: nextTokenId
+        });
+        emit ProjectNextTokenEjected({
+            projectId: projectId,
+            coreContract: coreContract
+        });
+    }
+
+    /**
+     * @notice Settles a completed auction for `tokenId`, if it exists and is
+     * not yet settled.
+     * Returns early (does not modify state) if
+     *   - there is no initialized auction for the project
+     *   - there is an auction that has already been settled for the project
+     *   - there is an auction for a different token ID on the project
+     *     (likely due to a front-run)
+     * This function reverts if the auction for `tokenId` exists, but has not
+     * yet ended.
+     * @param tokenId Token ID to settle auction for.
+     * @param coreContract Core contract address for the given token.
+     */
+    function settleAuction(uint256 tokenId, address coreContract) internal {
+        uint256 projectId = ABHelpers.tokenIdToProjectId(tokenId);
+        SEAProjectConfig storage _SEAProjectConfig = getSEAProjectConfig({
+            projectId: projectId,
+            coreContract: coreContract
+        });
+        Auction storage auction = _SEAProjectConfig.activeAuction;
+        // load from storage to memory for gas efficiency
+        address currentBidder = auction.currentBidder;
+        uint256 currentBid = auction.currentBid;
+        // CHECKS
+        // @dev this check is not strictly necessary, but is included for
+        // clear error messaging
+        require(auctionIsInitialized(auction), "Auction not initialized");
+        if (auction.settled || (auction.tokenId != tokenId)) {
+            // auction already settled or is for a different token ID, so
+            // return early and do not modify state
+            return;
+        }
+        // @dev important that the following check is after the early return
+        // block above to maintain desired behavior
+        require(block.timestamp >= auction.endTime, "Auction not yet ended");
+        // EFFECTS
+        auction.settled = true;
+        // INTERACTIONS
+        // send token to the winning bidder
+        IERC721(coreContract).transferFrom({
+            from: address(this),
+            to: currentBidder,
+            tokenId: tokenId
+        });
+        // distribute revenues from auction
+        SplitFundsLib.splitRevenuesETHNoRefund({
+            projectId: projectId,
+            valueInWei: currentBid,
+            coreContract: coreContract
+        });
+
+        emit AuctionSettled({
+            tokenId: tokenId,
+            coreContract: coreContract,
+            winner: currentBidder,
+            price: currentBid
+        });
+    }
+
+    /**
+     * @notice Enters a bid for token `tokenId`.
+     * If an auction for token `tokenId` does not exist, an auction will be
+     * initialized as long as any existing auction for the project has been
+     * settled.
+     * In order to successfully place the bid, the token bid must be:
+     * - greater than or equal to a project's minimum bid price if a new
+     *   auction is initialized
+     * - sufficiently greater than the current highest bid, according to the
+     *   minter's bid increment percentage `minterMinBidIncrementPercentage`,
+     *   if an auction for the token already exists
+     * If the bid is unsuccessful, the transaction will revert.
+     * If the bid is successful, but outbid by another bid before the auction
+     * ends, the funds will be noncustodially returned to the bidder's address,
+     * `msg.sender`. A fallback method of sending funds back to the bidder via
+     * SELFDESTRUCT (SENDALL) prevents denial of service attacks, even if the
+     * original bidder reverts or runs out of gas during receive or fallback.
+     * ------------------------------------------------------------------------
+     * WARNING: bidders must be prepared to handle the case where their bid is
+     * outbid and their funds are returned to the original `msg.sender` address
+     * via SELFDESTRUCT (SENDALL).
+     * ------------------------------------------------------------------------
+     * Note that the use of `tokenId` is to prevent the possibility of
+     * transactions that are stuck in the pending pool for long periods of time
+     * from unintentionally bidding on auctions for future tokens.
+     * If a new auction is initialized during this call, the project's next
+     * token will be attempted to be minted to this minter contract, preparing
+     * it for the next auction. If the project's next token cannot be minted
+     * due to e.g. reaching the maximum invocations on the core contract or
+     * minter, the project's next token will not be minted.
+     * @param tokenId Token ID being bid on.
+     * @param coreContract Core contract address for the given project.
+     * @param minterTimeBufferSeconds Time buffer to extend the auction to if
+     * the bid is placed within the last `minterTimeBufferSeconds` of the
+     * auction.
+     * @param minterRefundGasLimit Gas limit to use when refunding the previous
+     * highest bidder.
+     * @param minterFilter Minter filter to use when minting the next token for
+     * the project.
+     * @dev nonReentrant modifier is used to prevent reentrancy attacks, e.g.
+     * an an auto-bidder that would be able to atomically outbid a user's
+     * new bid via a reentrant call to createBid.
+     */
+    function createBid(
+        uint256 tokenId,
+        address coreContract,
+        uint256 minterTimeBufferSeconds,
+        uint256 minterRefundGasLimit,
+        IMinterFilterV1 minterFilter
+    ) internal {
+        uint256 projectId = ABHelpers.tokenIdToProjectId(tokenId);
+        SEAProjectConfig storage SEAProjectConfig_ = getSEAProjectConfig({
+            projectId: projectId,
+            coreContract: coreContract
+        });
+        Auction storage auction = SEAProjectConfig_.activeAuction;
+        // CHECKS
+        // if no auction exists, or current auction is already settled, attempt
+        // to initialize a new auction for the input token ID and immediately
+        // return
+        if ((!auctionIsInitialized(auction)) || auction.settled) {
+            _initializeAuctionWithBid({
+                projectId: projectId,
+                coreContract: coreContract,
+                targetTokenId: tokenId,
+                minterFilter: minterFilter
+            });
+            return;
+        }
+        // @dev this branch is guaranteed to have an initialized auction that
+        // not settled, so no need to check for initialized or not settled
+
+        // ensure bids for a specific token ID are only applied to the auction
+        // for that token ID.
+        require(auction.tokenId == tokenId, "Token ID does not match auction");
+
+        // ensure auction is not already ended
+        require(auction.endTime > block.timestamp, "Auction already ended");
+
+        // require bid to be sufficiently greater than current highest bid
+        // @dev no overflow enforced automatically by solidity ^0.8.0
+        require(msg.value >= getMinimumNextBid(auction), "Bid is too low");
+
+        // EFFECTS
+        // record previous highest bidder and bid for refunding
+        address payable previousBidder = auction.currentBidder;
+        uint256 previousBid = auction.currentBid;
+
+        // update auction bid state
+        auctionUpdateBid({
+            auction: auction,
+            timeBufferSeconds: minterTimeBufferSeconds,
+            bidAmount: msg.value,
+            bidder: payable(msg.sender)
+        });
+
+        // INTERACTIONS
+        // refund previous highest bidder
+        SplitFundsLib.forceSafeTransferETH({
+            to: previousBidder,
+            amount: previousBid,
+            minterRefundGasLimit: minterRefundGasLimit
+        });
+
+        emit AuctionBid({
+            tokenId: tokenId,
+            coreContract: coreContract,
+            bidder: msg.sender,
+            bidAmount: msg.value
+        });
+    }
+
+    /**
+     * @notice Internal function that attempts to mint a new token to the next
+     * token slot for the project `projectId`.
+     * This function returns early and does not modify state if
+     *   - the project has reached its maximum invocations on either the core
+     *     contract or minter
+     *   - the project config's `nextTokenNumberIsPopulated` is already true
+     * @param projectId The ID of the project to mint a new token for.
+     * @param coreContract The core contract address
+     * @param minterFilter The minter filter contract address
+     * @dev this calls mint with `msg.sender` as the sender, allowing artists
+     * to mint tokens to the next token slot for their project while a project
+     * is still paused. This happens when an artist is configuring their
+     * project's auction parameters or minter max invocations.
+     */
+    function tryMintTokenToNextSlot(
+        uint256 projectId,
+        address coreContract,
+        IMinterFilterV1 minterFilter
+    ) internal {
+        SEAProjectConfig storage SEAProjectConfig_ = getSEAProjectConfig({
+            projectId: projectId,
+            coreContract: coreContract
+        });
+        if (SEAProjectConfig_.nextTokenNumberIsPopulated) {
+            return;
+        }
+        // INTERACTIONS
+        // attempt to mint new token to this minter contract, only if max
+        // invocations has not been reached
+        // we require up-to-date invocation data to properly handle last token
+        // and avoid revert if relying on core to limit invocations, therefore
+        // use MaxInvocationsLib.invocationsRemain, which calls core contract
+        // to get latest invocation data
+        if (
+            !MaxInvocationsLib.invocationsRemain({
+                projectId: projectId,
+                coreContract: coreContract
+            })
+        ) {
+            // we have reached the max invocations, so we do not mint a new
+            // token as the "next token", and leave the next token number as
+            // not populated
+            return;
+        }
+        // @dev this is an effect after a trusted contract interaction
+        SEAProjectConfig_.nextTokenNumberIsPopulated = true;
+        // mint a new token to this project's "next token" slot
+        // @dev this is an interaction with a trusted contract
+        uint256 nextTokenId = minterFilter.mint_joo({
+            to: address(this),
+            projectId: projectId,
+            coreContract: coreContract,
+            sender: msg.sender
+        });
+        // update state to reflect new token number
+        // @dev state changes after trusted contract interaction
+        // @dev unchecked is safe because mod 1e6 is guaranteed to be less than
+        // max uint24
+        unchecked {
+            SEAProjectConfig_.nextTokenNumber = uint24(
+                ABHelpers.tokenIdToTokenNumber(nextTokenId)
+            );
+        }
+        // update local maxHasBeenInvoked value if necessary
+        MaxInvocationsLib.validatePurchaseEffectsInvocations({
+            tokenId: nextTokenId,
+            coreContract: coreContract
+        });
+        emit ProjectNextTokenUpdated({
+            projectId: projectId,
+            coreContract: coreContract,
+            tokenId: nextTokenId
+        });
+    }
+
     /**
      * @notice Determines if a project is configured or not on this minter.
      * Uses project config's `auctionDurationSeconds` to determine if project
      * is configured, because `auctionDurationSeconds` is required to be
      * non-zero when configured.
-     * @param _SEAProjectConfig The project config to check.
+     * @param projectId The project ID being queried
+     * @param coreContract The core contract address being queried
      */
     function projectIsConfigured(
-        SEAProjectConfig storage _SEAProjectConfig
+        uint256 projectId,
+        address coreContract
     ) internal view returns (bool) {
-        return _SEAProjectConfig.auctionDurationSeconds != 0;
+        SEAProjectConfig storage SEAProjectConfig_ = getSEAProjectConfig({
+            projectId: projectId,
+            coreContract: coreContract
+        });
+        return SEAProjectConfig_.auctionDurationSeconds != 0;
     }
 
     /**
@@ -161,46 +640,51 @@ library SEALib {
      * Uses auction's `currentBidder` address to determine if auction is
      * initialized, because `currentBidder` is always non-zero after an auction
      * has been initialized.
-     * @param _auction The auction to check.
+     * @param auction The auction to check.
      */
     function auctionIsInitialized(
-        Auction storage _auction
+        Auction storage auction
     ) internal view returns (bool isInitialized) {
         // auction is initialized if currentBidder is non-zero
-        return _auction.currentBidder != address(0);
+        return auction.currentBidder != address(0);
     }
 
     /**
-     * Returns bool representing if an auction is accepting bids above base
+     * @notice Function returns bool representing if an auction is accepting bids above base
      * price. It is accepting bids if it is initialized and has not reached its
      * end time.
-     * @param _auction The auction to check.
+     * @param auction The auction to check.
      */
     function auctionIsAcceptingIncreasingBids(
-        Auction storage _auction
+        Auction storage auction
     ) internal view returns (bool isAcceptingBids) {
         // auction is accepting bids if it is initialized and has not reached
         // its end time
-        isAcceptingBids = (auctionIsInitialized(_auction) &&
-            block.timestamp < _auction.endTime);
-        return isAcceptingBids;
+        isAcceptingBids = (auctionIsInitialized(auction) &&
+            block.timestamp < auction.endTime);
     }
 
     /**
      * @notice SEAProjectConfig => active auction details.
      * @dev reverts if no auction exists for the project.
-     * @param _SEAProjectConfig SEAProjectConfig to query
+     * @param projectId The project ID being queried
+     * @param coreContract The core contract address being queried
      */
     function projectActiveAuctionDetails(
-        SEAProjectConfig storage _SEAProjectConfig
+        uint256 projectId,
+        address coreContract
     ) internal view returns (Auction memory auction) {
-        Auction storage _auction = _SEAProjectConfig.activeAuction;
+        SEAProjectConfig storage SEAProjectConfig_ = getSEAProjectConfig({
+            projectId: projectId,
+            coreContract: coreContract
+        });
+        // load auction storage pointer to pass ref to utility function
+        Auction storage auction_ = SEAProjectConfig_.activeAuction;
         // do not return uninitialized auctions (i.e. auctions that do not
         // exist, where currentBidder is still the default value)
-        require(auctionIsInitialized(_auction), "No auction exists on project");
-        // load entire auction into memory
-        auction = _SEAProjectConfig.activeAuction;
-        return auction;
+        require(auctionIsInitialized(auction_), "No auction exists on project");
+        // load entire auction into memory to return
+        auction = SEAProjectConfig_.activeAuction;
     }
 
     /**
@@ -213,47 +697,55 @@ library SEALib {
      * target bid token ID to be passed in as an argument.
      * The function reverts if a project does not have an active auction and
      * the next expected token ID has not been populated.
-     * @param _SEAProjectConfig SEAProjectConfig to query
-     * @param _projectId The project ID being queried
+     * @param projectId The project ID being queried
+     * @param coreContract The core contract address being queried
      * @return The current token ID being auctioned, or the next token ID to be
      * auctioned if a new auction is ready to be created.
      */
     function getTokenToBid(
-        SEAProjectConfig storage _SEAProjectConfig,
-        uint256 _projectId
+        uint256 projectId,
+        address coreContract
     ) internal view returns (uint256) {
-        Auction storage _auction = _SEAProjectConfig.activeAuction;
+        SEAProjectConfig storage SEAProjectConfig_ = getSEAProjectConfig({
+            projectId: projectId,
+            coreContract: coreContract
+        });
+        Auction storage auction = SEAProjectConfig_.activeAuction;
         // if project has an active token auction that is not settled, return
         // that token ID
         if (
-            auctionIsInitialized(_auction) &&
-            (_auction.endTime > block.timestamp)
+            auctionIsInitialized(auction) && (auction.endTime > block.timestamp)
         ) {
-            return _auction.tokenId;
+            return auction.tokenId;
         }
         // otherwise, return the next expected token ID to be auctioned.
-        return getNextTokenId(_SEAProjectConfig, _projectId);
+        return getNextTokenId(projectId, coreContract);
     }
 
     /**
      * @notice View function that returns the next token ID to be auctioned
-     * by this minter for project `_projectId`.
+     * by this minter for project `projectId`.
      * Reverts if the next token ID has not been populated for the project.
-     * @param _SEAProjectConfig SEAProjectConfig to query
-     * @param _projectId The project ID being queried
+     * @param projectId The project ID being queried
+     * @param coreContract The core contract address being queried
      */
     function getNextTokenId(
-        SEAProjectConfig storage _SEAProjectConfig,
-        uint256 _projectId
+        uint256 projectId,
+        address coreContract
     ) internal view returns (uint256 nextTokenId) {
-        if (!_SEAProjectConfig.nextTokenNumberIsPopulated) {
-            revert("Next token not populated");
-        }
+        SEAProjectConfig storage SEAProjectConfig_ = getSEAProjectConfig({
+            projectId: projectId,
+            coreContract: coreContract
+        });
+        require(
+            SEAProjectConfig_.nextTokenNumberIsPopulated,
+            "Next token not populated"
+        );
+
         // @dev overflow automatically checked in Solidity ^0.8.0
         nextTokenId =
-            (_projectId * ONE_MILLION) +
-            _SEAProjectConfig.nextTokenNumber;
-        return nextTokenId;
+            (projectId * ONE_MILLION) +
+            SEAProjectConfig_.nextTokenNumber;
     }
 
     /**
@@ -269,20 +761,29 @@ library SEALib {
      * the project is configured, `isConfigured` will be true, and
      * `tokenPriceInWei` will be the minimum initial bid price for the next
      * token auction.
-     * @param _SEAProjectConfig SEAProjectConfig to be evaluated.
+     * @param projectId Project ID to get price info for
+     * @param coreContract Core contract address to get price info for
      * @return isConfigured true only if project auctions are configured.
      * @return tokenPriceInWei price in wei to become the leading bidder on a
      * token auction.
      */
-    function getPriceInfoFromSEAProjectConfig(
-        SEAProjectConfig storage _SEAProjectConfig
+    function getPriceInfo(
+        uint256 projectId,
+        address coreContract
     ) internal view returns (bool isConfigured, uint256 tokenPriceInWei) {
-        Auction storage _auction = _SEAProjectConfig.activeAuction;
+        SEAProjectConfig storage SEAProjectConfig_ = getSEAProjectConfig({
+            projectId: projectId,
+            coreContract: coreContract
+        });
+        Auction storage auction = SEAProjectConfig_.activeAuction;
         // base price of zero not allowed when configuring auctions, so use it
         // as indicator of whether auctions are configured for the project
-        bool projectIsConfigured_ = projectIsConfigured(_SEAProjectConfig);
+        bool projectIsConfigured_ = projectIsConfigured({
+            projectId: projectId,
+            coreContract: coreContract
+        });
         bool auctionIsAcceptingIncreasingBids_ = auctionIsAcceptingIncreasingBids(
-                _auction
+                auction
             );
         isConfigured =
             projectIsConfigured_ ||
@@ -291,12 +792,12 @@ library SEALib {
         if (isConfigured) {
             if (auctionIsAcceptingIncreasingBids_) {
                 // return minimum next bid, given current bid
-                tokenPriceInWei = getMinimumNextBid(_auction);
+                tokenPriceInWei = getMinimumNextBid(auction);
             } else {
                 // return base (starting) price if if current auction is not
                 // accepting bids (i.e. the minimum initial bid price for the
                 // next token auction)
-                tokenPriceInWei = _SEAProjectConfig.basePrice;
+                tokenPriceInWei = SEAProjectConfig_.basePrice;
             }
         }
         // else leave tokenPriceInWei as default value of zero
@@ -304,17 +805,191 @@ library SEALib {
     }
 
     /**
-     * Returns the minimum next bid amount in a configured auction, given the
+     * @notice Function returns the minimum next bid amount in a configured auction, given the
      * current bid amount and the project's configured minimum bid increment
      * percentage.
-     * @param _auction Auction to query
+     * @param auction Auction to query
      */
     function getMinimumNextBid(
-        Auction storage _auction
+        Auction storage auction
     ) internal view returns (uint256 minimumNextBid) {
-        // @dev overflow automatically checked in Solidity ^0.8.0
-        return
-            (_auction.currentBid * (100 + _auction.minBidIncrementPercentage)) /
-            100;
+        // @dev unchecked due to 0 <= minBidIncrementPercentage <= 255, and
+        // currentBid is capped at supply of ETH, so no risk of overflow
+        unchecked {
+            return
+                (auction.currentBid *
+                    (100 + auction.minBidIncrementPercentage)) / 100;
+        }
+    }
+
+    /**
+     * @dev Private function to initialize an auction for the next token ID
+     * on project `projectId` with a bid of `msg.value` from `msg.sender`.
+     * This function reverts in any of the following cases:
+     *   - project is not configured on this minter
+     *   - project is configured but has not yet reached its start time
+     *   - project has a current active auction that is not settled
+     *   - insufficient bid amount (msg.value < basePrice)
+     *   - no next token has been minted for the project (artist may need to
+     *     call `tryPopulateNextToken`)
+     *   - `targetTokenId` does not match the next token ID for the project
+     * After initializing a new auction, this function attempts to mint a new
+     * token and assign it to the project's next token slot, in preparation for
+     * a future token auction. However, if the project has reached its maximum
+     * invocations on either the core contract or minter, the next token slot
+     * for the project will remain empty.
+     * @dev This should be executed in a nonReentrant context to provide redundant
+     * protection against reentrancy.
+     * @param projectId The project ID to initialize an auction for
+     * @param coreContract The core contract address to initialize an auction for
+     * @param targetTokenId The token ID to initialize an auction for
+     * @param minterFilter The minter filter contract address
+     */
+    function _initializeAuctionWithBid(
+        uint256 projectId,
+        address coreContract,
+        uint256 targetTokenId,
+        IMinterFilterV1 minterFilter
+    ) private {
+        SEAProjectConfig storage SEAProjectConfig_ = getSEAProjectConfig({
+            projectId: projectId,
+            coreContract: coreContract
+        });
+        Auction storage auction = SEAProjectConfig_.activeAuction;
+        // CHECKS
+        // ensure project auctions are configured
+        // @dev base price of zero indicates auctions are not configured
+        // because only base price of gt zero is allowed when configuring
+        require(
+            projectIsConfigured({
+                projectId: projectId,
+                coreContract: coreContract
+            }),
+            "Project not configured"
+        );
+        // only initialize new auctions if they meet the start time
+        // requirement
+        require(
+            block.timestamp >= SEAProjectConfig_.timestampStart,
+            "Only gte project start time"
+        );
+        // the following require statement is redundant based on how this
+        // internal function is called, but it is included for protection
+        // against future changes that could easily introduce a bug if this
+        // check is not present
+        // @dev no cover else branch of next line because unreachable
+        require(
+            (!auctionIsInitialized(auction)) || auction.settled,
+            "Existing auction not settled"
+        );
+        // require valid bid value
+        require(
+            msg.value >= SEAProjectConfig_.basePrice,
+            "Insufficient initial bid"
+        );
+        // require next token number is populated
+        // @dev this should only be encountered if the project has reached
+        // its maximum invocations on either the core contract or minter
+        require(
+            SEAProjectConfig_.nextTokenNumberIsPopulated,
+            "No next token, check max invocations"
+        );
+        // require next token number is the target token ID
+        require(
+            SEAProjectConfig_.nextTokenNumber ==
+                ABHelpers.tokenIdToTokenNumber(targetTokenId),
+            "Incorrect target token ID"
+        );
+
+        // EFFECTS
+        // create new auction, overwriting previous auction if it exists
+        uint64 endTime = overwriteProjectActiveAuction({
+            SEAProjectConfig_: SEAProjectConfig_,
+            targetTokenId: targetTokenId,
+            bidAmount: msg.value,
+            bidder: payable(msg.sender)
+        });
+        // mark next token number as not populated
+        // @dev intentionally not setting nextTokenNumber to zero to avoid
+        // unnecessary gas costs
+        SEAProjectConfig_.nextTokenNumberIsPopulated = false;
+
+        // @dev we intentionally emit event here due to potential of early
+        // return in INTERACTIONS section
+        emit AuctionInitialized({
+            tokenId: targetTokenId,
+            coreContract: coreContract,
+            bidder: msg.sender,
+            bidAmount: msg.value,
+            endTime: endTime,
+            minBidIncrementPercentage: SEAProjectConfig_
+                .activeAuction
+                .minBidIncrementPercentage
+        });
+
+        // INTERACTIONS
+        // attempt to mint new token to this minter contract, only if max
+        // invocations has not been reached
+        tryMintTokenToNextSlot({
+            projectId: projectId,
+            coreContract: coreContract,
+            minterFilter: minterFilter
+        });
+    }
+
+    /**
+     * @notice Function to overwrite the active auction for a project with a new auction.
+     * @dev This function is used to initialize a new auction. Care must be
+     * taken to ensure that the existing auction is fully complete and settled.
+     * @param SEAProjectConfig_ SEAProjectConfig to update
+     * @param targetTokenId token ID to create the auction for
+     * @param bidAmount initial bid amount
+     * @param bidder initial bidder's payable address
+     * @return endTime end time of the newly created auction
+     */
+    function overwriteProjectActiveAuction(
+        SEAProjectConfig storage SEAProjectConfig_,
+        uint256 targetTokenId,
+        uint256 bidAmount,
+        address payable bidder
+    ) private returns (uint64 endTime) {
+        // calculate auction end time
+        endTime = (block.timestamp + SEAProjectConfig_.auctionDurationSeconds)
+            .toUint64();
+        // set active auction on SEAProjectConfig
+        SEAProjectConfig_.activeAuction = Auction({
+            tokenId: targetTokenId,
+            currentBid: bidAmount,
+            currentBidder: bidder,
+            endTime: endTime,
+            minBidIncrementPercentage: SEAProjectConfig_
+                .minBidIncrementPercentage,
+            settled: false
+        });
+    }
+
+    /**
+     * Loads the SEAProjectConfig for a given project and core
+     * contract.
+     * @param projectId Project Id to get config for
+     * @param coreContract Core contract address to get config for
+     */
+    function getSEAProjectConfig(
+        uint256 projectId,
+        address coreContract
+    ) internal view returns (SEAProjectConfig storage) {
+        return s().SEAProjectConfigs[coreContract][projectId];
+    }
+
+    /**
+     * @notice Return the storage struct for reading and writing. This library
+     * uses a diamond storage pattern when managing storage.
+     * @return storageStruct The SEALibStorage struct.
+     */
+    function s() internal pure returns (SEALibStorage storage storageStruct) {
+        bytes32 position = SEA_LIB_STORAGE_POSITION;
+        assembly ("memory-safe") {
+            storageStruct.slot := position
+        }
     }
 }