feat: offline tx building, batch operations, currency conversion, and request retry

[orsar-rita]

What this fixes

This pull request resolves four related core SDK capabilities:

1. Request Timeout and Retry Logic (Add request timeout and retry logic #1030):
   Network calls to Soroban RPC or Horizon endpoints lacked unified configurable timeout deadlines and exponential backoff retry policies. Transient hiccups, 429 rate limits, and 503 service unavailable responses could fail requests immediately without automatic recovery.
2. Currency Conversion Utilities (Implement currency conversion utilities #1031):
   Display and invoice calculation components lacked a robust, general-purpose currency conversion engine supporting external exchange rate providers, inverse rate derivation, cross-currency triangulation (e.g. through USD or XLM), rigorous input validation, and TTL-based caching.
3. Batch Operation Support (Add batch operation support #1032):
   Submitting multiple transactions sequentially caused excessive latency, non-atomic partial execution risks, and elevated transaction fees. Batching multiple operations into a single atomic Stellar transaction envelope was not systematically supported with validation and fee aggregation.
4. Offline Transaction Building (Implement offline transaction building #1033):
   Cold-storage, air-gapped devices, and offline signing workflows require constructing, validating, and signing transactions without network connectivity, along with lossless serialization for transport.

What changed

1. Request Timeout & Exponential Backoff Retry (#1030)

• Created src/requestRetry.ts implementing RequestRetryManager, executeWithTimeoutAndRetry, and calculateBackoffDelay.
• Supports configurable timeouts enforced via AbortController, aborting requests that exceed deadlines and throwing RequestTimeoutError.
• Implemented exponential backoff with configurable baseDelayMs, maxDelayMs, backoffMultiplier, and proportional or full random jitter.
• Enforced hard retry limits (maxRetries / maxAttempts), throwing MaxRetriesExceededError with context when attempts are exhausted.
• Comprehensive error classification distinguishes retryable transient failures (408, 429, 500, 502, 503, 504, ECONNRESET, ETIMEDOUT, network aborts) from non-retryable terminal errors (400, 401, 403, 404, validation errors).

2. Currency Conversion Utilities (#1031)

• Enhanced src/currencyConverter.ts with the CurrencyConverter class and convertCurrency functional helper.
• Added support for pluggable ExchangeRateProvider functions and PriceOracleAdapter instances.
• Added automatic inverse rate calculation (1 / rate) and multi-hop cross-currency triangulation via base currencies (e.g. USD).
• Added rigorous input validation rejecting negative amounts, non-finite values, empty currency codes, and non-positive exchange rates.
• Integrated high-performance TTL caching with hit/miss statistics tracking, pair invalidation, and full cache clearing.
• Fixed missing PriceOracleAdapter interface definition in currencyConverter.ts.

3. Batch Operation Support (#1032)

• Created src/batchOperations.ts implementing BatchOperationBuilder and BatchExecutor.
• Provided a fluent builder API for composing payments, account creation, data entries (manageData), trustlines (changeTrust), and custom contract operations into a single batch.
• Added sound pre-execution validation ensuring 1 to 100 operations (Stellar protocol limit), valid Ed25519 public keys, positive amounts, and data size limits.
• Guaranteed atomicity by bundling all operations into a single Stellar Transaction with automated base fee scaling (BASE_FEE * opCount).
• Handled signing and execution submission with atomic error reporting.

4. Offline Transaction Building (#1033)

• Created src/offlineTransaction.ts implementing OfflineTransactionBuilder requiring zero network access.
• Supports offline transaction composition with manual sequence numbering, base fees, timebounds, and memos (text, ID, hash, return).
• Implemented offline Ed25519 signing via Keypair or secret seed strings, supporting multi-signature collection and cryptographic signature verification against the transaction hash.
• Created lossless round-trip serialization to standard base64 XDR and structured OfflineTxPackage JSON packages for air-gapped transport.

5. SDK Entry Point & Tests

• Re-exported new classes, functions, and types in src/index.ts.
• Added complete unit test suites in test/requestRetry.test.ts, test/currencyConverter.test.ts, test/batchOperations.test.ts, and test/offlineTransaction.test.ts.

Testing

All tests were executed and passed cleanly:

• test/requestRetry.test.ts (15 tests passed)
• test/currencyConverter.test.ts (20 tests passed)
• test/batchOperations.test.ts (12 tests passed)
• test/offlineTransaction.test.ts (13 tests passed)
• Baseline SDK test suite: npm run test (110 tests passed)
• Related timeout & currency tests: test/timeout.test.ts, test/retryPolicy.test.ts, test/currencyNormalizer.test.ts (55 tests passed)

Issues

closes #1030
closes #1031
closes #1032
closes #1033

[drips-wave]

@orsar-rita 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