How sponsorship works
Sponsorship is not a separate feature bolted onto settlement. For theexact scheme it is the settlement mechanism. At settle time the facilitator loads its own signer account, rebuilds the transaction with that signer as the transaction source, and pays BASE_FEE + minResourceFee out of its own XLM. The buyer’s contribution is only the signed authorization entry that moves the asset; the buyer is never the transaction source and holds no XLM.
Because the source is the facilitator and the transfer from is the buyer, sponsorship and the non-custodial invariant are the same on-ledger fact seen from two sides. On transaction 3f6031ed…, fee_charged is 22973 stroops (about 0.0023 XLM) paid by the facilitator’s source account.
areFeesSponsored is computed, never declared
/supported advertises extra.areFeesSponsored: true, and the flag must reflect reality rather than be advertised falsely. Rail402 makes that impossible to get wrong: the flag is derived from the actual running configuration, and startup refuses to boot with FEES_SPONSORED=false, because the exact scheme’s settle path is the sponsoring rebuild. There is no non-sponsoring code path to honestly advertise as false, so a facilitator that cannot sponsor cannot start and claim it can.
The
/supported contract is generated from the same scheme registry the facilitator settles with, so an advertised capability is always a reachable one.The fee ceiling
Sponsoring the fee means the facilitator signs a transaction whose fee it pays. Left unbounded, a settlement with a large simulated resource fee could cost the sponsor far more than expected.MAX_TRANSACTION_FEE_STROOPS is the guard: the facilitator refuses to sign a settlement whose simulation-derived fee exceeds it, with a legible reason rather than a silent overspend.
The ceiling is enforced on both schemes, but by different code:
exactis enforced inside@x402/stellarduring verify (settlementFeeStroops = minResourceFee + BASE_FEE).uptois enforced by Rail402’s own facilitator code before signing (scheme-upto-stellar/src/facilitator.ts). This was added deliberately: theuptopath did not originally check the ceiling, so a smart-account settle at about 174k stroops would have been signed under a 100k ceiling. It now refuses withinvalid_upto_stellar_payload_fee_exceeds_maximum.
Why the deployed ceiling is raised
Two Stellar realities push the fee well above a plain keypair payment, and an operator serving those cases must raise the ceiling. This is a documented deployment requirement, not a test artifact.
A smart-account payment cross-calls a signature verifier and a spending policy, so its Soroban resource fee is 7 to 9 times a keypair’s. And on a congested ledger the simulated resource fee for a metered USDC settlement rose past 3M stroops. The Railway deployment sets the ceiling to 10,000,000 so both cases settle. The 100k default correctly refuses them, with a reason, on a facilitator that has not opted in.
Throughput without a fee bottleneck
Sponsorship means every settlement is signed by the facilitator’s account, which raises a sequence-number question under bursty agent traffic. Rail402 handles it with a channel-account pool and, optionally, fee-bump transactions, covered in Stellar-specific engineering. A fee-bump wrapper additionally decouples who pays the fee from whose sequence number advances, so fee payment and sequencing can scale independently.Next steps
The settlement path
Where the sponsoring rebuild sits in verify and settle.
Throughput
Channel accounts and per-signer sequence lanes.
Smart accounts
Why a contract account costs more to settle.
Configuration
Every fee and sponsorship setting an operator controls.