feat(dapp-client): add isSponsored for explicit sponsorship checks

`DappClient.isSponsored(chainId, transactions)` and
`ChainSessionManager.isSponsored(calls)` return true only when the
relayer's `/FeeOptions` endpoint explicitly reports sponsorship; any
error, network failure, or absence of sponsorship returns false. A true
result is always safe to surface as "free gas" in UI.

Prefer this over inferring sponsorship from an empty `getFeeOptions`
array — a swallowed `/FeeOptions` error produces the same empty shape as
a real subsidy. `getFeeOptions` is unchanged.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: matt416

.changeset/dapp-client-is-sponsored.md

@@ -0,0 +1,19 @@
+---
+'@0xsequence/dapp-client': minor
+---
+
+Add `isSponsored` for explicit sponsorship checks.
+
+`DappClient.isSponsored(chainId, transactions)` and
+`ChainSessionManager.isSponsored(calls)` return `true` only when the relayer's
+`/FeeOptions` endpoint explicitly reports sponsorship. Any error, network
+failure, or absence of sponsorship returns `false`, so a `true` result is
+always safe to surface as "free gas" in UI.
+
+Prefer this over inferring sponsorship from an empty `getFeeOptions` array — a
+swallowed `/FeeOptions` error also produces an empty array, so the inference
+can misclassify a failed quote as a real subsidy. The new method uses the
+positive `sponsored: boolean` signal from `@0xsequence/relayer`'s widened
+`feeOptions` return.
+
+`getFeeOptions` is unchanged.

packages/wallet/dapp-client/src/ChainSessionManager.ts

@@ -878,6 +878,54 @@ export class ChainSessionManager {
     }
   }
 
+  /**
+   * Checks whether the given transactions would be sponsored by an active
+   * relayer policy on this chain.
+   *
+   * Returns `true` only when the relayer's `/FeeOptions` endpoint explicitly
+   * reports sponsorship. A failed quote, network error, or absence of
+   * sponsorship all return `false`, so a `true` result is always safe to
+   * surface as "free gas" in UI.
+   */
+  async isSponsored(calls: Transaction[]): Promise<boolean> {
+    const callsToSend = calls.map((tx) => ({
+      to: tx.to,
+      value: tx.value,
+      data: tx.data,
+      gasLimit: tx.gasLimit ?? BigInt(0),
+      delegateCall: tx.delegateCall ?? false,
+      onlyFallback: tx.onlyFallback ?? false,
+      behaviorOnError: tx.behaviorOnError ?? ('revert' as const),
+    }))
+    try {
+      const signedCall = await this._buildAndSignCalls(callsToSend)
+      const fingerprint = this._fingerprintCalls(callsToSend)
+      if (fingerprint) {
+        this.lastSignedCallCache = {
+          fingerprint,
+          signedCall,
+          createdAtMs: Date.now(),
+        }
+      }
+      const walletAddress = this.walletAddress
+      if (!walletAddress) throw new InitializationError('Wallet is not initialized.')
+      const feeOptions = await this.relayer.feeOptions(
+        walletAddress,
+        this.chainId,
+        signedCall.to,
+        callsToSend,
+        signedCall.data,
+      )
+      return feeOptions.sponsored === true && !feeOptions.failed
+    } catch (err) {
+      console.warn(
+        `isSponsored check failed for chain ${this.chainId}:`,
+        err instanceof Error ? err.message : String(err),
+      )
+      return false
+    }
+  }
+
   /**
    * Builds, signs, and sends a batch of transactions.
    * @param transactions The transactions to be sent.

packages/wallet/dapp-client/src/DappClient.ts

@@ -806,6 +806,30 @@ export class DappClient {
     return await chainSessionManager.getFeeOptions(transactions)
   }
 
+  /**
+   * Checks whether the given transactions would be sponsored on `chainId`.
+   *
+   * Returns `true` only when the relayer's `/FeeOptions` endpoint explicitly
+   * reports sponsorship. A failed quote, network error, or absence of
+   * sponsorship all return `false`, so a `true` result is always safe to
+   * surface as "free gas" in UI.
+   *
+   * Prefer this over inferring sponsorship from an empty `getFeeOptions`
+   * array — a swallowed `/FeeOptions` error also produces an empty array.
+   *
+   * @example
+   * if (await dappClient.isSponsored(1, transactions)) {
+   *   // safe to show "Free gas, sponsored by app"
+   * } else {
+   *   const feeOptions = await dappClient.getFeeOptions(1, transactions)
+   *   // present feeOptions[0..n] to the user as payment choices
+   * }
+   */
+  async isSponsored(chainId: number, transactions: Transaction[]): Promise<boolean> {
+    const chainSessionManager = await this.getOrInitializeChainManager(chainId)
+    return await chainSessionManager.isSponsored(transactions)
+  }
+
   /**
    * Fetches fee tokens for a chain.
    * @returns A promise that resolves with the fee tokens response. {@link GetFeeTokensResponse}