fix: real Stellar submission for sendPayment (closes #63)

[christabel888]

Closes #63.

Root cause (not just "fixed the bug")

app/api/wallet/send/route.ts validated request shape and then returned a fabricated result:

const hash = `0x${Math.random().toString(16).slice(2, 66)}`
const result = { success: true, hash, status: 'completed' }

No transaction was ever built, signed, or submitted, and 0x-prefixed hex isn't even a valid Stellar tx hash shape. wallet.service.ts::sendPayment compounded this by persisting every attempt as status: 'completed' regardless of what the route returned — so fixing the route alone would not have fixed local transaction history.

Full root-cause writeup, the backend-vs-direct-SDK design decision and why, and everything below in more detail: docs/issue-63.md.

Design decision

Chose direct @stellar/stellar-sdk usage inside this app's own route over proxying to Orbit-Wal/backend's /api/v1/wallet/send: that endpoint needs a raw sourceSecretKey in the request body, and Globe Wallet has no secret-key storage anywhere in its account model — proxying would add a second network hop and a second service to configure without removing the actual hard part (key custody). @stellar/stellar-sdk is already a direct dependency here and already used server-side (transaction-sync.service.ts, soroban.service.ts), so this builds on existing, proven integration instead of adding new cross-service surface area.

Real submission needs a signing key this app doesn't have anywhere (the mock accounts are placeholder public keys with no secret, by design — this is a demo/mock wallet). Rather than inventing fake custody, I added a server-only STELLAR_SOURCE_SECRET_KEY env var (optional — unset by default, a fresh checkout still boots). If it's unset, the route fails loud with 503 ERR_PAYMENT_NOT_CONFIGURED instead of fabricating anything (same pattern as the existing SorobanService.requireConfig()). Real per-account custody is explicitly called out as follow-up work, not something this issue tries to solve.

Definition of done — addressed explicitly

• Route delegates to real transaction building/signing/submission: new lib/services/stellar-payment.service.ts builds a TransactionBuilder payment operation, signs with the configured Keypair, and calls server.submitTransaction() — same shape as Orbit-Wal/backend's StellarService.sendPayment.
• status reflects actual ledger state: successful from Horizon drives completed/failed. A definitive Horizon rejection (result codes present, e.g. op_underfunded) → failed. A response-less network error (timeout — we never got Horizon's answer) → pending, since the envelope may still land in a ledger; the already-existing TransactionSyncService.syncFromNetwork() settlement poller reconciles it later.
• Persisted record stores a real, verifiable tx hash: hash is transaction.hash().toString('hex') — the SDK's own pre-submission signature hash — present even on failure/timeout, so every attempt is independently checkable on Horizon.

Evidence the code actually runs

Real testnet run (not mocked) — verify-send.ts

Ran the actual route handler against Stellar testnet with a friendbot-funded throwaway keypair (GCTQDBNWV4PFO35SFBTB5ULEQQGOELIEYJHIWLGK6XTVZKGYGVLOTFPY):

--- Case 1: real payment, should complete ---
{
  "httpStatus": 200,
  "body": {
    "success": true,
    "hash": "d6effc88280522fec9579d24da3e513b0f6dd9b4166ecdde2cf821a3f9bf0b56",
    "status": "completed"
  }
}

--- Case 2: overdraw the source account, should fail (real Horizon rejection) ---
{
  "httpStatus": 200,
  "body": {
    "success": false,
    "hash": "e6e7c35020442f3200344bfd89873343516a2db22fb01917b62b476812f2ca24",
    "status": "failed",
    "error": "Horizon rejected the transaction (HTTP 400): transaction=tx_failed, operations=op_underfunded"
  }
}

--- Case 3: destination account does not exist, should fail ---
{
  "httpStatus": 200,
  "body": {
    "success": false,
    "hash": "55e33f7793796f4501b6338791a318e903abbc2fcf9057c1cb6b92ac53d78b60",
    "status": "failed",
    "error": "Horizon rejected the transaction (HTTP 400): transaction=tx_failed, operations=op_no_destination"
  }
}

Independently re-verified every hash directly against Horizon (GET /transactions/:hash, not this app's own code):

hash	Horizon successful	Horizon ledger
d6effc88...9bf0b56 (completed)	true	3726945
e6e7c350...12f2ca24 (op_underfunded)	false	3726946
55e33f77...53d78b60 (op_no_destination)	false	3727025

All three are publicly checkable, e.g. https://stellar.expert/explorer/testnet/tx/d6effc88280522fec9579d24da3e513b0f6dd9b4166ecdde2cf821a3f9bf0b56 — note that even the two "failed" transactions were included in a real ledger with a real hash (Stellar charges the fee and includes tx_failed transactions on-chain), which is exactly the "real, verifiable hash even on failure" requirement.

Automated test suite

$ npx jest tests/unit/services/stellar-payment.service.test.ts tests/integration/api-wallet.test.ts \
    tests/integration/fixture-integration.test.ts tests/integration/wallet-send-unconfigured.test.ts \
    tests/unit/services/wallet.service.test.ts tests/unit/hooks/useWalletSend.test.ts \
    tests/component/send-form.test.tsx tests/unit/env.test.ts --verbose

PASS tests/unit/services/stellar-payment.service.test.ts   (9 tests — completed/failed/pending/config/asset)
PASS tests/integration/api-wallet.test.ts                  (13 tests — real TransactionBuilder/StrKey, mocked network only)
PASS tests/integration/fixture-integration.test.ts         (14 tests)
PASS tests/integration/wallet-send-unconfigured.test.ts    (1 test  — 503 ERR_PAYMENT_NOT_CONFIGURED)
PASS tests/unit/services/wallet.service.test.ts            (14 tests — incl. 2 new status-persistence tests)
PASS tests/unit/hooks/useWalletSend.test.ts                (8 tests — incl. new pending-outcome test)
PASS tests/component/send-form.test.tsx                    (10 tests — incl. new pending-vs-completed UI test)
PASS tests/unit/env.test.ts                                (3 tests — env schema + .env.example sync)

Test Suites: 8 passed, 8 total
Tests:       72 passed, 72 total

Coverage on touched files, well above jest.config.js's configured thresholds: app/api/wallet/send/route.ts 81% stmts/87.5% branches (req. 75%), lib/services/wallet.service.ts 90%/90% (req. 85%), lib/services/stellar-payment.service.ts 96%/77% (no threshold configured, included for completeness).

Pre-existing, unrelated breakage (verified via git stash on this exact branch, confirmed identical before and after this change — not something this PR causes or needs to fix): 13 test suites fail on main for unrelated reasons (@simplewebauthn/server never added to package.json, hooks/use-toast.ts has a syntax error, several analytics/chart API tests expect response shapes their routes don't return, etc.). next build also currently fails on main independent of this change, for the same @simplewebauthn/server/use-toast.ts reasons.

Adjacent behavior re-verified

• wallet.service.ts status-persistence bug: was hardcoding status: 'completed' on every save regardless of the route's actual response. Fixed to use result.status; covered by 2 new tests.
• useWalletSend/SendForm UI: success now means "not a definitive failure" (covers completed and pending), so a pending broadcast doesn't show as a false "Payment failed." The success card now distinguishes "Send Complete" from "Send Submitted — awaiting network confirmation" via the existing TransactionStatusBadge component.
• Destination validation: upgraded from a regex (/^G[A-Z0-9]{55}$/i — accepts non-checksummed strings) to real StrKey.isValidEd25519PublicKey checksum validation. Several test fixture addresses (GDXSPAYWALLET7QK3..., GC3G2N7N5LRYX6L5...) were never valid Stellar keys, just regex-shaped — replaced with real checksummed keys where the new validation now correctly rejects them.
• Asset/memo validation: route previously accepted any string as asset and never checked memo length. Both now validated pre-flight against SUPPORTED_STELLAR_ASSETS and Stellar's 28-byte MEMO_TEXT limit (ERR_UNSUPPORTED_ASSET, ERR_MEMO_TOO_LONG).
• Drive-by (same domain): soroban.service.ts hardcoded the Futurenet passphrase for NEXT_PUBLIC_STELLAR_NETWORK=testnet — a real, separate bug in the same network-passphrase logic this issue touches. Fixed to use the SDK's own Networks.TESTNET.
• Drive-by (test infra): components/ui/alert.tsx had AlertTitle declared twice (verbatim copy-paste duplicate) — broke Jest's parse for every test importing Alert transitively, including send-form.test.tsx which this PR extends. Removed the duplicate; unblocked 4 previously-broken suites as a side effect (noted in docs/issue-63.md).

Files changed

• lib/services/stellar-payment.service.ts (new) — real build/sign/submit + status mapping
• app/api/wallet/send/route.ts — delegates to the above; real StrKey/asset/memo validation; new error codes
• lib/services/wallet.service.ts — status-persistence fix
• lib/errors.ts — ERR_UNSUPPORTED_ASSET, ERR_MEMO_TOO_LONG, ERR_ACCOUNT_KEY_MISMATCH, ERR_PAYMENT_NOT_CONFIGURED
• lib/env.mjs, .env.example — new STELLAR_SOURCE_SECRET_KEY (optional, server-only)
• components/app/send-form.tsx — pending vs completed UI distinction
• components/ui/alert.tsx — drive-by duplicate-declaration fix
• lib/services/soroban.service.ts — drive-by Futurenet/testnet passphrase fix
• next.config.mjs, jest.config.js — uint8array-extras transpile/transform allowlist (needed once the route imports the SDK directly)
• docs/issue-63.md (new), docs/issue-28.md, README.md — design rationale + env var docs
• Tests: tests/unit/services/stellar-payment.service.test.ts (new), tests/integration/wallet-send-unconfigured.test.ts (new), plus updates to tests/integration/api-wallet.test.ts, tests/integration/fixture-integration.test.ts, tests/unit/services/wallet.service.test.ts, tests/unit/hooks/useWalletSend.test.ts, tests/component/send-form.test.tsx
• verify-send.ts (new, repo root) — manual real-testnet verification script, mirrors the existing verify.ts/test-err.ts precedent

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com