feat(contracts): forward legacy ABI to old impl via fallback

[jonastheis]

Summary

The router-decoupling rework on jonas/router-decoupling replaces the
market's pre-router fulfillment ABI with a slimmer FulfillmentBatch[]
shape and routes verification through BoundlessRouter. Old brokers will
keep submitting the original (Fulfillment[], AssessorReceipt) shape for
the duration of the broker rollout, so the deployed market must continue
to accept legacy calls without us rewriting or re-auditing the old
fulfillment logic.

This branch wires up a fallback() external payable on the new market
that delegate-calls into the already-deployed audited implementation
at the proxy's pre-upgrade impl address. Nothing new is written for the
legacy ABI surface — the audited bytecode handles it byte-identically to
pre-upgrade, just delegate-called. The only new on-chain code is a ~50 B
inline-assembly shim plus a LEGACY_IMPL constructor immutable.

A frozen copy of the audited source lives at contracts/src/legacy/, used
exclusively for tests and CI parity invariants — production deployments
point LEGACY_IMPL at the existing impl on Base mainnet. The legacy
sources mirror main at commit
507f7469
(BM-2598: add depositCollateralTo and depositCollateralWithPermitTo,
the last commit on main that touched any of the files in this tree).
The only deltas are file-basename + import renames; contract bodies are
unchanged.

Architecture

                ┌──────────────────────────────────────┐
                │  Proxy (BoundlessMarket, address P)  │
                │  unchanged across the upgrade        │
                └──────────────┬───────────────────────┘
                               │
                               ▼
        ┌──────────────────────────────────────────────────────────┐
        │  NEW impl (this branch)                                  │
        │                                                          │
        │  Selectors handled directly:                             │
        │    fulfill(FulfillmentBatch[])                           │
        │    fulfillAndWithdraw(FulfillmentBatch[])                │
        │    priceAndFulfill(SlimRequest[], FulfillmentBatch[])    │
        │    priceAndFulfillAndWithdraw(...)                       │
        │    submitRootAndFulfill(addr,bytes32,bytes,batch[])      │
        │    submitRootAndFulfillAndWithdraw(...)                  │
        │    submitRootAndPriceAndFulfill(...)                     │
        │    submitRootAndPriceAndFulfillAndWithdraw(...)          │
        │    initialize(address)                                   │
        │    LEGACY_IMPL(), ROUTER()                               │
        │                                                          │
        │  Selectors shared with legacy → also handled here:       │
        │    lockRequest, lockRequestWithSignature, priceRequest   │
        │    slash, withdraw, submitRequest, submitRoot            │
        │    deposit, depositTo, depositCollateral*, withdrawColl. │
        │    accounts, balanceOf, balanceOfCollateral              │
        │    requestIsLocked, requestIsFulfilled, requestIsSlashed │
        │    requestDeadline, requestLockDeadline, requestLocks    │
        │    eip712Domain, eip712DomainSeparator                   │
        │    COLLATERAL_TOKEN_CONTRACT                             │
        │    ADMIN_ROLE, grantRole, hasRole, ..., proxiableUUID    │
        │                                                          │
        │  fallback() → delegatecall(LEGACY_IMPL, msg.data)        │
        └──────────────────────────┬───────────────────────────────┘
                                   │ msg.sender, msg.value, proxy
                                   │ storage all preserved
                                   ▼
        ┌──────────────────────────────────────────────────────────┐
        │  LEGACY impl                                             │
        │  Base mainnet: 0x22bb6bbe5d221ef3e738029dab4d1d27ec725cd3│
        │  (the impl pointed to by the proxy before this upgrade)  │
        │                                                          │
        │  Selectors handled here (reached only via fallback):     │
        │    fulfill(Fulfillment[], AssessorReceipt)               │
        │    fulfillAndWithdraw(Fulfillment[], AssessorReceipt)    │
        │    priceAndFulfill(ProofRequest[], bytes[],              │
        │                    Fulfillment[], AssessorReceipt)       │
        │    priceAndFulfillAndWithdraw(...)                       │
        │    submitRootAndFulfill(addr,bytes32,bytes,              │
        │                         Fulfillment[], AssessorReceipt)  │
        │    submitRootAndFulfillAndWithdraw(...)                  │
        │    submitRootAndPriceAndFulfill(...)                     │
        │    submitRootAndPriceAndFulfillAndWithdraw(...)          │
        │    verifyDelivery(Fulfillment[], AssessorReceipt) [view] │
        │    imageInfo() [view]                                    │
        │    setImageUrl(string) [admin]                           │
        │    VERIFIER, APPLICATION_VERIFIER, ASSESSOR_ID [view]    │
        │    DEPRECATED_ASSESSOR_ID,                               │
        │    DEPRECATED_ASSESSOR_EXPIRES_AT [view]                 │
        │    DEFAULT_MAX_GAS_FOR_VERIFY [view]                     │
        └──────────────────────────────────────────────────────────┘

Methods that actually exercise the legacy contract

Forwarded through fallback() to the audited legacy impl. Everything in
the list below has a different selector on the new market (different param
types) or doesn't exist on it at all:

Class	Methods
Fulfillment ABI	fulfill(Fulfillment[],AssessorReceipt), fulfillAndWithdraw(...), priceAndFulfill(ProofRequest[],bytes[],Fulfillment[],AssessorReceipt), priceAndFulfillAndWithdraw(...)
SubmitRoot bundles	submitRootAndFulfill(addr,bytes32,bytes,Fulfillment[],AssessorReceipt), submitRootAndFulfillAndWithdraw(...), submitRootAndPriceAndFulfill(...), submitRootAndPriceAndFulfillAndWithdraw(...)
Admin / metadata	setImageUrl(string), legacy initialize(address,string)
Views	verifyDelivery(Fulfillment[],AssessorReceipt), imageInfo(), VERIFIER(), APPLICATION_VERIFIER(), ASSESSOR_ID(), DEPRECATED_ASSESSOR_ID(), DEPRECATED_ASSESSOR_EXPIRES_AT(), DEFAULT_MAX_GAS_FOR_VERIFY()

Everything else — lockRequest, lockRequestWithSignature, slash,
withdraw, all the deposit*/depositCollateral* variants,
submitRoot, every view getter shared with the legacy ABI, every
AccessControl role method — has the same selector on the new market
and therefore runs on the new impl, even when invoked from a legacy
broker. The legacy impl's body for those methods is unreachable from the
proxy; the audited-bytecode-reuse story only covers the methods in the
table above. Shared methods are covered by the new impl's audit.

Gas impact

The fallback path adds one delegate-call hop + calldata/returndata copy on
every legacy-only call.

Per-method overhead (via-fallback BoundlessMarketLegacyViaFallbackBasicTest
gas snapshot vs. the standalone legacy suite running identical scenarios):

Method	Standalone	Via fallback	Δ
fulfill: a locked request	87,293	89,513	+2,220 (+2.5%)
fulfill: a locked request with 10kB journal	344,971	349,365	+4,394 (+1.3%)
fulfill: another prover fulfills without payment	82,256	84,608	+2,352 (+2.9%)
fulfillAndWithdraw: a locked request	99,163	101,224	+2,061 (+2.1%)
submitRootAndFulfill: a locked request	121,966	123,789	+1,823 (+1.5%)
submitRootAndFulfillAndWithdraw: a locked request	133,271	134,935	+1,664 (+1.2%)

Mean overhead across the 43 measured methods: +566 gas. Typical
fulfillment path: ~2.2k gas extra. Worst case (10kB journal): ~4.4k gas
extra, dominated by the returndatacopy of the large output.

A handful of batch-fulfill rows show a small negative delta (a few
hundred gas faster via fallback). That's noise from different CREATE
nonce ordering in the test setups (cold/warm state on participating
contracts differs); the actual per-call overhead is positive and bounded
by the delegate-call cost.

Implementation runtime bytecode: 29,456 → 30,293 B (+837 B). The
overshoot vs the originally-budgeted ~50 B comes from the public
LEGACY_IMPL() getter the immutable generates and from the dispatcher's
new tail changing optimizer inlining decisions. Still over EIP-170;
the size shrink to fit under the cap is tracked separately on
jonas/market-bytecode-shrink.

How to review

The largest commit by line count is the legacy source / test imports.
Reviewing those line-by-line is wasteful — they're frozen copies of
main's sources. Use the commands below to confirm there are no
differences vs main beyond the explicit renames (file basenames and
import paths).

1. Production source tree (contracts/src/legacy/)

The renamed root contracts:

diff <(git show 507f7469:contracts/src/BoundlessMarket.sol) \
     <(cat contracts/src/legacy/BoundlessMarketLegacy.sol)

diff <(git show 507f7469:contracts/src/IBoundlessMarket.sol) \
     <(cat contracts/src/legacy/IBoundlessMarketLegacy.sol)

diff <(git show 507f7469:contracts/src/IBoundlessMarketCallback.sol) \
     <(cat contracts/src/legacy/IBoundlessMarketCallbackLegacy.sol)

Expected diffs: import-path strings rewritten to point at the renamed
files inside legacy/. Nothing else.

The frozen library + type subtrees should be byte-identical to main:

for f in contracts/src/legacy/libraries/*.sol contracts/src/legacy/types/*.sol; do
  base="${f#contracts/src/legacy/}"
  diff <(git show 507f7469:contracts/src/$base) <(cat $f) \
       || echo ">> drift in $base"
done

The two commands above should produce no output. If they do, that's
where to focus the source review.

2. Test tree (contracts/test/legacy/)

The standalone-legacy port of the test suite:

diff <(git show 507f7469:contracts/test/BoundlessMarket.t.sol) \
     <(cat contracts/test/legacy/BoundlessMarketLegacy.t.sol)

Expected diffs: import paths rewritten to legacy/, the four top-level
test contracts prefixed with Legacy so gas snapshots land in their own
JSON files.

Helpers (frozen):

for f in TestUtils.sol MockCallback.sol clients/BaseClient.sol \
         clients/Client.sol clients/SmartContractClient.sol \
         clients/MockSmartContractWallet.sol; do
  diff <(git show 507f7469:contracts/test/$f) <(cat contracts/test/legacy/$f) \
       || echo ">> drift in $f"
done

Expected diffs: import paths only (../src/ → ../../src/legacy/ or
../../src/).

The via-fallback port:

diff contracts/test/legacy/BoundlessMarketLegacy.t.sol \
     contracts/test/legacy/BoundlessMarketLegacyViaFallback.t.sol

Expected diffs: setUp rewires the proxy to point at the new market with
LEGACY_IMPL set to a freshly-deployed legacy impl; test contracts
prefixed with ViaFallback; two regression assertions re-baselined for
the shifted proxy address (see comment in the file).

3. Bytecode-parity invariant

The truly load-bearing check that the legacy tree is the audited code:

just check-legacy-bytecode
just check-storage-layout

The first asserts legacy/BoundlessMarketLegacy.sol compiles
byte-identical to cast code 0x22bb...cd3 --rpc-url $BASE_RPC (modulo
masked immutable slots; values cross-checked against
contracts/test/legacy/deployed-bytecode.meta.toml). The second asserts
the new and legacy storage layouts agree at every slot reachable from
either contract.

Both run automatically in CI (legacy-bytecode-parity job in
.github/workflows/contracts.yml).

4. Commits to review individually

The substantive changes are in these commits — review the diffs directly:

Commit	What changed
feat(contracts): forward legacy ABI to a configurable impl via fallback	BoundlessMarket.sol (LEGACY_IMPL, fallback()), BoundlessMarketLib, every constructor call site + payable casts
chore(contracts): verify legacy/ bytecode parity against deployed OLD impl	Verifier script + reference snapshot + meta + CI job + justfile recipe
chore(contracts): enforce storage layout interop between src/ and src/legacy/	Storage-layout verifier script + CI step + justfile recipe
test(contracts): pin cross-ABI invariants in a focused suite	CrossABI.t.sol — the 4 invariants unique to the fallback shape
chore(contracts): wire legacy impl into Deploy.s.sol	Localnet auto-deploys a fresh legacy impl; production uses BOUNDLESS_LEGACY_IMPL env var