feat(api): bridge API — deposit quotes, registration, status

[sadiq1971]

Part of #358 and epic #361. Stacked on #374 (xreserve adapter) — review the last two commits until #374 merges.

What

Token-agnostic bridge endpoints on the api-server (pkg/bridgeapi). The dapp never encodes a bridge transaction: it asks for a quote — fully ABI-encoded unsigned transactions — signs blindly, then registers the sent tx hash for status tracking. The EVM mirror of the Canton prepare/execute pattern; one dapp flow for every token, present and future.

Endpoints

• GET /api/v2/bridge/tokens — bridgeable tokens (symbol, mechanism, decimals, fee, indicative ETA)
• POST /api/v2/bridge/deposit/quote (auth) — {token, amount} → {chain_id, steps[], fees, estimated_seconds}. Steps: conditional ERC-20 approve + the mechanism's deposit call. Recipient encoding (keccak256(partyId) + party id in hookData for xreserve) is resolved server-side from the authenticated user's Canton party and never leaves the server. Quoting is stateless — a pure encoding function, nothing persisted, quotes can be re-requested freely.
• POST /api/v2/bridge/deposits (auth) — {token, amount, tx_hash} → forwards to the relayer's POST /api/v1/transfers. Token/amount are re-validated and the recipient party is re-derived from the authenticated session, never taken from the caller. No quote binding is needed: the chain is the source of truth, and a registration with wrong parameters only yields a status row the adapter never completes.
• GET /api/v2/bridge/transfers/{id} — relayer status proxy (status + stage)

Auth is the existing per-handler X-Signature/X-Message EIP-191 pattern (same as pkg/transfer).

Design points

• DepositQuoter per mechanism, xreserve first. The xreserve quoter's depositToRemote calldata is round-trip tested (unpack + assert every argument, including the keccak recipient hash). The ABI follows Circle's published interface; mainnet verification is a chore(bridge): hardening + mainnet enablement #360 item.
• Allowance check is optional: with eth_rpc_url configured, an eth_call decides whether to include the approve step; unset (or on RPC failure) the approve step is always included — a redundant approve is safe, a missing one strands the deposit. This keeps the api-server free of a hard outbound-EVM dependency.
• Config: new optional bridge block on APIServer (relayer_url, chain_id, optional eth_rpc_url, per-token mechanism/evm_address/decimals/xreserve{contract, remote_domain, max_fee}). Omitted → no routes mounted.

Not in this PR

• List-by-address (GET /bridge/transfers?address=) — needs an address filter on the relayer list endpoint; follow-up.
• Withdraw prepare/execute — that's feat: USDCx outbound — burn via BridgeUserAgreement + release tracking #359, next in the stack.

Testing

• Quoter: full calldata round-trip assertions; allowance sufficient/low/error paths
• Service: quote happy path + validation matrix (unsupported token, bad amounts, precision overflow, unregistered user); registration derives recipient from session + validation matrix
• golangci-lint clean; config tests pass with the new optional field

[codecov-commenter]

Codecov Report

❌ Patch coverage is 38.53211% with 201 lines in your changes missing coverage. Please review.
✅ Project coverage is 35.27%. Comparing base (864d5ff) to head (2e1fdd7).

Files with missing lines	Patch %	Lines
pkg/bridgeapi/http.go	0.00%	74 Missing ⚠️
pkg/bridgeapi/relayer.go	0.00%	53 Missing ⚠️
pkg/bridgeapi/allowance.go	0.00%	22 Missing ⚠️
pkg/app/api/server.go	0.00%	21 Missing ⚠️
pkg/bridgeapi/service.go	81.72%	9 Missing and 8 partials ⚠️
pkg/bridgeapi/xreserve.go	79.66%	6 Missing and 6 partials ⚠️
pkg/bridgeapi/config.go	60.00%	1 Missing and 1 partial ⚠️

❌ Your patch status has failed because the patch coverage (38.53%) is below the target coverage (50.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@                    Coverage Diff                    @@
##           feat/xreserve-inbound     #375      +/-   ##
=========================================================
+ Coverage                  35.24%   35.27%   +0.03%     
=========================================================
  Files                        170      176       +6     
  Lines                      13243    13569     +326     
=========================================================
+ Hits                        4667     4787     +120     
- Misses                      8198     8390     +192     
- Partials                     378      392      +14     

Flag	Coverage Δ
unittests	35.27% <38.53%> (+0.03%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
pkg/config/config.go	71.18% <ø> (ø)
pkg/bridgeapi/config.go	60.00% <60.00%> (ø)
pkg/bridgeapi/xreserve.go	79.66% <79.66%> (ø)
pkg/bridgeapi/service.go	81.72% <81.72%> (ø)
pkg/app/api/server.go	0.00% <0.00%> (ø)
pkg/bridgeapi/allowance.go	0.00% <0.00%> (ø)
pkg/bridgeapi/relayer.go	0.00% <0.00%> (ø)
pkg/bridgeapi/http.go	0.00% <0.00%> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.