@stellar/typescript-wallet-sdk 3.0.0 → 3.0.1

package/lib/walletSdk/Exceptions/index.d.ts

@@ -133,6 +133,9 @@ export declare class SigningKeypairMissingSecretError extends Error {
 export declare class DefaultSignerDomainAccountError extends Error {
     constructor();
 }
+export declare class DomainSigningModifiedError extends Error {
+    constructor();
+}
 export declare class AuthHeaderSigningKeypairRequiredError extends Error {
     constructor();
 }

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",
+  "version": "3.0.1",
   "engines": {
     "node": ">=20"
   },

package/src/walletSdk/Auth/index.ts

@@ -12,6 +12,7 @@ import {
   ExpiredTokenError,
   ChallengeValidationFailedError,
   NetworkPassphraseMismatchError,
+  DomainSigningModifiedError,
 } from "../Exceptions";
 import {
   AuthenticateParams,
@@ -189,15 +190,27 @@ export class Sep10 {
       networkPassphrase,
     ) as Transaction;
 
-    // check if verifying client domain as well
-    for (const op of transaction.operations) {
-      if (op.type === "manageData" && op.name === "client_domain") {
-        transaction = await walletSigner.signWithDomainAccount({
-          transactionXDR: challengeResponse.transaction,
-          networkPassphrase,
-          accountKp,
-        });
+    const hasClientDomain = transaction.operations.some(
+      (op) => op.type === "manageData" && op.name === "client_domain",
+    );
+
+    if (hasClientDomain) {
+      const originalHash = transaction.hash();
+      const returned = await walletSigner.signWithDomainAccount({
+        transactionXDR: challengeResponse.transaction,
+        networkPassphrase,
+        accountKp,
+      });
+
+      // Transaction.hash() covers the envelope body but excludes signatures, so
+      // a domain signer that only appends its signature preserves the hash. Any
+      // change to the operations, source account, memo, or other body fields
+      // changes the hash and is rejected here.
+      if (!returned.hash().equals(originalHash)) {
+        throw new DomainSigningModifiedError();
       }
+
+      transaction = returned;
     }
 
     walletSigner.signWithClientAccount({ transaction, accountKp });

package/src/walletSdk/Exceptions/index.ts

@@ -354,6 +354,15 @@ export class DefaultSignerDomainAccountError extends Error {
   }
 }
 
+export class DomainSigningModifiedError extends Error {
+  constructor() {
+    super(
+      "Domain signer returned a transaction whose body differs from the original challenge. Only the client_domain signature should be added.",
+    );
+    Object.setPrototypeOf(this, DomainSigningModifiedError.prototype);
+  }
+}
+
 export class AuthHeaderSigningKeypairRequiredError extends Error {
   constructor() {
     super("Must be SigningKeypair to sign auth header");

package/src/walletSdk/Horizon/Stellar.ts

@@ -24,6 +24,13 @@ import {
 import { getResultCode } from "../Utils/getResultCode";
 import { SigningKeypair } from "./Account";
 
+const SUBMIT_504_MAX_RETRIES = 5;
+const SUBMIT_504_BASE_DELAY_MS = 1000;
+const SUBMIT_504_MAX_DELAY_MS = 30000;
+
+const sleep = (ms: number) =>
+  new Promise<void>((resolve) => setTimeout(resolve, ms));
+
 /**
  * Interaction with the Stellar Network.
  * Do not create this object directly, use the Wallet class.
@@ -118,30 +125,58 @@ 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,
   ): Promise<boolean> {
-    try {
-      const response = await this.server.submitTransaction(signedTransaction);
-      if (!response.successful) {
-        throw new TransactionSubmitFailedError(response);
-      }
-      return true;
-    } catch (e) {
-      if (e.response.status === 504) {
-        // in case of 504, keep retrying this tx until submission succeeds or we get a different error
+    let lastError: unknown;
+    for (let attempt = 0; attempt <= SUBMIT_504_MAX_RETRIES; attempt++) {
+      try {
+        const response = await this.server.submitTransaction(signedTransaction);
+        if (!response.successful) {
+          throw new TransactionSubmitFailedError(response);
+        }
+        return true;
+      } catch (e) {
+        if (e?.response?.status !== 504) {
+          throw e;
+        }
+        lastError = e;
+        if (attempt === SUBMIT_504_MAX_RETRIES) {
+          break;
+        }
         // https://developers.stellar.org/api/errors/http-status-codes/horizon-specific/timeout
         // https://developers.stellar.org/docs/encyclopedia/error-handling#timeouts
-        return await this.submitTransaction(signedTransaction);
+        // 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 half = cappedDelay / 2;
+        await sleep(half + Math.random() * half);
       }
-      throw e;
     }
+    throw lastError;
   }
 
   /**
@@ -211,6 +246,7 @@ export class Stellar {
           signerFunction,
           baseFee: newFee,
           memo,
+          maxFee,
         });
       }
       throw e;

package/test/auth.test.ts

@@ -16,7 +16,7 @@ import { randomBytes } from "crypto";
 import axios from "axios";
 import sinon from "sinon";
 
-import { validateToken, Sep10 } from "../src/walletSdk/Auth";
+import { validateToken, Sep10, type WalletSigner } from "../src/walletSdk/Auth";
 import {
   Config,
   StellarConfiguration,
@@ -30,6 +30,7 @@ import {
   ChallengeValidationFailedError,
   NetworkPassphraseMismatchError,
   MissingSigningKeyError,
+  DomainSigningModifiedError,
 } from "../src/walletSdk/Exceptions";
 
 const createToken = (payload: Record<string, unknown>): string => {
@@ -618,6 +619,108 @@ describe("Sep10 challenge validation", () => {
     });
   });
 
+  describe("client_domain signing integrity", () => {
+    const buildClientDomainChallenge = (clientKeypair: Keypair) => {
+      const clientDomainKeypair = Keypair.random();
+      return buildChallenge({
+        clientKeypair,
+        additionalOps: [
+          Operation.manageData({
+            name: "client_domain",
+            value: "wallet.example.com",
+            source: clientDomainKeypair.publicKey(),
+          }),
+        ],
+      });
+    };
+
+    it("should accept when domain signer returns the same transaction with an appended signature", async () => {
+      const clientKeypair = Keypair.random();
+      const { xdr, serverKeypair } = buildClientDomainChallenge(clientKeypair);
+
+      const accountKp = SigningKeypair.fromSecret(clientKeypair.secret());
+      const token = createJwt(clientKeypair);
+      const { sep10 } = setupSep10({
+        serverSigningKey: serverKeypair.publicKey(),
+        challengeXdr: xdr,
+        token,
+      });
+
+      const walletSigner: WalletSigner = {
+        signWithClientAccount: ({ transaction, accountKp: kp }) => {
+          transaction.sign(kp.keypair);
+          return transaction;
+        },
+        // eslint-disable-next-line @typescript-eslint/require-await
+        signWithDomainAccount: async ({ transactionXDR }) => {
+          const tx = SdkTransactionBuilder.fromXDR(
+            transactionXDR,
+            networkPassphrase,
+          ) as Transaction;
+          tx.sign(Keypair.random());
+          return tx;
+        },
+      };
+
+      const authToken = await sep10.authenticate({
+        accountKp,
+        clientDomain: "wallet.example.com",
+        walletSigner,
+      });
+      expect(authToken.account).toBe(clientKeypair.publicKey());
+    });
+
+    it("should reject when domain signer returns a transaction with a different body", async () => {
+      const clientKeypair = Keypair.random();
+      const { xdr, serverKeypair } = buildClientDomainChallenge(clientKeypair);
+
+      const accountKp = SigningKeypair.fromSecret(clientKeypair.secret());
+      const token = createJwt(clientKeypair);
+      const { sep10, postStub } = setupSep10({
+        serverSigningKey: serverKeypair.publicKey(),
+        challengeXdr: xdr,
+        token,
+      });
+
+      const differentSource = new Account(clientKeypair.publicKey(), "0");
+      const differentTx = new SdkTransactionBuilder(differentSource, {
+        fee: BASE_FEE,
+        networkPassphrase,
+      })
+        .addOperation(
+          Operation.payment({
+            destination: Keypair.random().publicKey(),
+            asset: Asset.native(),
+            amount: "100",
+          }),
+        )
+        .setTimeout(300)
+        .build();
+
+      const signWithClientAccountSpy = sinon.spy(
+        ({ transaction, accountKp: kp }) => {
+          transaction.sign(kp.keypair);
+          return transaction;
+        },
+      );
+      const walletSigner: WalletSigner = {
+        signWithClientAccount: signWithClientAccountSpy,
+        // eslint-disable-next-line @typescript-eslint/require-await
+        signWithDomainAccount: async () => differentTx,
+      };
+
+      await expect(
+        sep10.authenticate({
+          accountKp,
+          clientDomain: "wallet.example.com",
+          walletSigner,
+        }),
+      ).rejects.toThrow(DomainSigningModifiedError);
+      expect(signWithClientAccountSpy.notCalled).toBe(true);
+      expect(postStub.notCalled).toBe(true);
+    });
+  });
+
   describe("network passphrase mismatch", () => {
     it("should reject when server returns a different network passphrase", async () => {
       const { xdr, serverKeypair, clientKeypair } = buildChallenge();

package/test/stellar.test.ts

@@ -1,5 +1,12 @@
-import { Keypair, Memo, MemoText, Horizon } from "@stellar/stellar-sdk";
+import {
+  Keypair,
+  Memo,
+  MemoText,
+  Horizon,
+  Transaction,
+} from "@stellar/stellar-sdk";
 import axios from "axios";
+import sinon from "sinon";
 
 import { Stellar, Wallet } from "../src";
 import {
@@ -14,6 +21,7 @@ import {
 } from "../src/walletSdk/Asset";
 import { TransactionStatus, WithdrawTransaction } from "../src/walletSdk/Types";
 import {
+  TransactionSubmitWithFeeIncreaseFailedError,
   WithdrawalTxMissingDestinationError,
   WithdrawalTxMissingMemoError,
   WithdrawalTxNotPendingUserTransferStartError,
@@ -158,6 +166,51 @@ describe("Stellar", () => {
     expect(txn.fee).toBe("200");
   });
 
+  it("should enforce maxFee across multiple submitWithFeeIncrease retries", async () => {
+    const txTooLateRejection = {
+      response: {
+        status: 400,
+        statusText: "Bad Request",
+        data: {
+          extras: {
+            result_codes: { transaction: "tx_too_late" },
+          },
+        },
+      },
+    };
+
+    // Always reject with tx_too_late so the fee climbs on every retry. With the
+    // fix the maxFee cap is honored across all retries and submitWithFeeIncrease
+    // eventually throws; without it the cap is dropped after the first retry and
+    // the recursion never stops. Restore the spy in a finally block: a leaked
+    // mock on submitTransaction would turn the next test's real submission into
+    // a no-op.
+    const submitStub = jest
+      .spyOn(stellar, "submitTransaction")
+      .mockRejectedValue(txTooLateRejection);
+
+    const buildingFunction = (builder) =>
+      builder.transfer(kp.publicKey, new NativeAssetId(), "2");
+
+    try {
+      await expect(
+        stellar.submitWithFeeIncrease({
+          sourceAddress: kp,
+          timeout: 180,
+          baseFeeIncrease: 100,
+          buildingFunction,
+          baseFee: 100,
+          maxFee: 250,
+        }),
+      ).rejects.toThrow(TransactionSubmitWithFeeIncreaseFailedError);
+      // The cap is enforced only after several retries, proving it survives
+      // past the first retry (the bug being fixed).
+      expect(submitStub.mock.calls.length).toBeGreaterThan(1);
+    } finally {
+      submitStub.mockRestore();
+    }
+  });
+
   it("should add and remove asset support", async () => {
     const asset = new IssuedAssetId(
       "USDC",
@@ -202,6 +255,74 @@ describe("Stellar", () => {
     expect(fee).toBeTruthy();
   });
 
+  describe("submitTransaction 504 handling", () => {
+    let clock: sinon.SinonFakeTimers;
+    let randomStub: sinon.SinonStub;
+
+    beforeEach(() => {
+      clock = sinon.useFakeTimers();
+      // Zero jitter for deterministic test timing.
+      randomStub = sinon.stub(Math, "random").returns(0);
+    });
+
+    afterEach(() => {
+      clock.restore();
+      randomStub.restore();
+      jest.restoreAllMocks();
+    });
+
+    const make504 = () => ({ response: { status: 504 } });
+
+    it("retries once on 504 then returns on success", async () => {
+      const serverStub = jest
+        .spyOn(stellar.server, "submitTransaction")
+        .mockRejectedValueOnce(make504())
+        .mockResolvedValueOnce({ successful: true } as any);
+
+      const tx = {} as Transaction;
+      const promise = stellar.submitTransaction(tx);
+
+      // 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);
+    });
+
+    it("rethrows immediately on a non-504 error", async () => {
+      const serverStub = jest
+        .spyOn(stellar.server, "submitTransaction")
+        .mockRejectedValueOnce({ response: { status: 500 } });
+
+      await expect(
+        stellar.submitTransaction({} as Transaction),
+      ).rejects.toMatchObject({ response: { status: 500 } });
+      expect(serverStub).toHaveBeenCalledTimes(1);
+    });
+
+    it("gives up after the bounded number of retries and rethrows the last 504", async () => {
+      // SUBMIT_504_MAX_RETRIES = 5 → 1 initial + 5 retries = 6 total attempts.
+      const serverStub = jest
+        .spyOn(stellar.server, "submitTransaction")
+        .mockRejectedValue(make504());
+
+      const promise = stellar.submitTransaction({} as Transaction);
+      // Surface the rejection eagerly so an unhandled rejection doesn't crash
+      // the test runner mid-tick.
+      promise.catch(() => undefined);
+
+      // 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 },
+      });
+      expect(serverStub).toHaveBeenCalledTimes(6);
+    });
+  });
+
   describe("TransactionBuilder/transferWithdrawalTransaction", () => {
     it("should transfer withdrawal transaction", async () => {
       const memoExamples = [