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