Seaport Marketplace Protocol

If an order is constructed with an appropriate order type to enable partial fills, it can be fulfilled for a fraction of the total amount. This allows subsequent fills to bypass signature verification.

Key Rules for Partial Fills:

• Divisibility: All items (offer and consideration) must be cleanly divisible by the supplied fraction (no remainder).
• Overflow Protection: If a requested fraction exceeds the remaining amount, the fill is automatically reduced to the amount remaining. To enforce "all or none," use a basic order method or a match order with explicit amounts.
• Ascending/Descending Amounts: For items with different startAmount and endAmount, the fraction is applied to both amounts before determining the price. This ensures consistency regardless of when the order is fulfilled.
• Criteria-based Items: Partial fills can be combined with criteria-based items to allow partial fulfillment of items like ERC721s.

When using fulfillOrder or fulfillAdvancedOrder, Seaport executes a specific sequence of operations to ensure the order is valid, signed, and correctly filled. The process follows these stages:

1. Hashing: Derives hashes for offer and consideration items, retrieves the current counter for the offerer, and derives the final order hash.
2. Initial Validation: Checks that the current time is within the order's valid range and verifies that the caller is authorized for the specific order type (potentially querying a zone for restricted order types).
3. Status Update: Verifies the order is not cancelled or fully filled, validates the signature, determines the fill fraction based on user preference and available amount, and updates the order status.
4. Amount Determination: Calculates the amount for each item. If start and end amounts are equal, it applies the fill fraction. If they differ, it applies the fraction to both and performs a linear fit based on the current time.
5. Criteria Resolution: Applies criteria resolvers to ensure item identifiers are valid via inclusion proofs (if a non-zero criteria root exists) and updates item types and identifiers.
6. Event Emission: Emits the OrderFulfilled event with the updated item details.
7. Transfers: Executes transfers of offer items (from offerer to caller) and consideration items (from caller to recipients) using either conduit or Seaport directly, depending on the order type and preference.

When matching a group of orders via matchOrders or matchAdvancedOrders, the first six steps (Hashing, Validation, Status Update, Amount Determination, Criteria Resolution, and Event Emission) are performed for each supplied order. The process then diverges into specific matching logic:

1. Apply Fulfillments:
   • Ensures each fulfillment refers to offer and consideration items with matching types, tokens, approval sources, and recipients.
   • Reduces amounts on items to zero and tracks totals.
   • Balances the amounts by adding any remaining amount back to the first item on the appropriate side of the order.
   • Returns a single execution for each fulfillment.
2. Scan Consideration Items: Ensures no consideration item has a non-zero amount remaining.
3. Perform Transfers: Executes transfers using conduit or Seaport directly. Note that executions where to == from are ignored.

Contract orders follow different rules than standard off-chain orders in several key areas:

Criteria-based Items

When a collection-wide criteria-based item (identifierOrCriteria = 0) is used in a contract order, the Seaport app has full latitude to choose the identifier mid-flight. Unlike standard orders, Seaport does not expect a CriteriaResolver for contract orders; providing one will cause a revert.

Native Token (ETH) Support

Contract orders allow for the use of native tokens (e.g., Ether) as offer items.

• Direct Transfer: Order generator contracts can send native tokens directly to Seaport during the generateOrder call.
• Reentrancy: Seaport makes exceptions to its normal reentrancy policies for order generators, allowing them to call the receive hook and provide native tokens.
• Availability: Any native tokens sent to Seaport are immediately spendable by the current or next caller.

Security Warning

Because contract orders can modify state during generateOrder, they can potentially lower the value of an offered NFT (e.g., by transferring out attached tokens). To mitigate this, consider using a mirrored order that allows for post-transfer validation.

When auditing or interacting with Seaport, the following core invariants must be upheld. Any violation that puts user funds at risk is considered a High/Critical severity issue:

1. Controlled Transfers: Only items explicitly offered in a valid order may be transferred from an offerer's account, provided they have set token approvals on Seaport directly or on a conduit that only has Seaport set as a channel.
2. Offer Limits: No order fulfillment may spend more than the offer items explicitly set for that order (though not all offered items must be spent).
3. Consideration Fulfillment: All consideration items (or fractions thereof for partial fills) must be received in full by the named recipients before the corresponding offer items are spent.
   • Note: Additional consideration items (e.g., "tips") may be added during fulfillment.
   • Note: When using fulfillment methods other than matchOrders or matchAdvancedOrders, an implied "mirror" order is created for the fulfiller. In these cases, offer items on fulfilled orders should be treated as consideration items for the fulfiller (except in fulfillBasicOrder where specific ERC721/ERC1155 to ERC20 routes use a portion of the offered item to pay consideration).