Merge pull request #29 from ProjectOpenSea/more-comments

More comments

reference/lib/ReferenceConsiderationStructs.sol

@@ -1,29 +1,44 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.13;
 
-import { ItemType, OrderType } from "seaport-types/src/lib/ConsiderationEnums.sol";
+import {
+    ItemType, OrderType
+} from "seaport-types/src/lib/ConsiderationEnums.sol";
 
 import {
     ReceivedItem,
     SpentItem
 } from "seaport-types/src/lib/ConsiderationStructs.sol";
 
-import { ConduitTransfer } from "seaport-types/src/conduit/lib/ConduitStructs.sol";
+import { ConduitTransfer } from
+    "seaport-types/src/conduit/lib/ConduitStructs.sol";
 
 // This file should only be used by the Reference Implementation
 
+/**
+ * @dev A struct used to hold the numerator and denominator of an order in-memory
+ *      during validation, before it is written to storage when updating order
+ *      status.
+ */
 struct StoredFractions {
     uint256 storedNumerator;
     uint256 storedDenominator;
 }
 
+/**
+ * @dev An intermediate struct used to hold information about an order after
+ *      validation to prepare for execution.
+ */
 struct OrderValidation {
     bytes32 orderHash;
     uint256 newNumerator;
     uint256 newDenominator;
     OrderToExecute orderToExecute;
 }
 
+/**
+ * @dev A struct used to hold the parameters used to validate an order.
+ */
 struct OrderValidationParams {
     bool revertOnInvalid;
     uint256 maximumFulfilled;

reference/lib/ReferenceCriteriaResolution.sol

@@ -317,6 +317,8 @@ contract ReferenceCriteriaResolution is CriteriaResolutionErrors {
             }
         }
 
+        // Skip validating criteria resolvers for considerationItems on contract
+        // orders, since contract offerers may resolve wildcard items themselves.
         if (advancedOrder.parameters.orderType == OrderType.CONTRACT) {
             return;
         }

src/core/lib/BasicOrderFulfiller.sol

@@ -25,6 +25,7 @@ import {
     AdditionalRecipient_size,
     BasicOrder_additionalRecipients_data_cdPtr,
     BasicOrder_additionalRecipients_length_cdPtr,
+    BasicOrder_basicOrderParameters_cd_offset,
     BasicOrder_basicOrderType_cdPtr,
     BasicOrder_common_params_size,
     BasicOrder_considerationAmount_cdPtr,
@@ -1022,9 +1023,16 @@ contract BasicOrderFulfiller is OrderValidator {
         OrderStatus storage orderStatus = _validateBasicOrder(
             orderHash,
             _toBytesReturnType(_decodeBytes)(
+                // Wrap the absolute pointer to the order signature as a
+                // CalldataPointer.
                 CalldataPointer.wrap(
-                    CalldataPointer.wrap(BasicOrder_signature_cdPtr)
-                        .readMaskedUint256() + 0x24
+                    // Read the relative pointer to the order signature.
+                    CalldataPointer
+                        .wrap(BasicOrder_signature_cdPtr)
+                        .readMaskedUint256() +
+                        // Add the BasicOrderParameters struct offset to the
+                        // relative pointer.
+                        BasicOrder_basicOrderParameters_cd_offset
                 )
             )
         );

src/core/lib/ConsiderationEncoder.sol

@@ -357,8 +357,13 @@ contract ConsiderationEncoder {
      * @param extraData       The extraData bytes array used to construct the
      *                        encoded `authorizeOrder` calldata.
      * @param orderHashes     An array of bytes32 values representing the order
-     *                        hashes of all orders included as part of the
-     *                        current fulfillment.
+     *                        hashes of all available orders validated thus far
+     *                        as part of current fulfillment. 
+     *                        Note that this differs from the orderHashes array
+     *                        passed to `validateOrder` in that the latter
+     *                        includes *all* available and validated orders
+     *                        in the final fulfillment, as it is only a subset
+     *                        of the final fulfilled orderHashes.
      *
      * @return dst  A memory pointer referencing the encoded `authorizeOrder`
      *              calldata.
@@ -488,7 +493,7 @@ contract ConsiderationEncoder {
             MemoryPointer.unwrap(orderHashesLengthLocation)
         );
 
-        // Write the shorted orderHashes array length.
+        // Write the shortened orderHashes array length.
         orderHashesLengthLocation.write(orderIndex);
 
         // Modify encoding size to account for the shorter orderHashes array.

src/core/lib/LowLevelHelpers.sol

@@ -120,7 +120,6 @@ contract LowLevelHelpers {
      *      array length.
      */
     function _getReadAdvancedOrderByOffset(
-        // function (MemoryPointer, uint256) internal pure returns (MemoryPointer) fn1
     ) internal pure returns (
         function (AdvancedOrder[] memory, uint256) internal pure returns (AdvancedOrder memory) fn2
     ) {

src/core/lib/OrderFulfiller.sol

@@ -120,9 +120,12 @@ contract OrderFulfiller is
             recipient
         );
 
-        // Declare empty bytes32 array and populate with the order hash.
+        // Declare an empty length-1 array to hold the order hash, but do not
+        // write to it until after the order has been authorized or generated.
         bytes32[] memory orderHashes = new bytes32[](1);
 
+        // Declare a boolean that cannot be optimized out by the compiler
+        // outside of the if-else statement so it can be used in either.
         bool _true = _runTimeConstantTrue();
         if (orderType != OrderType.CONTRACT) {
             _assertRestrictedAdvancedOrderAuthorization(
@@ -140,6 +143,7 @@ contract OrderFulfiller is
 
         _transferEach(orderParameters, fulfillerConduitKey, recipient);
 
+        // Write the order hash to the orderHashes array.
         orderHashes[0] = orderHash;
 
         // Ensure restricted orders have a valid submitter or pass a zone check.

src/core/lib/OrderValidator.sol

@@ -195,7 +195,8 @@ contract OrderValidator is Executor, ZoneInteraction {
             if (invalidFraction) {
                 _revertBadFraction();
             }
-
+            // Return a placeholder orderHash and a fill fraction of 1/1.
+            // The real orderHash will be returned by _getGeneratedOrder.
             return (
                 bytes32(uint256(1)), 1, 1
             );
@@ -389,6 +390,19 @@ contract OrderValidator is Executor, ZoneInteraction {
         }
     }
 
+    /**
+     * @dev Internal function to update the status of an order by applying the
+     *      supplied fill fraction to the remaining order fraction. If
+     *      revertOnInvalid is true, the function will revert if the order is
+     *      unavailable or if it is not possible to apply the supplied fill 
+     *      fraction to the remaining amount (e.g., if there is not enough
+     *      of the order remaining to fill the supplied fraction, or if the
+     *      fractions cannot be represented by two uint120 values).
+     * @param orderHash The hash of the order.
+     * @param numerator The numerator of the fraction filled to write to the order status.
+     * @param denominator The denominator of the fraction filled to write to the order status.
+     * @param revertOnInvalid Whether to revert if an order is already filled.
+     */
     function _updateStatus(
         bytes32 orderHash,
         uint256 numerator,

src/core/lib/ZoneInteraction.sol

@@ -334,8 +334,7 @@ contract ZoneInteraction is
         address target,
         bytes32 orderHash,
         MemoryPointer callData,
-        uint256 size/* ,
-        uint256 errorSelector */
+        uint256 size
     ) internal {
         bool success;
         bool magicMatch;
@@ -378,7 +377,6 @@ contract ZoneInteraction is
             assembly {
                 // The error selector is already in memory at the zero slot.
                 mstore(0x80, orderHash)
-
                 // revert(abi.encodeWithSelector(
                 //     "InvalidRestrictedOrder(bytes32)",
                 //     orderHash

src/types/lib/ConsiderationConstants.sol

@@ -302,6 +302,7 @@ uint256 constant BasicOrder_zone_cdPtr = 0xa4;
 uint256 constant BasicOrder_offerToken_cdPtr = 0xc4;
 uint256 constant BasicOrder_offerIdentifier_cdPtr = 0xe4;
 uint256 constant BasicOrder_offerAmount_cdPtr = 0x104;
+uint256 constant BasicOrder_basicOrderParameters_cd_offset = 0x24;
 uint256 constant BasicOrder_basicOrderType_cdPtr = 0x124;
 uint256 constant BasicOrder_startTime_cdPtr = 0x144;
 uint256 constant BasicOrder_endTime_cdPtr = 0x164;