feat(deposit-address): env-gated per-lane bridgeOverride on v3 executes

[ashwinrava]

Motivation

The quote-api's POST /deposit-addresses/execute accepts an ops escape hatch, bridgeOverride: "cctp" | "spokepool" | "oft", but the sweeper never sends it — lane selection is always the API's amount-aware router. That leaves no operational lever to (a) force a healthy rail during a lane incident (e.g. an Iris outage failing CCTP quotes) or (b) exercise lanes the router never picks (the dedup rule prefers spokepool over oft for the same input, so OFT sweeps can only be tested by hand-broadcasting).

Change

Per-lane forced bridge on v3 executes, dark by default and double-gated (the ENABLE_* pattern used by ENABLE_EXECUTE_INPUT_TOKEN / ENABLE_EXECUTE_ERC20_TRANSFER_METADATA):

• ENABLE_EXECUTE_BRIDGE_OVERRIDE=true — master gate; off ⇒ requests are byte-identical to today.
• EXECUTE_BRIDGE_OVERRIDES — JSON map "originChainId:inputToken:destinationChainId" → "cctp" | "spokepool" | "oft" (input token lowercased, origin-chain-native encoding). Config parsing fails fast on malformed JSON, malformed lane keys, or unknown bridge values.
• _getExecuteTx looks up the funded lane and, on a hit, includes bridgeOverride in the execute request (debug-logged). No entry ⇒ field omitted ⇒ the API's router decides, exactly as today.

Safe by construction: the API clamps bridgeOverride to the committed executable lane set for (origin, inputToken, destination) — a stale or wrong entry produces a typed 400, never a mis-signed or wrong-lane sweep. The bot adds no routing logic of its own.

Tests

Three new cases in test/DepositAddressHandler.ts: override applied on a lane match, omitted on a miss, omitted when the gate is off despite a match. 51 passing locally; the 3 pre-existing executionFeeRecipient checksum-casing failures reproduce identically on clean master and are untouched.

Rollout

Intended for the test bot first (flag on + a single OFT lane entry to validate the Arbitrum USDT → HyperEVM lane through the production path), default-off everywhere else. Requires no API change — the endpoint already accepts the field.

🤖 Generated with Claude Code