Surface relayer sponsorship signal end-to-end (additive, non-breaking) (#1007)

* feat(relayer): propagate sponsored signal and mark swallowed errors

`RpcRelayer.feeOptions` now forwards the server's `sponsored: boolean` to
callers, and both `feeOptions` and `feeTokens` mark their swallowed-error
returns with `failed: true`. The `Relayer` interface and all bundled
implementations (Rpc, Sequence, Local, EIP6963, Pk) are widened to match.

Additive change: existing consumers ignoring the new fields are unaffected.
Downstream sponsorship classifiers should switch from `!feeOption` inference
to `sponsored === true` so a real subsidy is no longer indistinguishable
from a swallowed `/FeeOptions` error.

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

* feat(wallet-wdk): carry sponsored/failed on StandardRelayerOption

`StandardRelayerOption` gains optional `sponsored` and `failed` fields,
populated on both construction branches in `transactions.ts` from the
relayer SDK's new `feeOptions` return. `isStandardRelayerOption` /
`isERC4337RelayerOption` are re-exported so consumers can narrow before
reading the new fields.

UI consumers that classified sponsorship by "no fee option attached"
should switch to `sponsored === true` to distinguish a real subsidy from
a swallowed `/FeeOptions` error.

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

* 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>

---------

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.

.changeset/relayer-sponsored-signal.md

@@ -0,0 +1,20 @@
+---
+'@0xsequence/relayer': minor
+---
+
+Surface explicit sponsorship signal on `feeOptions` and an error marker on
+`feeOptions` / `feeTokens`.
+
+- `RpcRelayer.feeOptions` now returns `sponsored: boolean`, forwarded from the
+  server's `FeeOptionsReturn.sponsored`. The `Relayer` interface and all
+  bundled implementations (`RpcRelayer`, `SequenceRelayer`, `LocalRelayer`,
+  `EIP6963Relayer`, `PkRelayer`) carry the new field.
+- When `feeOptions` swallows a transport / server error it now returns
+  `{ options: [], sponsored: false, failed: true }` (was `{ options: [] }`).
+- When `feeTokens` swallows an error it now returns
+  `{ isFeeRequired: false, failed: true }` (was `{ isFeeRequired: false }`).
+
+These changes are additive — existing consumers that ignore the new fields are
+unaffected. Consumers that classified sponsorship by "no fee option attached"
+should migrate to `sponsored === true` to distinguish a real subsidy from a
+swallowed `/FeeOptions` error.

.changeset/wdk-sponsored-signal.md

@@ -0,0 +1,23 @@
+---
+'@0xsequence/wallet-wdk': minor
+---
+
+Carry `sponsored` / `failed` through `StandardRelayerOption`.
+
+`StandardRelayerOption` now exposes two optional fields:
+
+- `sponsored?: boolean` — populated from the relayer SDK's new `feeOptions`
+  return field. `true` means the server confirmed an active sponsorship policy
+  match; `false` means it did not (or the quote failed).
+- `failed?: boolean` — `true` when the relayer's `feeOptions` call was swallowed
+  due to a transport or server error.
+
+Both fields are populated on the empty-options construction branch and the
+per-option mapping branch in `transactions.ts`. The new `isStandardRelayerOption`
+and `isERC4337RelayerOption` runtime helpers are now re-exported from the
+package root for consumers that need to narrow `RelayerOption` before reading
+the new fields.
+
+UI / wallet consumers that previously classified sponsorship by "no `feeOption`
+attached" should switch to `sponsored === true` so a real subsidy is no longer
+indistinguishable from a swallowed `/FeeOptions` error.

packages/services/relayer/src/relayer/relayer.ts

@@ -11,15 +11,20 @@ export interface Relayer {
 
   isAvailable(wallet: Address.Address, chainId: number): Promise<boolean>
 
-  feeTokens(): Promise<{ isFeeRequired: boolean; tokens?: FeeToken[]; paymentAddress?: Address.Address }>
+  feeTokens(): Promise<{
+    isFeeRequired: boolean
+    tokens?: FeeToken[]
+    paymentAddress?: Address.Address
+    failed?: boolean
+  }>
 
   feeOptions(
     wallet: Address.Address,
     chainId: number,
     to: Address.Address,
     calls: Payload.Call[],
     data?: Hex.Hex,
-  ): Promise<{ options: FeeOption[]; quote?: FeeQuote }>
+  ): Promise<{ options: FeeOption[]; quote?: FeeQuote; sponsored: boolean; failed?: boolean }>
 
   relay(to: Address.Address, data: Hex.Hex, chainId: number, quote?: FeeQuote): Promise<{ opHash: Hex.Hex }>
 

packages/services/relayer/src/relayer/rpc-relayer/index.ts

@@ -123,7 +123,12 @@ export class RpcRelayer implements Relayer {
     return Promise.resolve(this.chainId === chainId)
   }
 
-  async feeTokens(): Promise<{ isFeeRequired: boolean; tokens?: RpcFeeToken[]; paymentAddress?: Address.Address }> {
+  async feeTokens(): Promise<{
+    isFeeRequired: boolean
+    tokens?: RpcFeeToken[]
+    paymentAddress?: Address.Address
+    failed?: boolean
+  }> {
     try {
       const { isFeeRequired, tokens, paymentAddress } = await this.client.feeTokens()
       if (isFeeRequired) {
@@ -140,7 +145,7 @@ export class RpcRelayer implements Relayer {
       }
     } catch (e) {
       console.warn('RpcRelayer.feeTokens failed:', e)
-      return { isFeeRequired: false }
+      return { isFeeRequired: false, failed: true }
     }
   }
 
@@ -150,7 +155,7 @@ export class RpcRelayer implements Relayer {
     to: Address.Address,
     calls: Payload.Call[],
     data?: Hex.Hex,
-  ): Promise<{ options: FeeOption[]; quote?: FeeQuote }> {
+  ): Promise<{ options: FeeOption[]; quote?: FeeQuote; sponsored: boolean; failed?: boolean }> {
     // IMPORTANT:
     // The relayer FeeOptions endpoint simulates `eth_call(to, data)`.
     // Callers that already built a wallet transaction should pass its `to` and `data`.
@@ -182,10 +187,10 @@ export class RpcRelayer implements Relayer {
         gasLimit: option.gasLimit,
       }))
 
-      return { options, quote }
+      return { options, quote, sponsored: result.sponsored }
     } catch (e) {
       console.warn('RpcRelayer.feeOptions failed:', e)
-      return { options: [] }
+      return { options: [], sponsored: false, failed: true }
     }
   }
 

packages/services/relayer/src/relayer/standard/eip6963.ts

@@ -23,7 +23,12 @@ export class EIP6963Relayer implements Relayer {
     return this.relayer.isAvailable(wallet, chainId)
   }
 
-  feeTokens(): Promise<{ isFeeRequired: boolean; tokens?: FeeToken[]; paymentAddress?: Address.Address }> {
+  feeTokens(): Promise<{
+    isFeeRequired: boolean
+    tokens?: FeeToken[]
+    paymentAddress?: Address.Address
+    failed?: boolean
+  }> {
     return this.relayer.feeTokens()
   }
 
@@ -32,7 +37,7 @@ export class EIP6963Relayer implements Relayer {
     chainId: number,
     to: Address.Address,
     calls: Payload.Call[],
-  ): Promise<{ options: FeeOption[]; quote?: FeeQuote }> {
+  ): Promise<{ options: FeeOption[]; quote?: FeeQuote; sponsored: boolean; failed?: boolean }> {
     return this.relayer.feeOptions(wallet, chainId, to, calls)
   }
 

packages/services/relayer/src/relayer/standard/local.ts

@@ -56,7 +56,12 @@ export class LocalRelayer implements Relayer {
     return new LocalRelayer(new EIP1193ProviderAdapter(provider))
   }
 
-  feeTokens(): Promise<{ isFeeRequired: boolean; tokens?: FeeToken[]; paymentAddress?: Address.Address }> {
+  feeTokens(): Promise<{
+    isFeeRequired: boolean
+    tokens?: FeeToken[]
+    paymentAddress?: Address.Address
+    failed?: boolean
+  }> {
     return Promise.resolve({
       isFeeRequired: false,
     })
@@ -67,8 +72,8 @@ export class LocalRelayer implements Relayer {
     _chainId: number,
     _to: Address.Address,
     _calls: Payload.Call[],
-  ): Promise<{ options: FeeOption[]; quote?: FeeQuote }> {
-    return Promise.resolve({ options: [] })
+  ): Promise<{ options: FeeOption[]; quote?: FeeQuote; sponsored: boolean; failed?: boolean }> {
+    return Promise.resolve({ options: [], sponsored: false })
   }
 
   async relay(

packages/services/relayer/src/relayer/standard/pk-relayer.ts

@@ -107,7 +107,12 @@ export class PkRelayer implements Relayer {
     return providerChainId === chainId
   }
 
-  feeTokens(): Promise<{ isFeeRequired: boolean; tokens?: FeeToken[]; paymentAddress?: Address.Address }> {
+  feeTokens(): Promise<{
+    isFeeRequired: boolean
+    tokens?: FeeToken[]
+    paymentAddress?: Address.Address
+    failed?: boolean
+  }> {
     return this.relayer.feeTokens()
   }
 
@@ -116,7 +121,7 @@ export class PkRelayer implements Relayer {
     chainId: number,
     to: Address.Address,
     calls: Payload.Call[],
-  ): Promise<{ options: FeeOption[]; quote?: FeeQuote }> {
+  ): Promise<{ options: FeeOption[]; quote?: FeeQuote; sponsored: boolean; failed?: boolean }> {
     return this.relayer.feeOptions(wallet, chainId, to, calls)
   }
 

packages/services/relayer/src/relayer/standard/sequence.ts

@@ -17,7 +17,12 @@ export class SequenceRelayer implements Relayer {
     return true
   }
 
-  async feeTokens(): Promise<{ isFeeRequired: boolean; tokens?: FeeToken[]; paymentAddress?: Address.Address }> {
+  async feeTokens(): Promise<{
+    isFeeRequired: boolean
+    tokens?: FeeToken[]
+    paymentAddress?: Address.Address
+    failed?: boolean
+  }> {
     const { isFeeRequired, tokens, paymentAddress } = await this.service.feeTokens()
     if (isFeeRequired) {
       Address.assert(paymentAddress)
@@ -39,17 +44,18 @@ export class SequenceRelayer implements Relayer {
     to: Address.Address,
     calls: Payload.Call[],
     transactionData?: Hex.Hex,
-  ): Promise<{ options: FeeOption[]; quote?: FeeQuote }> {
+  ): Promise<{ options: FeeOption[]; quote?: FeeQuote; sponsored: boolean; failed?: boolean }> {
     const execute = AbiFunction.from('function execute(bytes calldata _payload, bytes calldata _signature)')
     const payload = Payload.encode({ type: 'call', space: 0n, nonce: 0n, calls }, to)
     const signature = '0x0001' // TODO: use a stub signature
     const data = transactionData ?? AbiFunction.encodeData(execute, [Bytes.toHex(payload), signature])
 
-    const { options, quote } = await this.service.feeOptions({ wallet, to, data })
+    const { options, quote, sponsored } = await this.service.feeOptions({ wallet, to, data })
 
     return {
       options,
       quote: quote ? { _tag: 'FeeQuote', _quote: quote } : undefined,
+      sponsored,
     }
   }
 

packages/services/relayer/test/relayer/relayer.test.ts

@@ -294,6 +294,7 @@ describe('Relayer', () => {
       vi.mocked(mockRelayer.feeOptions).mockResolvedValue({
         options: [],
         quote: undefined,
+        sponsored: false,
       })
       vi.mocked(mockRelayer.relay).mockResolvedValue({
         opHash: TEST_OP_HASH,
@@ -375,6 +376,60 @@ describe('Relayer', () => {
         data: expectedData,
       })
     })
+
+    it('should propagate sponsored:true from the server', async () => {
+      const fetchImpl = vi.fn(
+        async () => new Response(JSON.stringify({ options: [], sponsored: true }), { status: 200 }),
+      )
+      const relayer = new Relayer.RpcRelayer('https://relayer.test', TEST_CHAIN_ID, 'https://rpc.test', fetchImpl)
+
+      const result = await relayer.feeOptions(TEST_WALLET_ADDRESS, TEST_CHAIN_ID, TEST_TO_ADDRESS, [mockCall])
+
+      expect(result.sponsored).toBe(true)
+      expect(result.options).toEqual([])
+      expect(result.failed).toBeUndefined()
+    })
+
+    it('should propagate sponsored:false from the server', async () => {
+      const fetchImpl = vi.fn(
+        async () => new Response(JSON.stringify({ options: [], sponsored: false }), { status: 200 }),
+      )
+      const relayer = new Relayer.RpcRelayer('https://relayer.test', TEST_CHAIN_ID, 'https://rpc.test', fetchImpl)
+
+      const result = await relayer.feeOptions(TEST_WALLET_ADDRESS, TEST_CHAIN_ID, TEST_TO_ADDRESS, [mockCall])
+
+      expect(result.sponsored).toBe(false)
+      expect(result.failed).toBeUndefined()
+    })
+
+    it('should return sponsored:false and failed:true when the server errors', async () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const fetchImpl = vi.fn(
+        async () =>
+          new Response(JSON.stringify({ error: 'Aborted', code: 1005, msg: 'simulation failed' }), { status: 400 }),
+      )
+      const relayer = new Relayer.RpcRelayer('https://relayer.test', TEST_CHAIN_ID, 'https://rpc.test', fetchImpl)
+
+      const result = await relayer.feeOptions(TEST_WALLET_ADDRESS, TEST_CHAIN_ID, TEST_TO_ADDRESS, [mockCall])
+
+      expect(result).toEqual({ options: [], sponsored: false, failed: true })
+      expect(warn).toHaveBeenCalled()
+      warn.mockRestore()
+    })
+  })
+
+  describe('RpcRelayer.feeTokens', () => {
+    it('should return failed:true when the server errors', async () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const fetchImpl = vi.fn(async () => new Response('boom', { status: 500 }))
+      const relayer = new Relayer.RpcRelayer('https://relayer.test', TEST_CHAIN_ID, 'https://rpc.test', fetchImpl)
+
+      const result = await relayer.feeTokens()
+
+      expect(result).toEqual({ isFeeRequired: false, failed: true })
+      expect(warn).toHaveBeenCalled()
+      warn.mockRestore()
+    })
   })
 
   describe('Type compatibility', () => {