@fluent.xyz/connect 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/INTEGRATION.md ADDED
@@ -0,0 +1,1242 @@
1
+ # Integrating `@fluent.xyz/connect`
2
+
3
+ A step-by-step guide to adding the Fluent Connect widget to a React app.
4
+
5
+ > **Breaking in 0.3.0 — Partner is now App.**
6
+ >
7
+ > - `FluentWidgetConfig.partnerId` is renamed to `appId`. Passing `partnerId` throws
8
+ > with this hint; there is no alias.
9
+ > - The id value is `app_<32 hex>`, re-issued for every App and shown in the Fluent
10
+ > Dashboard. Old `partner_<32 hex>` ids are refused at startup (the widget asserts
11
+ > `^app_[0-9a-f]{32}$`) and are unknown to the service.
12
+ > - `FluentAuthError.code` values `unknown_partner`, `partner_not_auth_enabled` and
13
+ > `partner_mismatch` are now `unknown_app`, `app_not_auth_enabled` and `app_mismatch`.
14
+ > - The PostHog event property `partner_id` is now `app_id`.
15
+
16
+ The widget provides everything between "user clicks Connect" and "transaction is
17
+ confirmed on Fluent": login (Privy), a ZeroDev smart account, the account/wallet
18
+ UI, gas payment in ERC-20, and a single execution API (`createBatchOp`) that
19
+ works for both smart accounts and external EOAs.
20
+
21
+ > **Scope.** This widget targets apps running **on the Fluent network**. Auth,
22
+ > the smart account, and the paymaster all use Fluent's shared infrastructure —
23
+ > you bring an `appId`, not your own Privy/ZeroDev project.
24
+
25
+ ---
26
+
27
+ ## 1. Prerequisites
28
+
29
+ Before writing code you need:
30
+
31
+ 1. **A Fluent `appId`** — the `app_<32 hex>` id of your App, shown in the
32
+ Fluent Dashboard. Identity: sponsorship, auth and analytics speak it.
33
+ Required; the widget throws without it, and throws on any other shape.
34
+ 2. **A Privy app client (`privyClientId`)** — the `client-…` value Fluent
35
+ issued alongside. Login configuration: your allowed origins live on it.
36
+ Required; the widget throws without it.
37
+ 3. **A target network** — `testnet` (default) or `mainnet`.
38
+ 4. **Your app's origin registered on that Privy app client** — what
39
+ `authMode: "direct"` needs, and `"direct"` is the mode to set.
40
+
41
+ > **Hosted mode is deprecated.** `authMode: "hosted"` is no longer supported and will be
42
+ > removed in 0.5.0 — use `authMode: "direct"`. It is still the config default
43
+ > ([§4](#4-config-reference-fluentwidgetconfig)), so every example in this guide sets
44
+ > `authMode` explicitly and so should your app. What hosted mode still does, while it is
45
+ > here, is [§8](#8-auth-modes).
46
+
47
+ > **Migrating from `clientId`?** The option is gone. The value it held is now
48
+ > `privyClientId`, and `appId` is new — passing `clientId` throws with the
49
+ > same hint.
50
+
51
+ Peer requirement: **React 18 or 19**.
52
+
53
+ ---
54
+
55
+ ## 2. Install
56
+
57
+ ```bash
58
+ pnpm add @fluent.xyz/connect react react-dom viem wagmi @tanstack/react-query
59
+ ```
60
+
61
+ `react`, `react-dom`, `viem`, `wagmi`, and `@tanstack/react-query` are
62
+ **peer dependencies** — you install them in your app so there is exactly **one**
63
+ copy of each in the tree (see §9 for why this matters). Privy, ZeroDev, and
64
+ Reown AppKit are bundled by the widget; you don't install those.
65
+
66
+ Peer version ranges: `react >=18`, `viem ^2`, `wagmi ^2`, `@tanstack/react-query ^5`.
67
+
68
+ ### `Buffer` is provided for you
69
+
70
+ You do not need a `Buffer` polyfill. Importing `@fluent.xyz/connect` defines
71
+ `globalThis.Buffer` when the page has none: Privy's embedded wallet calls `Buffer.from(...)`
72
+ while signing a UserOperation, and a browser has no `Buffer`, so without it the first
73
+ signature fails. The SDK ships the polyfill as a side-effecting module of its own, which
74
+ survives a production build's tree-shaking, and it never replaces an existing
75
+ `globalThis.Buffer` — a polyfill your app already ships keeps working.
76
+
77
+ ---
78
+
79
+ ## 3. Minimal setup
80
+
81
+ Import the stylesheet once at your app entry, then mount `<FluentWidget>` near
82
+ the root and render your app inside its render prop:
83
+
84
+ ```tsx
85
+ import { FluentWidget, resolveFluentWidgetNetworkFromEnv } from "@fluent.xyz/connect";
86
+ import "@fluent.xyz/connect/styles.css";
87
+
88
+ export function App() {
89
+ return (
90
+ <FluentWidget
91
+ config={{
92
+ appId: "app_<32 hex, from the Fluent Dashboard>",
93
+ privyClientId: "client-<issued by Fluent>",
94
+ network: resolveFluentWidgetNetworkFromEnv() ?? "testnet",
95
+ appName: "My App",
96
+ authMode: "direct",
97
+ }}
98
+ mode="page"
99
+ renderPage={() => <YourApp />}
100
+ />
101
+ );
102
+ }
103
+ ```
104
+
105
+ `@fluent.xyz/connect/styles.css` is the package's **only** stylesheet and
106
+ carries everything the widget renders, including RainbowKit's styles for the
107
+ bridge wallet picker. The JavaScript entry imports no CSS of its own, so
108
+ `import "@fluent.xyz/connect"` also works where no bundler handles stylesheets
109
+ — server-side rendering, plain Node scripts, Jest.
110
+
111
+ `<FluentWidget>` is a **provider + UI host**. Everything rendered through
112
+ `renderPage` (or `renderHome`) — and any component below it — can read the widget
113
+ via `useFluentWidget()` / `useWidget()`. No prop-drilling required.
114
+
115
+ Set the network from an env var if you prefer:
116
+
117
+ ```bash
118
+ # testnet (default) — aliases: development, dev
119
+ VITE_FLUENT_WIDGET_NETWORK=testnet
120
+ # mainnet — aliases: production, prod
121
+ VITE_FLUENT_WIDGET_NETWORK=mainnet
122
+ ```
123
+
124
+ ### Networks and chain ids
125
+
126
+ The chain id is **different per network** and is not derivable from the network
127
+ name, so anything in your app that is pinned to a chain — a wagmi/viem config, a
128
+ deployment address map, a subgraph — has to match the network the widget runs on.
129
+
130
+ | `network` | Chain id | Chain name | Settles on | Explorer |
131
+ |-------------|----------|----------------|----------------------|----------|
132
+ | `"mainnet"` | `25363` | Fluent Mainnet | Ethereum (`1`) | https://fluentscan.xyz |
133
+ | `"testnet"` | `20994` | Fluent Testnet | Sepolia (`11155111`) | https://testnet.fluentscan.xyz |
134
+
135
+ RPC endpoints: `https://rpc.fluent.xyz/` and `https://rpc.testnet.fluent.xyz/`.
136
+
137
+ Prefer reading these from the SDK over hardcoding them — the values travel with
138
+ the package, so a chain id change is a version bump rather than a hunt through
139
+ your codebase:
140
+
141
+ ```ts
142
+ import { getFluentChainForNetwork, getFluentChainByChainId } from "@fluent.xyz/connect";
143
+
144
+ const chain = getFluentChainForNetwork("mainnet"); // viem Chain — chain.id === 25363
145
+ const definition = getFluentChainByChainId(20994); // reverse lookup — { id: "fluent-testnet", name, rpcUrls, … }
146
+ ```
147
+
148
+ `fluentMainnet` and `fluentTestnet` are also exported directly as viem chains,
149
+ ready to drop into `createConfig({ chains: [...] })`.
150
+
151
+ > **Mismatch symptom.** A host pinned to one network while the widget runs on
152
+ > another fails with an *unsupported chain id* error at the first write, not at
153
+ > mount — the read path works fine until then, so the mismatch looks like a
154
+ > broken transaction rather than a broken config. If you see that error, compare
155
+ > your chain list against `network` before debugging the call itself.
156
+
157
+ **Treat the network as a deploy-time choice.** There is no `switchNetwork()` API,
158
+ and switching at runtime is not a supported flow today: changing `config.network`
159
+ does rebuild the widget's network context and remount its auth provider, but what
160
+ happens to an active session across that remount is undefined. If your app needs
161
+ to offer more than one network, mount the widget per network behind your own
162
+ routing rather than mutating `config.network` under a live session.
163
+
164
+ ---
165
+
166
+ ## 4. Config reference (`FluentWidgetConfig`)
167
+
168
+ | Field | Required | Default | Notes |
169
+ |---------------|----------|--------------------|-------|
170
+ | `appId` | ✅ | — | The App's `app_<32 hex>` id — identity for sponsorship, auth and analytics; the token `aud`. Asserted at startup. |
171
+ | `privyClientId` | ✅ | — | Privy app client issued by Fluent — login configuration; allowed origins live on it. |
172
+ | `network` | ➖ | env → `"testnet"` | `"testnet"` or `"mainnet"` — see [Networks and chain ids](#networks-and-chain-ids). |
173
+ | `appName` | ➖ | `"Fluent Connect Demo"` | Shown in login UI. |
174
+ | `authMode` | ➖ | `"hosted"` | `"direct"` = Fluent's own sign-in dialog inside your page (needs an allow-listed origin) — the one to set. `"hosted"` = the Fluent authorize popup, **deprecated**, removed in 0.5.0; it is still the default, so leaving `authMode` out opts into it. |
175
+ | `customOAuthRedirectUrl` | ➖ | current page | Exact HTTPS callback for the widget's Privy OAuth flows; no credentials, query, or fragment. See [Capacitor OAuth](#capacitor-oauth). |
176
+ | `enabledAuthMethods` | ➖ | `["google", "email", "passkey"]` | Methods the `"direct"` dialog offers beside X, in the order given. X is always offered — see [Sign-in methods](#sign-in-methods). |
177
+ | `source` | ➖ | `"fluent_connect_widget"` | Attribution tag. |
178
+ | `campaign` | ➖ | — | Attribution tag. |
179
+ | `reconnectOnMount` | ➖ | unset | Unset restores only injected wallets (including EIP-6963) and WalletConnect silently on page load. `true` restores every connector, including Base Account and Coinbase Wallet SDK, which may prompt. Explicit `false` restores none. Explicit connection and the Fluent session are unaffected. |
180
+ | `disableAnalytics` | ➖ | `false` | `true` turns off all analytics — PostHog is never initialised, nothing sent or stored. |
181
+ | `gasPayment` | ➖ | `{ defaultToken: "ETH", sponsorship: "auto" }` | Initial token, native-gas sponsorship policy, and optional `ethValueByToken` hints. A Fluent ID's saved token choice takes precedence; an external wallet applies no saved choice and always pays native gas — see [What the widget stores for a signed-in user](#what-the-widget-stores-for-a-signed-in-user). |
182
+ | `swapper` | ➖ | Fluent defaults | On-ramp/bridge config. |
183
+ | `reputationEnabled` | ➖ | `true` | `false` hides the Reputation tab — and with it the tab strip, leaving Home. The families request is never made. |
184
+ | `assets` | ➖ | Fluent brand | Override logo etc. |
185
+ | `avatar` | ➖ | Fluent mark | `{ defaultLogoUrl, forceDefault }` — see [Account avatar](#account-avatar). |
186
+ | `scopes` | ➖ | network defaults | Permission scopes requested at login. |
187
+
188
+ ### Capacitor OAuth
189
+
190
+ Capacitor apps run at a local origin such as `capacitor://localhost` on iOS.
191
+ For X and other social sign-in, use `authMode: "direct"` and set
192
+ `customOAuthRedirectUrl` to an HTTPS Universal Link that returns to the app:
193
+
194
+ ```tsx
195
+ <FluentWidget
196
+ config={{
197
+ appId,
198
+ privyClientId,
199
+ authMode: "direct",
200
+ enabledAuthMethods: [], // X remains available.
201
+ customOAuthRedirectUrl: "https://app.example.com/auth/ios/callback",
202
+ }}
203
+ />
204
+ ```
205
+
206
+ The widget passes this URL to its internal `PrivyProvider`. Omitting it, or
207
+ passing a blank string, keeps Privy's current-page callback. Values are trimmed
208
+ and otherwise preserved to match the dashboard's exact redirect allowlist.
209
+ Custom schemes such as `capacitor://localhost` are not supported as callbacks.
210
+ This option does not configure the separate hosted authorize popup's redirect.
211
+
212
+ The host still needs to:
213
+
214
+ 1. Register `capacitor://localhost` and the callback's HTTPS domain in the
215
+ Fluent-issued Privy client's allowed origins; enable X in the shared Privy app.
216
+ Register the exact callback URL in Privy's allowed OAuth redirects.
217
+ 2. Configure iOS Associated Domains and serve an `apple-app-site-association`
218
+ file for the callback domain and the app's team/bundle identifier.
219
+ 3. Install Capacitor's App/Browser plugins and handle `appUrlOpen` (and the
220
+ launch URL when appropriate). Validate the callback origin and path, then
221
+ copy its `privy_oauth_code`, `privy_oauth_state`, and `privy_oauth_provider`
222
+ query parameters to the local webview URL so Privy can finish its OAuth flow.
223
+ Keep the local OAuth session/state intact and close the browser after return.
224
+ 4. Test sign-in, cancellation, and return on an iOS device. Dashboard allowlists
225
+ and Universal Links are deployment prerequisites; setting this option alone
226
+ does not complete native authentication.
227
+
228
+ See [Privy's Capacitor OAuth guide](https://docs.privy.io/recipes/capacitor-oauth)
229
+ and [allowed OAuth redirects](https://docs.privy.io/recipes/react/allowed-oauth-redirects).
230
+ This uses X OAuth through the browser; it does not guarantee a handoff to the
231
+ installed X app.
232
+
233
+ ### Sign-in methods
234
+
235
+ With `authMode: "direct"`, sign-in methods default to this order: **X, Google,
236
+ email, passkey**. They and the external wallet list share a single Fluent dialog.
237
+ Email verification stays in place; X and Google redirect to their OAuth provider
238
+ and resume the matching dialog on return. Passkey login uses the browser's
239
+ credential prompt for an existing passkey. Enable these methods in the shared
240
+ Privy app's dashboard; displaying a button does not enable its provider.
241
+ Privy still owns any required MFA, recovery, or signing prompt, and the Fluent
242
+ dialog yields while those are open.
243
+ The wallet list scrolls within the dialog on smaller screens. WalletConnect hands
244
+ off to its QR flow after closing the Fluent dialog.
245
+
246
+ All four methods are on by default. `enabledAuthMethods` names the ones an app
247
+ wants beside X — **Google, email, passkey** — and the order it wants them in.
248
+ **Sign-in with X is always offered and cannot be switched off**, so it is not a
249
+ value here; it stays first whatever the list says.
250
+
251
+ ```tsx
252
+ <FluentWidget
253
+ config={{
254
+ appId,
255
+ privyClientId,
256
+ authMode: "direct",
257
+ // Leaves X and email.
258
+ enabledAuthMethods: ["email"],
259
+ }}
260
+ />
261
+ ```
262
+
263
+ Omit it to keep all three; pass `[]` to leave X as the only Fluent method. The
264
+ external wallet list is unaffected either way. The option only applies to
265
+ `authMode: "direct"`; the hosted popup owns its own method list.
266
+
267
+ Hosts supplying their own `wallet` prop can optionally provide `choices` (an array
268
+ of `{ id, name, icon?, handoff? }`) and `connectChoice(id)` to use the inline list.
269
+ Set `handoff: true` for a choice that owns its own dialog. Without these optional
270
+ fields, **Other wallets** retains the existing `wallet.open()` behavior.
271
+
272
+ ### Account avatar
273
+
274
+ The tile on the connect button and in the account drawer shows the user's X
275
+ profile picture when Privy has one, and the Fluent mark otherwise. `avatar`
276
+ replaces that fallback with your own logo:
277
+
278
+ ```tsx
279
+ <FluentWidget
280
+ config={{
281
+ appId,
282
+ privyClientId,
283
+ authMode: "direct",
284
+ avatar: {
285
+ // URL or data URI — rendered in a 32px rounded tile.
286
+ defaultLogoUrl: "/brand/logo.svg",
287
+ // Ignore the X avatar and always show `defaultLogoUrl`.
288
+ forceDefault: true,
289
+ },
290
+ }}
291
+ />
292
+ ```
293
+
294
+ | Field | Default | Notes |
295
+ |------------------|---------|-------|
296
+ | `defaultLogoUrl` | Fluent mark | Shown when there is no X avatar. A logo that fails to load falls back to the Fluent mark. |
297
+ | `forceDefault` | `false` | `true` drops the X avatar entirely, so every user sees `defaultLogoUrl`. |
298
+
299
+ Rendering your own button through `renderConnectButton` bypasses this — pass the
300
+ logo yourself, or reuse the exported `AccountAvatar` component.
301
+
302
+ ---
303
+
304
+ ## 5. Placing the connect button
305
+
306
+ By default a floating **Connect / Account** button renders top-right
307
+ (`connectButton="fixed"`). You have three options:
308
+
309
+ ```tsx
310
+ // (a) default floating button — do nothing.
311
+
312
+ // (b) inline the default button where you want it
313
+ <FluentWidget connectButton={false} renderConnectButton={({ DefaultButton }) => (
314
+ <header><DefaultButton /></header>
315
+ )} mode="page" renderPage={() => <YourApp />} />
316
+
317
+ // (c) fully custom CTA
318
+ <FluentWidget connectButton={false} mode="page" renderPage={({
319
+ openConnect, openAccount, hasConnectedAccount,
320
+ }) => (
321
+ <button onClick={hasConnectedAccount ? openAccount : openConnect}>
322
+ {hasConnectedAccount ? "Account" : "Connect"}
323
+ </button>
324
+ )} />
325
+ ```
326
+
327
+ ---
328
+
329
+ ## 6. Reading account state
330
+
331
+ From any component under the widget:
332
+
333
+ ```tsx
334
+ import { useFluentWidget } from "@fluent.xyz/connect";
335
+
336
+ function Balance() {
337
+ const { widget, session, openConnect, refreshBalances } = useFluentWidget();
338
+
339
+ const address = widget.account.address ?? session?.wallet.smartAccountAddress;
340
+ const ready = widget.account.connected && widget.account.executionReady;
341
+
342
+ if (!ready) return <button onClick={openConnect}>Connect</button>;
343
+ return <span>{address}</span>;
344
+ }
345
+ ```
346
+
347
+ Key fields on `widget.account`:
348
+
349
+ - `connected` — a user is signed in.
350
+ - `executionReady` — the account can send transactions **now**.
351
+ - `executionStatus` / `executionError` — `"disconnected" | "ready" | "unavailable" | "error"` and a message.
352
+ - `type` — `"smart"` or `"eoa"`.
353
+ - `capabilities` — `{ atomicBatch, erc20Gas }` (both smart-account only), so you can adapt UI without branching on `type`. `erc20Gas` means gas can be paid in an ERC-20 via the paymaster — not free/sponsored gas.
354
+
355
+ Use `useWidget()` if you only need the `widget` API and nothing else from the context.
356
+
357
+ ### What the widget stores for a signed-in user
358
+
359
+ Three things belong to the person, not to your page, and the widget keeps them on
360
+ the Fluent service so they follow the user between your app, every other app that
361
+ embeds the widget, and every browser they sign in from:
362
+
363
+ - **Quick sign** — the "sign without a confirmation popup" preference.
364
+ - **The gas token** — which token the paymaster is asked to charge.
365
+ - **Their own token list** — the tokens they added by contract address
366
+ ([§6](#6-reading-account-state)'s token list, not your `tokens` prop).
367
+
368
+ Your `tokens` prop and Fluent's own defaults are untouched by this: they are part
369
+ of the app, not of the user.
370
+
371
+ The first two describe a Fluent smart account and nothing else: Quick sign
372
+ governs the Fluent ID's signer, and the gas token decides what the paymaster is
373
+ charged. **For an external wallet (`widget.account.type === "eoa"`) the widget
374
+ neither applies nor writes either one.** It still performs the settings read —
375
+ the user's token list rides on it — and that list is still loaded, added to,
376
+ removed from and one-time-imported exactly as below, but no `PATCH /me/settings`
377
+ is ever sent for a preference, on any path. An external wallet confirms every
378
+ call in the wallet itself and pays native gas, so a stored value for either
379
+ preference would describe nothing it does; and writing one would overwrite what
380
+ the same person's Fluent ID keeps, because the service resolves both of their
381
+ sessions to one person and cannot tell them apart.
382
+
383
+ The widget reads once per sign-in and writes every change back — for an external
384
+ wallet, every change to the token list — using the same Fluent token
385
+ `getAuthToken()` returns ([§8](#8-auth-modes)). Nothing is sent but that token —
386
+ no user id is ever put in a request by the widget.
387
+
388
+ It falls back to this browser's `localStorage` in the two states where no Fluent
389
+ token can exist, and behaves there exactly as it did before 0.4.0:
390
+
391
+ | State | The user's token list | Quick sign and the gas token |
392
+ | --- | --- | --- |
393
+ | direct / Fluent ID | the service, or `localStorage` if the read fails | the service, or the in-memory defaults if the read fails |
394
+ | direct / external wallet | the service, or `localStorage` if the read fails | not kept: neither applies to an external wallet |
395
+ | hosted / external wallet | the service, or `localStorage` if the read fails | not kept: neither applies to an external wallet |
396
+ | hosted / Fluent ID | `localStorage` (`getAuthToken()` rejects with `hosted_not_supported`) | the in-memory defaults |
397
+ | nobody connected | `localStorage` | the in-memory defaults |
398
+
399
+ The first time a user signs in with tokens already in this browser's
400
+ `localStorage` and none on the service, the widget carries that list over once and
401
+ then clears the local key. This is the token list, so it happens for an external
402
+ wallet too.
403
+
404
+ ### What an external-wallet user sees in Settings
405
+
406
+ The wallet menu's Settings screen says the same thing the table does, so nothing
407
+ on it is a control over something that cannot happen. For an external wallet:
408
+
409
+ - **Quick sign** is shown off and disabled, described as "Available with a Fluent
410
+ smart account". Every call is confirmed in the wallet, whatever the row holds.
411
+ - **Gas payment** is shown disabled, with the same description and the network's
412
+ native token (ETH) as its value — what an external wallet always pays fees in,
413
+ whatever `gasPayment.defaultToken` names.
414
+ - **Faucet** is hidden. It funds a Fluent smart account, and there is none here.
415
+ - **Explorer** reads "View account on explorer" and opens the EOA's own address
416
+ rather than a smart account's.
417
+
418
+ The user's token list is on the same screen's Home panel and behaves as it does
419
+ for a Fluent ID: it loads from the service, and additions and removals are
420
+ written there. A Fluent ID's Settings screen is unchanged — both preferences are
421
+ live, the faucet is offered on a faucet network, and Explorer opens the smart
422
+ account.
423
+
424
+ One more thing is kept in `localStorage`, and it is not a preference: the **refresh
425
+ token** that renews the Fluent token without asking the user to sign again. It is
426
+ keyed by service, `appId` and account like everything else here, it is cleared when
427
+ the user disconnects, and it is never exposed through a widget API. What it is, how
428
+ long it lasts and what keeping it there costs you:
429
+ [§8](#where-the-session-is-kept-and-what-that-costs).
430
+
431
+ Nothing here is ever thrown at your app, and a read and a write fail differently:
432
+
433
+ - **A failed read** falls back to what the table above calls the read-failure
434
+ case: this browser's `localStorage` token list, and for the two preferences
435
+ whatever is on screen already — the in-memory defaults (Quick sign on, the
436
+ network's default gas token), or the user's own choice if they have changed one
437
+ since signing in. A failed read never applies the defaults over a value the
438
+ person chose. Whether they are told depends on what failed:
439
+ - **Nothing is shown** when the read only says "not yet" — no wallet connected
440
+ yet, no Privy token yet. It is read again as soon as the missing wallet
441
+ signer arrives for the same account. A service with no settings routes at all
442
+ (a bare `404`) is also silent: that describes a deployment, not anything the
443
+ person did or can clear.
444
+ - **The message is shown** for every other failure — the user rejects the
445
+ wallet signature, the network is down, the service answers 401 or 500. The
446
+ wallet menu's Settings screen puts the service's message on its status line,
447
+ the same line a failed write uses. There is no retry behind the user's back;
448
+ it is read again the next time they sign in.
449
+
450
+ Nothing is logged either way. For an external wallet only the token list is
451
+ affected: it applied neither preference from a read that succeeded either, and
452
+ the defaults it is left with are inert — but a read failure that has a message
453
+ still shows it, because the same read carries the token list.
454
+ - **A failed write** — a preference the user just changed, or a token they added
455
+ or removed — is visible: the wallet menu's Settings screen shows the service's
456
+ message on its status line, and `AddTokenForm` shows it under the address
457
+ field. The value the user chose stays in place for the rest of the session, and
458
+ a failed removal is logged through `debugLogging`
459
+ ([§9b](#9b-debugging-an-integration)). An external wallet writes no preference
460
+ at all, so only its token writes can fail this way.
461
+
462
+ Failed writes are not queued or replayed. The next sign-in reads whatever the
463
+ service holds, which for a write that never landed is the old value.
464
+
465
+ > **Breaking in 0.4.0.** `UserTokenStore` is now asynchronous — `list`, `add` and
466
+ > `remove` return promises, and `add` has a new `{ status: "failed", message }`
467
+ > result. If you inject your own `userTokenStore`, wrap each method's return value in
468
+ > `Promise.resolve()` to port a 0.3.x implementation.
469
+ >
470
+ > `useFluentUserTokens()` changed shape with it, and that one needs no injected store to
471
+ > reach you: `add` and `remove` return promises — `add` resolving that same result — and
472
+ > `tokens` starts as an empty array on every mount, filling when the first load settles,
473
+ > so an empty `tokens` on the first render means "not loaded yet", not "no tokens".
474
+ > Called without `{ store }`, the hook reads and writes **this browser's `localStorage`
475
+ > only**, never the service's list the widget syncs for a signed-in user, and after the
476
+ > widget's one-time import moves the local list to the service, that local list is empty.
477
+ > The widget does not expose its service-backed store, so a host that needs the user's
478
+ > synced list must pass its own `store`. A failed load leaves the
479
+ > last list that settled on screen and tells your component nothing; the failure goes to
480
+ > `debugLogging`'s output ([§9b](#9b-debugging-an-integration)).
481
+
482
+ ---
483
+
484
+ ## 7. Sending a transaction
485
+
486
+ All execution goes through **one** API: `widget.createBatchOp({...}).execute()`.
487
+ The widget internally routes a smart account (one sponsored UserOp, signed under
488
+ the user's Quick sign setting) vs an external EOA (sequential native-gas txs,
489
+ each confirmed in the wallet, where Quick sign does not apply), waits for
490
+ inclusion, and refreshes balances — **no host-side branching by account type.**
491
+
492
+ The result includes `receipt` for `hash`, plus `userOpHash` for a smart-account
493
+ operation. Hosts can validate the receipt's logs and read application state at
494
+ `receipt.blockNumber` immediately, without waiting for another confirmation.
495
+ For a sequential EOA batch, `receipt` belongs to the final call; execution stops
496
+ if any call reverts. These fields are optional for compatibility with custom
497
+ executors and older SDKs. An included receipt is not a finality guarantee.
498
+
499
+ Each call is either raw calldata (`data`) or `abi + method + args`. The `to`
500
+ address can be **any** contract — there is no token allow-list on operations.
501
+
502
+ ### Example: approve + deposit (one atomic batch on a smart account)
503
+
504
+ ```tsx
505
+ import { useWidget } from "@fluent.xyz/connect";
506
+ import { erc20Abi } from "./abi";
507
+
508
+ function DepositButton({ asset, vault, amount, account }) {
509
+ const widget = useWidget();
510
+
511
+ async function onDeposit() {
512
+ if (!widget.account.executionReady) return; // guard first
513
+
514
+ const op = widget.createBatchOp({
515
+ id: "approve-deposit",
516
+ reviewTitle: "Approve + deposit",
517
+ calls: [
518
+ { to: asset, abi: erc20Abi, method: "approve", args: [vault, amount] },
519
+ { to: vault, abi: vaultAbi, method: "deposit", args: [amount, account] },
520
+ ],
521
+ });
522
+
523
+ const { hash, atomic } = await op.execute();
524
+ // atomic === true → both landed in a single UserOp (smart account)
525
+ }
526
+
527
+ return <button onClick={onDeposit}>Deposit</button>;
528
+ }
529
+ ```
530
+
531
+ ### Gas payment
532
+
533
+ The widget starts with native **ETH** selected. On a Fluent ID a valid saved user
534
+ preference takes precedence, and the user can choose another supported gas token
535
+ in the menu. An external wallet pays native gas on every call: its menu shows the
536
+ choice disabled over ETH, no saved preference is applied to it, and nothing is
537
+ saved from it ([§6](#what-an-external-wallet-user-sees-in-settings)).
538
+ Set the initial/fallback token and native-gas sponsorship policy in config:
539
+
540
+ ```tsx
541
+ <FluentWidget
542
+ config={{
543
+ appId,
544
+ privyClientId,
545
+ authMode: "direct",
546
+ gasPayment: { defaultToken: "ETH", sponsorship: "never" },
547
+ }}
548
+ />
549
+ ```
550
+
551
+ `sponsorship: "never"` pays native gas from the smart account's ETH balance and
552
+ skips sponsorship authentication and paymaster requests. The default `"auto"`
553
+ retains app-sponsored execution with native-gas fallback. This policy does not
554
+ disable an ERC-20 token's paymaster when the user selects BLEND or USDnr.
555
+ The configured token must be a supported gas token on the selected network.
556
+
557
+ Gas defaults to the token selected in the widget's own gas selector. To force a
558
+ token explicitly, pass just its **symbol** — the widget resolves the ERC-20
559
+ address for the active network internally, so you never pass (or mistype) an
560
+ address:
561
+
562
+ ```ts
563
+ await op.execute({
564
+ gasPayment: { symbol: "BLEND" },
565
+ });
566
+ ```
567
+
568
+ To also fund the paymaster's ERC-20 allowance in the same batch, add
569
+ `includeApproval: true` and `approveAmount`:
570
+
571
+ ```ts
572
+ await op.execute({
573
+ gasPayment: { symbol: "BLEND", includeApproval: true, approveAmount: 100n * 10n ** 18n },
574
+ });
575
+ ```
576
+
577
+ Gas can be paid in `USDnr`, `BLEND`, or native `ETH` (symbol `"ETH"` = native
578
+ gas, no ERC-20 paymaster; app sponsorship still follows the policy above).
579
+ This list is the *gas* token allow-list — it does **not**
580
+ restrict which tokens your calls operate on.
581
+
582
+ Per-operation `gasPayment.sponsorship` overrides the configured policy, so
583
+ `op.execute({ gasPayment: { symbol: "ETH", sponsorship: "auto" } })` can request
584
+ sponsorship even when the widget defaults to `"never"`.
585
+
586
+ ### Execution timing
587
+
588
+ Set `<FluentWidget debugLogging />` to emit `[fluent execution stage]` progress
589
+ before waits and timing entries for setup, preparation, signing, broadcast and
590
+ inclusion. Timing entries contain durations and public hashes, not signatures,
591
+ calldata or authentication tokens. Each sponsored/fallback submission attempt
592
+ has its own timing entry. Logging is off by default and does not repeat gas
593
+ estimation, signing or submission.
594
+
595
+ ETH avoids the ERC-20 paymaster request but still needs UserOperation gas
596
+ estimation. Shorter receipt polling and receipt reuse do not remove bundler or
597
+ paymaster preparation latency; compare these stages before attributing a delay
598
+ to Fluent execution. Receipt inclusion is not additional block confirmation or
599
+ L1 finality.
600
+
601
+ Migration: the initial/fallback gas token changes from BLEND to ETH, without
602
+ overwriting saved preferences. External-wallet auto-reconnect now restores only injected wallets (including
603
+ EIP-6963) and WalletConnect when `reconnectOnMount` is unset. Base Account,
604
+ Coinbase Wallet SDK and unknown connectors do not reconnect or prompt by default;
605
+ explicit connection remains available. Set `reconnectOnMount: true` to restore
606
+ every connector, or explicitly set `false` to restore none. Wallet users returning
607
+ from Link X can therefore resume with the same EOA under the default policy.
608
+
609
+ ### Always guard on `executionReady`
610
+
611
+ `createBatchOp` throws only on malformed input (an empty `calls` array, or a call
612
+ with neither `data` nor `abi` + `method`), but `execute()` rejects if the session
613
+ can't execute. Gate the button on `widget.account.executionReady` and surface
614
+ `widget.account.executionError` to the user.
615
+
616
+ ---
617
+
618
+ ## 7b. Requesting a signature
619
+
620
+ `widget.signMessage` and `widget.signTypedData` ask the connected account for an
621
+ off-chain signature — marketplace orders, listings, signed approvals. Like
622
+ `createBatchOp`, they route by account type so the host never branches:
623
+
624
+ - **Smart account** (Fluent ID login): the signature comes from the ZeroDev Kernel
625
+ account and is an **ERC-1271** signature. While the account is not deployed yet
626
+ it is **ERC-6492**-wrapped; the wrapper is dropped automatically once it is.
627
+ - **External wallet**: the wallet itself signs; the result is a plain ECDSA
628
+ signature.
629
+
630
+ ```tsx
631
+ import { useWidget } from "@fluent.xyz/connect";
632
+
633
+ function ListButton({ order }) {
634
+ const widget = useWidget();
635
+
636
+ async function onList() {
637
+ const signature = await widget.signTypedData({
638
+ domain: { name: "Marketplace", version: "1", chainId: 20994, verifyingContract: exchange },
639
+ types: { Order: [{ name: "maker", type: "address" }, { name: "price", type: "uint256" }] },
640
+ primaryType: "Order",
641
+ message: order,
642
+ });
643
+ await submitOrder({ order, signature });
644
+ }
645
+
646
+ return <button onClick={onList}>List</button>;
647
+ }
648
+
649
+ // EIP-191 personal message
650
+ const signature = await widget.signMessage({ message: "Sign in to Marketplace" });
651
+ ```
652
+
653
+ The user reviews every request in the widget before anything is signed: the
654
+ origin of the page asking, the signing account, and — for typed data — the
655
+ domain, primary type and message. **Quick sign never applies to signatures**;
656
+ turning it on skips the review for transactions only. A dismissed review
657
+ rejects the promise with `User rejected Fluent signature review`.
658
+
659
+ ### Verify with ERC-1271 / ERC-6492, never `ecrecover`
660
+
661
+ A smart-account signature does not recover to the account address, or to any
662
+ address you can compare against. Verify it by asking the account:
663
+
664
+ - **Off-chain**: viem `publicClient.verifyTypedData` / `verifyMessage` (they handle
665
+ EOA, ERC-1271 and ERC-6492 in one call). Pass `address: widget.account.address`.
666
+ - **On-chain**: OpenZeppelin `SignatureChecker.isValidSignatureNow(account, hash, signature)`.
667
+ For a not-yet-deployed account use an ERC-6492-aware validator, or deploy the
668
+ account first (any transaction through `createBatchOp` deploys it).
669
+
670
+ A backend that does `ecrecover` and compares addresses will reject every
671
+ smart-account user. Check `widget.account.type` if you need to know which kind of
672
+ signature to expect.
673
+
674
+ ### EIP-2612 `permit` does not work for smart accounts
675
+
676
+ `permit(owner, spender, value, deadline, v, r, s)` recovers an EOA signature on
677
+ chain; a Kernel account cannot produce one. Do not build a permit flow for
678
+ smart-account users — batch the `approve` and the call instead, which lands in
679
+ **one** atomic UserOp and needs no signature step:
680
+
681
+ ```ts
682
+ await widget.createBatchOp({
683
+ reviewTitle: "Approve + buy",
684
+ calls: [
685
+ { to: token, abi: erc20Abi, method: "approve", args: [exchange, price] },
686
+ { to: exchange, abi: exchangeAbi, method: "buy", args: [orderId] },
687
+ ],
688
+ }).execute();
689
+ ```
690
+
691
+ For an external wallet `permit` works as usual, so a host that supports both can
692
+ branch on `widget.account.capabilities.atomicBatch`.
693
+
694
+ ### Signing requires direct mode
695
+
696
+ Both methods need `authMode: "direct"`. In hosted mode there is no signer on the
697
+ page, and they reject with `FluentAuthError` code `hosted_not_supported` — the
698
+ same code `getAuthToken()` uses for a Fluent ID in hosted mode (§8).
699
+
700
+ ## 7c. Embedding a marketplace iframe
701
+
702
+ A page embedded in your app on another origin cannot see the account signed in
703
+ here: the browser partitions its storage by top-level site, so a widget inside the
704
+ iframe would ask the user to sign in again. `useFluentIframeBridge` answers the
705
+ embedded page's wallet calls with this page's account instead, over the JSON-RPC
706
+ 2.0 `postMessage` protocol `@ledgerhq/iframe-provider` speaks, which white-label
707
+ marketplace frontends use to borrow the host page's wallet, so such a page works
708
+ without a second sign-in.
709
+
710
+ ```tsx
711
+ import { useRef } from "react";
712
+ import { useFluentIframeBridge } from "@fluent.xyz/connect";
713
+
714
+ function Marketplace() {
715
+ const iframeRef = useRef<HTMLIFrameElement>(null);
716
+ useFluentIframeBridge(iframeRef, { allowedOrigin: "https://market.example" });
717
+ return <iframe ref={iframeRef} src="https://market.example/collection/cards" />;
718
+ }
719
+ ```
720
+
721
+ `allowedOrigin` is the origin the marketplace is served from, scheme and host,
722
+ normalised the way `event.origin` is; `"*"` and a bare host are refused at
723
+ construction. Messages from any other
724
+ origin, or from any other window, are dropped without a reply; this is the only
725
+ origin check in the exchange, because the iframe side posts to `"*"` and checks
726
+ nothing itself.
727
+
728
+ What the bridge answers:
729
+
730
+ | Method | Answer |
731
+ | --- | --- |
732
+ | `eth_accounts`, `eth_requestAccounts`, `enable` | the signed-in address, or `[]` |
733
+ | `eth_chainId` | the widget's chain |
734
+ | `eth_signTypedData_v4` / `_v3` / `eth_signTypedData`, `personal_sign` | `signTypedData` / `signMessage`, with the usual review |
735
+ | `eth_sendTransaction` | `createBatchOp([...]).execute()`; the hash returned is the one `execute()` returns, which the embedded page can poll with `eth_getTransactionReceipt` |
736
+ | `eth_call`, `eth_estimateGas`, `eth_getTransactionReceipt`, and the other read-only `eth_*` methods | forwarded to the chain RPC |
737
+ | anything else (`wallet_*`, `eth_sign`, `eth_sendRawTransaction`) | error `4200 Unsupported method` |
738
+
739
+ A request that names another address as `from` or signer is refused with `4100`.
740
+ A dismissed review reaches the iframe as `4001` (`FluentReviewRejectedError` on
741
+ this side); any other failure as `-32603` with the widget's message. The bridge states
742
+ `chainChanged` and `accountsChanged` ahead of its first reply, so a page that
743
+ loaded after the bridge still learns them; sign-in and sign-out reach the iframe
744
+ as `accountsChanged` after that. `eth_sendTransaction` resolves once the
745
+ transaction is included, so the hash it returns already has a receipt.
746
+
747
+ Like signing, the bridge needs `authMode: "direct"`: in hosted mode the signing
748
+ and sending methods reject with `FluentAuthError` code `hosted_not_supported`,
749
+ which the iframe sees as `4200` with that code in the message. And as in §7b, a
750
+ smart-account signature is ERC-1271, so the marketplace's order validation has to
751
+ accept that; a validator without an ERC-6492 path also needs the account deployed,
752
+ which means a not-yet-deployed account must send one transaction before its first
753
+ listing validates.
754
+
755
+ Outside React, `createFluentIframeBridge(iframe, { allowedOrigin, executor })` is
756
+ the same bridge with the widget calls injected; `createFluentIframeRpcHandler(executor)`
757
+ is the method mapping alone, for a transport of your own.
758
+
759
+ ---
760
+
761
+ ## 8. Auth modes
762
+
763
+ > **Hosted mode is deprecated.** `authMode: "hosted"` is no longer supported and will be
764
+ > removed in 0.5.0 — use `authMode: "direct"`. It is still the config default
765
+ > ([§4](#4-config-reference-fluentwidgetconfig)), so set `authMode` explicitly. What follows
766
+ > describes both modes as they behave in this release.
767
+
768
+ - **`direct`** — clicking Connect opens **Fluent's own sign-in dialog** inside your page,
769
+ carrying the sign-in methods and the external wallet list on one screen
770
+ ([§4](#sign-in-methods)); Privy runs headless behind it and renders no modal of its own.
771
+ Your origin **must** be registered on the Privy app client behind your `privyClientId`
772
+ first, otherwise Privy rejects it with `invalid_origin` and the login button does nothing.
773
+ Required for `signMessage` and `signTypedData` ([§7b](#7b-requesting-a-signature)), for
774
+ the iframe bridge ([§7c](#7c-embedding-a-marketplace-iframe)), for `linkX()`
775
+ ([§8c](#8c-linking-x)), and for `getAuthToken()` with a Fluent ID.
776
+ - **`hosted` (deprecated, and still the default)** — clicking Connect opens the Fluent
777
+ authorize popup. No Privy origin setup; sign-in works anywhere. A Fluent ID signed in
778
+ that way keeps its Privy session on the authorize page rather than in your page, which is
779
+ what every refusal below comes down to.
780
+
781
+ What each mode and account type gets in this SDK version:
782
+
783
+ | Mode / account | Fluent token (`getAuthToken()`) minted by | Prompt | Signing | Sponsorship |
784
+ | --- | --- | --- | --- | --- |
785
+ | direct / Fluent ID | widget, with the in-page Privy tokens | none | in page, with review | yes, with the Fluent token |
786
+ | direct / external wallet | widget, challenge + wallet signature | one per session | the wallet | none: an EOA pays its own gas |
787
+ | hosted / Fluent ID *(deprecated)* | unavailable in this version: `getAuthToken()` rejects with `hosted_not_supported` | — | unavailable: `signMessage` and `signTypedData` reject with `hosted_not_supported` ([§7b](#7b-requesting-a-signature)) | none in this version (no Fluent token in the page) |
788
+ | hosted / external wallet *(deprecated)* | widget, challenge + wallet signature | one per session | unavailable: `signMessage` and `signTypedData` reject with `hosted_not_supported` ([§7b](#7b-requesting-a-signature)) | none |
789
+
790
+ A Fluent ID's Privy session lives on the Fluent authorize page in hosted mode, so
791
+ the page has no tokens to exchange; an external wallet signs the challenge in the
792
+ page in either mode. With nobody connected, `getAuthToken()` rejects with
793
+ `not_connected` in both modes. How your backend checks the token:
794
+ [§8b](#8b-verify-the-token-on-your-backend).
795
+
796
+ ### The token renews itself, silently
797
+
798
+ A Fluent token lives five minutes. The session behind it lives thirty days, and the
799
+ widget renews the token from that session without involving the user at all — no
800
+ Privy round trip for a Fluent ID, **and no wallet prompt for an external wallet**.
801
+ The "one per session" in the Prompt column above is the whole change: the wallet
802
+ signs when the session opens, and the renewals that follow ask it for nothing.
803
+
804
+ What makes this work is a second, long-lived credential the service issues
805
+ alongside every Fluent token — a **refresh token**, an opaque string with no
806
+ structure that only the service can interpret. The widget keeps it, spends it for a
807
+ new pair when the Fluent token is close to `exp`, and gets a fresh refresh token
808
+ back each time. Each one is single-use: presenting the same one twice ends the
809
+ session, which is how a stolen copy is caught. All of the above rests on the service
810
+ issuing that credential: a deployment old enough to answer the exchange without a refresh
811
+ half leaves the widget nothing to renew from, and the last case below is what happens
812
+ instead.
813
+
814
+ Your app never sees it, and never should. `getAuthToken()` returns the short-lived
815
+ Fluent token and nothing else; no widget API exposes the refresh token.
816
+
817
+ A **new signature** — a new full exchange — is needed only when:
818
+
819
+ - the session's thirty days are up (the service's `REFRESH_TOKEN_TTL` default; a
820
+ renewal hands out a new credential but never moves that deadline);
821
+ - the service rejects the stored credential, because the session was revoked
822
+ elsewhere or the same credential was presented twice;
823
+ - there is no stored credential in this browser: the user disconnected, cleared
824
+ site data, or opened your app in another browser or another profile;
825
+ - the service answered the exchange without a refresh credential at all — a service
826
+ deployment that predates refresh credentials. Nothing is stored, so nothing renews:
827
+ every expired token is another full exchange, which for an external wallet is another
828
+ signature every five minutes. The service this release targets issues one.
829
+
830
+ Two limits worth knowing. The first: renewal is coordinated **within one page**, not
831
+ across tabs. The stored credential is *shared* — the key carries the service, your
832
+ `appId` and the account, and nothing that distinguishes one tab from another — so two
833
+ tabs of your app hold one session between them, and only the page that renews knows the
834
+ credential rotated. If the other tab renews with the copy it read, the service sees the
835
+ same refresh token twice, ends that session as a suspected replay, and both tabs fall
836
+ back to a full exchange: one new signature for an external wallet, then business as
837
+ usual. Nothing is lost and nobody is signed out, but a multi-tab app should expect the
838
+ occasional extra prompt. Coordinating tabs is not in this release.
839
+
840
+ The second: a **hosted-mode Fluent ID has no session here at all** — `getAuthToken()`
841
+ rejects with `hosted_not_supported`, as the table says, and nothing above applies to it.
842
+
843
+ ### Where the session is kept, and what that costs
844
+
845
+ The refresh token is kept in this browser's `localStorage`, under a key carrying the
846
+ service URL, your `appId` and the connected account. One App never reads another's,
847
+ and two accounts sharing a browser never read each other's.
848
+
849
+ > **This is an XSS exposure, and we are not going to tell you otherwise.**
850
+ > `localStorage` is readable by any script running on your page. A script that gets
851
+ > onto your origin — through a compromised dependency, an injected tag, a `dangerouslySetInnerHTML`
852
+ > you did not audit — can read the refresh token and use it, from that same origin, for
853
+ > up to thirty days.
854
+ >
855
+ > Single-use rotation and the service's origin checks do **not** remove that. Rotation
856
+ > means a stolen credential is *detected* once the real client renews next and the
857
+ > session is then killed — it does not prevent the theft or the window before it.
858
+ > The origin check means the stolen credential is not usable from *another* site in a
859
+ > browser — it does nothing about the site it was taken from, which is yours. Both
860
+ > narrow the blast radius; neither closes it.
861
+ >
862
+ > The tradeoff bought here is a user who signs once instead of every five minutes. What
863
+ > narrows the exposure is a Content-Security-Policy and a dependency review you treat as
864
+ > load-bearing — they were already — plus disconnecting a session you are done with, which
865
+ > revokes the family and clears the stored credential. What does *not* remove it is
866
+ > exchanging the Fluent token for your own session: the widget has already obtained and
867
+ > stored the credential by the time it hands you a token to exchange, and holding a session
868
+ > of your own neither clears it nor revokes it. This release offers no way to turn the
869
+ > persistence off, so an app that cannot accept the exposure at all has no configuration to
870
+ > reach for — tell us and it becomes a requirement rather than a workaround.
871
+
872
+ Disconnecting ends the session properly: the widget asks the service to revoke it and
873
+ clears the stored credential, so the thirty days stop there rather than running out on
874
+ their own. A Fluent token already issued keeps verifying until its `exp` — at most five
875
+ minutes — because its signature is checked offline and nothing can recall it. That is
876
+ the same property the short lifetime was chosen for.
877
+
878
+ The widget's own teardown is immediate, and the `Promise` that `disconnect()` returns is
879
+ the one that waits: it resolves after every refresh family the disconnect ended has been
880
+ revoked, best effort, including one opened by a `getAuthToken()` that was still out when
881
+ the user disconnected. A wallet dialog answered a minute after the disconnect still opens
882
+ a session, and that promise is what tells you there is none left. It can therefore take as
883
+ long as such a request does, and it never rejects — a service you cannot reach does not
884
+ leave the user signed in here, but do not read a resolved promise as proof the service
885
+ agreed. If you await `disconnect()` before signing the user out of your own backend, that
886
+ is the ordering you get.
887
+
888
+ ### Sponsorship authenticates with the Fluent token
889
+
890
+ Gas sponsorship is the same token, used by the widget rather than by you. When a
891
+ Fluent ID sends a transaction in direct mode, the widget mints a Fluent token for
892
+ the signed-in user and sends it as the `Authorization` bearer to the sponsorship
893
+ paymaster, which checks that the token's `aud` is your App and that the operation's
894
+ sender is an address the user proved. **Release 0.4.0 of `@fluent.xyz/connect` is the
895
+ first that sends the Fluent token**; earlier releases sent the Privy access token,
896
+ which the service accepted through a transition path that applies neither check.
897
+ That transition path will be withdrawn, and the SDK release notes will say in which
898
+ release: this guide sets no date for it. Once it is gone, a page still running an earlier
899
+ release will get unsponsored transactions rather than a hard error — the account pays its
900
+ own gas, as the table's other rows already do.
901
+
902
+ The Sponsorship column above says what each combination gets in this version, and
903
+ only the first row is sponsored. An external wallet, in either mode, sends through
904
+ the wallet and never through the smart account, so there is no user operation to
905
+ sponsor. A Fluent ID in hosted mode has no Privy session in your page, so it has no
906
+ Fluent token to authenticate with. Nothing throws in any of those cases: the account
907
+ pays its own gas and the transaction goes through.
908
+
909
+ If the paymaster rejects a token with a `401`, the widget mints one fresh token and
910
+ retries the operation once before the account falls back to paying its own gas. A
911
+ `403` means your App is not set up for sponsorship, and the widget stops asking — for as
912
+ long as the widget's provider subtree lives, which is not the same as the page. The latch
913
+ sits in that subtree, and toggling Quick sign rebuilds it, so after a toggle the next
914
+ operation asks once more and latches again on the same `403`. Turn on `debugLogging`
915
+ ([§9b](#9b-debugging-an-integration)) to see which of these happened.
916
+
917
+ A Fluent token needs one more piece of setup, in either mode and for either
918
+ account type: your page origin must be registered on your App in the Fluent App
919
+ settings. That is the Fluent auth service's own list, separate from the Privy
920
+ origin registration direct mode needs. From an unregistered origin
921
+ `getAuthToken()` rejects with `FluentAuthError` code `origin_not_allowed`.
922
+
923
+ > **Breaking in 0.4.0, for a host that builds its own ZeroDev account.** Two exported
924
+ > helpers changed with the switch to the Fluent token.
925
+ > `createFluentZeroDevSponsoredPaymaster({ chain, rpcUrl, bearerToken })` takes
926
+ > `bearerToken` where 0.3.x took `accessToken`, and the value is now the Fluent token
927
+ > `getAuthToken()` mints rather than a Privy access token. `useFluentZeroDevAccount` no
928
+ > longer reads a token itself: it sponsors nothing unless it is given
929
+ > `sponsorshipTokenSource` — a function returning the token source for the signed-in
930
+ > user — beside `appId` and `sponsorshipUrl`. `<FluentWidget>` wires both for you; this
931
+ > matters only if you call them yourself.
932
+
933
+ ---
934
+
935
+ ## 8b. Verify the token on your backend
936
+
937
+ `widget.getAuthToken()` returns a short-lived ES256 JWT issued by the Fluent
938
+ auth service. Your backend needs no Fluent SDK to check it:
939
+
940
+ 1. Fetch `<iss>/.well-known/jwks.json` and cache it; the response carries
941
+ `Cache-Control: public, max-age=3600`.
942
+ 2. Pick the key by the token's `kid`. Require `alg == ES256`. Verify the signature.
943
+ 3. Check `iss` equals the issuer you pinned, `aud` equals your `app_…` id, and `exp` is in the
944
+ future.
945
+ 4. Use `sub` as the user id. Read `addresses.account` only if your App has the `addresses`
946
+ scope, and only for on-chain joins.
947
+
948
+ Go, with the same two libraries the Fluent auth service uses:
949
+
950
+ ```go
951
+ jwks, _ := keyfunc.NewDefaultCtx(ctx, []string{issuer + "/.well-known/jwks.json"})
952
+ tok, err := jwt.Parse(raw, jwks.Keyfunc,
953
+ jwt.WithIssuer(issuer),
954
+ jwt.WithAudience(appID),
955
+ jwt.WithValidMethods([]string{"ES256"}),
956
+ jwt.WithExpirationRequired(),
957
+ )
958
+ if err != nil || !tok.Valid { /* 401 */ }
959
+ sub, _ := tok.Claims.GetSubject()
960
+ ```
961
+
962
+ Node, with `jose`:
963
+
964
+ ```ts
965
+ const JWKS = createRemoteJWKSet(new URL(`${issuer}/.well-known/jwks.json`));
966
+ const { payload } = await jwtVerify(raw, JWKS, { issuer, audience: appId, algorithms: ["ES256"] });
967
+ const userId = payload.sub;
968
+ ```
969
+
970
+ Verify on every request, or exchange the token once for your own session. Both are fine; the
971
+ first needs no application-session state on your side.
972
+
973
+ Do not persist our token — call `getAuthToken()` each time you need one. It lives five minutes,
974
+ and the SDK renews it silently for both supported account types: a Fluent ID in direct mode, and
975
+ an external wallet in either mode. **Calling it often no longer prompts the wallet.** The wallet
976
+ signs once, when the session opens, and every renewal for the next thirty days is a background
977
+ request, for as long as the service issues the refresh credential a renewal spends
978
+ ([§8](#the-token-renews-itself-silently)); a hosted-mode Fluent ID is the exception, and
979
+ rejects with `hosted_not_supported` rather than returning a token at all.
980
+
981
+ So verifying on every request is a real option now, for external wallets too. Exchanging our
982
+ token once for your own session is still the lighter thing to do per request, and it is what to
983
+ reach for if you would rather your app's session outlive ours, or have its own expiry and its own
984
+ revocation. It does not change what the widget keeps in the browser: the refresh credential is
985
+ already stored by the time you have a token to exchange, and your own session neither clears nor
986
+ revokes it — see [§8](#where-the-session-is-kept-and-what-that-costs).
987
+
988
+ ---
989
+
990
+ ## 8c. Linking X
991
+
992
+ Some apps need to know a user's X account — a gated drop, a leaderboard, an entitlement that
993
+ belongs to a handle rather than to an address. `linkX()` is how a connected user gets one
994
+ linked, headless: no widget screen, no settings page, one call from your own UI.
995
+
996
+ It serves both account types. A **Fluent ID** — whether the user signed in *with* X, or with
997
+ Google, email or a passkey and has no X account yet — already has the Privy session the link
998
+ needs. An **external wallet** (MetaMask, say) gets one first: before the X redirect the SDK signs
999
+ the wallet in to Privy with Sign-In with Ethereum, which the user sees as a **signature
1000
+ prompt** — and mints the wallet's Fluent token, a second prompt unless this page holds the token
1001
+ already; see below. After that the two account types take exactly the same path, resolve the
1002
+ same results and reject with the same codes.
1003
+
1004
+ ### The call leaves the page, so it is idempotent instead
1005
+
1006
+ Linking X means an OAuth round trip through X, and that round trip **navigates away from your
1007
+ page**. There is no popup variant to reach for. So `linkX()` is not one long promise that waits
1008
+ for the user to come back — it could not be, because the page it was called on is gone by then.
1009
+ It is idempotent and re-enterable, and it resolves one of two things:
1010
+
1011
+ ```ts
1012
+ type FluentLinkXResult =
1013
+ | { status: "linked"; x: FluentXAccount } // done; the account is right here
1014
+ | { status: "redirecting" }; // the page is leaving for X
1015
+ ```
1016
+
1017
+ - **A user who already has X** resolves `{ status: "linked", x }`. No Privy dialog, no
1018
+ navigation, one request.
1019
+ - **A user who has none** resolves `{ status: "redirecting" }` once the navigation to X has
1020
+ been started. The code after that `await` does run — briefly. Use it to show a "taking you to
1021
+ X" state; do not use it to wait for the link, because the page is unloading and the link
1022
+ completes on the page that comes back.
1023
+
1024
+ When the browser comes back, **call `linkX()` again** — and this time it resolves `linked`.
1025
+ Calling it again after the last call has settled costs one request and changes nothing for a
1026
+ user who already has X. Keep **one `linkX()` in flight per page**: do not mount `useLinkX()` and
1027
+ also call `linkX()` on mount, and do not mount two `useLinkX()` hooks. A second call made while
1028
+ the first still waits for the return replaces it, and the first never settles.
1029
+
1030
+ ```ts
1031
+ type FluentXAccount = { id: string; handle: string; avatarUrl: string };
1032
+
1033
+ /** The wire body of `GET /api/v1/me/profile` and of the link request. `x` is nullable. */
1034
+ type FluentProfile = { subject: string; appId: string; x: FluentXAccount | null };
1035
+ ```
1036
+
1037
+ ### `useLinkX()` does the return trip for you
1038
+
1039
+ ```tsx
1040
+ import { useLinkX } from "@fluent.xyz/connect";
1041
+
1042
+ function LinkXButton() {
1043
+ const { linkX, status, x, error } = useLinkX();
1044
+
1045
+ if (x) return <span>Linked as @{x.handle}</span>;
1046
+ return (
1047
+ <>
1048
+ <button onClick={() => linkX()} disabled={status === "pending" || status === "redirecting"}>
1049
+ {status === "redirecting" ? "Taking you to X…" : "Link X"}
1050
+ </button>
1051
+ {error ? <p>{error.code}</p> : null}
1052
+ </>
1053
+ );
1054
+ }
1055
+ ```
1056
+
1057
+ Mount it and the return trip needs nothing from you: the hook sees that this tab started a link,
1058
+ waits for the widget to finish it, and reports `status: "linked"` with `x`. Mount it on a page
1059
+ that started no link and it does nothing at all.
1060
+
1061
+ The same call is on the render context — `const { linkX } = useFluentWidget()` — and behaves
1062
+ identically, including the return trip, for an integrator who would rather hold the state
1063
+ themselves.
1064
+
1065
+ A link that somebody else started in this tab — two people sharing a browser — or a stale
1066
+ record of one is discarded, never resumed: the hook's mount-time re-entry stays idle and reports
1067
+ no error, whether the other person is known from the stored session or only once Privy has
1068
+ restored them, and a `linkX()` call you make yourself — on the hook or on the render context —
1069
+ does no work and rejects with `link_failed`. Call again to start a link for the user who is
1070
+ signed in now. For an external wallet the same applies to a link another wallet started: the
1071
+ user switched wallets across the redirect, and the link the tab remembers is the other wallet's.
1072
+
1073
+ What the widget waits for on the way back is the **user Privy restores**, not a callback: after a
1074
+ redirected link, Privy's `onSuccess` never fires, because the intent that would have fired it did
1075
+ not survive the reload. It waits without polling, and the request that completes the link carries
1076
+ a freshly minted identity token — the service reads the X account out of that token, so a stale
1077
+ one would link nothing. For an external wallet it also waits for the wallet's client, which the
1078
+ connector hands over a moment after it has named the address: the client is what makes the
1079
+ connected address the wallet's own — the widget takes the address as connected only once the
1080
+ client that signs for it is there — and the link completes as that wallet. The ordinary return
1081
+ asks the client for nothing: the request that completes the link is authenticated with the
1082
+ wallet's Fluent token, renewed from the refresh credential the pre-redirect mint stored (see
1083
+ below). Only a page whose credential has expired in the meantime mints the token again, and that
1084
+ needs the client to sign.
1085
+
1086
+ ### An external wallet signs in to Privy first
1087
+
1088
+ Privy links X to a Privy user, and an external wallet has none until it signs in. So the first
1089
+ `linkX()` for a wallet user — and only the first, while that Privy session lasts — starts with
1090
+ **Sign-In with Ethereum**: the SDK asks Privy for a SIWE message for the connected address, asks
1091
+ the wallet to sign it, and hands Privy the signature. The user sees one **signature prompt** in
1092
+ their wallet, for a plain message naming your page and a nonce. **It is a signature, not a
1093
+ transaction**: nothing is sent to the chain and nothing costs gas. Then, still before the
1094
+ redirect, the SDK mints the wallet's Fluent token — the typed-data challenge of
1095
+ [§8](#8-auth-modes), the same one `getAuthToken()` signs — so that **every signature happens
1096
+ before the page leaves**. On a page that has not minted the token yet that is a second prompt;
1097
+ on one that already holds it (you called `getAuthToken()` first, or an earlier call minted it)
1098
+ the wallet is asked nothing more. Only then does the X redirect happen. The page that comes back
1099
+ renews the token from the refresh credential the mint stored and opens the wallet for nothing;
1100
+ and on every later call with that Privy session live, nothing is signed again. Tell your users
1101
+ to expect the prompts — a wallet user who has never seen Privy will not expect their wallet to
1102
+ open before a trip to X.
1103
+
1104
+ Each of Privy's two sign-in steps is bounded to ten seconds, and the wallet's own signature
1105
+ prompt to five minutes; a step that never answers rejects `link_failed` with a message naming
1106
+ the likely cause, and a late answer resumes nothing. **Captcha on the Privy app is not supported
1107
+ for `linkX()` today**: with it enabled, Privy's headless sign-in waits for a captcha this SDK
1108
+ does not render during `linkX()`, and the call fails after the bound. Wallet login disabled on
1109
+ the Privy app ends the same way. Check both in the Privy Dashboard before shipping the wallet
1110
+ path.
1111
+
1112
+ Nothing about the Fluent user changes over it. The connected account is still the wallet, its
1113
+ kind is still the external wallet's, and `getAuthToken()` still mints the wallet's own token —
1114
+ keyed on the address, renewed by the wallet's own refresh family ([§8](#8-auth-modes)) — before,
1115
+ during and after the link. The Privy session SIWE makes is the link's machinery, not an account:
1116
+ it never becomes a Fluent ID — not when Privy attaches an embedded wallet to it, not when the
1117
+ wallet is disconnected or swapped for another while it lives — and the widget never signs with it.
1118
+ The SDK tells that session from a Fluent ID's by the external wallet on the Privy user, which
1119
+ rests on one assumption: this SDK is the only way an external wallet lands on a Privy user of
1120
+ your Privy app — its sign-in offers no wallet method and links no wallets — so do not add one on
1121
+ the same Privy app. Should the user choose a Fluent ID later, from the connect modal or the
1122
+ account menu, while that session lives, the widget signs it out first: the sign-in method they
1123
+ chose — X, Google, email or passkey — runs only once Privy has confirmed the sign-out, and a
1124
+ sign-out that fails or runs past its bound runs no method and shows its error in the sign-in
1125
+ dialog, where the next click tries again. The wallet stays connected throughout.
1126
+
1127
+ Three things can go wrong that are the wallet's own:
1128
+
1129
+ - **The user declines the signature.** `linkX()` rejects with `user_rejected` — the same code as
1130
+ saying no at X — and nothing was linked or started; call again when they are ready.
1131
+ - **Privy signs in a user who does not hold the connected wallet.** The SDK checks the user Privy
1132
+ returns before it links anything: one without the connected address among their accounts is
1133
+ not a session the link can use, so the SDK asks Privy to sign it out again and `linkX()`
1134
+ rejects with `link_failed`, with nothing started. The sign-out is attempted and awaited within
1135
+ a bound of ten seconds, and the call rejects with `link_failed` either way: when Privy confirms
1136
+ it within the bound the session is gone, and when it does not — Privy's logout failed, or did
1137
+ not finish in time — the rejection says so in its message and the session may still be live on
1138
+ the page, though never as a Fluent ID: for as long as that page lives, the widget keeps reading
1139
+ it as the wallet's failed sign-in. Kept otherwise, it would be the one Privy session that could
1140
+ be taken for a Fluent ID on this page. The wallet stays connected and its token is untouched.
1141
+ - **The service refuses the link with `403 privy_wallet_mismatch`.** The Privy session that linked
1142
+ X belongs to a different wallet than the Fluent token's. `linkX()` rejects with `link_failed`.
1143
+ The SDK makes this hard to reach: a Privy session left in the browser by another wallet — the
1144
+ user switched accounts in MetaMask, and Privy kept the old session across the reload — is
1145
+ **replaced before the link**, logged out and the connected wallet signed in afresh, rather than
1146
+ reused; until then it stays that other wallet's session, never the start of a Fluent ID for
1147
+ the wallet connected now. The one Privy session the SDK will not replace is a Fluent ID's: with
1148
+ a Fluent ID signed in on the page — whether Privy has restored them yet or not — and an
1149
+ external wallet connected beside it, `linkX()` for the wallet rejects with `link_failed`, since
1150
+ signing the Fluent ID out from under the person is not the link's to do.
1151
+
1152
+ ### What it rejects with
1153
+
1154
+ Every rejection is a `FluentAuthError` with one of:
1155
+
1156
+ | `code` | What happened |
1157
+ | --- | --- |
1158
+ | `user_rejected` | The user said no at X, closed the flow, or declined the SIWE signature or the Fluent token's challenge. |
1159
+ | `linked_to_another_user` | That X account is already linked to another Fluent user. |
1160
+ | `not_authenticated` | No Fluent ID or external wallet is connected, or the wallet's client is not here yet. Connect first, or wait and call again. |
1161
+ | `hosted_not_supported` | Hosted mode. Refused before any other call — see below. |
1162
+ | `bad_request` | The service refused the request body. Report it; it is ours, not yours. |
1163
+ | `link_failed` | Everything else: a discarded link, `privy_wallet_mismatch`, a Fluent ID signed in beside the wallet, a sign-in step that timed out, a failure under the call. |
1164
+
1165
+ No other code reaches you from `linkX()`. A refusal raised under it — by the request that mints
1166
+ the Fluent token, say — keeps its message and arrives as `link_failed`, so one `switch` over the
1167
+ six codes above is complete.
1168
+
1169
+ **Hosted mode cannot link X.** A hosted-mode Fluent ID has its Privy session on the Fluent
1170
+ authorize page, not in yours, so there is nothing in your page to link an account to — the same
1171
+ reason `getAuthToken()` refuses there ([§8](#8-auth-modes)).
1172
+ `linkX()` rejects with `hosted_not_supported` before it touches Privy, the wallet or the network.
1173
+
1174
+ ### The sequence your backend sees
1175
+
1176
+ 1. Call `linkX()` until it reports `linked`. (`redirecting` means the browser is leaving; after
1177
+ it returns, `useLinkX()` or your own call finishes the job.)
1178
+ 2. Call `getAuthToken()` for a fresh Fluent token.
1179
+ 3. Your backend verifies that token ([§8b](#8b-verify-the-token-on-your-backend)) and makes its
1180
+ own check — `GET /api/v1/me/profile` with the token, server to server, reading `x`. The same
1181
+ account `linkX()` returned is the one that endpoint reports.
1182
+
1183
+ Step 3 is the one that counts. `linkX()` resolving `linked` is the widget telling you the link
1184
+ went through; your backend verifying it is the part an entitlement should hang on.
1185
+
1186
+ ---
1187
+
1188
+ ## 9. One copy of the web3 stack (peer dependencies)
1189
+
1190
+ `viem`, `wagmi`, and `@tanstack/react-query` are peer dependencies precisely
1191
+ because they rely on **single-instance React context and singletons**:
1192
+
1193
+ - **wagmi / react-query** — hooks resolve their provider by React-context object
1194
+ identity. A second copy of the package is a *different* context object, so
1195
+ hooks silently fail to see the provider across the boundary.
1196
+ - **viem** — you build the `abi` / `Address` / `Hex` values you pass into
1197
+ `createBatchOp` with *your* viem. A second, mismatched copy makes those types
1198
+ incompatible at the boundary.
1199
+
1200
+ Installing them as peers (§2) guarantees your package manager resolves a single
1201
+ shared copy. **Do not** add them back as direct nested dependencies with a
1202
+ divergent version.
1203
+
1204
+ ### Provider model (phase 1: single-chain)
1205
+
1206
+ `<FluentWidget>` mounts its own `WagmiProvider` + `QueryClientProvider` (Fluent
1207
+ chain) and renders your app **inside** them via `renderPage`. For a single-chain
1208
+ app that has no other wagmi, this is exactly what you want — the widget is the
1209
+ one source of wallet/account state, and you read it through `useFluentWidget()`.
1210
+
1211
+ > If you later need **multiple chains** (your own wagmi config alongside the
1212
+ > widget's), that's a separate architecture — shared providers / a single
1213
+ > `WagmiProvider`. Not supported in phase 1; talk to the Fluent team.
1214
+
1215
+ ---
1216
+
1217
+ ## 9b. Debugging an integration
1218
+
1219
+ The widget's internal connect / smart-account / signing diagnostics are silent by
1220
+ default. Turn them on with the `debugLogging` prop while wiring things up:
1221
+
1222
+ ```tsx
1223
+ <FluentWidget config={{ /* … */ }} debugLogging mode="page" renderPage={() => <YourApp />} />
1224
+ ```
1225
+
1226
+ `debugLogging={false}` (the default) suppresses **all** widget console output.
1227
+ Leave it off in production.
1228
+
1229
+ ## 10. Checklist
1230
+
1231
+ - [ ] Got a Fluent `appId` and `privyClientId`.
1232
+ - [ ] Picked network (`testnet` / `mainnet`) — and every chain id pinned elsewhere in the app matches it (§3).
1233
+ - [ ] (`direct` only) origin allow-listed in Fluent Privy.
1234
+ - [ ] (`getAuthToken()`, either mode) page origin registered on your App in the Fluent App settings (§8).
1235
+ - [ ] (linking X) called `linkX()` until it reports `linked` — it is re-entered after the redirect, not awaited across it — and verified the account on your backend (§8c).
1236
+ - [ ] Imported `@fluent.xyz/connect/styles.css` once.
1237
+ - [ ] Mounted `<FluentWidget>` at the root; app rendered via `renderPage`.
1238
+ - [ ] Read account via `useFluentWidget()` / `useWidget()`.
1239
+ - [ ] All txs go through `createBatchOp(...).execute()`, guarded on `executionReady`.
1240
+ - [ ] Signatures go through `widget.signMessage` / `widget.signTypedData` and are verified with ERC-1271/6492, not `ecrecover` (§7b).
1241
+ - [ ] Checked provider coexistence if the app already uses wagmi / viem / react-query (§9).
1242
+ ```