feat(auth-capture/facilitator): make settle feeBps + delegated feeReceiver a facilitator policy

[A1igator]

Closes #64.

Problem

The auth-capture facilitator hard-coded two settle-time values that the merchant's signature actually leaves open as a choice within signed bounds:

1. feeBps — hard-coded to paymentInfo.minFeeBps. The signature commits only to the band [minFeeBps, maxFeeBps]; the escrow's _validateFee accepts any in-band value. So for any captureAuthorizer that honors the forwarded fee (EOA path, thin pass-throughs), the fee was always the floor and maxFeeBps was dead.

2. feeReceiver — hard-coded to paymentInfo.feeReceiver. Per the scheme spec, feeRecipient may be set to address(0) "to let the captureAuthorizer specify any non-zero recipient at capture/charge time." The facilitator never supplied one, so that delegation path was dead: feeRecipient = address(0) with maxFeeBps > 0 pairs feeBps > 0 with receiver 0 → on-chain ZeroFeeReceiver revert. The delegated receiver could never be paid.

Both are the same defect: a knob the spec exposes for settle-time choice, silently collapsed to one value because the facilitator had no input to pick from. Picking within those bounds is the settle-time operator's discretion, and in x402's facilitator-submits flow the facilitator is that operator — so the choice belongs to facilitator config, not the merchant-authored wire extra.

Changes

• Add optional selectFeeBps and selectFeeReceiver policies to the AuthCaptureEvmScheme constructor (AuthCaptureFacilitatorOptions).
  • selectFeeBps defaults to the band floor (minFeeBps).
  • selectFeeReceiver is consulted only when the merchant delegated (feeRecipient == address(0)); a configured non-zero recipient is passed through unchanged, because the escrow forces a match.
• One resolveFee returning { feeBps, feeReceiver }, shared by settle and simulateSettle, so neither value can drift between simulate and submit (issue Q3 — lockstep is now structural).
• Validate before submitting: an out-of-band feeBps → fee_bps_out_of_range; a non-zero fee with a zero receiver → zero_fee_receiver. Both mirror the escrow's own custom errors, so a misconfigured facilitator fails fast with a clean typed reason instead of an opaque on-chain revert.

Backward compatibility

Defaults reproduce the old behavior exactly — floor feeBps + the configured recipient — so a facilitator that passes no options is unchanged. The new policies are an optional 2nd constructor arg.

Not changed

• No contract change. Contracts that recompute the fee (e.g. PaymentOperator) are unaffected — the forwarded values are inert for them.
• No wire-format / extra change. The merchant's knobs stay the band and feeRecipient (incl. the address(0) delegation the spec already documents).

Tests

settle — facilitator feeBps policy and settle — feeReceiver delegation suites cover: defaults (floor + configured recipient); in-band/delegated values forwarded to both the charge args and the simulation; out-of-band feeBps and fee-with-zero-receiver rejected before any writeContract; configured recipient passed through with the policy not consulted; and zero receiver allowed when no fee is taken. 132/132 unit tests pass.

Note: tests are unit-level against a mocked signer (same as the existing suite); the on-chain _validateFee / ZeroFeeReceiver behavior this relies on is taken from the scheme spec + escrow error surface, not re-verified against a live escrow here.

🤖 Generated with Claude Code

[vraspar]

I think the overall direction is sound: choosing the settle-time fee in facilitator config does not expand payer authorization because the payer still signs the [minFeeBps, maxFeeBps] band and the escrow enforces it. I also do not see this requiring a client or wire-format change; keeping it out of extra is the right boundary.

That said, I think this needs a docs/precision pass before merge. The current wording makes stronger guarantees than the code can provide for arbitrary selector callbacks, and the scheme spec still contradicts the implementation around settlement arg shape. Those are exactly the kinds of details future facilitator authors will cargo-cult, so I would rather fix them now while this PR is touching the fee policy surface.

One additional top-level note because the spec file is not in this diff: specs/schemes/auth-capture/scheme_auth_capture_evm.md still says settlement calls authorize/charge with only (paymentInfo, amount, tokenCollector, collectorData), and still describes Permit2 collector data as ABI-encoded. The implementation now uses the six-arg charge tail for fee policy and passes the raw Permit2 signature, so the spec should be brought back into sync or future implementers can rebuild the old broken path.

[vraspar]

The helper is shared, but settle() still calls the selector once during verify()/simulateSettle and then again before writeContract. A stateful or time-dependent selector can therefore simulate one in-band fee/receiver and submit another, so the “can never drift” guarantee is stronger than the code actually enforces. Either resolve the fee once for the settle path and reuse the same values for simulation + write, or explicitly require deterministic/pure selectors and soften the lockstep language/tests around this.

[vraspar]

This wording can read as if the constructor policy controls both charge and later two-phase capture, but the implementation only consults the selectors when facilitator settle() chooses charge (autoCapture: true). For authorize/two-phase flow, capture-time fee choice is still the captureAuthorizer’s job. I’d narrow this section to “facilitator-submitted charge” and trim the repeated rationale so facilitator authors do not infer an upstream client/wire-format change is needed.