@opensea/seaport-js 1.3.0 → 2.0.1

package/src/utils/gcd.ts

@@ -0,0 +1,26 @@
+import { BigNumber, BigNumberish } from "ethers";
+
+export const gcd = (a: BigNumberish, b: BigNumberish): BigNumber => {
+  const bnA = BigNumber.from(a);
+  const bnB = BigNumber.from(b);
+
+  if (bnA.eq(0)) {
+    return bnB;
+  }
+
+  return gcd(bnB.mod(a), bnA);
+};
+
+export const findGcd = (elements: BigNumberish[]) => {
+  let result = BigNumber.from(elements[0]);
+
+  for (let i = 1; i < elements.length; i++) {
+    result = gcd(elements[i], result);
+
+    if (result.eq(1)) {
+      return result;
+    }
+  }
+
+  return result;
+};

package/src/utils/item.ts

@@ -0,0 +1,142 @@
+import { BigNumber } from "ethers";
+import { ItemType } from "../constants";
+import type { InputCriteria, Item, Order, OrderParameters } from "../types";
+import { getItemToCriteriaMap } from "./criteria";
+import { findGcd } from "./gcd";
+
+export const isCurrencyItem = ({ itemType }: Item) =>
+  [ItemType.NATIVE, ItemType.ERC20].includes(itemType);
+
+export const isNativeCurrencyItem = ({ itemType }: Item) =>
+  itemType === ItemType.NATIVE;
+
+export const isErc20Item = (itemType: Item["itemType"]) =>
+  itemType === ItemType.ERC20;
+
+export const isErc721Item = (itemType: Item["itemType"]) =>
+  [ItemType.ERC721, ItemType.ERC721_WITH_CRITERIA].includes(itemType);
+
+export const isErc1155Item = (itemType: Item["itemType"]) =>
+  [ItemType.ERC1155, ItemType.ERC1155_WITH_CRITERIA].includes(itemType);
+
+export const isCriteriaItem = (itemType: Item["itemType"]) =>
+  [ItemType.ERC721_WITH_CRITERIA, ItemType.ERC1155_WITH_CRITERIA].includes(
+    itemType
+  );
+
+export type TimeBasedItemParams = {
+  isConsiderationItem?: boolean;
+  currentBlockTimestamp: number;
+  ascendingAmountTimestampBuffer: number;
+} & Pick<OrderParameters, "startTime" | "endTime">;
+
+export const getPresentItemAmount = ({
+  startAmount,
+  endAmount,
+  timeBasedItemParams,
+}: Pick<Item, "startAmount" | "endAmount"> & {
+  timeBasedItemParams?: TimeBasedItemParams;
+}): BigNumber => {
+  const startAmountBn = BigNumber.from(startAmount);
+  const endAmountBn = BigNumber.from(endAmount);
+
+  if (!timeBasedItemParams) {
+    return startAmountBn.gt(endAmountBn) ? startAmountBn : endAmountBn;
+  }
+
+  const {
+    isConsiderationItem,
+    currentBlockTimestamp,
+    ascendingAmountTimestampBuffer,
+    startTime,
+    endTime,
+  } = timeBasedItemParams;
+
+  const duration = BigNumber.from(endTime).sub(startTime);
+  const isAscending = endAmountBn.gt(startAmount);
+  const adjustedBlockTimestamp = BigNumber.from(
+    isAscending
+      ? currentBlockTimestamp + ascendingAmountTimestampBuffer
+      : currentBlockTimestamp
+  );
+
+  if (adjustedBlockTimestamp.lt(startTime)) {
+    return startAmountBn;
+  }
+
+  const elapsed = (
+    adjustedBlockTimestamp.gt(endTime)
+      ? BigNumber.from(endTime)
+      : adjustedBlockTimestamp
+  ).sub(startTime);
+
+  const remaining = duration.sub(elapsed);
+
+  // Adjust amounts based on current time
+  // For offer items, we round down
+  // For consideration items, we round up
+  return startAmountBn
+    .mul(remaining)
+    .add(endAmountBn.mul(elapsed))
+    .add(isConsiderationItem ? duration.sub(1) : 0)
+    .div(duration);
+};
+
+export const getSummedTokenAndIdentifierAmounts = ({
+  items,
+  criterias,
+  timeBasedItemParams,
+}: {
+  items: Item[];
+  criterias: InputCriteria[];
+  timeBasedItemParams?: TimeBasedItemParams;
+}) => {
+  const itemToCriteria = getItemToCriteriaMap(items, criterias);
+
+  const tokenAndIdentifierToSummedAmount = items.reduce<
+    Record<string, Record<string, BigNumber>>
+  >((map, item) => {
+    const identifierOrCriteria =
+      itemToCriteria.get(item)?.identifier ?? item.identifierOrCriteria;
+
+    return {
+      ...map,
+      [item.token]: {
+        ...map[item.token],
+        // Being explicit about the undefined type as it's possible for it to be undefined at first iteration
+        [identifierOrCriteria]: (
+          (map[item.token]?.[identifierOrCriteria] as BigNumber | undefined) ??
+          BigNumber.from(0)
+        ).add(
+          getPresentItemAmount({
+            startAmount: item.startAmount,
+            endAmount: item.endAmount,
+            timeBasedItemParams,
+          })
+        ),
+      },
+    };
+  }, {});
+
+  return tokenAndIdentifierToSummedAmount;
+};
+
+/**
+ * Returns the maximum size of units possible for the order
+ * If any of the items on a partially fillable order specify a different "startAmount" and "endAmount
+ * (e.g. they are ascending-amount or descending-amount items), the fraction will be applied to both amounts
+ * prior to determining the current price. This ensures that cleanly divisible amounts can be chosen when
+ * constructing the order without a dependency on the time when the order is ultimately fulfilled.
+ */
+export const getMaximumSizeForOrder = ({
+  parameters: { offer, consideration },
+}: Order) => {
+  const allItems = [...offer, ...consideration];
+
+  const amounts = allItems.flatMap(({ startAmount, endAmount }) => [
+    startAmount,
+    endAmount,
+  ]);
+
+  return findGcd(amounts);
+};

package/src/utils/match.ts

@@ -0,0 +1,55 @@
+/** Giant TODO for match orders
+# Match orders
+
+- Format: list of fulfillments
+    - Each fulfillment represents a single transfer or “execution”
+    - Each fulfillment specifies an array of offer “components” corresponding to offer items to spend as well as an array of consideration “components” corresponding to consideration items to receive
+    - every offer component and consideration component contains an index of the order it is from as well as an index of the item in the respective offer or consideration array on that order
+    - the “from” address will be the offerer of whatever offer items are being spent
+    - the “to” address will be the recipient of whatever consideration items are being received
+- the “One rule” to follow for the whole set of fulfillments:
+    - All consideration items must be fully accounted for after adjusting for partial fills and ascending/descending amounts
+- the “Four rules” to follow for each distinct fulfillment:
+    1. you need at least one offer component and at least one consideration component for each fulfillment; otherwise you don’t know what the “from” or “to” address should be
+    2. the offer item corresponding to the first offer component has to match the consideration item corresponding to the first consideration component (with the exception of the amount); otherwise you’re not sending the item that the recipient is expecting
+    3. any additional offer items need to match the original offer items (with the exception of the amount) and the same *the offerer*; otherwise you’re composing different items or different origins.
+        1. This implies that ERC721 fulfillments will always have a single offer component (even if that corresponding offer item is present in multiple fulfillments, i.e. criteria-based partial fills)
+
+Example: Bulk purchase
+
+- Five distinct sellers create orders to sell ERC721 NFTs for ETH.
+    - single offer item on each order: the NFT
+    - two consideration items on each order: 10 ETH to the offerer and 1 ETH to OpenSea
+    - order index 1 through 5
+- To fulfill this, fulfiller creates a *sixth* order to buy all 5 NFTs for ETH
+    - single offer item: 55 ETH or `(10 + 1) * 5`
+    - five consideration items: all five NFTs
+    - order index 0 (by convention)
+- This order requires exactly 11 transfers or executions (assuming 5 distinct sellers), translating to 11 fulfillments:
+    - 5 transfers of 10 ETH each from order 0 offerer (i.e. fulfiller) to order 1-5 offerers
+        - These fulfillments will have a single offer component and single consideration component (offer component: order 0 index 0 and consideration component: orders 1-5 index 0)
+    - 5 transfers of 1 NFT each from order 1-5 offers to order 0 offerer (i.e. fulfiller)
+        - These fulfillments will have a single offer component and single fulfillment component (offer component: orders 1-5 index 0 and consideration component order 0 index 0-4)
+    - 1 transfer of 5 ETH from order 0 offerer (i.e. fulfiller) to OpenSea
+        - This fulfillment will have a single offer component mapping to order index 0 + item index 0, but *five* consideration components mapping to order index 1-5 + item index 1
+
+The algorithm (broad-strokes first pass)
+
+1. Take all the orders you want to fulfill and retrieve the latest amounts for those orders based on amount filled, amount *desired* to fill, and ascending/descending amounts (include sufficient buffer on those)
+2. “flatten” those orders into:
+    - all the offer items (and include the order index, item index, and offerer alongside the item)
+    - all the consideration items (and include the order index and item index alongside the item; the recipient is already on the consideration items)
+3. Aggregate those items by type + token + identifier + (offerer / recipient), summing up all the amounts (we do need to track the original amounts as well here)
+4. Quickly check to see if there are any aggregated offer items with the same type + token + identifier + offerer as an aggregated consideration item’s type + token + identifier + recipient (i.e. offerer == recipient) — if so, create a fulfillment for those and decrement both (no execution / transfer will be created for these fulfillments)
+5. Retrieve all approvals and balances for each aggregated offer item; increment / decrement them as we go and ensure they never go below zero
+6. Search for fulfillments that can already be performed before the fulfiller’s order has even been created; if any exist, generate those fulfillments first (the goal is to reduce the number of items on the fulfiller’s order).
+    - To generate a fulfillment, subtract whatever is lower between the aggregated offer and aggregated consideration it is being matched with from both and register the fulfillment.
+    - There will likely be some combination that optimizes for total number of transfers; see if these can be optimized.
+        - By way of example, say a fulfiller is accepting offers to sell multiple NFTs at once, and the aggregate fees owed to OpenSea are exactly 1 WETH and it so happens that one of the NFTS has an offer for exactly 1 WETH — that offerer should pay the fees for all the orders being fulfilled in a single transaction.
+    - Repeat this process until the fulfillments cannot be compressed any further.
+7. Then, create the mirror order with an offer item for each remaining (aggregated) consideration item and a consideration item for each remaining (aggregated) offer item; check for sufficient approval on each derived offer item
+8. Run the same sequence as from in step 6, but include the last order as well
+9. Ensure that all consideration items have been met!
+  */
+
+export {};

package/src/utils/merkletree.ts

@@ -0,0 +1,33 @@
+import { BigNumber } from "ethers";
+import { keccak256 } from "ethers/lib/utils";
+import MerkleTreeJS from "merkletreejs";
+
+const hashIdentifier = (identifier: string) =>
+  keccak256(
+    Buffer.from(
+      BigNumber.from(identifier).toHexString().slice(2).padStart(64, "0"),
+      "hex"
+    )
+  );
+
+/**
+ * Simple wrapper over the MerkleTree in merkletreejs.
+ * Handles hashing identifiers to be compatible with Seaport.
+ */
+export class MerkleTree {
+  tree: MerkleTreeJS;
+
+  constructor(identifiers: string[]) {
+    this.tree = new MerkleTreeJS(identifiers.map(hashIdentifier), keccak256, {
+      sort: true,
+    });
+  }
+
+  getProof(identifier: string): string[] {
+    return this.tree.getHexProof(hashIdentifier(identifier));
+  }
+
+  getRoot() {
+    return this.tree.getRoot().toString("hex") ? this.tree.getHexRoot() : "0";
+  }
+}

package/src/utils/order.ts

@@ -0,0 +1,288 @@
+import { BigNumber, BigNumberish, ethers } from "ethers";
+import { concat, keccak256, randomBytes, toUtf8Bytes } from "ethers/lib/utils";
+import { ItemType, ONE_HUNDRED_PERCENT_BP } from "../constants";
+import type {
+  ConsiderationItem,
+  CreateInputItem,
+  Fee,
+  Item,
+  OfferItem,
+  Order,
+  OrderParameters,
+} from "../types";
+import { getMaximumSizeForOrder, isCurrencyItem } from "./item";
+import { MerkleTree } from "./merkletree";
+
+const multiplyBasisPoints = (amount: BigNumberish, basisPoints: BigNumberish) =>
+  BigNumber.from(amount)
+    .mul(BigNumber.from(basisPoints))
+    .div(ONE_HUNDRED_PERCENT_BP);
+
+export const feeToConsiderationItem = ({
+  fee,
+  token,
+  baseAmount,
+  baseEndAmount = baseAmount,
+}: {
+  fee: Fee;
+  token: string;
+  baseAmount: BigNumberish;
+  baseEndAmount?: BigNumberish;
+}): ConsiderationItem => {
+  return {
+    itemType:
+      token === ethers.constants.AddressZero ? ItemType.NATIVE : ItemType.ERC20,
+    token,
+    identifierOrCriteria: "0",
+    startAmount: multiplyBasisPoints(baseAmount, fee.basisPoints).toString(),
+    endAmount: multiplyBasisPoints(baseEndAmount, fee.basisPoints).toString(),
+    recipient: fee.recipient,
+  };
+};
+
+export const deductFees = <T extends Item>(
+  items: T[],
+  fees?: readonly Fee[]
+): T[] => {
+  if (!fees) {
+    return items;
+  }
+
+  const totalBasisPoints = fees.reduce(
+    (accBasisPoints, fee) => accBasisPoints + fee.basisPoints,
+    0
+  );
+
+  return items.map((item) => ({
+    ...item,
+    startAmount: isCurrencyItem(item)
+      ? BigNumber.from(item.startAmount)
+          .sub(multiplyBasisPoints(item.startAmount, totalBasisPoints))
+          .toString()
+      : item.startAmount,
+    endAmount: isCurrencyItem(item)
+      ? BigNumber.from(item.endAmount)
+          .sub(multiplyBasisPoints(item.endAmount, totalBasisPoints))
+          .toString()
+      : item.endAmount,
+  }));
+};
+
+export const mapInputItemToOfferItem = (item: CreateInputItem): OfferItem => {
+  // Item is an NFT
+  if ("itemType" in item) {
+    // Convert this to a criteria based item
+    if ("identifiers" in item || "criteria" in item) {
+      const root =
+        "criteria" in item
+          ? item.criteria
+          : new MerkleTree(item.identifiers).getRoot();
+
+      return {
+        itemType:
+          item.itemType === ItemType.ERC721
+            ? ItemType.ERC721_WITH_CRITERIA
+            : ItemType.ERC1155_WITH_CRITERIA,
+        token: item.token,
+        identifierOrCriteria: root,
+        startAmount: item.amount ?? "1",
+        endAmount: item.endAmount ?? item.amount ?? "1",
+      };
+    }
+
+    if ("amount" in item || "endAmount" in item) {
+      return {
+        itemType: item.itemType,
+        token: item.token,
+        identifierOrCriteria: item.identifier,
+        // @ts-ignore
+        startAmount: item.amount,
+        // @ts-ignore
+        endAmount: item.endAmount ?? item.amount ?? "1",
+      };
+    }
+
+    return {
+      itemType: item.itemType,
+      token: item.token,
+      identifierOrCriteria: item.identifier,
+      startAmount: "1",
+      endAmount: "1",
+    };
+  }
+
+  // Item is a currency
+  return {
+    itemType:
+      item.token && item.token !== ethers.constants.AddressZero
+        ? ItemType.ERC20
+        : ItemType.NATIVE,
+    token: item.token ?? ethers.constants.AddressZero,
+    identifierOrCriteria: "0",
+    startAmount: item.amount,
+    endAmount: item.endAmount ?? item.amount,
+  };
+};
+
+export const areAllCurrenciesSame = ({
+  offer,
+  consideration,
+}: Pick<OrderParameters, "offer" | "consideration">) => {
+  const allItems = [...offer, ...consideration];
+  const currencies = allItems.filter(isCurrencyItem);
+
+  return currencies.every(
+    ({ itemType, token }) =>
+      itemType === currencies[0].itemType &&
+      token.toLowerCase() === currencies[0].token.toLowerCase()
+  );
+};
+
+export const totalItemsAmount = <T extends OfferItem>(items: T[]) => {
+  const initialValues = {
+    startAmount: BigNumber.from(0),
+    endAmount: BigNumber.from(0),
+  };
+
+  return items
+    .map(({ startAmount, endAmount }) => ({
+      startAmount,
+      endAmount,
+    }))
+    .reduce<typeof initialValues>(
+      (
+        { startAmount: totalStartAmount, endAmount: totalEndAmount },
+        { startAmount, endAmount }
+      ) => ({
+        startAmount: totalStartAmount.add(startAmount),
+        endAmount: totalEndAmount.add(endAmount),
+      }),
+      {
+        startAmount: BigNumber.from(0),
+        endAmount: BigNumber.from(0),
+      }
+    );
+};
+
+/**
+ * Maps order offer and consideration item amounts based on the order's filled status
+ * After applying the fraction, we can view this order as the "canonical" order for which we
+ * check approvals and balances
+ */
+export const mapOrderAmountsFromFilledStatus = (
+  order: Order,
+  { totalFilled, totalSize }: { totalFilled: BigNumber; totalSize: BigNumber }
+): Order => {
+  if (totalFilled.eq(0) || totalSize.eq(0)) {
+    return order;
+  }
+
+  // i.e if totalFilled is 3 and totalSize is 4, there are 1 / 4 order amounts left to fill.
+  const basisPoints = totalSize
+    .sub(totalFilled)
+    .mul(ONE_HUNDRED_PERCENT_BP)
+    .div(totalSize);
+
+  return {
+    parameters: {
+      ...order.parameters,
+      offer: order.parameters.offer.map((item) => ({
+        ...item,
+        startAmount: multiplyBasisPoints(
+          item.startAmount,
+          basisPoints
+        ).toString(),
+        endAmount: multiplyBasisPoints(item.endAmount, basisPoints).toString(),
+      })),
+      consideration: order.parameters.consideration.map((item) => ({
+        ...item,
+        startAmount: multiplyBasisPoints(
+          item.startAmount,
+          basisPoints
+        ).toString(),
+        endAmount: multiplyBasisPoints(item.endAmount, basisPoints).toString(),
+      })),
+    },
+    signature: order.signature,
+  };
+};
+
+const multiplyDivision = (
+  amount: BigNumberish,
+  numerator: BigNumberish,
+  denominator: BigNumberish
+) => BigNumber.from(amount).mul(BigNumber.from(numerator)).div(denominator);
+
+/**
+ * Maps order offer and consideration item amounts based on the units needed to fulfill
+ * After applying the fraction, we can view this order as the "canonical" order for which we
+ * check approvals and balances
+ * Returns the numerator and denominator as well, converting this to an AdvancedOrder
+ */
+export const mapOrderAmountsFromUnitsToFill = (
+  order: Order,
+  {
+    unitsToFill,
+    totalSize,
+  }: { unitsToFill: BigNumberish; totalSize: BigNumber }
+): Order => {
+  const unitsToFillBn = BigNumber.from(unitsToFill);
+
+  if (unitsToFillBn.lte(0)) {
+    throw new Error("Units to fill must be greater than 1");
+  }
+
+  const maxUnits = getMaximumSizeForOrder(order);
+
+  if (totalSize.eq(0)) {
+    totalSize = maxUnits;
+  }
+
+  return {
+    parameters: {
+      ...order.parameters,
+      offer: order.parameters.offer.map((item) => ({
+        ...item,
+        startAmount: multiplyDivision(
+          item.startAmount,
+          unitsToFillBn,
+          totalSize
+        ).toString(),
+        endAmount: multiplyDivision(
+          item.endAmount,
+          unitsToFillBn,
+          totalSize
+        ).toString(),
+      })),
+      consideration: order.parameters.consideration.map((item) => ({
+        ...item,
+        startAmount: multiplyDivision(
+          item.startAmount,
+          unitsToFillBn,
+          totalSize
+        ).toString(),
+        endAmount: multiplyDivision(
+          item.endAmount,
+          unitsToFillBn,
+          totalSize
+        ).toString(),
+      })),
+    },
+    signature: order.signature,
+  };
+};
+
+export const generateRandomSalt = (domain?: string) => {
+  if (domain) {
+    return `0x${Buffer.from(
+      concat([
+        keccak256(toUtf8Bytes(domain)).slice(0, 10),
+        Uint8Array.from(Array(20).fill(0)),
+        randomBytes(8),
+      ])
+    ).toString("hex")}`;
+  }
+  return `0x${Buffer.from(randomBytes(8)).toString("hex").padStart(64, "0")}`;
+};
+
+export const shouldUseMatchForFulfill = () => true;

package/src/utils/usecase.ts

@@ -0,0 +1,124 @@
+import { CallOverrides, Contract, Overrides, PayableOverrides } from "ethers";
+import { keccak256, toUtf8Bytes } from "ethers/lib/utils";
+
+import {
+  CreateBulkOrdersAction,
+  CreateOrderAction,
+  ExchangeAction,
+  OrderUseCase,
+  TransactionMethods,
+  ContractMethodReturnType,
+} from "../types";
+
+export const executeAllActions = async <
+  T extends CreateOrderAction | CreateBulkOrdersAction | ExchangeAction
+>(
+  actions: OrderUseCase<T>["actions"]
+) => {
+  for (let i = 0; i < actions.length - 1; i++) {
+    const action = actions[i];
+    if (action.type === "approval") {
+      const tx = await action.transactionMethods.transact();
+      await tx.wait();
+    }
+  }
+
+  const finalAction = actions[actions.length - 1] as T;
+
+  switch (finalAction.type) {
+    case "create":
+      return finalAction.createOrder();
+    case "createBulk":
+      return finalAction.createBulkOrders();
+    default:
+      return finalAction.transactionMethods.transact();
+  }
+};
+
+const instanceOfOverrides = <
+  T extends Overrides | PayableOverrides | CallOverrides
+>(
+  obj: Object | undefined
+): obj is T => {
+  const validKeys = [
+    "gasLimit",
+    "gasPrice",
+    "maxFeePerGas",
+    "maxPriorityFeePerGas",
+    "nonce",
+    "type",
+    "accessList",
+    "customData",
+    "ccipReadEnabled",
+    "value",
+    "blockTag",
+    "CallOverrides",
+  ];
+
+  return (
+    obj === undefined ||
+    Object.keys(obj).every((key) => validKeys.includes(key))
+  );
+};
+
+export const getTransactionMethods = <
+  T extends Contract,
+  U extends keyof T["functions"]
+>(
+  contract: T,
+  method: U,
+  args: Parameters<T["functions"][U]>,
+  domain?: string
+): TransactionMethods<ContractMethodReturnType<T, U>> => {
+  const lastArg = args[args.length - 1];
+
+  let initialOverrides: Overrides;
+
+  if (instanceOfOverrides(lastArg)) {
+    initialOverrides = lastArg;
+    args.pop();
+  }
+
+  const buildTransaction = async (overrides?: Overrides) => {
+    const mergedOverrides = { ...initialOverrides, ...overrides };
+    const populatedTransaction = await contract.populateTransaction[
+      method as string
+    ](...[...args, mergedOverrides]);
+
+    if (domain) {
+      const tag = getTagFromDomain(domain);
+      populatedTransaction.data = populatedTransaction.data + tag;
+    }
+
+    return populatedTransaction;
+  };
+
+  return {
+    callStatic: (overrides?: Overrides) => {
+      const mergedOverrides = { ...initialOverrides, ...overrides };
+
+      return contract.callStatic[method as string](
+        ...[...args, mergedOverrides]
+      );
+    },
+    estimateGas: (overrides?: Overrides) => {
+      const mergedOverrides = { ...initialOverrides, ...overrides };
+
+      return contract.estimateGas[method as string](
+        ...[...args, mergedOverrides]
+      );
+    },
+    transact: async (overrides?: Overrides) => {
+      const mergedOverrides = { ...initialOverrides, ...overrides };
+
+      const data = await buildTransaction(mergedOverrides);
+
+      return contract.signer.sendTransaction(data);
+    },
+    buildTransaction,
+  };
+};
+
+export const getTagFromDomain = (domain: string) => {
+  return keccak256(toUtf8Bytes(domain)).slice(2, 10);
+};