@stellar/typescript-wallet-sdk 3.0.0-beta.1779920488639 → 3.0.1

package/lib/walletSdk/Horizon/Stellar.d.ts

@@ -44,11 +44,22 @@ export declare class Stellar {
      */
     makeFeeBump({ feeAddress, transaction, baseFee, }: FeeBumpTransactionParams): FeeBumpTransaction;
     /**
-     * Submits a signed transaction to the server. If the submission fails with status
-     * 504 indicating a timeout error, it will automatically retry.
+     * Submits a signed transaction to Horizon.
+     *
+     * On HTTP 504 (timeout), retries with exponential backoff up to
+     * {@link SUBMIT_504_MAX_RETRIES} times. Any non-504 error is rethrown
+     * immediately without retrying.
+     *
      * @param {Transaction|FeeBumpTransaction} signedTransaction - The signed transaction to submit.
-     * @returns {boolean} `true` if the transaction was successfully submitted.
-     * @throws {TransactionSubmitFailedError} If the transaction submission fails.
+     * @returns {boolean} `true` if Horizon confirmed the submission as successful.
+     * @throws {TransactionSubmitFailedError} If Horizon responded with a non-successful
+     *   submission result (the transaction reached Horizon but was rejected).
+     * @throws The underlying 504 error if every retry attempt timed out. In this
+     *   case the transaction's on-chain status is **indeterminate** — Horizon may
+     *   have ingested it on the final attempt without responding in time. Callers
+     *   should poll the transaction hash to determine the actual outcome rather
+     *   than resubmit blindly; resubmitting a signed transaction with the same
+     *   sequence number will fail with `tx_bad_seq` once the original lands.
      */
     submitTransaction(signedTransaction: Transaction | FeeBumpTransaction): Promise<boolean>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stellar/typescript-wallet-sdk",
-  "version": "3.0.0-beta.1779920488639",
+  "version": "3.0.1",
   "engines": {
     "node": ">=20"
   },
@@ -75,4 +75,4 @@
     "example:sep24": "ts-node examples/sep24/sep24.ts",
     "example:sep12": "ts-node examples/sep12/sep12.ts"
   }
-}
+}

package/src/walletSdk/Horizon/Stellar.ts

@@ -125,11 +125,22 @@ export class Stellar {
   }
 
   /**
-   * Submits a signed transaction to the server. If the submission fails with status
-   * 504 indicating a timeout error, it will automatically retry.
+   * Submits a signed transaction to Horizon.
+   *
+   * On HTTP 504 (timeout), retries with exponential backoff up to
+   * {@link SUBMIT_504_MAX_RETRIES} times. Any non-504 error is rethrown
+   * immediately without retrying.
+   *
    * @param {Transaction|FeeBumpTransaction} signedTransaction - The signed transaction to submit.
-   * @returns {boolean} `true` if the transaction was successfully submitted.
-   * @throws {TransactionSubmitFailedError} If the transaction submission fails.
+   * @returns {boolean} `true` if Horizon confirmed the submission as successful.
+   * @throws {TransactionSubmitFailedError} If Horizon responded with a non-successful
+   *   submission result (the transaction reached Horizon but was rejected).
+   * @throws The underlying 504 error if every retry attempt timed out. In this
+   *   case the transaction's on-chain status is **indeterminate** — Horizon may
+   *   have ingested it on the final attempt without responding in time. Callers
+   *   should poll the transaction hash to determine the actual outcome rather
+   *   than resubmit blindly; resubmitting a signed transaction with the same
+   *   sequence number will fail with `tx_bad_seq` once the original lands.
    */
   async submitTransaction(
     signedTransaction: Transaction | FeeBumpTransaction,
@@ -152,12 +163,17 @@ export class Stellar {
         }
         // https://developers.stellar.org/api/errors/http-status-codes/horizon-specific/timeout
         // https://developers.stellar.org/docs/encyclopedia/error-handling#timeouts
+        // Equal-jitter backoff: each attempt waits at least half the capped
+        // exponential delay (a deterministic, progressive floor) plus a random
+        // amount up to the other half. Keeps the schedule predictable while
+        // smoothing correlated retries across many clients during a Horizon
+        // outage. Total sleep stays within SUBMIT_504_MAX_DELAY_MS.
         const cappedDelay = Math.min(
           SUBMIT_504_BASE_DELAY_MS * 2 ** attempt,
           SUBMIT_504_MAX_DELAY_MS,
         );
-        const jitter = Math.random() * (cappedDelay / 2);
-        await sleep(cappedDelay + jitter);
+        const half = cappedDelay / 2;
+        await sleep(half + Math.random() * half);
       }
     }
     throw lastError;
@@ -218,7 +234,7 @@ export class Stellar {
       if (resultCode === "tx_too_late") {
         const newFee = parseInt(transaction.fee) + baseFeeIncrease;
 
-        if (maxFee !== undefined && newFee > maxFee) {
+        if (maxFee && newFee > maxFee) {
           throw new TransactionSubmitWithFeeIncreaseFailedError(maxFee, e);
         }
 

package/test/stellar.test.ts

@@ -282,8 +282,9 @@ describe("Stellar", () => {
       const tx = {} as Transaction;
       const promise = stellar.submitTransaction(tx);
 
-      // First retry waits SUBMIT_504_BASE_DELAY_MS = 1000ms (jitter stubbed to 0).
-      await clock.tickAsync(1000);
+      // Equal-jitter sleep at attempt 0 with Math.random stubbed to 0 is
+      // cappedDelay/2 = 1000/2 = 500ms.
+      await clock.tickAsync(500);
 
       await expect(promise).resolves.toBe(true);
       expect(serverStub).toHaveBeenCalledTimes(2);
@@ -311,9 +312,9 @@ describe("Stellar", () => {
       // the test runner mid-tick.
       promise.catch(() => undefined);
 
-      // Sum of capped exponential delays with zero jitter:
-      // 1000 + 2000 + 4000 + 8000 + 16000 = 31000ms.
-      await clock.tickAsync(31000);
+      // Sum of equal-jitter sleeps (cappedDelay/2) with Math.random stubbed
+      // to 0: 500 + 1000 + 2000 + 4000 + 8000 = 15500ms.
+      await clock.tickAsync(15500);
 
       await expect(promise).rejects.toMatchObject({
         response: { status: 504 },