Repository navigation
fix: batch fulfill availability, unit clamping, forwarded-offer balances, zero fees, conduit case, and exports (8 community contributions) - #985
Merged
Conversation
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.
This was referenced Aug 22, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Eight community PRs opened against seaport-js on 2026-08-22, stacked onto one branch so the overlapping edits to
src/utils/fulfill.tsandsrc/seaport.tsresolve 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 anItemTypethat had nowhere to be imported from, andfulfillOrder's doc comment pointed at agetMaximumSizeForOrderhelper 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)multiplyBasisPointsfloors, so below a certain price a fee lands on 0 and_formatOrderappended the zero-amount consideration item anyway. Seaport rejects those withMissingItemAmount, 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 ascending0 -> 250fee alone.fix: resolve a conduit key regardless of its hex case(#980, @Dusk1e)conduitKeyToConduitwas indexed with the key as it arrived. Abytes32written in a different hex case missed the lookup, the operator came outundefined, and the caller saw an ethersunsupported addressable valueerror 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 declaredPromise<TransactionResponse>, but the exchange branch ofOrderUseCaseand three casts infulfill.tsnamedContractTransaction. In ethers v6 those are different types, soawait 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)fulfillOrdersis documented as best effort andfulfillAvailableAdvancedOrdersbehaves that way on chain, but the SDK mapped every order throughvalidateAndSanitizeFromOrderStatusand 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)validateStandardFulfillBalancesAndApprovalscredits the offered items to the fulfiller before checking consideration, which holds only while the offer reaches them.recipientAddressforwards it elsewhere and the check never learned that, so accepting a bid and forwarding the proceeds passed validation and then reverted on chain withpanic 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
scaleOrderStatusToMaxUnitsrewrites atotalSizeof 0 before the tip-scaling code sees it.style: biome formatting on the conduit lookupbiome checkrejects #980 as submitted, which is why itslintcheck is the one red result across the eight. Formatting only.Verification
npm run check-typesandbiome check .both clean,npm test237 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 totsc.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:
expected { Seaport: [Function Seaport] } to have property 'ItemType', same forgetMaximumSizeForOrderexpected [ { itemType: +0 }, ...(1) ] to have a length of 1 but got 2-- the zero item still presentunsupported addressable value (argument="target", value=null); the matching-case control still passestscerrors,Property 'wait' does not exist on type 'ContractTransaction', while mocha stays greenThe order you are trying to fulfill is cancelled/is already filled, and the all-unfillable case reports the wrong messageThe offerer does not have the amount needed to create or fulfillexpected promise to be rejected with an error including 'The fulfiller does not have the balan...' but it was fulfilled; both controls still passTwo notes on that table. Reverting all of #977 removes the exported
clampUnitsToRemainingand 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 infulfill-units.spec.tsexercise 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 beRangeError: Division by zero, but the assertion does not pin that.Not fixed here
deductFeessums basis points and floors once, whilefeeToConsiderationItemfloors 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 withMissingItemAmount; now it fills, one unit short of nominal. Worth its own change.