lockAssets/unlockAssets/setBoost never pin address in Freighter's signTransaction call and never validate the returned signerAddress

[prodbycorne]

Overview

@stellar/freighter-api (this project's dependency, ^3.1.0) exposes signTransaction with an optional address field that pins which of the extension's accounts must sign, and its response includes a signerAddress field confirming which account actually did:

// @stellar/freighter-api's own type surface (signTransaction.d.ts)
export declare const signTransaction: (transactionXdr: string, opts?: {
    networkPassphrase?: string;
    address?: string;
}) => Promise<{
    signedTxXdr: string;
    signerAddress: string;
} & { error?: FreighterApiError }>;

This codebase's own FreighterWalletApi interface never models or uses either field:

// src/lib/soroban.ts:149-154
export interface FreighterWalletApi {
  signTransaction: (
    transactionXdr: string,
    options: { networkPassphrase: string },
  ) => Promise<FreighterSignTransactionResult>;
}

Every real call site — lockAssets (soroban.ts:939-943), unlockAssets (soroban.ts:1080-1084), setBoost (soroban.ts:1209-1213) — passes only { networkPassphrase }, never address: userAddress, so Freighter is free to sign with whichever account is currently "active" inside the extension, not necessarily the userAddress/publicKey this app believes is connected. Worse, getSignedTransactionXdr (soroban.ts:300-320), the function that unwraps Freighter's response, only ever reads result.signedTxXdr — it never reads or checks result.signerAddress against the userAddress the caller intended:

function getSignedTransactionXdr(result: FreighterSignTransactionResult): string {
  if (typeof result === 'string') return result;
  if (result.error) { throw new Error(...); }
  if (result.signedTxXdr) { return result.signedTxXdr; }   // signerAddress silently discarded
  throw new Error('Freighter did not return a signed transaction XDR');
}

Since the built transaction embeds userAddress as the required authorizing party (e.g. Address.fromString(args.publicKey).toScVal() in buildLockAssetsTransaction), a mismatched signer would generally cause the on-chain authorization check to fail rather than silently succeed for the wrong account — but SmartDrop itself has zero client-side defense-in-depth here: it neither pins the signer up front (which would let Freighter itself reject a mismatched-account attempt before ever producing a signature) nor verifies the signer after the fact (which would let SmartDrop surface a fast, clear, client-side error — "you signed with a different account than the one connected" — instead of spending a real transaction submission on an authorization failure discovered only on-chain).

Requirements

• Pass address: userAddress in the options object of every walletApi.signTransaction(...) call (lockAssets, unlockAssets, setBoost), so Freighter itself enforces the correct signer up front where its own API supports doing so.
• Update FreighterWalletApi's interface and getSignedTransactionXdr to read and validate result.signerAddress === userAddress, throwing a clear, actionable SecurityError/FreighterError if they diverge, before ever calling sendTransaction.
• Surface this as a distinct, user-legible error message ("You signed with a different Freighter account than the one connected to SmartDrop") rather than letting a mismatch surface only as an opaque on-chain authorization failure.

Acceptance Criteria

• lockAssets/unlockAssets/setBoost all pass address: userAddress to walletApi.signTransaction.
• getSignedTransactionXdr (or its caller) rejects with a clear error if result.signerAddress is present and doesn't match the expected userAddress, before any sendTransaction call is made.
• A test with a mocked walletApi.signTransaction returning a signerAddress different from the userAddress passed into lockAssets asserts the flow fails fast with the new, specific error, and that sendTransaction is never called.
• Existing happy-path behavior (signer matches expected address) is unaffected.

Additional Notes

More precise references

• src/lib/soroban.ts:149-154 (FreighterWalletApi interface) — confirmed no address option or signerAddress response field is modeled.
• src/lib/soroban.ts:141-147 (FreighterSignTransactionResult type) — confirmed the union type (string | { signedTxXdr?, signerAddress?, error? }) already has an optional signerAddress?: unknown slot in its shape (implicitly, via being a loosely-typed object) that is simply never read.
• src/lib/soroban.ts:300-320 (getSignedTransactionXdr) — confirmed line-by-line that only result.signedTxXdr is ever accessed; signerAddress is never referenced anywhere in this function or its callers.
• src/lib/soroban.ts:939-943 (lockAssets), :1080-1084 (unlockAssets), :1209-1213 (setBoost) — confirmed all three call walletApi.signTransaction(preparedTransaction.toXDR(), { networkPassphrase }) with no address field, despite userAddress/publicKey being in scope at each call site.
• Confirmed via the installed @stellar/freighter-api type declarations (signTransaction.d.ts, matching the ^3.1.0 version pinned in package.json) that both address (request) and signerAddress (response) are real, current parts of the library's public API surface, not a hypothetical/future capability.

Additional edge cases

• This is a defense-in-depth gap that remains valuable independent of StellarWalletContext never detects a Freighter account switch while connected, leaving publicKey stale #97/StellarWalletContext never detects a Freighter account switch while connected, leaving publicKey stale #67 (Freighter account-switch detection while connected) and lockAssets/unlockAssets have no guard against the wallet disconnecting between simulate and sign #100/lockAssets/unlockAssets have no guard against the wallet disconnecting between simulate and sign #70 (wallet disconnecting between simulate and sign) — even if both of those were fully fixed, a user could still, in principle, pick a different account from within Freighter's own signing-prompt UI at the moment of signing (a user-driven choice inside the extension's popup, not a "switch" event SmartDrop's own state could ever observe), which this issue's fix would catch and those fixes would not.
• Pinning address also changes Freighter's own UX for the better: with address specified, Freighter can show the user exactly which account it's about to sign with (and can refuse outright if that account isn't unlocked/available), rather than silently proceeding with whatever account happens to be active.

Implementation sketch

export interface FreighterWalletApi {
  signTransaction: (
    transactionXdr: string,
    options: { networkPassphrase: string; address?: string },
  ) => Promise<FreighterSignTransactionResult>;
}

function getSignedTransactionXdr(result: FreighterSignTransactionResult, expectedSigner: string): string {
  if (typeof result === 'string') return result; // no signerAddress to check in the legacy string-return shape
  if (result.error) { throw new Error(...); }
  if (result.signerAddress && result.signerAddress !== expectedSigner) {
    throw new SecurityError(
      `Transaction was signed by ${result.signerAddress}, not the connected account ${expectedSigner}. Please sign with the correct Freighter account.`,
    );
  }
  if (result.signedTxXdr) return result.signedTxXdr;
  throw new Error('Freighter did not return a signed transaction XDR');
}

// call sites:
await walletApi.signTransaction(preparedTransaction.toXDR(), { networkPassphrase, address: userAddress });

Test/reproduction plan

• Mock walletApi.signTransaction to resolve { signedTxXdr: '...', signerAddress: 'GDIFFERENT...' } while lockAssets is called with userAddress = 'GEXPECTED...'; assert the call throws the new mismatch error and rpcServer.sendTransaction/this.rpcServer.sendTransaction is never invoked.
• Mock a matching signerAddress; assert the flow proceeds normally through to submission.
• Assert walletApi.signTransaction was called with address: userAddress in its options object, for each of lockAssets/unlockAssets/setBoost.

Cross-references

• Complementary to, not a duplicate of, StellarWalletContext never detects a Freighter account switch while connected, leaving publicKey stale #97/StellarWalletContext never detects a Freighter account switch while connected, leaving publicKey stale #67 (stale publicKey after an account switch) and lockAssets/unlockAssets have no guard against the wallet disconnecting between simulate and sign #100/lockAssets/unlockAssets have no guard against the wallet disconnecting between simulate and sign #70 (wallet disconnecting between simulate and sign) — those cover different points in the same broader "is the signing party actually who SmartDrop thinks it is" concern; all three should be considered together but are independently reproducible and independently fixable.

[Hollujay]

i would like to work on this issue because I will get it done efficiently @prodbycorne

[abayomicornelius]

The wallet integration is not taking advantage of Freighter's account-binding and signer-verification capabilities.

@stellar/freighter-api exposes an optional address parameter on signTransaction, allowing the application to explicitly require a particular Freighter account to sign. Its response also includes signerAddress, which identifies the account that actually signed the transaction.

However, the project's FreighterWalletApi abstraction does not model or use either field. This means the application cannot explicitly bind a signing request to the connected account through its current interface, nor verify from Freighter's response that the expected account actually signed.

That creates a dangerous account-switching edge case: if the user changes the active Freighter account between connection and transaction signing, the signing operation is not explicitly constrained to the account the application believes is connected. The resulting transaction could therefore be signed by a different account than the one represented by the application's wallet state.

I have experience reviewing wallet integrations where the connected identity must remain consistent across asynchronous user interactions. The abstraction should expose Freighter's address option and signerAddress response, pass the expected public key into every signing request, and verify the returned signer before accepting the signed transaction.

[grantfox-oss]

🦊 GrantFox — @abayomicornelius has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #139)
2. Your PR will be reviewed by the SmartDropLabs maintainers

Good luck! Track your progress on GrantFox.