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 the
fallback forwarding — the new market inherits OpenZeppelin's Proxy and
overrides _implementation() to return LEGACY_IMPL — plus the
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.

The new market's own test harnesses (the Solidity unit suite, the Rust
test harness, and the deployment-scripts e2e) point LEGACY_IMPL at a
non-functional stub address, so a current-ABI call can never be silently
served by the fallback — any accidental fallback hit fails instead of
working. The real legacy impl is stood up only by the dedicated
test/legacy/ suites (which exercise the fallback on purpose) and by the
deploy scripts on fresh networks.

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,556 B (+1,100 B). The
overshoot vs the originally-budgeted ~50 B comes from the public
LEGACY_IMPL() getter the immutable generates, the dispatcher's new tail
changing optimizer inlining decisions, and the OpenZeppelin Proxy
indirection (+263 B vs the prior hand-rolled assembly fallback — via-ir
at 100 runs doesn't fully inline fallback() → _fallback() → _delegate()
back down to the bare delegatecall). 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 (BoundlessMarketLegacyViaFallback.t.sol) is no
longer a copy of the suite — it subclasses it, so review the whole file
directly (~110 lines). The standalone-legacy base now exposes a virtual _deployMarket() hook and virtual getters for the two signature-recovery
addresses; the via-fallback file is a thin BoundlessMarketLegacyViaFallbackTest
base that overrides _deployMarket() (deploy the new market with
LEGACY_IMPL pointed at a freshly-deployed legacy impl) plus subclasses
that inherit the full battery and re-baseline the two recovered addresses
for the shifted proxy address. Foundry runs both the standalone and
via-fallback contracts, so each entry point keeps full coverage.

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
refactor(contracts): forward legacy ABI via OpenZeppelin Proxy	Replaces the hand-rolled assembly fallback() with inheritance from OZ Proxy + an _implementation() override (review feedback)
refactor(contracts): de-duplicate legacy ABI test suites via inheritance	Collapses the via-fallback test file to thin subclasses over the standalone-legacy base (review feedback, −4,384 lines)
fix(test-utils): pass legacyImpl to the 3-arg BoundlessMarket constructor	Regenerates the Rust market bindings (build.rs / bytecode.rs) for the 3-arg constructor and points the Rust test harness's legacyImpl at a non-functional stub
fix(contracts): resolve legacyImpl in manage deploy/upgrade scripts	Manage.s.sol DeployBoundlessMarket/UpgradeBoundlessMarket resolve legacyImpl (deploy-if-zero from config / preserve the deployed market's existing LEGACY_IMPL); the deployment-scripts CI job sets BOUNDLESS_LEGACY_IMPL to a non-functional stub
test(contracts): migrate deployment-test to the new batched ABI	deployment-test/Deploymnet.t.sol exercises the new market via the batched fulfill (it had imported legacy types while calling the batched API)
test(contracts): stub the legacy impl in the BoundlessMarket harness	BoundlessMarket.t.sol points legacyImpl at a non-functional stub instead of deploying a real BoundlessMarketLegacy — the suite never calls the legacy ABI (that lives in test/legacy/)

[linear]

BM-3037