feat: support partial row settlement and weighted rewards

[g4titanx]

Summary

escrow-side implementation of the pricing model spec

This PR updates EscrowBatch to accept normalized value weights and a pricing commitment supplied during deployment. Rewards and bonds are calculated using normalized row values, allowing single-row, batch, and mixed-asset escrows to distribute the reward pot consistently without comparing raw token amounts.

Collection is now progressive. Successfully proved rows are permanently settled, while unfinished rows remain under the same bid and deadline. Partial settlement releases the corresponding bond, expiry forfeits only the remaining bond and reopens only unfinished rows, and consumed proof identifiers prevent the same receipt item from settling multiple rows. Failed direct payouts become withdrawable claims instead of reopening completed rows.

Cancellation cleanup can release multiple expired bids through a bounded call, and is_bonded() now checks outstanding bid state in constant time. Pricing formulas, platform-fee accounting, DEX swaps, quote verification, blinded-signer authorization, and expiry automation remain API/Nomad responsibilities.

How to review

Start with src/EscrowBatch.sol:

1. Review the constructor changes: valueWeight, quoteCommitment, and reward-asset funding.
2. Review bid(), collect(), and _settleProvedRows() together to follow proportional bond release and progressive row settlement.
3. Review proof-consumption tracking, expireBid() / expireBids(), and claim withdrawal.
4. Review test/EscrowBatch.t.sol for the 9-of-10 settlement, remainder-only retry, hybrid payout, cancellation cleanup, and outstanding-bid tests.
5. Review the Tempo and USDT tests for real receipt-proof and token-compatibility coverage.
6. Review generated artifacts last.

[g4titanx]

@ozwaldorf i would prefer that #33 is merged before this

[g4titanx]

@claude review

[claude]

Claude finished @g4titanx's task in 4m 38s —— View job

---

Claude finished reviewing

• Gather context (PR body, review thread, changed files)
• Read diff against origin/master
• Review src/EscrowBatch.sol core logic (bid/collect/settlement/expiry/claims)
• Review test coverage changes
• Post final review feedback

Note: the OpenZeppelin/forge-std submodules aren't checked out in this environment (network access is unavailable to me here), so I could not run forge build/forge test. This review is based on manual reading of the diff and full src/EscrowBatch.sol.

Overall this is a solid, well-tested refactor — progressive settlement, proof-item consumption, and the claim-fallback path are all covered by dedicated tests (testNineOfTenSettlementExpiresOnlyRemainder, testHybridPayoutPaysImmediatelyAndFallsBackToClaim, testRejectsDuplicateReceiptLogAcrossCollectCalls), and the reward math (_calculateRewardShare) can't hit a division-by-zero since isFinalCollection is checked before it's called. A few things worth a look before merge:

1. Blinded-signer supply has no relationship to expected retries (src/EscrowBatch.sol:166-219, constructor)
blindedSignerUsed[signer] is permanent — once a signer authorizes a bid(), it can never be reused, even if that bid later expires with unfinished rows (per the "no bond" design agreed in the review thread). The constructor doesn't require _blindedSigners.length to have any relation to _expectedTransfers.length or to a client's expected retry budget. If a batch sees enough abandoned/expired bids to exhaust the signer set, the remaining rows become permanently un-biddable (the only recovery is cancelAndWithdraw by the deployer, forfeiting the whole batch) even though funds are still escrowed. Since this is a spec/off-chain provisioning concern rather than a contract bug, it may be intentional — but worth confirming the API/Nomad side always mints enough spare signers per batch.

2. _handleExpiredBids() still does a full O(bidders) sweep on every bid()/collect() (src/EscrowBatch.sol:729-738)
This matches the resolution reached in the review thread (blinded-signer gating makes the bidder count low-risk, so auto-clearing was kept instead of switching to caller-only cleanup). Just flagging that the bound is activeBidCount (≤ MAX_BLINDED_SIGNERS/MAX_ROWS, effectively ≤256), and each expired bidder found also triggers _clearBid, which itself loops over that bidder's bidTransferIndexes. Worst case (many stale bidders each holding many rows) a single bid()/collect() call could touch a few hundred storage slots — likely fine given MAX_ROWS/MAX_BLINDED_SIGNERS = 256, but worth a sanity gas-benchmark test with a saturated bidder set if one doesn't already exist.

3. Test gap: trySafeTransfer isn't exercised against a genuine no-return-data token through collect() (test/USDTCompatibility.t.sol:109-142, src/EscrowBatch.sol:923-930)
testBatchFundingBidAndWithdrawalAcceptNoReturnData only calls bid() then cancelAndWithdraw(), which pays out via _sendAsset/safeTransfer (reverts on failure) — it never calls collect(). So the new _trySendAsset/trySafeTransfer path (added specifically to convert failed payouts into claims, per this PR) is only tested against a token that always returns abi.encode(true) (BatchTempo.t.sol) or one that reverts via require (testHybridPayoutPaysImmediatelyAndFallsBackToClaim, using the disable-flag mock). Neither covers trySafeTransfer's behavior on a real void-return success (mainnet USDT's actual case), which is the scenario this test file is meant to validate. Suggest adding a collect()-based settlement test using NoReturnERC20 to close that gap. Fix this →

4. Minor: PR description is stale
"How to review" step 1 says to review valueWeight, quoteCommitment, and reward-asset funding in the constructor — but quoteCommitment was dropped from the design after ozwaldorf's review comment ("why does the escrow need a commitment?"). The current constructor takes _blindedSigners instead. Might be worth updating the PR body so future reviewers aren't looking for a field that no longer exists.

Nothing else stood out — proof-consumption tracking (consumedProofItems), progressive remainingRows accounting, and the checks-effects-interactions ordering in withdrawClaim/_settleProvedRows all look correct.

[ozwaldorf]

Review pass on the partial-settlement changes. One small fix, one doc correction.

1. Unbounded gas forwarded to a bidder-controlled address in collect()

src/EscrowBatch.sol:925 — _trySendAsset does to.call{value: amount}("") with no gas cap. It runs inside nonReentrant after all row/reward/bid state is terminal, and a failed transfer falls back to claimable, so there is no reentrancy or state-corruption issue.

The problem is that the fallback is not actually reachable for the case it exists to handle. A bidder contract with an expensive receive() consumes the collector's remaining gas and OOGs the entire collect(), reverting valid proofs rather than accruing a claim. Capping the forwarded gas would make the claimable path do what the comment above it says it does.

Worth fixing since the claim mechanism is already built — it just needs a gas bound to be effective.

2. is_bonded() is not constant time

src/EscrowBatch.sol:257 — the PR description says is_bonded() "now checks outstanding bid state in constant time." It is still an O(bidders.length) scan; only the loop body changed.

Not worth restructuring the code — the linear scan is bounded by MAX_BLINDED_SIGNERS and behaves correctly. Just worth correcting the description, or switching to activeBidCount if constant time was actually intended.

Minor related note: the old guard was expiresAt > 0 && block.timestamp <= expiresAt; the new one keeps only expiresAt >= block.timestamp. That is currently safe only because _clearBid always calls _untrackBidder, so a zeroed bid never stays in bidders. That invariant is now load-bearing and undocumented — a one-line comment would help.

---

Checked and clean: consumedProofItems replay prevention and the two domain-separated proof tags, _validateBidIndexes guards (completed rows, reserved rows, duplicates), value-weight accounting across partial settlement, and the _clearBid / activeBidCount paths (mutually exclusive, no double-decrement).