Skip to content

fix: check the fulfiller can cover a whole batch, not just each order - #984

Merged
ryanio merged 1 commit into
mainfrom
fix/cumulative-fulfiller-balance
Aug 22, 2026
Merged

ryanio merged 1 commit into
mainfrom
fix/cumulative-fulfiller-balance

Conversation

@ryanio

@ryanio ryanio commented Aug 22, 2026

Copy link
Copy Markdown
Collaborator

fulfillOrders validated every order against the same un-decremented balances, so a fulfiller who could afford each order individually but not all of them together got no error at all. The SDK returned an exchange action and handed back a transaction that cannot succeed.

Measured: a fulfiller holding 25 against two listings priced 10 and 20 in the same ERC20. fulfillOrders returned approval, exchange rather than throwing The fulfiller does not have the balances needed to fulfill.

This is the sibling of #975. There the native total accumulated while the approval amount did not; here the native total accumulates while the balance requirement does not.

The part I got wrong first, since it shaped the design

My first version dropped the credit for currency the batch pays the fulfiller, on the reasoning that the per-order check already rejects any order the fulfiller cannot afford from their raw balance, making such a credit unreachable.

That was wrong, and the existing suite caught it: four tests broke, all offer fulfillments ("ERC20 <=> ERC721", "ERC20 <=> ERC1155", the criteria-based pair, and the contract-wallet order). Accepting a bid puts its ERC20 fee items in the consideration the fulfiller owes while they are funded by the bid's own ERC20 offer, and the per-order check handles that by crediting each order's offer before checking its consideration. Without the credit, every offer-fulfillment batch would be rejected.

So the credit is load-bearing rather than defensive, and the helper now records why, so nobody removes it for the reason I nearly did.

Scope, deliberately narrow

ERC20 only. Native balances cannot be checked without modelling gas, and a token with no lookup entry is skipped rather than treated as zero. Both are the fail-open direction on purpose: an over-strict check here blocks a working batch, which is worse than the silence it replaces.

The credit is batch-wide while the per-order check is per-order, so this check is the looser of the two and cannot reject anything the per-order check accepts except on the batch total, which is the case it exists for.

Verification

npm run build, npm run lint (tsc and Biome), and npm test all clean at 212 passing.

Tripwire: disabling the check, with the tests left in place, fails on the assertion it is named for:

AssertionError: expected promise to be rejected with an error including
'The fulfiller does not have the balan…' but it was fulfilled with { …(3) }

That fulfilled value is the doomed transaction being handed back. The companion test, that a batch the fulfiller can cover in total still goes through and both NFTs transfer, passes on both sides of the tripwire, so the check is not over-firing.

Behavior change

Order sets that today build a transaction destined to revert will now throw client-side instead. That is the intent, and it is why this was raised for a decision rather than bundled into #975.

Still outstanding

createBulkOrders has the same root cause on the offerer side: per-input approvals are merged by dedup key, keeping the first, so two ERC20 offers approve only the first input's amount. A clean fix needs _formatOrder to return its insufficient approvals so the check can be cumulative, which is order-creation surface rather than the fulfill path. A sum-on-dedup half-fix would hit the same partial-allowance trap described in #975.

`fulfillOrders` validated every order against the same un-decremented balances,
so a fulfiller who could afford each order individually but not all of them
together got no error at all. The SDK returned an exchange action and handed
back a transaction that cannot succeed. Measured: 25 held against two listings
needing 10 and 20.

Sum the batch's requirement and check it once, after every order is folded in.

The credit for currency the batch pays the fulfiller is load-bearing, not
defensive. Accepting a bid puts its ERC20 fee items in the consideration the
fulfiller owes while they are funded by the bid's own ERC20 offer, and the
per-order check handles that by crediting each order's offer first. Dropping the
credit broke four existing offer-fulfillment tests ("ERC20 <=> ERC721",
"ERC20 <=> ERC1155", the criteria-based pair and the contract-wallet order), so
it is kept and the reason is recorded in the helper.

Scoped to ERC20 on purpose. Native balances cannot be checked without modelling
gas, and a token with no lookup entry is skipped. Both are the fail-open
direction: an over-strict check here would block a working batch, which is worse
than the silence it replaces.

Verified as a tripwire: disabling the check fails the new test with "expected
promise to be rejected ... but it was fulfilled", and the companion test that an
affordable batch still goes through passes on both sides, so the check is not
over-firing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@ryanio
ryanio merged commit e12c172 into main Aug 22, 2026
8 checks passed
@ryanio
ryanio deleted the fix/cumulative-fulfiller-balance branch August 22, 2026 19:40
ryanio added a commit that referenced this pull request Aug 22, 2026
#978 stopped the per-order check crediting the fulfiller with offer items
that recipientAddress sends elsewhere. #984 added a batch-wide check in the
same release, and it credits the batch's whole offer unconditionally, so the
same class of shortfall is still accepted on the batch path.

A fulfiller holding 0.3 ERC20 who accepts two bids with a 250bp fee each
owes 0.5 with the proceeds forwarded away. Each order passes the per-order
check alone, and the batch check clears the total against a credit for
20 ERC20 the fulfiller never receives. It reverts on transfer.
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.

1 participant