Skip to content

fix: batch fulfill availability, unit clamping, forwarded-offer balances, zero fees, conduit case, and exports (8 community contributions) - #985

Merged
ryanio merged 9 commits into
mainfrom
fix/community-batch-2026-08-22
Aug 22, 2026
Merged

ryanio merged 9 commits into
mainfrom
fix/community-batch-2026-08-22

Conversation

@ryanio

@ryanio ryanio commented Aug 22, 2026

Copy link
Copy Markdown
Collaborator

Eight community PRs opened against seaport-js on 2026-08-22, stacked onto one branch so the overlapping edits to src/utils/fulfill.ts and src/seaport.ts resolve once rather than eight times. Each contributor keeps authorship of their own commit.

Every one of these supersedes an open PR, which needs closing once this lands: #976, #977, #978, #979, #980, #981, #982, #983.

What each commit does

fix: export the symbols the docs tell people to use (#983, @Dusk1e)
The entry point exported only Seaport, so both README order examples were written with an ItemType that had nowhere to be imported from, and fulfillOrder's doc comment pointed at a getMaximumSizeForOrder helper that was deep-import only. Exports both and adds the missing import line to the two README blocks.

fix: leave out a fee item that rounds down to zero (#979, @Ruzzgar)
multiplyBasisPoints floors, so below a certain price a fee lands on 0 and _formatOrder appended the zero-amount consideration item anyway. Seaport rejects those with MissingItemAmount, so a cheap listing with a fee was signed, published, and then unfillable. The item is dropped only when both ends of its range are zero, which leaves an ascending 0 -> 250 fee alone.

fix: resolve a conduit key regardless of its hex case (#980, @Dusk1e)
conduitKeyToConduit was indexed with the key as it arrived. A bytes32 written in a different hex case missed the lookup, the operator came out undefined, and the caller saw an ethers unsupported addressable value error naming neither the conduit nor the key. Five call sites now go through one private helper that lowercases both the map and the key.

fix: type executeAllActions as the transaction it actually sends (#982, @Ruzzgar)
transact() is declared Promise<TransactionResponse>, but the exchange branch of OrderUseCase and three casts in fulfill.ts named ContractTransaction. In ethers v6 those are different types, so await executeAllActions() then .wait() did not compile on code that ran correctly. Types only, nothing moves at runtime.

fix: drop unfillable orders from a batch instead of failing the batch (#976, @Dusk1e)
fulfillOrders is documented as best effort and fulfillAvailableAdvancedOrders behaves that way on chain, but the SDK mapped every order through validateAndSanitizeFromOrderStatus and threw on the first cancelled or filled one. One stale order took the whole call down before a transaction was built, which is the ordinary case for an aggregator sweeping listings. Unfillable orders are filtered out and every positionally indexed array downstream reads the filtered list. An all-unfillable batch still throws.

fix: cap unitsToFill at what is left of a partially filled order (#977, @Xowiek)
The comment above the code said the order is adjusted by the minimum of the requested amount and the remainder; no minimum was taken. Seaport itself caps, so asking for 8 units when 4 remain settles on chain, while the SDK sized the offer side for 8 and rejected it with "The offerer does not have the amount needed to create or fulfill" -- an error that points at the offerer, who is fine. Capped on both the single and batch paths.

fix: stop crediting the fulfiller with offer items sent to someone else (#978, @Xowiek)
validateStandardFulfillBalancesAndApprovals credits the offered items to the fulfiller before checking consideration, which holds only while the offer reaches them. recipientAddress forwards it elsewhere and the check never learned that, so accepting a bid and forwarding the proceeds passed validation and then reverted on chain with panic code 0x11. The credit is now applied only when the offer lands with the fulfiller, with the zero address and the fulfiller's own address both counting as landing with them.

test: pin the zero-totalSize tip-scaling resolution from #972 (#981, @chalomdev)
Test only. Pins the hardening merged in #972, which is not reachable through the public API today because scaleOrderStatusToMaxUnits rewrites a totalSize of 0 before the tip-scaling code sees it.

style: biome formatting on the conduit lookup
biome check rejects #980 as submitted, which is why its lint check is the one red result across the eight. Formatting only.

Verification

npm run check-types and biome check . both clean, npm test 237 passing 0 failing, coverage run completes. Lint was run separately from the tests: hardhat runs mocha without typechecking, and #982's regression is visible only to tsc.

Each fix was tripwire-checked by reverting its source hunk alone on this branch and confirming the test fails on the assertion it is named for:

Fix Failure when the source is reverted
#983 expected { Seaport: [Function Seaport] } to have property 'ItemType', same for getMaximumSizeForOrder
#979 expected [ { itemType: +0 }, ...(1) ] to have a length of 1 but got 2 -- the zero item still present
#980 3 failing with unsupported addressable value (argument="target", value=null); the matching-case control still passes
#982 4 tsc errors, Property 'wait' does not exist on type 'ContractTransaction', while mocha stays green
#976 The order you are trying to fulfill is cancelled / is already filled, and the all-unfillable case reports the wrong message
#977 both integration cases fail The offerer does not have the amount needed to create or fulfill
#978 expected promise to be rejected with an error including 'The fulfiller does not have the balan...' but it was fulfilled; both controls still pass

Two notes on that table. Reverting all of #977 removes the exported clampUnitsToRemaining and the unit test file then fails at module load rather than on an assertion, so the revert was narrowed to the two call sites; the four unit cases in fulfill-units.spec.ts exercise the helper directly and are not tripwires for the wiring, the two integration cases are. #981 is a hardening pin with no source change to revert, and its first assertion is a bare .to.throw(); the throw was confirmed by hand to be RangeError: Division by zero, but the assertion does not pin that.

Not fixed here

deductFees sums basis points and floors once, while feeToConsiderationItem floors each fee separately. With a price of 100 and two 50 bp fees, consideration drops to 99 and both fee items floor to 0, so 99 of 100 is paid out. This predates #979 and is not introduced by it: before, the order was unfillable with MissingItemAmount; now it fills, one unit short of nominal. Worth its own change.

chalomdev and others added 9 commits August 22, 2026 12:00
Adds a focused unit test against mapTipAmountsFromUnitsToFill covering
both halves of the #971/#972 hardening: the function throws given a
raw totalSize of 0 (why the resolution exists), and correctly scales
a tip once totalSize is resolved to the order's maximum size via
getMaximumSizeForOrder, matching what fulfillStandardOrder does
before calling it.
The entry point exports Seaport and nothing else, so that is the whole
surface a consumer gets without a deep import:

  require("@opensea/seaport-js")  ->  [ 'Seaport' ]

Both order examples in the README are written with ItemType.ERC721, and no
example imports it because there is nowhere to import it from. Copying
either one leaves ItemType undefined. fulfillOrder's doc comment has the
same problem: "We expose a helper to get this: getMaximumSizeForOrder", and
that helper is not exported either.

Export the two the documentation already promises, and add the import line
the README examples were missing. Adding to the entry point breaks nothing;
Seaport keeps resolving exactly as it did.

The second example also reached for a bare parseEther while the first uses
ethers.parseEther, so it now matches its neighbour.

Left alone deliberately: the rest of the constants and the input types are
still deep-import only. Widening the public surface further is a call worth
making on purpose rather than as a side effect of a docs fix.
multiplyBasisPoints floors, so on a small enough price the fee comes out as
0 and _formatOrder appends a zero-amount consideration item anyway. Seaport
rejects zero-amount items with MissingItemAmount, so the order is signed,
published and impossible to fill.

  price 100 at 50 bp   -> consideration [100, 0]  -> MissingItemAmount
  price 10  at 250 bp  -> consideration [10, 0]   -> MissingItemAmount
  price 1000 at 250 bp -> consideration [975, 25] -> fills

Nothing surfaces at creation time. The seller finds out when a buyer cannot
take the listing.

The item is worth nothing anyway -- deductFees floors the same way, so the
consideration was never reduced for it -- and dropping it leaves an order
that behaves exactly as the arithmetic says. That is better than refusing to
build the order, which would block low priced listings outright.

Only drop it when both ends are zero. A fee can floor to zero at the start
of an ascending range and still pay across the rest of it; Seaport looks at
the amount current at fill time, and an order like that settles today.
conduitKeyToConduit is indexed with the conduit key exactly as it arrives.
A conduit key is a bytes32, so the same value can be written in any hex
case, and a key that differs only in case misses the lookup. The operator
comes back undefined and the failure surfaces from ethers as

  unsupported addressable value (argument="target", value=null)

which mentions neither the conduit nor the key.

Five call sites read that map: the operator approvals are granted to at
order creation, the offerer and fulfiller operators on fulfillOrder, and the
same two on fulfillOrders. All five are affected, so an order carrying a
re-cased key cannot be created or filled.

Everywhere else the SDK compares hex it already lowercases both sides --
tokens in findBalanceAndApproval and getSummedTokenAndIdentifierAmounts,
operators in getApprovalDedupKey, owners in balanceOf, the recipient in
shouldUseBasicFulfill, currencies in areAllCurrenciesSame. The conduit key
is the one hex comparison left keyed on the raw string.

Lower case the map when it is built and lower case the key on the way in,
behind a small helper so all five sites go through the same path. A key that
already matches the configured case resolves exactly as before.
On an exchange use case executeAllActions returns
finalAction.transactionMethods.transact(), which resolves to a
TransactionResponse. OrderUseCase declares ContractTransaction for that
branch, and the three fulfill helpers cast to it on the way out.

Those are different things in ethers v6. ContractTransaction is a prepared
request; TransactionResponse is a transaction that has been sent. The
response carries hash, wait() and confirmations(), and the request carries
none of them, so the natural thing to write after a fulfillment does not
compile:

  const transaction = await useCase.executeAllActions()
  await transaction.wait()
    Property 'wait' does not exist on type 'ContractTransaction'

The code runs fine, it is only the annotation that is wrong. Callers are
left casting through any to get at the receipt.

Point the branch and the three casts at TransactionResponse, which is
already what transact() is declared to return.
fulfillOrders is documented as best effort: "Orders that fail will not
revert the whole transaction". fulfillAvailableAdvancedOrders behaves that
way on chain, skipping what it cannot fill and settling the rest.

The SDK never gets that far. fulfillAvailableOrders maps every order
through validateAndSanitizeFromOrderStatus, which throws on the first
cancelled or fully filled one, so a single stale order takes down the whole
call before any transaction is built. Cancel one of two listings and the
contract reports availableOrders [false, true] for the pair, while the SDK
throws "The order you are trying to fulfill is cancelled" and the caller
gets nothing.

That is the normal case for an aggregator: orders go stale between reading
them and filling them, which is the reason to use this method at all.

Filter those orders out of the batch and build the call from what is left.
Everything downstream is indexed by position in that list, so the
fulfillments and criteria resolvers now come from the filtered list too --
they were reading the unfiltered one, which only matched while nothing was
ever dropped. If no order survives, throw, since there is nothing to send.

Single order fulfillOrder still throws as before. There is no batch to fall
back on there, and a silent no-op would be worse than a clear error.
The comment over this code already describes the intended behaviour -- the
order is adjusted by "the minimum of the amount to fill and the remaining
order left to be fulfilled" -- but no minimum is ever taken. unitsToFill
goes into mapOrderAmountsFromUnitsToFill and
getAdvancedOrderNumeratorDenominator exactly as passed.

Seaport caps the fill itself. On an order with 4 of 10 units left, asking
for 8 transfers 4 and closes the order. The SDK instead sizes the offer
side for 8 units the offerer no longer holds, so its own balance check
rejects the fill:

  The offerer does not have the amount needed to create or fulfill.

The message points at the offerer, who is fine; the request simply ran past
the remainder. The same call placed directly against the contract settles.

Take the minimum the comment calls for, in both the single and batch paths.
Amounts, tips and numerator/denominator are then derived from a fill that
will actually happen, and the value attached to the transaction covers the
units that really transfer.

Only applies once an order is partially filled. Asking for more units than
the order was ever divisible into is a caller error rather than a race, and
getAdvancedOrderNumeratorDenominator still rejects that with its own
message.
validateStandardFulfillBalancesAndApprovals adds the offered items to the
fulfiller's balances before checking consideration, per requirement 2 in its
own doc comment: the fulfiller "does not need to own the ERC20 item as it
will first be received from the offerer".

That only holds when the offer actually reaches the fulfiller.
recipientAddress forwards it somewhere else, and the check never sees that
value -- fulfillStandardOrder and fulfillAvailableOrders both take
recipientAddress but never pass it down. The credit is applied either way.

Accepting a bid is where it shows. The offerer bids 10 ERC20 with a 2.5%
fee, so the fulfiller receives 10 and settles 0.25 out of it. Hand the
proceeds to a third party with recipientAddress and the fee has to come from
the fulfiller's own balance instead. With a zero balance the SDK reports no
problem and hands back a fulfillment that reverts on transfer with panic
0x11, which says nothing about what went wrong.

Only apply the credit when the offer lands with the fulfiller. The zero
address means it stays with them, and naming the fulfiller explicitly is the
same thing, so both keep the existing behaviour -- checked on chain, that
second case really does settle.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants