@opensea/sdk 11.7.0 → 11.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/README.md +1 -1
  2. package/lib/abi/abis.d.ts +16 -0
  3. package/lib/abi/abis.js +13 -1
  4. package/lib/abi/abis.js.map +1 -1
  5. package/lib/api/accounts.d.ts +6 -1
  6. package/lib/api/accounts.js +7 -0
  7. package/lib/api/accounts.js.map +1 -1
  8. package/lib/api/api.d.ts +10 -4
  9. package/lib/api/api.js +11 -3
  10. package/lib/api/api.js.map +1 -1
  11. package/lib/api/apiPaths.d.ts +1 -0
  12. package/lib/api/apiPaths.js +6 -2
  13. package/lib/api/apiPaths.js.map +1 -1
  14. package/lib/api/types.d.ts +26 -1
  15. package/lib/api/types.js.map +1 -1
  16. package/lib/api/walletAuth.d.ts +37 -0
  17. package/lib/api/walletAuth.js +40 -5
  18. package/lib/api/walletAuth.js.map +1 -1
  19. package/lib/constants.d.ts +6 -0
  20. package/lib/constants.js +7 -1
  21. package/lib/constants.js.map +1 -1
  22. package/lib/orders/erc20Fulfillment.d.ts +41 -0
  23. package/lib/orders/erc20Fulfillment.js +190 -0
  24. package/lib/orders/erc20Fulfillment.js.map +1 -0
  25. package/lib/orders/orderUseCase.d.ts +18 -0
  26. package/lib/orders/orderUseCase.js +29 -0
  27. package/lib/orders/orderUseCase.js.map +1 -0
  28. package/lib/sdk/base.d.ts +32 -7
  29. package/lib/sdk/base.js +19 -7
  30. package/lib/sdk/base.js.map +1 -1
  31. package/lib/sdk/cancellation.d.ts +2 -1
  32. package/lib/sdk/cancellation.js +2 -0
  33. package/lib/sdk/cancellation.js.map +1 -1
  34. package/lib/sdk/fulfillment.d.ts +57 -3
  35. package/lib/sdk/fulfillment.js +147 -4
  36. package/lib/sdk/fulfillment.js.map +1 -1
  37. package/lib/sdk/orders.d.ts +16 -3
  38. package/lib/sdk/orders.js +27 -13
  39. package/lib/sdk/orders.js.map +1 -1
  40. package/lib/types.d.ts +2 -1
  41. package/lib/types.js +1 -0
  42. package/lib/types.js.map +1 -1
  43. package/lib/utils/chain.js +6 -0
  44. package/lib/utils/chain.js.map +1 -1
  45. package/lib/utils/chainIds.generated.js +1 -0
  46. package/lib/utils/chainIds.generated.js.map +1 -1
  47. package/package.json +3 -3
  48. package/src/abi/abis.ts +13 -0
  49. package/src/api/accounts.ts +14 -0
  50. package/src/api/api.ts +15 -3
  51. package/src/api/apiPaths.ts +4 -0
  52. package/src/api/types.ts +38 -0
  53. package/src/api/walletAuth.ts +53 -0
  54. package/src/constants.ts +8 -0
  55. package/src/orders/erc20Fulfillment.ts +218 -0
  56. package/src/orders/orderUseCase.ts +34 -0
  57. package/src/sdk/base.ts +20 -6
  58. package/src/sdk/cancellation.ts +4 -1
  59. package/src/sdk/fulfillment.ts +188 -6
  60. package/src/sdk/orders.ts +27 -15
  61. package/src/types.ts +1 -0
  62. package/src/utils/chain.ts +10 -0
  63. package/src/utils/chainIds.generated.ts +1 -0
@@ -0,0 +1,218 @@
1
+ /**
2
+ * Helpers for ERC20-denominated listing fulfillment.
3
+ *
4
+ * When a listing is priced in an ERC20 token instead of the native currency,
5
+ * `transaction.value` is `0` and Seaport pulls the payment from the buyer with
6
+ * `transferFrom`. That only works if the buyer has already approved the spender,
7
+ * so the fulfillment reverts with a bare "execution reverted" when they haven't.
8
+ * These helpers read the payment token and amount out of the API's fulfillment
9
+ * input data so the SDK can check the allowance before spending gas.
10
+ */
11
+
12
+ /** Seaport `ItemType` for an ERC20 item. 0 is native, and anything >= 2 is an NFT. */
13
+ const ITEM_TYPE_ERC20 = 1
14
+
15
+ /**
16
+ * Seaport `BasicOrderRouteType` values where the fulfiller pays with an ERC20
17
+ * token: `ERC20_TO_ERC721` (2) and `ERC20_TO_ERC1155` (3). Routes 0-1 are
18
+ * native-priced listings; routes 4-5 are offer fulfillments, where the fulfiller
19
+ * provides the NFT and the ERC20 comes from the offerer instead.
20
+ */
21
+ const ERC20_PAYMENT_ROUTES = new Set([2, 3])
22
+
23
+ /** A `bytes32(0)` conduit key means Seaport transfers directly, with no conduit. */
24
+ export const ZERO_CONDUIT_KEY = `0x${"0".repeat(64)}`
25
+
26
+ export type Erc20Payment = {
27
+ /** Payment token contract address. */
28
+ token: string
29
+ /** Total amount the fulfiller owes, in the token's base units. */
30
+ amount: bigint
31
+ }
32
+
33
+ type ConsiderationItemLike = {
34
+ itemType?: unknown
35
+ token?: unknown
36
+ startAmount?: unknown
37
+ }
38
+
39
+ /**
40
+ * Coerce a value an RPC adapter may return as a bigint, a decimal string, or a
41
+ * number into a bigint. Returns null for anything else.
42
+ */
43
+ export function toBigInt(value: unknown): bigint | null {
44
+ if (typeof value === "bigint") {
45
+ return value
46
+ }
47
+ if (typeof value === "number" && Number.isInteger(value)) {
48
+ return BigInt(value)
49
+ }
50
+ if (typeof value === "string" && /^\d+$/.test(value.trim())) {
51
+ return BigInt(value.trim())
52
+ }
53
+ return null
54
+ }
55
+
56
+ function toNumber(value: unknown): number | null {
57
+ const asBigInt = toBigInt(value)
58
+ return asBigInt === null ? null : Number(asBigInt)
59
+ }
60
+
61
+ function isRecord(value: unknown): value is Record<string, unknown> {
62
+ return typeof value === "object" && value !== null
63
+ }
64
+
65
+ /**
66
+ * Sum the ERC20 consideration items of a listing, which together are what the
67
+ * fulfiller pays (seller proceeds plus marketplace and creator fees).
68
+ *
69
+ * Returns null unless every consideration item is the same ERC20 token. A native
70
+ * item means the listing is native-priced, an NFT item means this is an offer
71
+ * fulfillment rather than a purchase, and mixed tokens are not something we can
72
+ * express as a single allowance.
73
+ */
74
+ function sumErc20Consideration(consideration: unknown): Erc20Payment | null {
75
+ if (!Array.isArray(consideration) || consideration.length === 0) {
76
+ return null
77
+ }
78
+
79
+ let token: string | null = null
80
+ let total = 0n
81
+
82
+ for (const rawItem of consideration as ConsiderationItemLike[]) {
83
+ if (!isRecord(rawItem)) {
84
+ return null
85
+ }
86
+ const itemType = toNumber(rawItem.itemType)
87
+ if (itemType !== ITEM_TYPE_ERC20) {
88
+ // Native payment, an NFT in the consideration, or an unreadable item type.
89
+ return null
90
+ }
91
+ const itemToken = rawItem.token
92
+ if (typeof itemToken !== "string") {
93
+ return null
94
+ }
95
+ if (token === null) {
96
+ token = itemToken
97
+ } else if (token.toLowerCase() !== itemToken.toLowerCase()) {
98
+ return null
99
+ }
100
+ const amount = toBigInt(rawItem.startAmount)
101
+ if (amount === null) {
102
+ return null
103
+ }
104
+ total += amount
105
+ }
106
+
107
+ return token === null ? null : { token, amount: total }
108
+ }
109
+
110
+ /**
111
+ * Sum the ERC20 payment for a basic order, whose consideration is flattened into
112
+ * `considerationAmount` plus one entry per `additionalRecipients` fee.
113
+ */
114
+ function basicOrderErc20Payment(
115
+ basicOrderParameters: unknown,
116
+ ): Erc20Payment | null {
117
+ if (!isRecord(basicOrderParameters)) {
118
+ return null
119
+ }
120
+
121
+ const basicOrderType = toNumber(basicOrderParameters.basicOrderType)
122
+ if (basicOrderType === null) {
123
+ return null
124
+ }
125
+ // Four order types share each route: full/partial x open/restricted.
126
+ if (!ERC20_PAYMENT_ROUTES.has(Math.floor(basicOrderType / 4))) {
127
+ return null
128
+ }
129
+
130
+ const token = basicOrderParameters.considerationToken
131
+ if (typeof token !== "string") {
132
+ return null
133
+ }
134
+
135
+ let total = toBigInt(basicOrderParameters.considerationAmount)
136
+ if (total === null) {
137
+ return null
138
+ }
139
+
140
+ const additionalRecipients = basicOrderParameters.additionalRecipients
141
+ if (additionalRecipients !== undefined) {
142
+ if (!Array.isArray(additionalRecipients)) {
143
+ return null
144
+ }
145
+ for (const recipient of additionalRecipients) {
146
+ if (!isRecord(recipient)) {
147
+ return null
148
+ }
149
+ const amount = toBigInt(recipient.amount)
150
+ if (amount === null) {
151
+ return null
152
+ }
153
+ total += amount
154
+ }
155
+ }
156
+
157
+ return { token, amount: total }
158
+ }
159
+
160
+ /**
161
+ * Read the ERC20 payment a fulfiller owes from the `inputData` of an OpenSea
162
+ * fulfillment response.
163
+ *
164
+ * Returns null whenever the payment is not a single ERC20 amount we can read
165
+ * with confidence, including native-priced listings and offer fulfillments.
166
+ * Callers must treat null as "no preflight possible" and submit the transaction
167
+ * unchanged, so an unfamiliar response shape can never block a working purchase.
168
+ */
169
+ export function getErc20Payment(inputData: unknown): Erc20Payment | null {
170
+ if (!isRecord(inputData)) {
171
+ return null
172
+ }
173
+
174
+ if ("basicOrderParameters" in inputData) {
175
+ return basicOrderErc20Payment(inputData.basicOrderParameters)
176
+ }
177
+
178
+ const order = isRecord(inputData.advancedOrder)
179
+ ? inputData.advancedOrder
180
+ : isRecord(inputData.order)
181
+ ? inputData.order
182
+ : null
183
+ if (!order || !isRecord(order.parameters)) {
184
+ return null
185
+ }
186
+
187
+ return sumErc20Consideration(order.parameters.consideration)
188
+ }
189
+
190
+ /**
191
+ * Read the fulfiller's conduit key, which decides who the buyer must approve:
192
+ * the resolved conduit for a non-zero key, or Seaport itself for `bytes32(0)`.
193
+ * Returns null when the response does not carry one.
194
+ */
195
+ export function getFulfillerConduitKey(inputData: unknown): string | null {
196
+ if (!isRecord(inputData)) {
197
+ return null
198
+ }
199
+ const direct = inputData.fulfillerConduitKey
200
+ if (typeof direct === "string") {
201
+ return direct
202
+ }
203
+ if (isRecord(inputData.basicOrderParameters)) {
204
+ const fromBasicOrder = inputData.basicOrderParameters.fulfillerConduitKey
205
+ if (typeof fromBasicOrder === "string") {
206
+ return fromBasicOrder
207
+ }
208
+ }
209
+ return null
210
+ }
211
+
212
+ /** Whether a conduit key means "transfer directly from Seaport, no conduit". */
213
+ export function isZeroConduitKey(conduitKey: string | null): boolean {
214
+ if (!conduitKey) {
215
+ return true
216
+ }
217
+ return conduitKey.toLowerCase() === ZERO_CONDUIT_KEY
218
+ }
@@ -0,0 +1,34 @@
1
+ import type {
2
+ CreateOrderAction,
3
+ OrderComponents,
4
+ OrderUseCase,
5
+ } from "@opensea/seaport-js/lib/types"
6
+
7
+ /**
8
+ * Run the approval transactions from a seaport-js create-order use case and
9
+ * return the resulting order components, without asking the wallet to sign.
10
+ *
11
+ * `executeAllActions()` also requests an EIP-712 signature. Callers that
12
+ * validate the order onchain have no use for one, since Seaport's `validate()`
13
+ * takes the transaction sender as proof the offerer approved the order.
14
+ * Requesting it anyway costs an extra wallet prompt for a signature that is
15
+ * discarded, and shuts out contract accounts that cannot produce an offchain
16
+ * signature at all.
17
+ *
18
+ * @param useCase The use case returned by `seaport.createOrder`
19
+ * @returns Order components ready for onchain validation
20
+ *
21
+ * @throws Error if the use case has no create-order action.
22
+ */
23
+ export const executeApprovalsAndGetOrderComponents = async (
24
+ useCase: OrderUseCase<CreateOrderAction>,
25
+ ): Promise<OrderComponents> => {
26
+ await useCase.executeApprovals()
27
+
28
+ const createAction = useCase.actions.find(action => action.type === "create")
29
+ if (!createAction) {
30
+ throw new Error("Seaport create-order use case has no create action")
31
+ }
32
+
33
+ return createAction.orderComponents
34
+ }
package/src/sdk/base.ts CHANGED
@@ -111,7 +111,7 @@ export class BaseOpenSeaSDK {
111
111
  /**
112
112
  * Request a free-tier OpenSea API key without authentication. The returned
113
113
  * key can be passed as `apiKey` into the SDK constructor to bootstrap usage.
114
- * Rate limited to 3 keys per hour per IP; keys expire after 30 days.
114
+ * Keys expire after 7 days.
115
115
  *
116
116
  * @example
117
117
  * ```ts
@@ -412,18 +412,26 @@ export class BaseOpenSeaSDK {
412
412
  return this._fulfillmentManager.approveOrder(order, domain)
413
413
  }
414
414
 
415
- /** Validates an order onchain using Seaport's validate() method. */
415
+ /**
416
+ * Validates an order onchain using Seaport's validate() method, approving it
417
+ * without an offchain signature. Does not post the order to OpenSea.
418
+ */
416
419
  public async validateOrderOnchain(
417
420
  orderComponents: OrderComponents,
418
421
  accountAddress: string,
422
+ protocolAddress?: string,
419
423
  ) {
420
424
  return this._fulfillmentManager.validateOrderOnchain(
421
425
  orderComponents,
422
426
  accountAddress,
427
+ protocolAddress,
423
428
  )
424
429
  }
425
430
 
426
- /** Create and validate a listing onchain. */
431
+ /**
432
+ * Create a listing and validate it onchain instead of signing it offchain.
433
+ * Does not post the listing to OpenSea. Returns a transaction hash.
434
+ */
427
435
  public async createListingAndValidateOnchain(options: {
428
436
  asset: AssetWithTokenId
429
437
  accountAddress: string
@@ -440,7 +448,10 @@ export class BaseOpenSeaSDK {
440
448
  return this._fulfillmentManager.createListingAndValidateOnchain(options)
441
449
  }
442
450
 
443
- /** Create and validate an offer onchain. */
451
+ /**
452
+ * Create an offer and validate it onchain instead of signing it offchain.
453
+ * Does not post the offer to OpenSea. Returns a transaction hash.
454
+ */
444
455
  public async createOfferAndValidateOnchain(options: {
445
456
  asset: AssetWithTokenId
446
457
  accountAddress: string
@@ -478,14 +489,17 @@ export class BaseOpenSeaSDK {
478
489
  return this._cancellationManager.cancelOrders(options)
479
490
  }
480
491
 
481
- /** Cancel an order onchain, preventing it from ever being fulfilled. */
492
+ /**
493
+ * Cancel an order onchain, preventing it from ever being fulfilled.
494
+ * @returns Transaction hash of the cancellation.
495
+ */
482
496
  public async cancelOrder(options: {
483
497
  order?: OrderV2
484
498
  orderHash?: string
485
499
  accountAddress: string
486
500
  protocolAddress?: string
487
501
  domain?: string
488
- }) {
502
+ }): Promise<string> {
489
503
  return this._cancellationManager.cancelOrder(options)
490
504
  }
491
505
 
@@ -27,6 +27,7 @@ export class CancellationManager {
27
27
  * @param options.accountAddress The account address that will be cancelling the order.
28
28
  * @param options.protocolAddress Required when using orderHash. The Seaport protocol address for the order.
29
29
  * @param options.domain An optional domain to be hashed and included at the end of fulfillment calldata. This can be used for onchain order attribution to assist with analytics.
30
+ * @returns Transaction hash of the cancellation.
30
31
  *
31
32
  * @throws Error if neither order nor orderHash is provided.
32
33
  * @throws Error if the accountAddress is not available through wallet or provider.
@@ -44,7 +45,7 @@ export class CancellationManager {
44
45
  accountAddress: string
45
46
  protocolAddress?: string
46
47
  domain?: string
47
- }) {
48
+ }): Promise<string> {
48
49
  // Validate input
49
50
  if (!order && !orderHash) {
50
51
  throw new Error(
@@ -106,6 +107,8 @@ export class CancellationManager {
106
107
  EventType.CancelOrder,
107
108
  "Cancelling order",
108
109
  )
110
+
111
+ return transactionHash
109
112
  }
110
113
 
111
114
  /**
@@ -1,6 +1,14 @@
1
1
  import { SeaportABI } from "@opensea/seaport-js/lib/abi/Seaport"
2
2
  import type { OrderComponents } from "@opensea/seaport-js/lib/types"
3
+ import { CONDUIT_CONTROLLER_ABI, ERC20_ABI } from "../abi/abis"
3
4
  import type { Listing, Offer, Order } from "../api/types"
5
+ import { CONDUIT_CONTROLLER_ADDRESS } from "../constants"
6
+ import {
7
+ getErc20Payment,
8
+ getFulfillerConduitKey,
9
+ isZeroConduitKey,
10
+ toBigInt,
11
+ } from "../orders/erc20Fulfillment"
4
12
  import {
5
13
  computePrivateListingValue,
6
14
  constructPrivateListingCounterOrder,
@@ -15,6 +23,7 @@ import {
15
23
  OrderSide,
16
24
  } from "../types"
17
25
  import {
26
+ getDefaultConduit,
18
27
  getSeaportInstance,
19
28
  hasErrorCode,
20
29
  requireValidProtocol,
@@ -221,6 +230,13 @@ export class FulfillmentManager {
221
230
  params = Object.values(inputData)
222
231
  }
223
232
 
233
+ // ERC20-priced listings send no native value; Seaport pulls the payment from
234
+ // the buyer instead, which reverts with a bare "execution reverted" when the
235
+ // spender has not been approved. Catch that before spending gas.
236
+ await this.requireErc20PaymentIsSpendable(inputData, transaction.to, {
237
+ accountAddress,
238
+ })
239
+
224
240
  const encodedData = this.context.contractCaller.encodeFunctionData({
225
241
  abi: SeaportABI,
226
242
  functionName,
@@ -247,6 +263,137 @@ export class FulfillmentManager {
247
263
  return tx.hash
248
264
  }
249
265
 
266
+ /**
267
+ * Throw an actionable error when the buyer cannot pay for an ERC20-priced
268
+ * listing, because they hold too little of the payment token or have not
269
+ * approved the address Seaport pulls it from.
270
+ *
271
+ * The check is skipped for native-priced listings, for offer fulfillments, and
272
+ * for any response shape or RPC read it cannot interpret, so it never blocks a
273
+ * purchase that would otherwise have succeeded.
274
+ */
275
+ private async requireErc20PaymentIsSpendable(
276
+ inputData: unknown,
277
+ seaportAddress: string,
278
+ { accountAddress }: { accountAddress: string },
279
+ ): Promise<void> {
280
+ const payment = getErc20Payment(inputData)
281
+ if (!payment) {
282
+ return
283
+ }
284
+
285
+ const spender = await this.resolveFulfillerSpender(
286
+ getFulfillerConduitKey(inputData),
287
+ seaportAddress,
288
+ )
289
+ if (!spender) {
290
+ return
291
+ }
292
+
293
+ const spendState = await this.readErc20SpendState(
294
+ payment.token,
295
+ accountAddress,
296
+ spender,
297
+ )
298
+ if (!spendState) {
299
+ return
300
+ }
301
+
302
+ const amounts = `have ${spendState.balance}, need ${payment.amount} (base units of the payment token)`
303
+ if (spendState.balance < payment.amount) {
304
+ throw new Error(
305
+ `Insufficient ${payment.token} balance to fulfill this listing: ${amounts}. ` +
306
+ `Fund ${accountAddress} with the payment token before fulfilling.`,
307
+ )
308
+ }
309
+ if (spendState.allowance < payment.amount) {
310
+ throw new Error(
311
+ `Payment token ${payment.token} is not approved for this listing: allowance for ` +
312
+ `${spender} is ${spendState.allowance}, need ${payment.amount} (base units of the ` +
313
+ `payment token). ERC20-priced listings send no native value, so Seaport pulls the ` +
314
+ `payment through this spender. Send approve(${spender}, ${payment.amount}) from ` +
315
+ `${accountAddress} first.`,
316
+ )
317
+ }
318
+ }
319
+
320
+ /**
321
+ * Resolve the address that will pull the payment token: Seaport itself when the
322
+ * fulfiller conduit key is `bytes32(0)`, otherwise the conduit registered for
323
+ * that key. Returns null when the key cannot be resolved.
324
+ */
325
+ private async resolveFulfillerSpender(
326
+ conduitKey: string | null,
327
+ seaportAddress: string,
328
+ ): Promise<string | null> {
329
+ if (!conduitKey || isZeroConduitKey(conduitKey)) {
330
+ return seaportAddress
331
+ }
332
+
333
+ const defaultConduit = getDefaultConduit(this.context.chain)
334
+ if (conduitKey.toLowerCase() === defaultConduit.key.toLowerCase()) {
335
+ return defaultConduit.address
336
+ }
337
+
338
+ try {
339
+ const result = await this.context.contractCaller.readContract({
340
+ address: CONDUIT_CONTROLLER_ADDRESS,
341
+ abi: CONDUIT_CONTROLLER_ABI,
342
+ functionName: "getConduit",
343
+ args: [conduitKey],
344
+ })
345
+ if (
346
+ !Array.isArray(result) ||
347
+ typeof result[0] !== "string" ||
348
+ result[1] !== true
349
+ ) {
350
+ return null
351
+ }
352
+ return result[0]
353
+ } catch (error) {
354
+ this.context.logger(
355
+ `Could not resolve conduit for key ${conduitKey}, skipping the ERC20 approval check: ${error}`,
356
+ )
357
+ return null
358
+ }
359
+ }
360
+
361
+ /** Read the buyer's payment-token balance and allowance for a spender. */
362
+ private async readErc20SpendState(
363
+ token: string,
364
+ owner: string,
365
+ spender: string,
366
+ ): Promise<{ balance: bigint; allowance: bigint } | null> {
367
+ const contractCaller = this.context.contractCaller
368
+ try {
369
+ const [rawBalance, rawAllowance] = await Promise.all([
370
+ contractCaller.readContract({
371
+ address: token,
372
+ abi: ERC20_ABI,
373
+ functionName: "balanceOf",
374
+ args: [owner],
375
+ }),
376
+ contractCaller.readContract({
377
+ address: token,
378
+ abi: ERC20_ABI,
379
+ functionName: "allowance",
380
+ args: [owner, spender],
381
+ }),
382
+ ])
383
+ const balance = toBigInt(rawBalance)
384
+ const allowance = toBigInt(rawAllowance)
385
+ if (balance === null || allowance === null) {
386
+ return null
387
+ }
388
+ return { balance, allowance }
389
+ } catch (error) {
390
+ this.context.logger(
391
+ `Could not read ${token} balance or allowance, skipping the ERC20 approval check: ${error}`,
392
+ )
393
+ return null
394
+ }
395
+ }
396
+
250
397
  /**
251
398
  * Returns whether an order is fulfillable.
252
399
  * An order may not be fulfillable if a target item's transfer function
@@ -324,22 +471,35 @@ export class FulfillmentManager {
324
471
 
325
472
  /**
326
473
  * Validates an order onchain using Seaport's validate() method.
474
+ *
475
+ * The order is left with an empty signature: Seaport takes the transaction
476
+ * sender as proof the offerer approved it. This does not post the order to
477
+ * OpenSea. It becomes discoverable only once OpenSea ingests the resulting
478
+ * `OrderValidated` event.
479
+ *
480
+ * @param orderComponents The order to validate
481
+ * @param accountAddress Address sending the validate transaction
482
+ * @param protocolAddress Seaport protocol address the components were built
483
+ * for. Defaults to {@link DEFAULT_SEAPORT_CONTRACT_ADDRESS}.
484
+ * @returns Transaction hash of the validate transaction
485
+ *
486
+ * @throws Error if the accountAddress is not available through wallet or provider.
487
+ * @throws Error if the protocol address is not supported by OpenSea. See {@link isValidProtocol}.
327
488
  */
328
489
  async validateOrderOnchain(
329
490
  orderComponents: OrderComponents,
330
491
  accountAddress: string,
492
+ protocolAddress: string = DEFAULT_SEAPORT_CONTRACT_ADDRESS,
331
493
  ) {
332
494
  await this.context.requireAccountIsAvailable(accountAddress)
495
+ requireValidProtocol(protocolAddress)
333
496
 
334
497
  this.context.dispatch(EventType.ApproveOrder, {
335
498
  orderV2: { protocolData: orderComponents } as unknown as OrderV2,
336
499
  accountAddress,
337
500
  })
338
501
 
339
- const seaport = getSeaportInstance(
340
- DEFAULT_SEAPORT_CONTRACT_ADDRESS,
341
- this.context.seaport,
342
- )
502
+ const seaport = getSeaportInstance(protocolAddress, this.context.seaport)
343
503
  const transaction = await seaport
344
504
  .validate(
345
505
  [{ parameters: orderComponents, signature: "0x" }],
@@ -357,7 +517,18 @@ export class FulfillmentManager {
357
517
  }
358
518
 
359
519
  /**
360
- * Create and validate a listing onchain.
520
+ * Create a listing and validate it onchain, instead of signing it offchain.
521
+ *
522
+ * Runs any token approvals the listing needs, then sends one `validate()`
523
+ * transaction. The wallet is never asked for an EIP-712 signature, so this
524
+ * works for contract accounts that cannot produce one.
525
+ *
526
+ * Unlike {@link OrdersManager.createListing}, this does not post the listing
527
+ * to OpenSea. It becomes discoverable only once OpenSea ingests the
528
+ * `OrderValidated` event, so the returned hash is a transaction hash, not an
529
+ * order hash.
530
+ *
531
+ * @returns Transaction hash of the validate transaction
361
532
  */
362
533
  async createListingAndValidateOnchain({
363
534
  asset,
@@ -403,7 +574,18 @@ export class FulfillmentManager {
403
574
  }
404
575
 
405
576
  /**
406
- * Create and validate an offer onchain.
577
+ * Create an offer and validate it onchain, instead of signing it offchain.
578
+ *
579
+ * Runs any token approvals the offer needs, then sends one `validate()`
580
+ * transaction. The wallet is never asked for an EIP-712 signature, so this
581
+ * works for contract accounts that cannot produce one.
582
+ *
583
+ * Unlike {@link OrdersManager.createOffer}, this does not post the offer to
584
+ * OpenSea. It becomes discoverable only once OpenSea ingests the
585
+ * `OrderValidated` event, so the returned hash is a transaction hash, not an
586
+ * order hash.
587
+ *
588
+ * @returns Transaction hash of the validate transaction
407
589
  */
408
590
  async createOfferAndValidateOnchain({
409
591
  asset,