BM-2957: feat(contracts): decouple verification via BoundlessRouter

[jonastheis]

Summary

Decouple per-class verification dispatch from BoundlessMarket by introducing a governance-controlled BoundlessRouter. The market becomes a thin orchestrator: it binds each fill's slim payload to a client-signed request digest, then hands the batch to the router. The router resolves the seal's first-4-byte selector to a registered adapter, dispatches to the right per-fill interface, and tail-calls the class's required assessor adapter once per batch.

Adding new verifier classes — alternate zkVMs, signature-backed joint verifiers, future proof systems — no longer touches BoundlessMarket.sol. New classes plug in by registering an adapter address under a class id.

Architecture

Entry point is BoundlessMarket.fulfill(FulfillmentBatch[]). Each batch carries (SlimRequest[], Fulfillment[], assessorSeal, prover).

BoundlessMarket.fulfill(FulfillmentBatch[])
│
├─ _bindAndCollectDigests
│    reconstruct EIP-712 digest from slim payload
│    verify against lock / priced FulfillmentContext
│
├─ ROUTER.verifyBatch(batch, requestDigests)
│   │
│   ├─ resolve verifier class from seal[0:4]
│   │
│   ├─ per fill  (gas-bounded staticcall, try/catch)
│   │   │
│   │   ├─ verifier class
│   │   │    → IBoundlessVerifier.verify(seal, claimDigest)
│   │   │
│   │   └─ joint class
│   │        → IBoundlessJointVerifierAssessor.verifyJoint(
│   │              slim, fill, requestDigest, prover)
│   │
│   └─ if verifier class
│        → IBoundlessAssessor.verifyAssessor(batch, requestDigests)
│          (calldata tail-call optimization)
│
└─ _settleBatch
     credit prover · refund / charge client · fire callback

Three interfaces define the seam taxonomy:

• IBoundlessVerifier — per-fill cryptographic check; sees (seal, claimDigest) only. Pairs with a separate assessor seam.
• IBoundlessJointVerifierAssessor — per-fill combined seal verification + request-claim-prover binding. Skips the assessor seam.
• IBoundlessAssessor — per-batch fulfillment-check binding. Terminal — referenced by verifier classes via requiredAssessorClass, never selected as a verifier class.

Contracts in this PR

Area	File	code	comment	Notes
Router core	src/router/BoundlessRouter.sol	274	283	Two-mapping registry (entries + classes), namespace invariants, permanent tombstoning, governance-gated mutations. UUPS-upgradeable.
	src/router/interfaces/IBoundlessRouter.sol	5	19	Fulfill-path-only seam for callers.
	src/router/interfaces/IBoundlessVerifier.sol	4	15
	src/router/interfaces/IBoundlessAssessor.sol	5	54
	src/router/interfaces/IBoundlessJointVerifierAssessor.sol	8	46
Adapters	src/router/adapters/R0BoundlessVerifierAdapter.sol	17	41	One adapter per pinned R0 selector; immutable underlying verifier.
	src/router/adapters/R0BoundlessAssessorAdapter.sol	72	81	Reconstructs today's R0 assessor journal from the slim payload + fills + universal prover arg.
Types	src/types/SlimRequest.sol	35	57	Per-fill EIP-712-reconstructable payload (predicate + callback + selector + 3 digests).
	src/types/FulfillmentBatch.sol	9	36	{ requests, fills, assessorSeal, prover }.
	src/types/ProofRequestBatch.sol	6	17	Priced-path companion.
Market rewrite	src/BoundlessMarket.sol	593	191	Constructor (BoundlessRouter, collateralToken). fulfill / priceAndFulfill / submitRootAndFulfill* take FulfillmentBatch[]. AssessorReceipt gone; request-derived data sourced from binding-verified slim payloads.
	src/IBoundlessMarket.sol	110	220	Interface mirror.
Scripts	scripts/Deploy.Router.s.sol	54	29	Router proxy deploy + R0 class registration.
	scripts/Manage.Router.s.sol	74	37	RegisterR0Verifier / RegisterR0Assessor / RemoveEntry.

Plus updates to scripts/Deploy.s.sol, scripts/Manage.s.sol, src/libraries/BoundlessMarketLib.sol, src/types/Fulfillment.sol; deletion of src/types/AssessorReceipt.sol; regenerated crates/boundless-market/src/contracts/artifacts/ + bytecode.rs.

Tests

Area	File	code	comment	What it covers
Router	test/router/BoundlessRouter.registry.t.sol	657	39	All addClass / instantiate / removeClass / removeEntry invariants.
	test/router/BoundlessRouter.dispatch.t.sol	593	105	verifyBatch dispatch tree: class resolution, signed-selector matching, per-fill catch, assessor seam.
	test/router/RouterTestBase.sol	139	25	Minimal shared fixture (empty router; per-test class/entry setup).
	test/router/BenchBase.sol	277	77	Bench fixture with a pre-registered R0 adapter ecosystem.
	test/router/RouterBench.t.sol	39	44	Router dispatch overhead measurements.
	test/router/AdapterBench.t.sol	60	16	R0 adapter wrapping cost.
	test/mocks/RouterMocks.sol	105	58	Null / Reverting verifier / assessor / joint mocks; NullRiscZeroVerifier.
Adapter	test/router/R0BoundlessAssessorAdapter.t.sol	184	41	Length / seal-format gating, journal-digest reconstruction, sparse arrays, four tamper variants.
	test/router/R0AssessorImageRotation.t.sol	89	60	Parallel old/new selectors; post-tombstone lifecycle on a single locked request.

The rewritten test/BoundlessMarket.t.sol (1979 changed lines) ports the existing market suite onto the new architecture — locked / never-locked / partial-payment paths, smart-contract signatures, callbacks, set-builder R0 fixtures, slim-payload binding coverage.

Key design decisions

• Slim per-fill payload. SlimRequest carries predicate, callback, and selector in full plus imageUrlHash, inputDigest, offerDigest. The market reconstructs the EIP-712 struct hash from these fields and compares against the digest stored at lock time (or in transient storage from priceRequest). Once the comparison passes, every slim field is bound to the client-signed request — downstream consumers (router, adapters, callback dispatch) trust the payload without re-verification.
• Universal prover arg. Threaded through the router into both IBoundlessJointVerifierAssessor.verifyJoint and IBoundlessAssessor.verifyAssessor as the address the market will credit / slash. Each adapter binds it via its own mechanism (R0 STARK journal commitment, signature payload, attestation message). The market trusts the value uniformly.
• Two-namespace registry with permanent tombstoning. entries[selector] pins a concrete impl; classes[classId] groups conformant adapters with shared interface tag, required assessor class, and gas defaults. Both maps share a bytes4 namespace; tombstoning is permanent so an EIP-712-signed request can never be silently repointed by a later registration. removeClass refuses to tombstone a class with live entries (entriesPerClass counter is the guard).
• Calldata tail-call optimization. BoundlessRouter.verifyBatch(FulfillmentBatch, bytes32[]) and IBoundlessAssessor.verifyAssessor(FulfillmentBatch, bytes32[]) share an ABI tail, so the assessor staticcall reuses verbatim calldata via a single calldatacopy — skipping ABI re-encoding for the batch payload.
• Image-id rotation = router-level ceremony. Each R0BoundlessAssessorAdapter is immutable per image id. To rotate: deploy a fresh adapter at a new selector under the existing R0_ASSESSOR class, run both in parallel during broker transition, then removeEntry(oldSelector) to tombstone. The lock binds no assessor selector, so brokers holding locks can switch selectors at fulfillment time without re-locking.
• Joint adapter deferred. The IBoundlessJointVerifierAssessor interface ships as part of the seam taxonomy; no production impl in this PR. The dispatch path is fully covered by RouterMocks.NullJoint / RevertingJoint in the test suite.

[linear]

BM-2956

BM-2957

[capossele]

Thinking a bit about this, in the new path, BoundlessMarket._verifySubBatch passes only requestDigests, claimDigests, seals, and signedSelectors to the router. The R0 assessor adapter then reconstructs leaves using env.fulfillmentDataDigests supplied inside the prover-controlled assessor envelope. But the market later decodes callback data from fill.fulfillmentData.
Before, the market computed fill.fulfillmentDataDigest() itself before building assessor leaves. With this change we are losing that binding. A prover can satisfy the assessor against one fulfillment-data digest while passing different fulfillmentData to the callback path.

The market should compute fulfillment-data digests from sb.fills[I] and pass them through the router/assessor interface. So maybe we could extend IBoundlessAssessor.verifyAssessor and BoundlessRouter.verifySubBatch to include bytes32[] fulfillmentDataDigests?

[capossele]

after deriving this, the contract should either check fill.requestDigest == requestDigest, as we emit the provided one rather than the one we recompute

[willpote]

Previously for fulfill and submitRootAndFulfill it wasn't required for the prover to post the ProofRequest which was intended to save gas on the hot path (LockAndFulfill). It seems now every fulfill path takes SubBatch which includes the full ProofRequest, so the hot path will take a gas hit

Was this required for the refactor? If not maybe we introduce a

struct LockedSubBatch {
    Fulfillment[] fills;
    bytes         assessorSeal;
    address       prover;
}

or something to keep the previous behavior?

[jonastheis]

It adds indeed quite some gas. I just checked for ~100 requests:

• Mean ABI-encoded ProofRequest size: ~1024 bytes (sample is dominated by order-generator traffic which is fairly uniform, but it's representative of
  the actual hot-path workload).
• Calldata cost per fill: ~1024 bytes × ~14 gas/byte (mixed nonzero/zero) ≈ ~14k gas/fill.
• Plus EIP-712 re-derivation per fill: ~5k gas/fill.
• Total: ~19k extra gas per fill vs. a LockedSubBatch-shaped hot path.

[willpote]

(Related to my other comment about passing ProofRequest into all the fulfill endpoints)

Previously the assessor did two things:

1/ proving each claimDigest is a valid answer for its requestDigest, and prover is who produced it.
2/ surfacing the selector and callback.{addr, gasLimit} to the market so it could dispatch the callback and feed the router.

In this PR the market now gets selector/callback from ProofRequest[] in calldata, which is now possible because the full ProofRequest are now also posted in fulfill and submitRootAndFulfill

If we address my other comment and end up making ProofRequest not required, I think we need to change verifyAssessor to return the selectors/callbacks like:

function verifyAssessor(
        bytes32[] calldata requestDigests,
        bytes32[] calldata claimDigests,
        address prover,
        bytes calldata assessorSeal
    ) external view returns (
        bytes4[] memory signedSelectors,
        Callback[] memory callbacks
    );

[jonastheis]

2/ surfacing the selector and callback.{addr, gasLimit} to the market so it could dispatch the callback and feed the router.

This is the main reason I wanted to move the proof request to the calldata. I don't think this is a clean separation of concerns.

I get the concern about the gas cost. So there's clear motivation to avoid this. Especially for every request when most not even use the callback.

Extending the interface to return this data is imo also not super clean as this implies that every Assessor implementation needs to pass this data via seal and decode it internally.

Another option might be to store this data on lock request conditionally if the request has a callback and then load it in fullfill. This way the assessor doesn't need to provide it and most requests don't pay for it.

[willpote]

I don't fully understand the need for the class layer in the router, it seems it gives us:

1. Verifier -> assessor binding, gas limit, schema artifact set once per class.
2. A distinction between permissionless and non-permissionless verifiers
3. A way to bulk disable verifiers

But seems to add a lot of code + complexity, especially as verifiers are rarely added / removed so the potential duplication of things like assessor address, verifier etc doesn't seem like a big deal?

Am i missing something as to why this is important?

[jonastheis]

The class layer buys us four things (the last 3 you mentioned already):

1. Sign-many selector semantics. A requestor can sign a class id and accept any entry under that class. Without classes, every requestor pins one specific selector (or signs 0x00 and gets exactly the one default impl) — they can't say "any R0 verifier flavor is fine."
2. Required-assessor binding. The verifier↔assessor pairing lives on the class, not on each entry. Adding a 4th R0 verifier flavor doesn't risk it being wired to the wrong assessor.
3. Permissionless-tier convenience. A reserved-prefix policy (we already have RESERVED_PREFIX_MASK = 0xff000000) gates who can register just as well in a flat design. What classes still buy you is bundling the conformance constraints — permissionless registrants inherit (interface tag, required assessor, gas limit, schema) from the class instead of picking those values themselves. Without classes a permissionless registrant could pair their impl with a bogus assessor, but that just self-rugs at verify time, not a soundness issue.
4. Bulk disable + permissionless gate. One removeClass tombstones the whole group; one permissionlessInstantiate flag gates a whole group.

If we want to simplify, we'd flatten to one mapping: each entry carries its own (assessor, gasLimit, schema, permissionless), shrinks the contract by ~100 LOC, and means adding a 4th R0 verifier means duplicating the assessor pointer in storage — which, as you point out, isn't a big deal at v1 scale.

imo the class is really only necessary if we want to enable the flexibility of 1.

[willpote]

Overall looks good, will give a more in depth review once we have test / new gas snapshot numbers. For now just feedback on the API design / naming

[willpote]

Thoughts on having a wrapper to 1/ avoid these 2d arrays, 2/ more symmetry to SubBatch?

e.g.

struct ProofRequestBatch {
    requests: ProofRequest[]
    signatures: bytes[]
}

[willpote]

Also how about rename SubBatch -> FulfillmentBatch?

Then API is more intuitive and clearer imo:

priceAndFulfill(
    ProofRequestBatch[] requestBatches;
    FulfillmentBatch[] fulfillmentBatches;
)