@fluent.xyz/connect 0.4.2 → 0.5.0
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 +232 -96
- package/README.md +76 -20
- package/dist/fluent-connect.css +1 -1
- package/dist/index.d.ts +305 -56
- package/dist/index.js +1362 -1041
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
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** —
|
|
39
|
-
|
|
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
|
-
> **
|
|
42
|
-
>
|
|
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
|
|
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,
|
|
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
|
-
|
|
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.
|
|
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, **
|
|
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
|
-
|
|
300
|
-
|
|
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-
|
|
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`
|
|
389
|
-
|
|
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
|
-
|
|
|
394
|
-
|
|
|
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,53 @@ 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
|
+
paymasterVerificationGasLimit: 100_000n,
|
|
609
|
+
paymasterPostOpGasLimit: 50_000n,
|
|
610
|
+
},
|
|
611
|
+
});
|
|
612
|
+
```
|
|
613
|
+
|
|
614
|
+
The flag defaults to `false`. Without it, a fixed `callGasLimit` still leaves other
|
|
615
|
+
gas fields eligible for estimation. With it, the SDK skips the account's gas hook
|
|
616
|
+
and `eth_estimateUserOperationGas` for sponsored, native-gas and ERC-20-gas
|
|
617
|
+
UserOperations, including native-gas fallback after sponsorship fails. External
|
|
618
|
+
wallet transactions keep their wallet's estimation.
|
|
619
|
+
|
|
620
|
+
Supply all three account limits. The two paymaster limits are also required when
|
|
621
|
+
a paymaster is used. Limits are bigints: `preVerificationGas` must fit a positive
|
|
622
|
+
uint256, `paymasterPostOpGasLimit` a nonnegative uint128, and the others a positive
|
|
623
|
+
uint128. `callGasBuffer` cannot be combined with `skipEstimation: true`.
|
|
624
|
+
Gas-policy validation reports `FluentUserOperationGasError` with code
|
|
625
|
+
`invalid_policy` and names the option to correct.
|
|
626
|
+
|
|
627
|
+
The example values are illustrative. Choose limits that cover the complete batch,
|
|
628
|
+
including a prepended Gas token approval, account validation or deployment, and
|
|
629
|
+
paymaster execution. The SDK does not verify that these budgets are sufficient;
|
|
630
|
+
an underestimated operation can be rejected or fail during execution.
|
|
631
|
+
|
|
632
|
+
The SDK supplies these gas limits before paymaster authorization and preserves
|
|
633
|
+
them through signing. A data-only adapter's authorization or a stub marked final
|
|
634
|
+
is reused when it matches the limits; a nonfinal stub still requires final
|
|
635
|
+
authorization. An authorization that returns different gas limits fails that
|
|
636
|
+
attempt before signing with `FluentUserOperationGasError` code
|
|
637
|
+
`paymaster_gas_mismatch`. Normal sponsorship fallback still applies.
|
|
638
|
+
|
|
639
|
+
This flag does not disable fee quotes, nonce or factory reads, paymaster
|
|
640
|
+
authorization, signing, bundler submission checks or receipt waiting. A paymaster
|
|
641
|
+
service may still perform its own estimation internally; the SDK cannot control
|
|
642
|
+
that service's implementation.
|
|
643
|
+
|
|
586
644
|
### Execution timing
|
|
587
645
|
|
|
588
646
|
Set `<FluentWidget debugLogging />` to emit `[fluent execution stage]` progress
|
|
@@ -592,6 +650,11 @@ calldata or authentication tokens. Each sponsored/fallback submission attempt
|
|
|
592
650
|
has its own timing entry. Logging is off by default and does not repeat gas
|
|
593
651
|
estimation, signing or submission.
|
|
594
652
|
|
|
653
|
+
`[fluent submission timing]` carries the `feeSource` that quoted that attempt and
|
|
654
|
+
`[fluent inclusion timing]` the `receiptSource` that produced the receipt — the one that
|
|
655
|
+
answered, so a send that asked the chain and was answered by ZeroDev reads `"bundler"`. See
|
|
656
|
+
[Where a send reads fees and receipts](#where-a-send-reads-fees-and-receipts).
|
|
657
|
+
|
|
595
658
|
ETH avoids the ERC-20 paymaster request but still needs UserOperation gas
|
|
596
659
|
estimation. Shorter receipt polling and receipt reuse do not remove bundler or
|
|
597
660
|
paymaster preparation latency; compare these stages before attributing a delay
|
|
@@ -606,6 +669,68 @@ explicit connection remains available. Set `reconnectOnMount: true` to restore
|
|
|
606
669
|
every connector, or explicitly set `false` to restore none. Wallet users returning
|
|
607
670
|
from Link X can therefore resume with the same EOA under the default policy.
|
|
608
671
|
|
|
672
|
+
### Where a send reads fees and receipts
|
|
673
|
+
|
|
674
|
+
A smart-account send needs two answers that both the widget chain's RPC and the ZeroDev bundler
|
|
675
|
+
can give: what the operation's fees should be, and whether it has been included.
|
|
676
|
+
`FluentWidgetConfig.execution` decides which one is asked, and the defaults are the chain,
|
|
677
|
+
because the chain answers both in about 70 ms against about 590 ms for a ZeroDev gas-price
|
|
678
|
+
quote and about 345 ms for a ZeroDev receipt poll. Those per-request numbers are a probe's, not
|
|
679
|
+
a measurement of this widget: what a whole send gains on Fluent testnet is being measured on
|
|
680
|
+
`apps/sponsorship-demo` (FLU-1591), and the report is not in yet.
|
|
681
|
+
|
|
682
|
+
> **Experimental.** `execution` and its three fields may change or be removed in a minor
|
|
683
|
+
> release while the defaults are measured. The defaults are the recommended setting: leave
|
|
684
|
+
> them unset unless you need today's ZeroDev behaviour back.
|
|
685
|
+
|
|
686
|
+
```tsx
|
|
687
|
+
<FluentWidget
|
|
688
|
+
config={{
|
|
689
|
+
appId: "app_…",
|
|
690
|
+
privyClientId: "client-…",
|
|
691
|
+
execution: {
|
|
692
|
+
feeSource: "chain", // or "bundler"
|
|
693
|
+
receiptSource: "chain", // or "bundler"
|
|
694
|
+
chainCheckBeforeSign: false, // or true
|
|
695
|
+
},
|
|
696
|
+
}}
|
|
697
|
+
/>
|
|
698
|
+
```
|
|
699
|
+
|
|
700
|
+
| Field | Default | `"chain"` / `false` | `"bundler"` / `true` |
|
|
701
|
+
|---|---|---|---|
|
|
702
|
+
| `feeSource` | `"chain"` | `maxPriorityFeePerGas` is the chain's `eth_gasPrice`, and `maxFeePerGas` is that answer plus 10 %, rounded down | ZeroDev's `zd_getUserOperationGasPrice` quote, unchanged |
|
|
703
|
+
| `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 |
|
|
704
|
+
| `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 |
|
|
705
|
+
|
|
706
|
+
The same defaults apply on testnet and on mainnet, because each `chain` source falls back to
|
|
707
|
+
ZeroDev on its own and inside the send that needed it:
|
|
708
|
+
|
|
709
|
+
- a chain `eth_gasPrice` that fails after the RPC transport's own retries is answered by
|
|
710
|
+
ZeroDev's quote for that send, and the next send asks the chain again;
|
|
711
|
+
- a chain `eth_blockNumber`, `eth_getLogs` or `eth_getTransactionReceipt` that fails the same way
|
|
712
|
+
hands the wait back to `eth_getUserOperationReceipt` on the bundler, for what is left of the
|
|
713
|
+
120 s a send waits for its receipt. A send that reaches those 120 s with no receipt rejects
|
|
714
|
+
with viem's `WaitForUserOperationReceiptTimeoutError`, as it did before.
|
|
715
|
+
|
|
716
|
+
A bundler may refuse an operation whose `maxFeePerGas` or `maxPriorityFeePerGas` is below what
|
|
717
|
+
it will accept. That one rejection is retried once, inside the same send, whichever source
|
|
718
|
+
quoted the attempt it refused: the operation is prepared again with a fresh
|
|
719
|
+
`zd_getUserOperationGasPrice` quote, signed again — which in Prompt mode means a second
|
|
720
|
+
confirmation screen for the person — and submitted a second time. A second refusal is the bundler's answer to the bundler's own quote and reaches your
|
|
721
|
+
`catch` unchanged, after exactly two submissions. Nothing is remembered: the next send asks the
|
|
722
|
+
chain first again.
|
|
723
|
+
|
|
724
|
+
`chainCheckBeforeSign` is about the repeat, not about the check: the widget gives Privy its own
|
|
725
|
+
chain as the only chain it supports, and the chain is checked once when the smart account is
|
|
726
|
+
created, whatever this field says.
|
|
727
|
+
|
|
728
|
+
`execution` changes apply to the next send and the next signature — the widget does not have to
|
|
729
|
+
be remounted for them. A send already in flight keeps the three settings it started with, its
|
|
730
|
+
fee retry and its second signature included, and it keeps them to itself: a `widget.signMessage`
|
|
731
|
+
or a second send you start while it waits reads the settings as they are then, not as that send
|
|
732
|
+
read them.
|
|
733
|
+
|
|
609
734
|
### Always guard on `executionReady`
|
|
610
735
|
|
|
611
736
|
`createBatchOp` throws only on malformed input (an empty `calls` array, or a call
|
|
@@ -691,11 +816,12 @@ await widget.createBatchOp({
|
|
|
691
816
|
For an external wallet `permit` works as usual, so a host that supports both can
|
|
692
817
|
branch on `widget.account.capabilities.atomicBatch`.
|
|
693
818
|
|
|
694
|
-
###
|
|
819
|
+
### What answers the signature
|
|
695
820
|
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
821
|
+
For a Fluent ID the **in-page Signer** answers: the Privy embedded wallet that
|
|
822
|
+
signed the user in, reached through the ZeroDev kernel in your page. For an
|
|
823
|
+
external wallet the wallet answers. Either way the signature is produced where
|
|
824
|
+
the user is, with no second window and no service round trip.
|
|
699
825
|
|
|
700
826
|
## 7c. Embedding a marketplace iframe
|
|
701
827
|
|
|
@@ -744,10 +870,7 @@ loaded after the bridge still learns them; sign-in and sign-out reach the iframe
|
|
|
744
870
|
as `accountsChanged` after that. `eth_sendTransaction` resolves once the
|
|
745
871
|
transaction is included, so the hash it returns already has a receipt.
|
|
746
872
|
|
|
747
|
-
|
|
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
|
|
873
|
+
As in §7b, a smart-account signature is ERC-1271, so the marketplace's order validation has to
|
|
751
874
|
accept that; a validator without an ERC-6492 path also needs the account deployed,
|
|
752
875
|
which means a not-yet-deployed account must send one transaction before its first
|
|
753
876
|
listing validates.
|
|
@@ -758,39 +881,28 @@ is the method mapping alone, for a transport of your own.
|
|
|
758
881
|
|
|
759
882
|
---
|
|
760
883
|
|
|
761
|
-
## 8. Auth
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
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 |
|
|
884
|
+
## 8. Auth and the Fluent token
|
|
885
|
+
|
|
886
|
+
**Direct login** is the one way in. Clicking Connect opens **Fluent's own sign-in dialog**
|
|
887
|
+
inside your page, carrying the sign-in methods and the external wallet list on one screen
|
|
888
|
+
([§4](#sign-in-methods)); Privy runs headless behind it and renders no modal of its own.
|
|
889
|
+
Your origin **must** be registered on the Privy app client behind your `privyClientId`
|
|
890
|
+
first, otherwise Privy rejects it with `invalid_origin` and the login button does nothing.
|
|
891
|
+
Because the user's Privy session then lives in your page, so does everything that needs it:
|
|
892
|
+
`signMessage` and `signTypedData` ([§7b](#7b-requesting-a-signature)), the iframe bridge
|
|
893
|
+
([§7c](#7c-embedding-a-marketplace-iframe)), `linkX()` ([§8c](#8c-linking-x)) and
|
|
894
|
+
`getAuthToken()`.
|
|
895
|
+
|
|
896
|
+
What each account type gets:
|
|
897
|
+
|
|
898
|
+
| Account | Fluent token (`getAuthToken()`) minted by | Prompt | Signing | Sponsorship |
|
|
784
899
|
| --- | --- | --- | --- | --- |
|
|
785
|
-
|
|
|
786
|
-
|
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
|
|
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:
|
|
900
|
+
| Fluent ID, on Direct login | widget, with the in-page Privy tokens | none | in page, with review | yes, with the Fluent token |
|
|
901
|
+
| External wallet, on Direct login | widget, challenge + wallet signature | one per session | the wallet | none: an EOA pays its own gas |
|
|
902
|
+
|
|
903
|
+
A Fluent ID exchanges the Privy tokens your page holds; an external wallet signs the
|
|
904
|
+
challenge in the page. With nobody connected, `getAuthToken()` rejects with
|
|
905
|
+
`not_connected`. How your backend checks the token:
|
|
794
906
|
[§8b](#8b-verify-the-token-on-your-backend).
|
|
795
907
|
|
|
796
908
|
### The token renews itself, silently
|
|
@@ -837,9 +949,6 @@ back to a full exchange: one new signature for an external wallet, then business
|
|
|
837
949
|
usual. Nothing is lost and nobody is signed out, but a multi-tab app should expect the
|
|
838
950
|
occasional extra prompt. Coordinating tabs is not in this release.
|
|
839
951
|
|
|
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
952
|
### Where the session is kept, and what that costs
|
|
844
953
|
|
|
845
954
|
The refresh token is kept in this browser's `localStorage`, under a key carrying the
|
|
@@ -899,12 +1008,10 @@ release: this guide sets no date for it. Once it is gone, a page still running a
|
|
|
899
1008
|
release will get unsponsored transactions rather than a hard error — the account pays its
|
|
900
1009
|
own gas, as the table's other rows already do.
|
|
901
1010
|
|
|
902
|
-
The Sponsorship column above says what each
|
|
903
|
-
|
|
904
|
-
|
|
905
|
-
|
|
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.
|
|
1011
|
+
The Sponsorship column above says what each account type gets, and only the first row
|
|
1012
|
+
is sponsored. An external wallet sends through the wallet and never through the smart
|
|
1013
|
+
account, so there is no user operation to sponsor. Nothing throws: the wallet pays its
|
|
1014
|
+
own gas and the transaction goes through.
|
|
908
1015
|
|
|
909
1016
|
If the paymaster rejects a token with a `401`, the widget mints one fresh token and
|
|
910
1017
|
retries the operation once before the account falls back to paying its own gas. A
|
|
@@ -914,6 +1021,15 @@ sits in that subtree, and toggling Quick sign rebuilds it, so after a toggle the
|
|
|
914
1021
|
operation asks once more and latches again on the same `403`. Turn on `debugLogging`
|
|
915
1022
|
([§9b](#9b-debugging-an-integration)) to see which of these happened.
|
|
916
1023
|
|
|
1024
|
+
The SDK's chain, bundler and paymaster HTTP requests have a 30-second deadline per
|
|
1025
|
+
request. A slow gas estimate can use that time with sponsored, account-paid or
|
|
1026
|
+
ERC-20 gas, including account-paid fallback after sponsorship fails. Chain and
|
|
1027
|
+
bundler requests retain up to three retries with exponential backoff; paymaster
|
|
1028
|
+
authorization does not retry a timeout. These are request deadlines, so preparing
|
|
1029
|
+
and submitting a transaction can take longer than 30 seconds across requests and
|
|
1030
|
+
retries. A timeout reports an unanswered request and does not establish that the
|
|
1031
|
+
Fluent ID lacks ETH.
|
|
1032
|
+
|
|
917
1033
|
A Fluent token needs one more piece of setup, in either mode and for either
|
|
918
1034
|
account type: your page origin must be registered on your App in the Fluent App
|
|
919
1035
|
settings. That is the Fluent auth service's own list, separate from the Privy
|
|
@@ -971,12 +1087,11 @@ Verify on every request, or exchange the token once for your own session. Both a
|
|
|
971
1087
|
first needs no application-session state on your side.
|
|
972
1088
|
|
|
973
1089
|
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
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
978
|
-
([§8](#the-token-renews-itself-silently))
|
|
979
|
-
rejects with `hosted_not_supported` rather than returning a token at all.
|
|
1090
|
+
and the SDK renews it silently for both account types, a Fluent ID and an external wallet.
|
|
1091
|
+
**Calling it often no longer prompts the wallet.** The wallet signs once, when the session
|
|
1092
|
+
opens, and every renewal for the next thirty days is a background request, for as long as the
|
|
1093
|
+
service issues the refresh credential a renewal spends
|
|
1094
|
+
([§8](#the-token-renews-itself-silently)).
|
|
980
1095
|
|
|
981
1096
|
So verifying on every request is a real option now, for external wallets too. Exchanging our
|
|
982
1097
|
token once for your own session is still the lighter thing to do per request, and it is what to
|
|
@@ -1092,7 +1207,7 @@ the wallet to sign it, and hands Privy the signature. The user sees one **signat
|
|
|
1092
1207
|
their wallet, for a plain message naming your page and a nonce. **It is a signature, not a
|
|
1093
1208
|
transaction**: nothing is sent to the chain and nothing costs gas. Then, still before the
|
|
1094
1209
|
redirect, the SDK mints the wallet's Fluent token — the typed-data challenge of
|
|
1095
|
-
[§8](#8-auth-
|
|
1210
|
+
[§8](#8-auth-and-the-fluent-token), the same one `getAuthToken()` signs — so that **every signature happens
|
|
1096
1211
|
before the page leaves**. On a page that has not minted the token yet that is a second prompt;
|
|
1097
1212
|
on one that already holds it (you called `getAuthToken()` first, or an earlier call minted it)
|
|
1098
1213
|
the wallet is asked nothing more. Only then does the X redirect happen. The page that comes back
|
|
@@ -1111,7 +1226,7 @@ path.
|
|
|
1111
1226
|
|
|
1112
1227
|
Nothing about the Fluent user changes over it. The connected account is still the wallet, its
|
|
1113
1228
|
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-
|
|
1229
|
+
keyed on the address, renewed by the wallet's own refresh family ([§8](#8-auth-and-the-fluent-token)) — before,
|
|
1115
1230
|
during and after the link. The Privy session SIWE makes is the link's machinery, not an account:
|
|
1116
1231
|
it never becomes a Fluent ID — not when Privy attaches an embedded wallet to it, not when the
|
|
1117
1232
|
wallet is disconnected or swapped for another while it lives — and the widget never signs with it.
|
|
@@ -1158,18 +1273,12 @@ Every rejection is a `FluentAuthError` with one of:
|
|
|
1158
1273
|
| `user_rejected` | The user said no at X, closed the flow, or declined the SIWE signature or the Fluent token's challenge. |
|
|
1159
1274
|
| `linked_to_another_user` | That X account is already linked to another Fluent user. |
|
|
1160
1275
|
| `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
1276
|
| `bad_request` | The service refused the request body. Report it; it is ours, not yours. |
|
|
1163
1277
|
| `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
1278
|
|
|
1165
1279
|
No other code reaches you from `linkX()`. A refusal raised under it — by the request that mints
|
|
1166
1280
|
the Fluent token, say — keeps its message and arrives as `link_failed`, so one `switch` over the
|
|
1167
|
-
|
|
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.
|
|
1281
|
+
five codes above is complete.
|
|
1173
1282
|
|
|
1174
1283
|
### The sequence your backend sees
|
|
1175
1284
|
|
|
@@ -1230,8 +1339,8 @@ Leave it off in production.
|
|
|
1230
1339
|
|
|
1231
1340
|
- [ ] Got a Fluent `appId` and `privyClientId`.
|
|
1232
1341
|
- [ ] Picked network (`testnet` / `mainnet`) — and every chain id pinned elsewhere in the app matches it (§3).
|
|
1233
|
-
- [ ]
|
|
1234
|
-
- [ ] (`getAuthToken()
|
|
1342
|
+
- [ ] Origin allow-listed on the Privy app client behind your `privyClientId`.
|
|
1343
|
+
- [ ] (`getAuthToken()`) page origin registered on your App in the Fluent App settings (§8).
|
|
1235
1344
|
- [ ] (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
1345
|
- [ ] Imported `@fluent.xyz/connect/styles.css` once.
|
|
1237
1346
|
- [ ] Mounted `<FluentWidget>` at the root; app rendered via `renderPage`.
|
|
@@ -1239,4 +1348,31 @@ Leave it off in production.
|
|
|
1239
1348
|
- [ ] All txs go through `createBatchOp(...).execute()`, guarded on `executionReady`.
|
|
1240
1349
|
- [ ] Signatures go through `widget.signMessage` / `widget.signTypedData` and are verified with ERC-1271/6492, not `ecrecover` (§7b).
|
|
1241
1350
|
- [ ] Checked provider coexistence if the app already uses wagmi / viem / react-query (§9).
|
|
1242
|
-
|
|
1351
|
+
|
|
1352
|
+
---
|
|
1353
|
+
|
|
1354
|
+
## Upgrading from 0.4
|
|
1355
|
+
|
|
1356
|
+
0.5.0 removes hosted mode. Direct login — Fluent's sign-in dialog inside your page
|
|
1357
|
+
([§8](#8-auth-and-the-fluent-token)) — is the one way to log in to a Fluent ID.
|
|
1358
|
+
|
|
1359
|
+
- **`authMode` is removed from `FluentWidgetConfig`.** Delete the key. A config that passed
|
|
1360
|
+
`authMode: "direct"` keeps exactly the behaviour it had; the widget accepts the key one
|
|
1361
|
+
last time, ignores it and warns once. `authMode: "hosted"` throws at startup with these
|
|
1362
|
+
instructions.
|
|
1363
|
+
- **A config that omitted `authMode` was on hosted mode** — it was the 0.4.x default — and is
|
|
1364
|
+
now on Direct login. Direct login mounts Privy on your page, so your App's origin has to be
|
|
1365
|
+
registered on the Privy app client behind your `privyClientId`
|
|
1366
|
+
([§1](#1-prerequisites)). Ask Fluent to add it before you upgrade, or your
|
|
1367
|
+
users meet a login button that silently does nothing.
|
|
1368
|
+
- **`fluent.initialize().connect()` and `.buildAuthorizeUrl()` are removed**, together with
|
|
1369
|
+
the `authorizeUrl` and `redirectUri` options of `fluent.initialize()`. There is no authorize
|
|
1370
|
+
popup to open. `initialize`, `status()`, `setSession()` and `disconnect()` are unchanged.
|
|
1371
|
+
- **The `hosted_not_supported` error code is gone** from `FluentAuthError` and from the
|
|
1372
|
+
`linkX()` codes ([§8c](#8c-linking-x)): nothing refuses a signature, a token or a link for
|
|
1373
|
+
want of an in-page Privy session any more.
|
|
1374
|
+
- **A user signed in through hosted mode on 0.4.x signs in again** after your App upgrades.
|
|
1375
|
+
Their stored session still shows them as connected and the first signature finds no signer;
|
|
1376
|
+
Disconnect, then sign in again, clears it.
|
|
1377
|
+
- `FluentWidgetAuthMode` is no longer exported, and `FluentWidgetRenderContext` and
|
|
1378
|
+
`FluentIframeRpcExecutor` no longer carry `authMode`.
|