Fix TransactionResult.ledger type and resolve known TypeScript type mismatches

[phertyameen]

Summary

The TransactionResult interface defines ledger as number, but the Stellar Horizon SDK returns ledger as a string in certain response shapes and SDK versions. This will throw a runtime type error during sweep execution in some environments. This issue fixes this mismatch and audits the rest of the Stellar SDK integration for similar type assumptions that could cause silent failures or runtime errors.

Background

Why type mismatches with the Stellar SDK are risky
The @stellar/stellar-sdk is a large SDK with several response types that vary between versions. TypeScript types provided by the SDK do not always match what is actually returned at runtime — especially for numeric fields returned from Horizon's REST API, which are JSON and therefore may be strings even when typed as numbers. A mismatch here will not be caught at compile time if TypeScript is inferring from the SDK's own type definitions, but will throw at runtime when the value is used mathematically or compared.

Known issue

TransactionProvider.executeSweepTransaction() returns a TransactionResult with ledger: result.ledger. The Horizon submitTransaction response types the ledger field as number in some SDK versions but returns it as a string from the actual Horizon API. Any code that uses transactionResult.ledger arithmetically will fail at runtime.

Audit scope

While fixing the immediate ledger issue, audit the following areas for similar mismatches:

• Any field from Horizon loadAccount() used as a number - specifically sequence, which is returned as a string and must be handled by the SDK's Account class rather than used directly
• The amount field throughout the codebase - Stellar amounts are strings in Horizon responses but are sometimes treated as numbers in validation logic
• The SweepResult and TransactionResult interfaces - confirm every field type matches what the SDK actually returns at runtime, not just what TypeScript infers

The fix for ledger

The TransactionResult interface ledger field should be typed as number | string to reflect reality, or the value should be explicitly coerced to number at the point it is read from the Horizon response. Add a comment explaining why the coercion is necessary — future contributors should not remove it thinking it is unnecessary.

Where to look

• src/modules/sweeps/interfaces/: TransactionResult and related interfaces
• src/modules/sweeps/providers/transaction.provider.ts: where result.ledger is accessed
• src/modules/stellar/stellar.service.ts: any direct use of Horizon response fields
• Stellar Horizon API documentation: the actual JSON shapes returned by submitTransaction and loadAccount

Acceptance Criteria

• TransactionResult.ledger type is corrected to match actual Horizon response
• No runtime type errors occur when TransactionProvider.executeSweepTransaction() is called against a real Horizon testnet endpoint
• The audit identifies and documents any other type mismatches found - fixes them if simple, opens follow-up issues if complex
• TypeScript strict mode compilation passes with no new type errors introduced
• Changes are covered by a note in the PR explaining the Horizon type behavior for future contributors