SDK Integration Smoke Test Harness

[attyolu]

##closes #551

Summary

Adds an end-to-end smoke test suite that exercises the full happy-path flow — create invoice → preflight check → submit payment → verify receipt → check finality — against Stellar testnet using real Horizon calls and funded test accounts. Also adds the supporting SDK infrastructure (FinalityChecker, preflightCheck(), getReceipt()) required to support this flow.

Motivation

Without this harness, regressions in Horizon API compatibility, @stellar/stellar-sdk upgrades, or cross-module integration are only caught in production. This CI-gated integration test catches them before merge.

Changes

New Files

File	Description
src/finalityChecker.ts	FinalityChecker class that polls Soroban RPC for tx success, waits for minConfirmations ledger depth, then builds a finalized PaymentReceipt with Horizon-derived effectSummary
tests/integration/smokeTest.ts	End-to-end smoke test exercising the full invoice lifecycle against Stellar testnet

Modified Files

File	Description
src/receipt.ts	Extended PaymentReceipt / PaymentReceiptJSON with optional status and effectSummary fields; updated serialization and deserialization
src/client.ts	Added preflightCheck() (invoice status + expiry + payer readiness) and getReceipt() methods to StellarSplitClient
src/index.ts	Exported FinalityChecker from public API

Smoke Test Flow

1. Fund accounts — Creates four Keypair.random() accounts (creator, payer, recipient1, recipient2) and funds them via Friendbot (https://friendbot.stellar.org)
2. Create invoice — 2-recipient invoice with 60/40 split via client.createInvoice()
3. Preflight check — Calls client.preflightCheck() and asserts invoice is pending, not expired, and payer has sufficient balance
4. Submit payment — Calls client.submitPayment() for the full invoice amount
5. Verify receipt — Calls client.getReceipt() and asserts invoiceId, payer, totalPaid, and proofHash
6. Finality check — Calls FinalityChecker.check() with minConfirmations: 2 and asserts status === "finalized" with correct effectSummary balance deltas

Gating

• Smoke test is skipped when STELLAR_TESTNET_SMOKE is not set to "1"
• Tagged as @integration to exclude from the default npm test run
• Wallet signing is mocked via vi.mock() to use raw Keypair signing (no Freighter dependency)

How to Run

STELLAR_TESTNET_SMOKE=1 \
STELLAR_SPLIT_CONTRACT_ID=<deployed-contract-id> \
npx vitest run tests/integration/smokeTest.ts

Checklist

• Smoke test funds two Keypair accounts and creates a 2-recipient invoice with 60/40 split

• Calls preflightCheck() and asserts all preflight checks pass before submission

• Submits payment and waits for finality via FinalityChecker.check() with minConfirmations: 2

• Asserts PaymentReceipt.status === 'finalized' and effectSummary reflects correct balance deltas

• Test is skipped when STELLAR_TESTNET_SMOKE is not set; tagged as @integration

• TypeScript compilation passes for all new/modified files

• No merge conflicts with Test-Harness branch

• Add FinalityChecker class for tx finality polling and finalized PaymentReceipts with Horizon-derived effectSummary

• Extend PaymentReceipt with optional status and effectSummary fields

• Add preflightCheck and getReceipt methods to StellarSplitClient

• Export FinalityChecker from public API

• Add end-to-end smoke test gated by STELLAR_TESTNET_SMOKE=1 exercising full invoice flow against Stellar testnet

[drips-wave]

@attyolu 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