Bound Soroban RPC calls, add an explicit rail failover policy, and propagate request ids

[Maryermarh]

Summary

Closes four issues assigned to this account, all in the payments module.

Soroban RPC timeout (#1784)
Every RPC call — getAccount, simulateTransaction, sendTransaction, getTransaction — is now bounded, so a hung testnet/mainnet endpoint can no longer hold a request open indefinitely. The call is wrapped in the existing withTimeout helper and the budget comes from SOROBAN_RPC_TIMEOUT_MS (default 10000), validated at construction so a malformed value fails fast instead of creating an unbounded client.

A timeout is deliberately treated as transient, not terminal: a hung endpoint is an outage, not a verdict that the payment failed, so it retries within that endpoint's budget and then fails over to the next configured endpoint exactly like a connection error. SorobanRpcTimeoutError extends TransientRpcError so it flows through the existing isRetryable predicate. The docs and the log line both say so explicitly.

Rail failover policy (#1783)
The issue's framing was accurate: the registry threw, and the request just failed. Failover is now an explicit, opt-in policy rather than an implicit behaviour.

The important constraint is that a Payment stores its rail, and both the webhook and reconciliation paths resolve the adapter from that stored value. Switching rails for a payment that already exists would send its confirmation to the wrong adapter. So failover applies at initiation only:

• PaymentRailRegistry gains isAvailable(rail) and resolve(rail), which follows ordered PAYMENT_RAIL_FAILOVER edges (FROM=TO, comma-separated) and returns the first available rail.
• The Payment row stores the rail that was actually used; the requested rail is retained in metadata.requestedRail, and a WARN is logged when they differ.
• The strict get(rail) path is untouched and is still what webhook, reconciliation and refund use, so those always resolve the adapter that initiated the payment. getPaymentsService also compares the requested rail on an idempotency replay, so a replayed request is not mistaken for a different payload.
• Cycles, duplicate mappings and unknown rail names are rejected with explicit errors rather than silently ignored.

payments/adapters/README.md documents the policy: what failover means, when it applies, how to configure it, the degraded behaviour when no fallback is available, and what is deliberately not covered.

Request ID propagation (#1782)
Added outboundRequestHeaders() as the single source of truth. It returns both header names the middleware already accepts on inbound (x-request-id and x-correlation-id), so an id survives a full round trip, and returns an empty object when no request context is active — a placeholder id is never manufactured for background work. It is applied to:

• the manual-review SMTP alert, via nodemailer's message headers (a genuinely verifiable outbound propagation);
• the Soroban RPC transport, through the seam the pinned SDK exposes, with a documented type-guard so a future SDK that removes it degrades to log-only correlation instead of breaking.

The JSDoc is explicit that a third-party provider which does not accept custom headers cannot be made traceable by adding fields to that object.

Currency math audit (#1785)
The honest finding, rather than a manufactured bug: payments/utils contained no currency math (only with-timeout and retry-with-backoff), and the real basis-point allocation in credits/split-allocation.ts already used guarded integer arithmetic (Math.floor/% with a MAX_SAFE_INTEGER check). So no correct code was rewritten.

Instead:

• The audit was run across the whole backend for parseFloat, Number(), toFixed, Math.round, percentage and money arithmetic. No floating-point currency defect was found; the remaining Number(...) sites convert database integers or an enum, and toFixed/retry-jitter/TTL math are non-currency.
• payments/utils/minor-units.ts adds a strict, integer-only primitive so future payment code has a safe, audited helper instead of reaching for float math: it rejects non-integer/negative/NaN/unsafe values with a typed error, rejects an amount that cannot be scaled exactly rather than silently losing precision, and apportions by largest remainder so allocations always sum exactly to the input.
• credits/split-allocation.spec.ts gained regression assertions locking in the existing integer guarantee.

minor-units.ts is intentionally a separate primitive from split-allocation.ts — the latter is a configurable, tie-broken allocation with sort-order semantics and is left alone.

Configuration

Variable	Default	Purpose
SOROBAN_RPC_TIMEOUT_MS	10000	Per-RPC-call timeout; a timeout is transient and triggers failover
PAYMENT_RAIL_FAILOVER	unset	Ordered FROM=TO failover edges, initiation only

Testing

Per the task constraints, no install, build, lint, or test run was performed — the maintainer runs those manually. No new dependencies were added, so package-lock.json is unaffected.

New specs: payments/utils/minor-units.spec.ts, common/request-context.spec.ts. Extended: payment-rail-registry.spec.ts, payments.service.spec.ts, reconciliation.service.spec.ts, soroban-rpc-client.spec.ts, credits/split-allocation.spec.ts.

Reviewer notes

• A timed-out RPC call cannot cancel the underlying HTTP request: the caller stops waiting and fails over, but a late completion on the abandoned endpoint is still possible. That is inherent to abandoning a promise and is documented in the code.
• Rail availability means "configured and registered", not a live health probe. The adapters have no health-probe contract, and a provider error after initiation is deliberately not switched to another rail, since that could duplicate a side effect.
• Soroban header propagation depends on a seam exposed by the pinned stellar-sdk version; the type guard means removing it degrades to log-only correlation rather than failing.

Closing issues

Closes #1785
Closes #1784
Closes #1783
Closes #1782

[vercel]

@Maryermarh is attempting to deploy a commit to the naijabuz's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@Maryermarh Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits