@fluent.xyz/connect 0.4.2 → 0.5.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 CHANGED
@@ -35,14 +35,11 @@ Before writing code you need:
35
35
  issued alongside. Login configuration: your allowed origins live on it.
36
36
  Required; the widget throws without it.
37
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.
38
+ 4. **Your app's origin registered on that Privy app client** — Fluent's sign-in
39
+ dialog runs in your page, and Privy refuses an origin it does not know.
40
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).
41
+ > **Upgrading from 0.4?** The login config changed in 0.5.0 — see
42
+ > [Upgrading from 0.4](#upgrading-from-04).
46
43
 
47
44
  > **Migrating from `clientId`?** The option is gone. The value it held is now
48
45
  > `privyClientId`, and `appId` is new — passing `clientId` throws with the
@@ -93,7 +90,6 @@ export function App() {
93
90
  privyClientId: "client-<issued by Fluent>",
94
91
  network: resolveFluentWidgetNetworkFromEnv() ?? "testnet",
95
92
  appName: "My App",
96
- authMode: "direct",
97
93
  }}
98
94
  mode="page"
99
95
  renderPage={() => <YourApp />}
@@ -169,26 +165,36 @@ routing rather than mutating `config.network` under a live session.
169
165
  |---------------|----------|--------------------|-------|
170
166
  | `appId` | ✅ | — | The App's `app_<32 hex>` id — identity for sponsorship, auth and analytics; the token `aud`. Asserted at startup. |
171
167
  | `privyClientId` | ✅ | — | Privy app client issued by Fluent — login configuration; allowed origins live on it. |
168
+ | `clientId` | ⛔ | — | Removed in 0.2.0, and still typed (as `never`) only so the error can name the fix: pass the App's id as `appId` and the Privy app client as `privyClientId`. Passing it throws at resolve time. |
169
+ | `partnerId` | ⛔ | — | Renamed to `appId` in 0.3.0, and still typed (as `never`) only so the error can name the fix. Passing it throws at resolve time. |
172
170
  | `network` | ➖ | env → `"testnet"` | `"testnet"` or `"mainnet"` — see [Networks and chain ids](#networks-and-chain-ids). |
173
171
  | `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
172
  | `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). |
173
+ | `enabledAuthMethods` | ➖ | `["google", "email", "passkey"]` | Methods the sign-in dialog offers beside X, in the order given. X is always offered — see [Sign-in methods](#sign-in-methods). |
177
174
  | `source` | ➖ | `"fluent_connect_widget"` | Attribution tag. |
178
175
  | `campaign` | ➖ | — | Attribution tag. |
179
176
  | `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
177
  | `disableAnalytics` | ➖ | `false` | `true` turns off all analytics — PostHog is never initialised, nothing sent or stored. |
181
178
  | `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). |
179
+ | `quickSign` | ➖ | unset | `{ whitelistAddresses }` — call targets Quick sign may execute without the review. Set, an operation is silent only when every call's `to` is on the list (compared case-insensitively); any other target shows the review and the signer prompt even with Quick sign on, including for an explicit `confirmation: "session"`. An empty list stops Quick sign from silencing anything; unset covers every address. Message / typed-data signatures have no call target and are not scoped by it. |
180
+ | `execution` | ➖ | `{ feeSource: "chain", receiptSource: "chain", chainCheckBeforeSign: false }` | Where a smart-account send reads its fees and its receipt, and whether the Signer's chain is read before every signature — see [Where a send reads fees and receipts](#where-a-send-reads-fees-and-receipts). A value outside the ones documented there throws a `FluentWidgetConfigError` at startup. |
182
181
  | `swapper` | ➖ | Fluent defaults | On-ramp/bridge config. |
183
182
  | `reputationEnabled` | ➖ | `true` | `false` hides the Reputation tab — and with it the tab strip, leaving Home. The families request is never made. |
184
183
  | `assets` | ➖ | Fluent brand | Override logo etc. |
185
184
  | `avatar` | ➖ | Fluent mark | `{ defaultLogoUrl, forceDefault }` — see [Account avatar](#account-avatar). |
186
185
  | `scopes` | ➖ | network defaults | Permission scopes requested at login. |
186
+ | `sponsorshipUrl` | ➖ | network default | Point the widget at another sponsorship service. Local development only. |
187
+ | `authTokenRenewalOffsetSeconds` | ➖ | `30` | How many seconds before `exp` `getAuthToken()` stops reusing a token and fetches a fresh one. `0` drops the margin: a token is reused until `exp` itself, not fetched afresh on every call. |
188
+
189
+ ✅ required, ➖ optional, ⛔ forbidden. The table is the whole of `FluentWidgetConfig`: a ⛔
190
+ field is still part of the type so that a config carrying it fails the typecheck and, past the
191
+ type, throws a message naming its replacement. A key removed from the type outright is not in
192
+ the table at all — for those, see the upgrade sections at the end of this document.
187
193
 
188
194
  ### Capacitor OAuth
189
195
 
190
196
  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
197
+ For X and other social sign-in, set
192
198
  `customOAuthRedirectUrl` to an HTTPS Universal Link that returns to the app:
193
199
 
194
200
  ```tsx
@@ -196,7 +202,6 @@ For X and other social sign-in, use `authMode: "direct"` and set
196
202
  config={{
197
203
  appId,
198
204
  privyClientId,
199
- authMode: "direct",
200
205
  enabledAuthMethods: [], // X remains available.
201
206
  customOAuthRedirectUrl: "https://app.example.com/auth/ios/callback",
202
207
  }}
@@ -207,7 +212,6 @@ The widget passes this URL to its internal `PrivyProvider`. Omitting it, or
207
212
  passing a blank string, keeps Privy's current-page callback. Values are trimmed
208
213
  and otherwise preserved to match the dashboard's exact redirect allowlist.
209
214
  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
215
 
212
216
  The host still needs to:
213
217
 
@@ -232,7 +236,7 @@ installed X app.
232
236
 
233
237
  ### Sign-in methods
234
238
 
235
- With `authMode: "direct"`, sign-in methods default to this order: **X, Google,
239
+ Sign-in methods default to this order: **X, Google,
236
240
  email, passkey**. They and the external wallet list share a single Fluent dialog.
237
241
  Email verification stays in place; X and Google redirect to their OAuth provider
238
242
  and resume the matching dialog on return. Passkey login uses the browser's
@@ -253,7 +257,6 @@ value here; it stays first whatever the list says.
253
257
  config={{
254
258
  appId,
255
259
  privyClientId,
256
- authMode: "direct",
257
260
  // Leaves X and email.
258
261
  enabledAuthMethods: ["email"],
259
262
  }}
@@ -261,13 +264,12 @@ value here; it stays first whatever the list says.
261
264
  ```
262
265
 
263
266
  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.
267
+ external wallet list is unaffected either way.
266
268
 
267
269
  Hosts supplying their own `wallet` prop can optionally provide `choices` (an array
268
270
  of `{ id, name, icon?, handoff? }`) and `connectChoice(id)` to use the inline list.
269
271
  Set `handoff: true` for a choice that owns its own dialog. Without these optional
270
- fields, **Other wallets** retains the existing `wallet.open()` behavior.
272
+ fields, **Connect with other wallets** retains the existing `wallet.open()` behavior.
271
273
 
272
274
  ### Account avatar
273
275
 
@@ -280,7 +282,6 @@ replaces that fallback with your own logo:
280
282
  config={{
281
283
  appId,
282
284
  privyClientId,
283
- authMode: "direct",
284
285
  avatar: {
285
286
  // URL or data URI — rendered in a 32px rounded tile.
286
287
  defaultLogoUrl: "/brand/logo.svg",
@@ -296,8 +297,21 @@ replaces that fallback with your own logo:
296
297
  | `defaultLogoUrl` | Fluent mark | Shown when there is no X avatar. A logo that fails to load falls back to the Fluent mark. |
297
298
  | `forceDefault` | `false` | `true` drops the X avatar entirely, so every user sees `defaultLogoUrl`. |
298
299
 
299
- Rendering your own button through `renderConnectButton` bypasses this — pass the
300
- logo yourself, or reuse the exported `AccountAvatar` component.
300
+ For a custom button, `renderConnectButton` receives `userAvatarUrl`. Components
301
+ inside `renderPage` or `renderHome` can read the same URL with `useFluentWidget()`:
302
+
303
+ ```tsx
304
+ import { AccountAvatar, useFluentWidget } from "@fluent.xyz/connect";
305
+
306
+ function AccountPicture() {
307
+ const { userAvatarUrl } = useFluentWidget();
308
+ return <AccountAvatar userLogoUrl={userAvatarUrl} defaultLogoUrl="/brand/logo.svg" />;
309
+ }
310
+ ```
311
+
312
+ `userAvatarUrl` is undefined when Privy has no X picture, when an External wallet
313
+ is displayed, or when `avatar.forceDefault` is true. It does not include the
314
+ configured default logo; pass that separately to `AccountAvatar` if needed.
301
315
 
302
316
  ---
303
317
 
@@ -382,18 +396,16 @@ sessions to one person and cannot tell them apart.
382
396
 
383
397
  The widget reads once per sign-in and writes every change back — for an external
384
398
  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 —
399
+ `getAuthToken()` returns ([§8](#8-auth-and-the-fluent-token)). Nothing is sent but that token —
386
400
  no user id is ever put in a request by the widget.
387
401
 
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:
402
+ It falls back to this browser's `localStorage` where no Fluent token can exist,
403
+ and behaves there exactly as it did before 0.4.0:
390
404
 
391
405
  | State | The user's token list | Quick sign and the gas token |
392
406
  | --- | --- | --- |
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 |
407
+ | Fluent ID | the service, or `localStorage` if the read fails | the service, or the in-memory defaults if the read fails |
408
+ | external wallet | the service, or `localStorage` if the read fails | not kept: neither applies to an external wallet |
397
409
  | nobody connected | `localStorage` | the in-memory defaults |
398
410
 
399
411
  The first time a user signs in with tokens already in this browser's
@@ -542,7 +554,6 @@ Set the initial/fallback token and native-gas sponsorship policy in config:
542
554
  config={{
543
555
  appId,
544
556
  privyClientId,
545
- authMode: "direct",
546
557
  gasPayment: { defaultToken: "ETH", sponsorship: "never" },
547
558
  }}
548
559
  />
@@ -583,6 +594,64 @@ Per-operation `gasPayment.sponsorship` overrides the configured policy, so
583
594
  `op.execute({ gasPayment: { symbol: "ETH", sponsorship: "auto" } })` can request
584
595
  sponsorship even when the widget defaults to `"never"`.
585
596
 
597
+ ### Skipping UserOperation gas estimation
598
+
599
+ For a Fluent ID batch with known gas budgets, pass `userOperationGas.skipEstimation: true`:
600
+
601
+ ```ts
602
+ await widget.createBatchOp({ calls }).execute({
603
+ userOperationGas: {
604
+ skipEstimation: true,
605
+ callGasLimit: 600_000n,
606
+ verificationGasLimit: 500_000n,
607
+ preVerificationGas: 100_000n,
608
+ },
609
+ });
610
+ ```
611
+
612
+ The flag defaults to `false`. Without it, a fixed `callGasLimit` still leaves other
613
+ gas fields eligible for estimation. With it, the SDK skips the account's gas hook
614
+ and `eth_estimateUserOperationGas` for sponsored, native-gas and ERC-20-gas
615
+ UserOperations, including native-gas fallback after sponsorship fails. External
616
+ wallet transactions keep their wallet's estimation.
617
+
618
+ Supply all three account limits. With a paymaster, omit both paymaster limits to
619
+ use the provider's validation and post-operation limits. Its returned
620
+ `preVerificationGas` is accepted up to your configured value; a larger value
621
+ fails before signing. Execution and account-validation limits stay fixed. The
622
+ provider must return complete paymaster limits in its first response; later
623
+ authorization may keep or replace them. The SDK preserves the authorized values
624
+ through signing without invoking the account gas hook or bundler gas estimator.
625
+
626
+ Alternatively, supply both `paymasterVerificationGasLimit` and
627
+ `paymasterPostOpGasLimit` to fix every gas field, as in 0.5.0. When a paymaster is
628
+ used, supplying only one fails before authorization. Limits are bigints:
629
+ `preVerificationGas` must fit a positive
630
+ uint256, `paymasterPostOpGasLimit` a nonnegative uint128, and the others a positive
631
+ uint128. `callGasBuffer` cannot be combined with `skipEstimation: true`.
632
+ Gas-policy validation reports `FluentUserOperationGasError` with code
633
+ `invalid_policy` and names the option to correct.
634
+
635
+ The example values are illustrative. Choose limits that cover the complete batch,
636
+ including a prepended Gas token approval and account validation or deployment.
637
+ Fixed paymaster limits must cover paymaster execution. The SDK does not verify
638
+ that these budgets are sufficient; an underestimated operation can be rejected
639
+ or fail during execution.
640
+
641
+ The SDK supplies account gas before paymaster authorization. A data-only adapter's
642
+ authorization or a stub marked final is reused; a nonfinal stub still requires
643
+ final authorization. A changed execution or account-validation limit fails that
644
+ attempt before signing with `FluentUserOperationGasError` code
645
+ `paymaster_gas_mismatch`. With both paymaster limits fixed, any changed gas field
646
+ fails the same way. Malformed provider gas and calldata overhead above the
647
+ configured ceiling also fail before signing. Normal sponsorship fallback still
648
+ applies, with the configured account limits and no gas estimation.
649
+
650
+ This flag does not disable fee quotes, nonce or factory reads, paymaster
651
+ authorization, signing, bundler submission checks or receipt waiting. A paymaster
652
+ service may still perform its own estimation internally; the SDK cannot control
653
+ that service's implementation.
654
+
586
655
  ### Execution timing
587
656
 
588
657
  Set `<FluentWidget debugLogging />` to emit `[fluent execution stage]` progress
@@ -592,6 +661,11 @@ calldata or authentication tokens. Each sponsored/fallback submission attempt
592
661
  has its own timing entry. Logging is off by default and does not repeat gas
593
662
  estimation, signing or submission.
594
663
 
664
+ `[fluent submission timing]` carries the `feeSource` that quoted that attempt and
665
+ `[fluent inclusion timing]` the `receiptSource` that produced the receipt — the one that
666
+ answered, so a send that asked the chain and was answered by ZeroDev reads `"bundler"`. See
667
+ [Where a send reads fees and receipts](#where-a-send-reads-fees-and-receipts).
668
+
595
669
  ETH avoids the ERC-20 paymaster request but still needs UserOperation gas
596
670
  estimation. Shorter receipt polling and receipt reuse do not remove bundler or
597
671
  paymaster preparation latency; compare these stages before attributing a delay
@@ -606,6 +680,68 @@ explicit connection remains available. Set `reconnectOnMount: true` to restore
606
680
  every connector, or explicitly set `false` to restore none. Wallet users returning
607
681
  from Link X can therefore resume with the same EOA under the default policy.
608
682
 
683
+ ### Where a send reads fees and receipts
684
+
685
+ A smart-account send needs two answers that both the widget chain's RPC and the ZeroDev bundler
686
+ can give: what the operation's fees should be, and whether it has been included.
687
+ `FluentWidgetConfig.execution` decides which one is asked, and the defaults are the chain,
688
+ because the chain answers both in about 70 ms against about 590 ms for a ZeroDev gas-price
689
+ quote and about 345 ms for a ZeroDev receipt poll. Those per-request numbers are a probe's, not
690
+ a measurement of this widget: what a whole send gains on Fluent testnet is being measured on
691
+ `apps/sponsorship-demo` (FLU-1591), and the report is not in yet.
692
+
693
+ > **Experimental.** `execution` and its three fields may change or be removed in a minor
694
+ > release while the defaults are measured. The defaults are the recommended setting: leave
695
+ > them unset unless you need today's ZeroDev behaviour back.
696
+
697
+ ```tsx
698
+ <FluentWidget
699
+ config={{
700
+ appId: "app_…",
701
+ privyClientId: "client-…",
702
+ execution: {
703
+ feeSource: "chain", // or "bundler"
704
+ receiptSource: "chain", // or "bundler"
705
+ chainCheckBeforeSign: false, // or true
706
+ },
707
+ }}
708
+ />
709
+ ```
710
+
711
+ | Field | Default | `"chain"` / `false` | `"bundler"` / `true` |
712
+ |---|---|---|---|
713
+ | `feeSource` | `"chain"` | `maxPriorityFeePerGas` is the chain's `eth_gasPrice`, and `maxFeePerGas` is that answer plus 10 %, rounded down | ZeroDev's `zd_getUserOperationGasPrice` quote, unchanged |
714
+ | `receiptSource` | `"chain"` | inclusion is the EntryPoint's `UserOperationEvent`, polled with `eth_getLogs` every 200 ms on the chain's RPC | `eth_getUserOperationReceipt`, polled every 200 ms on the bundler |
715
+ | `chainCheckBeforeSign` | `false` | the Signer signs without being asked its chain id first | the Signer's chain is read, and switched if it has to be, before every signature |
716
+
717
+ The same defaults apply on testnet and on mainnet, because each `chain` source falls back to
718
+ ZeroDev on its own and inside the send that needed it:
719
+
720
+ - a chain `eth_gasPrice` that fails after the RPC transport's own retries is answered by
721
+ ZeroDev's quote for that send, and the next send asks the chain again;
722
+ - a chain `eth_blockNumber`, `eth_getLogs` or `eth_getTransactionReceipt` that fails the same way
723
+ hands the wait back to `eth_getUserOperationReceipt` on the bundler, for what is left of the
724
+ 120 s a send waits for its receipt. A send that reaches those 120 s with no receipt rejects
725
+ with viem's `WaitForUserOperationReceiptTimeoutError`, as it did before.
726
+
727
+ A bundler may refuse an operation whose `maxFeePerGas` or `maxPriorityFeePerGas` is below what
728
+ it will accept. That one rejection is retried once, inside the same send, whichever source
729
+ quoted the attempt it refused: the operation is prepared again with a fresh
730
+ `zd_getUserOperationGasPrice` quote, signed again without a second review, and submitted a
731
+ second time. A second refusal is the bundler's answer to the bundler's own quote and reaches your
732
+ `catch` unchanged, after exactly two submissions. Nothing is remembered: the next send asks the
733
+ chain first again.
734
+
735
+ `chainCheckBeforeSign` is about the repeat, not about the check: the widget gives Privy its own
736
+ chain as the only chain it supports, and the chain is checked once when the smart account is
737
+ created, whatever this field says.
738
+
739
+ `execution` changes apply to the next send and the next signature — the widget does not have to
740
+ be remounted for them. A send already in flight keeps the three settings it started with, its
741
+ fee retry and its second signature included, and it keeps them to itself: a `widget.signMessage`
742
+ or a second send you start while it waits reads the settings as they are then, not as that send
743
+ read them.
744
+
609
745
  ### Always guard on `executionReady`
610
746
 
611
747
  `createBatchOp` throws only on malformed input (an empty `calls` array, or a call
@@ -691,11 +827,12 @@ await widget.createBatchOp({
691
827
  For an external wallet `permit` works as usual, so a host that supports both can
692
828
  branch on `widget.account.capabilities.atomicBatch`.
693
829
 
694
- ### Signing requires direct mode
830
+ ### What answers the signature
695
831
 
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).
832
+ For a Fluent ID the **in-page Signer** answers: the Privy embedded wallet that
833
+ signed the user in, reached through the ZeroDev kernel in your page. For an
834
+ external wallet the wallet answers. Either way the signature is produced where
835
+ the user is, with no second window and no service round trip.
699
836
 
700
837
  ## 7c. Embedding a marketplace iframe
701
838
 
@@ -744,10 +881,7 @@ loaded after the bridge still learns them; sign-in and sign-out reach the iframe
744
881
  as `accountsChanged` after that. `eth_sendTransaction` resolves once the
745
882
  transaction is included, so the hash it returns already has a receipt.
746
883
 
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
884
+ As in §7b, a smart-account signature is ERC-1271, so the marketplace's order validation has to
751
885
  accept that; a validator without an ERC-6492 path also needs the account deployed,
752
886
  which means a not-yet-deployed account must send one transaction before its first
753
887
  listing validates.
@@ -758,39 +892,28 @@ is the method mapping alone, for a transport of your own.
758
892
 
759
893
  ---
760
894
 
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 |
895
+ ## 8. Auth and the Fluent token
896
+
897
+ **Direct login** is the one way in. Clicking Connect opens **Fluent's own sign-in dialog**
898
+ inside your page, carrying the sign-in methods and the external wallet list on one screen
899
+ ([§4](#sign-in-methods)); Privy runs headless behind it and renders no modal of its own.
900
+ Your origin **must** be registered on the Privy app client behind your `privyClientId`
901
+ first, otherwise Privy rejects it with `invalid_origin` and the login button does nothing.
902
+ Because the user's Privy session then lives in your page, so does everything that needs it:
903
+ `signMessage` and `signTypedData` ([§7b](#7b-requesting-a-signature)), the iframe bridge
904
+ ([§7c](#7c-embedding-a-marketplace-iframe)), `linkX()` ([§8c](#8c-linking-x)) and
905
+ `getAuthToken()`.
906
+
907
+ What each account type gets:
908
+
909
+ | Account | Fluent token (`getAuthToken()`) minted by | Prompt | Signing | Sponsorship |
784
910
  | --- | --- | --- | --- | --- |
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:
911
+ | Fluent ID, on Direct login | widget, with the in-page Privy tokens | none | in page, with review | yes, with the Fluent token |
912
+ | External wallet, on Direct login | widget, challenge + wallet signature | one per session | the wallet | none: an EOA pays its own gas |
913
+
914
+ A Fluent ID exchanges the Privy tokens your page holds; an external wallet signs the
915
+ challenge in the page. With nobody connected, `getAuthToken()` rejects with
916
+ `not_connected`. How your backend checks the token:
794
917
  [§8b](#8b-verify-the-token-on-your-backend).
795
918
 
796
919
  ### The token renews itself, silently
@@ -837,9 +960,6 @@ back to a full exchange: one new signature for an external wallet, then business
837
960
  usual. Nothing is lost and nobody is signed out, but a multi-tab app should expect the
838
961
  occasional extra prompt. Coordinating tabs is not in this release.
839
962
 
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
963
  ### Where the session is kept, and what that costs
844
964
 
845
965
  The refresh token is kept in this browser's `localStorage`, under a key carrying the
@@ -899,12 +1019,10 @@ release: this guide sets no date for it. Once it is gone, a page still running a
899
1019
  release will get unsponsored transactions rather than a hard error — the account pays its
900
1020
  own gas, as the table's other rows already do.
901
1021
 
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.
1022
+ The Sponsorship column above says what each account type gets, and only the first row
1023
+ is sponsored. An external wallet sends through the wallet and never through the smart
1024
+ account, so there is no user operation to sponsor. Nothing throws: the wallet pays its
1025
+ own gas and the transaction goes through.
908
1026
 
909
1027
  If the paymaster rejects a token with a `401`, the widget mints one fresh token and
910
1028
  retries the operation once before the account falls back to paying its own gas. A
@@ -914,6 +1032,15 @@ sits in that subtree, and toggling Quick sign rebuilds it, so after a toggle the
914
1032
  operation asks once more and latches again on the same `403`. Turn on `debugLogging`
915
1033
  ([§9b](#9b-debugging-an-integration)) to see which of these happened.
916
1034
 
1035
+ The SDK's chain, bundler and paymaster HTTP requests have a 30-second deadline per
1036
+ request. A slow gas estimate can use that time with sponsored, account-paid or
1037
+ ERC-20 gas, including account-paid fallback after sponsorship fails. Chain and
1038
+ bundler requests retain up to three retries with exponential backoff; paymaster
1039
+ authorization does not retry a timeout. These are request deadlines, so preparing
1040
+ and submitting a transaction can take longer than 30 seconds across requests and
1041
+ retries. A timeout reports an unanswered request and does not establish that the
1042
+ Fluent ID lacks ETH.
1043
+
917
1044
  A Fluent token needs one more piece of setup, in either mode and for either
918
1045
  account type: your page origin must be registered on your App in the Fluent App
919
1046
  settings. That is the Fluent auth service's own list, separate from the Privy
@@ -945,6 +1072,18 @@ auth service. Your backend needs no Fluent SDK to check it:
945
1072
  4. Use `sub` as the user id. Read `addresses.account` only if your App has the `addresses`
946
1073
  scope, and only for on-chain joins.
947
1074
 
1075
+ The issuer is **per network**, and no single rule derives it from the API host the widget calls.
1076
+ Pin the one your widget's `network` says, and read its key set from that issuer:
1077
+
1078
+ | `network` | `iss` | Key set |
1079
+ |-------------|-------|---------|
1080
+ | `"mainnet"` | `https://api.fluent.xyz/connect` | `https://api.fluent.xyz/connect/.well-known/jwks.json` |
1081
+ | `"testnet"` | `https://api.fluent-connect.dev.gblend.xyz` | `https://api.fluent-connect.dev.gblend.xyz/.well-known/jwks.json` |
1082
+
1083
+ Each issuer publishes its own key set, so a backend serving both networks pins both issuers and
1084
+ picks the one it expects for that App — not the `iss` the token carries, which is the value
1085
+ being checked.
1086
+
948
1087
  Go, with the same two libraries the Fluent auth service uses:
949
1088
 
950
1089
  ```go
@@ -971,12 +1110,11 @@ Verify on every request, or exchange the token once for your own session. Both a
971
1110
  first needs no application-session state on your side.
972
1111
 
973
1112
  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.
1113
+ and the SDK renews it silently for both account types, a Fluent ID and an external wallet.
1114
+ **Calling it often no longer prompts the wallet.** The wallet signs once, when the session
1115
+ opens, and every renewal for the next thirty days is a background request, for as long as the
1116
+ service issues the refresh credential a renewal spends
1117
+ ([§8](#the-token-renews-itself-silently)).
980
1118
 
981
1119
  So verifying on every request is a real option now, for external wallets too. Exchanging our
982
1120
  token once for your own session is still the lighter thing to do per request, and it is what to
@@ -1092,7 +1230,7 @@ the wallet to sign it, and hands Privy the signature. The user sees one **signat
1092
1230
  their wallet, for a plain message naming your page and a nonce. **It is a signature, not a
1093
1231
  transaction**: nothing is sent to the chain and nothing costs gas. Then, still before the
1094
1232
  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
1233
+ [§8](#8-auth-and-the-fluent-token), the same one `getAuthToken()` signs — so that **every signature happens
1096
1234
  before the page leaves**. On a page that has not minted the token yet that is a second prompt;
1097
1235
  on one that already holds it (you called `getAuthToken()` first, or an earlier call minted it)
1098
1236
  the wallet is asked nothing more. Only then does the X redirect happen. The page that comes back
@@ -1111,7 +1249,7 @@ path.
1111
1249
 
1112
1250
  Nothing about the Fluent user changes over it. The connected account is still the wallet, its
1113
1251
  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,
1252
+ keyed on the address, renewed by the wallet's own refresh family ([§8](#8-auth-and-the-fluent-token)) — before,
1115
1253
  during and after the link. The Privy session SIWE makes is the link's machinery, not an account:
1116
1254
  it never becomes a Fluent ID — not when Privy attaches an embedded wallet to it, not when the
1117
1255
  wallet is disconnected or swapped for another while it lives — and the widget never signs with it.
@@ -1158,18 +1296,12 @@ Every rejection is a `FluentAuthError` with one of:
1158
1296
  | `user_rejected` | The user said no at X, closed the flow, or declined the SIWE signature or the Fluent token's challenge. |
1159
1297
  | `linked_to_another_user` | That X account is already linked to another Fluent user. |
1160
1298
  | `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
1299
  | `bad_request` | The service refused the request body. Report it; it is ours, not yours. |
1163
1300
  | `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
1301
 
1165
1302
  No other code reaches you from `linkX()`. A refusal raised under it — by the request that mints
1166
1303
  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.
1304
+ five codes above is complete.
1173
1305
 
1174
1306
  ### The sequence your backend sees
1175
1307
 
@@ -1230,8 +1362,8 @@ Leave it off in production.
1230
1362
 
1231
1363
  - [ ] Got a Fluent `appId` and `privyClientId`.
1232
1364
  - [ ] 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).
1365
+ - [ ] Origin allow-listed on the Privy app client behind your `privyClientId`.
1366
+ - [ ] (`getAuthToken()`) page origin registered on your App in the Fluent App settings (§8).
1235
1367
  - [ ] (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
1368
  - [ ] Imported `@fluent.xyz/connect/styles.css` once.
1237
1369
  - [ ] Mounted `<FluentWidget>` at the root; app rendered via `renderPage`.
@@ -1239,4 +1371,31 @@ Leave it off in production.
1239
1371
  - [ ] All txs go through `createBatchOp(...).execute()`, guarded on `executionReady`.
1240
1372
  - [ ] Signatures go through `widget.signMessage` / `widget.signTypedData` and are verified with ERC-1271/6492, not `ecrecover` (§7b).
1241
1373
  - [ ] Checked provider coexistence if the app already uses wagmi / viem / react-query (§9).
1242
- ```
1374
+
1375
+ ---
1376
+
1377
+ ## Upgrading from 0.4
1378
+
1379
+ 0.5.0 removes hosted mode. Direct login — Fluent's sign-in dialog inside your page
1380
+ ([§8](#8-auth-and-the-fluent-token)) — is the one way to log in to a Fluent ID.
1381
+
1382
+ - **`authMode` is removed from `FluentWidgetConfig`.** Delete the key. A config that passed
1383
+ `authMode: "direct"` keeps exactly the behaviour it had; the widget accepts the key one
1384
+ last time, ignores it and warns once. `authMode: "hosted"` throws at startup with these
1385
+ instructions.
1386
+ - **A config that omitted `authMode` was on hosted mode** — it was the 0.4.x default — and is
1387
+ now on Direct login. Direct login mounts Privy on your page, so your App's origin has to be
1388
+ registered on the Privy app client behind your `privyClientId`
1389
+ ([§1](#1-prerequisites)). Ask Fluent to add it before you upgrade, or your
1390
+ users meet a login button that silently does nothing.
1391
+ - **`fluent.initialize().connect()` and `.buildAuthorizeUrl()` are removed**, together with
1392
+ the `authorizeUrl` and `redirectUri` options of `fluent.initialize()`. There is no authorize
1393
+ popup to open. `initialize`, `status()`, `setSession()` and `disconnect()` are unchanged.
1394
+ - **The `hosted_not_supported` error code is gone** from `FluentAuthError` and from the
1395
+ `linkX()` codes ([§8c](#8c-linking-x)): nothing refuses a signature, a token or a link for
1396
+ want of an in-page Privy session any more.
1397
+ - **A user signed in through hosted mode on 0.4.x signs in again** after your App upgrades.
1398
+ Their stored session still shows them as connected and the first signature finds no signer;
1399
+ Disconnect, then sign in again, clears it.
1400
+ - `FluentWidgetAuthMode` is no longer exported, and `FluentWidgetRenderContext` and
1401
+ `FluentIframeRpcExecutor` no longer carry `authMode`.