Add english auctions (#1160)

* add english auctions

* move decodeTokenIds tests to misc.spec.ts

* improve error

* update docs, remove more unused fields

Author: ryanio

README.md

@@ -201,7 +201,7 @@ See [Listening to Events](#listening-to-events) to respond to the setup transact
 
 English Auctions are auctions that start at a small amount (we recommend even doing 0!) and increase with every bid. At expiration time, the item sells to the highest bidder.
 
-To create an English Auction, create a listing that waits for the highest bid by setting `waitForHighestBid` to `true`:
+To create an English Auction set `englishAuction` to `true`:
 
 ```typescript
 // Create an auction to receive Wrapped Ether (WETH). See note below.
@@ -218,7 +218,7 @@ const order = await openseaSDK.createSellOrder({
   startAmount,
   expirationTime,
   paymentTokenAddress,
-  waitForHighestBid: true,
+  englishAuction: true,
 });
 ```
 
@@ -256,14 +256,12 @@ The available API filters for the orders endpoint is documented in the `OrdersQu
 ```TypeScript
 /**
    * Attrs used by orderbook to make queries easier
-   * More to come soon!
    */
   side: "bid" | "ask", // "bid" for buy orders, "ask" for sell orders
   protocol?: "seaport"; // Protocol of the order (more options may be added in future)
   maker?: string, // Address of the order's creator
   taker?: string, // The null address if anyone is allowed to take the order
   owner?: string, // Address of owner of the order's item
-  sale_kind?: SaleKind, // 0 for fixed-price, 1 for Dutch auctions
   assetContractAddress?: string, // Contract address for order's item
   paymentTokenAddress?: string; // Contract address for order's payment token
   tokenId?: number | string,

developerDocs/getting-started.md

@@ -131,7 +131,7 @@ See [Listening to Events](#listening-to-events) to respond to the setup transact
 
 English Auctions are auctions that start at a small amount (we recommend even doing 0!) and increase with every bid. At expiration time, the item sells to the highest bidder.
 
-To create an English Auction, create a listing that waits for the highest bid by setting `waitForHighestBid` to `true`:
+To create an English Auction set `englishAuction` to `true`:
 
 ```typescript
 // Create an auction to receive Wrapped Ether (WETH). See note below.
@@ -148,7 +148,7 @@ const auction = await openseaSDK.createSellOrder({
   startAmount,
   expirationTime,
   paymentTokenAddress,
-  waitForHighestBid: true,
+  englishAuction: true,
 });
 ```
 
@@ -186,14 +186,12 @@ The available API filters for the orders endpoint is documented in the `OrdersQu
 ```TypeScript
 /**
    * Attrs used by orderbook to make queries easier
-   * More to come soon!
    */
   side: "bid" | "ask", // "bid" for buy orders, "ask" for sell orders
   protocol?: "seaport"; // Protocol of the order (more options may be added in future)
   maker?: string, // Address of the order's creator
   taker?: string, // The null address if anyone is allowed to take the order
   owner?: string, // Address of owner of the order's item
-  sale_kind?: SaleKind, // 0 for fixed-price, 1 for Dutch auctions
   assetContractAddress?: string, // Contract address for order's item
   paymentTokenAddress?: string; // Contract address for order's payment token
   tokenId?: number | string,

src/constants.ts

@@ -8,6 +8,8 @@ export const API_BASE_TESTNET = "https://testnets-api.opensea.io";
 export const API_V1_PATH = `/api/v1`;
 
 export const DEFAULT_ZONE = ethers.constants.AddressZero;
+export const ENGLISH_AUCTION_ZONE =
+  "0x110b2b128a9ed1be5ef3232d8e4e41640df5c2cd";
 
 // Ignore eslint no-unused-modules for below to keep backward compatibility
 // in case a downstream user was already using these imports directly.

src/sdk.ts

@@ -19,7 +19,11 @@ import {
 import { parseEther } from "ethers/lib/utils";
 import { OpenSeaAPI } from "./api/api";
 import { Offer, NFT } from "./api/types";
-import { INVERSE_BASIS_POINT, DEFAULT_ZONE } from "./constants";
+import {
+  INVERSE_BASIS_POINT,
+  DEFAULT_ZONE,
+  ENGLISH_AUCTION_ZONE,
+} from "./constants";
 import {
   constructPrivateListingCounterOrder,
   getPrivateListingConsiderations,
@@ -429,6 +433,7 @@ export class OpenSeaSDK {
    * @param options.expirationTime Expiration time for the order, in UTC seconds.
    * @param options.paymentTokenAddress ERC20 address for the payment token in the order. If unspecified, defaults to ETH
    * @param options.buyerAddress Optional address that's allowed to purchase this item. If specified, no other address will be able to take the order, unless its value is the null address.
+   * @param options.englishAuction If true, the order will be listed as an English auction.
    * @returns The {@link OrderV2} that was created.
    *
    * @throws Error if the asset does not contain a token id.
@@ -448,6 +453,7 @@ export class OpenSeaSDK {
     expirationTime,
     paymentTokenAddress = ethers.constants.AddressZero,
     buyerAddress,
+    englishAuction,
   }: {
     asset: Asset;
     accountAddress: string;
@@ -460,6 +466,7 @@ export class OpenSeaSDK {
     expirationTime?: number;
     paymentTokenAddress?: string;
     buyerAddress?: string;
+    englishAuction?: boolean;
   }): Promise<OrderV2> {
     await this._requireAccountIsAvailable(accountAddress);
 
@@ -477,6 +484,12 @@ export class OpenSeaSDK {
       [BigNumber.from(quantity ?? 1)],
     );
 
+    if (englishAuction && paymentTokenAddress == ethers.constants.AddressZero) {
+      throw new Error(
+        `English auctions must use wrapped ETH or an ERC-20 token.`,
+      );
+    }
+
     const { basePrice, endPrice } = await this._getPriceParameters(
       OrderSide.Sell,
       paymentTokenAddress,
@@ -514,11 +527,11 @@ export class OpenSeaSDK {
         endTime:
           expirationTime?.toString() ??
           getMaxOrderExpirationTimestamp().toString(),
-        zone: DEFAULT_ZONE,
+        zone: englishAuction ? ENGLISH_AUCTION_ZONE : DEFAULT_ZONE,
         domain,
         salt: BigNumber.from(salt ?? 0).toString(),
-        restrictedByZone: false,
-        allowPartialFills: true,
+        restrictedByZone: englishAuction ? true : false,
+        allowPartialFills: englishAuction ? false : true,
       },
       accountAddress,
     );
@@ -988,17 +1001,13 @@ export class OpenSeaSDK {
    * @param expirationTime When the auction expires, or 0 if never.
    * @param startAmount The base value for the order, in the token's main units (e.g. ETH instead of wei)
    * @param endAmount The end value for the order, in the token's main units (e.g. ETH instead of wei). If unspecified, the order's `extra` attribute will be 0
-   * @param waitingForBestCounterOrder
-   * @param englishAuctionReservePrice
    */
   private async _getPriceParameters(
     orderSide: OrderSide,
     tokenAddress: string,
     expirationTime: BigNumberish,
     startAmount: BigNumberish,
     endAmount?: BigNumberish,
-    waitingForBestCounterOrder = false,
-    englishAuctionReservePrice?: BigNumberish,
   ) {
     const isEther = tokenAddress === ethers.constants.AddressZero;
     let paymentToken: OpenSeaFungibleToken | undefined;
@@ -1025,9 +1034,6 @@ export class OpenSeaSDK {
     const basePrice = startAmountWei;
     const endPrice = endAmountWei;
     const extra = priceDiffWei;
-    const reservePrice = englishAuctionReservePrice
-      ? ethers.utils.parseUnits(startAmount.toString(), decimals)
-      : undefined;
 
     // Validation
     if (startAmount == null || startAmountWei.lt(0)) {
@@ -1051,11 +1057,6 @@ export class OpenSeaSDK {
         );
       }
     }
-    if (isEther && waitingForBestCounterOrder) {
-      throw new Error(
-        `English auctions must use wrapped ETH or an ERC-20 token.`,
-      );
-    }
     if (isEther && orderSide === OrderSide.Buy) {
       throw new Error(`Offers must use wrapped ETH or an ERC-20 token.`);
     }
@@ -1069,18 +1070,7 @@ export class OpenSeaSDK {
         "Expiration time must be set if order will change in price.",
       );
     }
-    const reservePriceIsDefinedAndNonZero =
-      reservePrice && !reservePrice.isZero();
-    if (reservePriceIsDefinedAndNonZero && !waitingForBestCounterOrder) {
-      throw new Error("Reserve prices may only be set on English auctions.");
-    }
-    if (reservePriceIsDefinedAndNonZero && reservePrice?.lt(startAmountWei)) {
-      throw new Error(
-        "Reserve price must be greater than or equal to the start amount.",
-      );
-    }
-
-    return { basePrice, extra, paymentToken, reservePrice, endPrice };
+    return { basePrice, extra, paymentToken, endPrice };
   }
 
   private _dispatch(event: EventType, data: EventData) {

src/types.ts

@@ -164,14 +164,6 @@ export enum FeeMethod {
   SplitFee = 1,
 }
 
-/**
- * Type of sale.
- */
-export enum SaleKind {
-  FixedPrice = 0,
-  DutchAuction = 1,
-}
-
 /**
  * Types of asset contracts
  * Given by the asset_contract_type in the OpenSea API
@@ -675,13 +667,6 @@ export type ExchangeMetadata =
   | ExchangeMetadataForAsset
   | ExchangeMetadataForBundle;
 
-export enum HowToCall {
-  Call = 0,
-  DelegateCall = 1,
-  StaticCall = 2,
-  Create = 3,
-}
-
 export interface UnsignedOrder {
   hash?: string;
   exchange: string;
@@ -706,15 +691,8 @@ export interface UnsignedOrder {
 
   feeMethod: FeeMethod;
   side: OrderSide;
-  saleKind: SaleKind;
-  howToCall: HowToCall;
   quantity: BigNumber;
 
-  // OpenSea-specific
-  makerReferrerFee: BigNumber;
-  waitingForBestCounterOrder: boolean;
-  englishAuctionReservePrice?: BigNumber;
-
   metadata: ExchangeMetadata;
 }
 
@@ -741,7 +719,6 @@ export interface Order extends UnsignedOrder, Partial<ECSignature> {
   markedInvalid?: boolean;
   asset?: OpenSeaAsset;
   assetBundle?: OpenSeaAssetBundle;
-  nonce?: number;
 }
 
 /**
@@ -761,9 +738,7 @@ export interface OrderJSON extends Partial<ECSignature> {
   feeRecipient: string;
   feeMethod: number;
   side: number;
-  saleKind: number;
   target: string;
-  howToCall: number;
   calldata: string;
   replacementPattern: string;
   staticTarget: string;
@@ -775,15 +750,11 @@ export interface OrderJSON extends Partial<ECSignature> {
   expirationTime: number | string;
   salt: string;
 
-  makerReferrerFee: string;
   quantity: string;
-  englishAuctionReservePrice: string | undefined;
 
   // createdTime is undefined when order hasn't been posted yet
   createdTime?: number | string;
   metadata: ExchangeMetadata;
-
-  nonce?: number;
 }
 
 /**

test/integration/postOrder.spec.ts

@@ -10,6 +10,7 @@ import {
   sdkPolygon,
   walletAddress,
 } from "./setup";
+import { ENGLISH_AUCTION_ZONE } from "../../src/constants";
 import { getWETHAddress } from "../../src/utils";
 import { OFFER_AMOUNT } from "../utils/constants";
 import { expectValidOrder } from "../utils/utils";
@@ -57,6 +58,35 @@ suite("SDK: order posting", () => {
     expectValidOrder(order);
   });
 
+  test("Post Auction Sell Order - Mainnet", async function () {
+    if (!TOKEN_ADDRESS_MAINNET || !TOKEN_ID_MAINNET) {
+      this.skip();
+    }
+    const sellOrder = {
+      accountAddress: walletAddress,
+      startAmount: LISTING_AMOUNT,
+      asset: {
+        tokenAddress: TOKEN_ADDRESS_MAINNET as string,
+        tokenId: TOKEN_ID_MAINNET as string,
+      },
+      englishAuction: true,
+    };
+    try {
+      const order = await sdk.createSellOrder(sellOrder);
+      expectValidOrder(order);
+      expect(order.protocolData.parameters.zone.toLowerCase()).to.equal(
+        ENGLISH_AUCTION_ZONE,
+      );
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } catch (error: any) {
+      expect(
+        error.message.includes(
+          "There is already a live auction for this item. You can only have one auction live at any time.",
+        ),
+      );
+    }
+  });
+
   test("Post Sell Order - Polygon", async function () {
     if (!TOKEN_ADDRESS_POLYGON || !TOKEN_ID_POLYGON) {
       this.skip();