Implement fee-bump transaction support for sponsored accounts with zero XLM balance

[prodbycorne]

Problem

New Stellar accounts with no XLM cannot pay transaction fees. SmartDrop targets early-stage token participants who may have only the staking asset (e.g. a project's custom token) but no native XLM for fees. Without fee-bump support, these users are blocked from depositing.

Expected Behaviour

When the app detects that the connected wallet's XLM balance is below the minimum fee reserve, it offers to wrap the user's transaction in a fee-bump envelope signed by a sponsor keypair (provided via environment variable or a backend endpoint). The sponsor pays the fee; the inner transaction is signed by the user.

Acceptance Criteria

• src/lib/soroban.ts gains a buildFeeBumpTransaction(innerTx, sponsorPublicKey, networkPassphrase) utility using TransactionBuilder.buildFeeBump from the Stellar SDK
• SorobanService.lockAssets and unlockAssets detect XLM balance < fee threshold (fetched via fetchAccountBalances) and switch to fee-bump mode automatically
• The sponsor public key comes from process.env.NEXT_PUBLIC_FEE_SPONSOR_PUBLIC_KEY; the sponsor signature is obtained from a backend API route POST /api/sign-fee-bump that receives the inner XDR and returns the signed fee-bump XDR
• The API route is an optional Next.js Route Handler (src/app/api/sign-fee-bump/route.ts) that uses the sponsor secret stored in STELLAR_FEE_SPONSOR_SECRET (server-side only, never exposed to the browser)
• A warning banner in the deposit modal informs users when fee-bump mode is active: "Your fees are sponsored for this transaction"
• A Vitest test constructs a mock inner transaction and verifies buildFeeBumpTransaction wraps it correctly (correct source, fee, inner tx)

Relevant Files

• src/lib/soroban.ts — buildFeeBumpTransaction, integrate into lockAssets / unlockAssets
• src/app/api/sign-fee-bump/route.ts — create new API route
• src/lib/stellar.ts — fetchAccountBalances (needed for XLM check)

[collinsezedike]

The critical part of this design is keeping the sponsor secret strictly server-side, the spec is explicit about this, and it's the kind of boundary that's easy to accidentally leak through a misconfigured env var or an API route that returns too much.

Here's my plan:

• src/lib/soroban.ts: buildFeeBumpTransaction(innerTx, sponsorPublicKey, networkPassphrase) using TransactionBuilder.buildFeeBump
• fetchAccountBalances in stellar.ts checked inside lockAssets/unlockAssets; if XLM balance is below the fee threshold, switch to fee-bump mode automatically
• src/app/api/sign-fee-bump/route.ts: new Route Handler accepting inner XDR, signing the fee-bump envelope server-side with STELLAR_FEE_SPONSOR_SECRET (never sent to the client), returning only the signed fee-bump XDR
• Sponsor public key read from NEXT_PUBLIC_FEE_SPONSOR_PUBLIC_KEY on the client side for constructing the unsigned envelope
• Warning banner in the deposit modal: "Your fees are sponsored for this transaction" when fee-bump mode is active
• Vitest test constructing a mock inner transaction and asserting the fee-bump wraps it with correct source, fee, and inner tx

Happy to start as soon as I'm assigned.