@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 +255 -96
- package/README.md +82 -22
- package/dist/fluent-connect.css +1 -1
- package/dist/index.d.ts +316 -62
- package/dist/index.js +1444 -1091
- 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,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
|
-
###
|
|
830
|
+
### What answers the signature
|
|
695
831
|
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
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
|
-
|
|
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
|
|
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 |
|
|
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
|
-
|
|
|
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:
|
|
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
|
|
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.
|
|
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
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
978
|
-
([§8](#the-token-renews-itself-silently))
|
|
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-
|
|
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-
|
|
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
|
-
|
|
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
|
-
- [ ]
|
|
1234
|
-
- [ ] (`getAuthToken()
|
|
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`.
|