@fluent.xyz/connect 0.5.3 → 0.6.0-rc.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/docs/api.md ADDED
@@ -0,0 +1,1789 @@
1
+ # API reference
2
+
3
+ <!-- Generated by `pnpm --filter @fluent.xyz/connect docs:api` from the TSDoc in `src`;
4
+ do not edit by hand. -->
5
+
6
+ Every export of `@fluent.xyz/connect`: 63 names, 14 values and 49 types. A name or member marked **experimental** may change or be removed in a minor release; [experimental.md](experimental.md) explains each one. Every other name is kept after 0.6.0.
7
+
8
+ Each export shows its TSDoc, its declaration (a function's body left out), the literals of a union of strings, and a table of its members, nested members by their dotted path; a union of object types shows its members in its declaration instead.
9
+
10
+ ## Contents
11
+
12
+ - [Widget and hooks](#widget-and-hooks): `FluentWidget`, `FluentWidgetProps`, `FluentWidgetRenderContext`, `FluentWidgetConnectButtonRenderContext`, `useFluentWidget`, `FluentWidgetStatus`, `FluentWidgetSession`, `FluentWidgetAccount`, `FluentAccountType`, `FluentAccountCapabilities`, `FluentWidgetExecutionStatus`, `AccountAvatar`, `AccountAvatarProps`
13
+ - [Config](#config): `FluentWidgetConfig`, `FluentWidgetNetwork`, `FluentWidgetAuthMethod`, `FluentWidgetAssets`
14
+ - [Batch operations](#batch-operations): `FluentBatchApi`, `FluentBatchOperationInput`, `FluentBatchCallInput`, `FluentBatchOperation`, `FluentBatchOperationExecuteOptions`, `FluentEncodedBatchCall`, `FluentExecuteResult`, `FluentGasPayment`, `FluentWidgetGasPayment`, `FluentGasTokenSymbol`
15
+ - [Signing](#signing): `FluentSignApi`, `FluentSigningMode`
16
+ - [Auth and errors](#auth-and-errors): `FluentAuthError`, `FluentAuthErrorCode`, `FluentWidgetConfigError`, `FluentWidgetConfigErrorCode`, `FluentReviewRejectedError`, `FluentReviewRejectedErrorCode`, `FluentSponsorshipFallbackError`, `FluentSponsorshipReason`
17
+ - [Link X](#link-x): `useLinkX`, `FluentLinkXStatus`, `FluentLinkXResult`, `FluentXAccount`
18
+ - [Iframe](#iframe): `useFluentIframeBridge`, `UseFluentIframeBridgeOptions`, `FluentIframeElement`
19
+ - [Chains and tokens](#chains-and-tokens): `fluentMainnet`, `fluentTestnet`, `getFluentChainByChainId`, `getFluentChainForNetwork`, `FluentChainDefinition`, `FluentTokenDefinition`
20
+ - [Experimental](#experimental): `FluentPrivyAdapter`, `FluentExternalWalletState`, `FluentWalletChoice`, `FluentWidgetExecution`, `FluentWidgetExecutionSource`, `FluentUserOperationGas`, `FluentUserOperationGasError`, `FluentUserOperationGasErrorCode`, `FluentFixedAccountGas`, `FluentFixedPaymasterGas`, `FluentExecuteTiming`, `FluentExecuteTimingInstants`, `FluentGasPaymentEthRates`
21
+
22
+ ## Widget and hooks
23
+
24
+ ### `FluentWidget`
25
+
26
+ *value*
27
+
28
+ The Fluent Connect widget: the connect button, the sign-in dialog, the account drawer and the
29
+ Widget API, provided to the App's own content rendered through `renderHome` or `renderPage`.
30
+
31
+ **Throws** `FluentWidgetConfigError` from a render when `config` cannot be used, its `code`
32
+ `missing_option`, `invalid_option` or `removed_option` with the option named in its message,
33
+ or, for the experimental `execution`, `invalid_fee_source`, `invalid_receipt_source` or
34
+ `invalid_chain_check_before_sign`. The config is resolved again on every render that passes
35
+ a new `config` object, so such a render can throw too; keep `config` stable (a module
36
+ constant or a memo) to resolve it once.
37
+
38
+ **Example**
39
+
40
+ ```tsx
41
+ import { FluentWidget, type FluentWidgetConfig } from "@fluent.xyz/connect";
42
+
43
+ // The App's id, its login client and the Network: see the configuration guide.
44
+ declare const config: FluentWidgetConfig;
45
+
46
+ export function App() {
47
+ return <FluentWidget config={config} mode="page" renderPage={() => <main>Your App</main>} />;
48
+ }
49
+ ```
50
+
51
+ ```ts declaration
52
+ export function FluentWidget(props: FluentWidgetProps) { … }
53
+ ```
54
+
55
+ ### `FluentWidgetProps`
56
+
57
+ *type*
58
+
59
+ The props of `<FluentWidget>`.
60
+
61
+ ```ts declaration
62
+ export type FluentWidgetProps = {
63
+ wallet?: FluentExternalWalletState | null;
64
+ config: FluentWidgetConfig;
65
+ privyAdapter?: FluentPrivyAdapter;
66
+ mode?: "home" | "page";
67
+ connectButton?: "fixed" | "inline" | false;
68
+ renderConnectButton?: (context: FluentWidgetConnectButtonRenderContext) => ReactNode;
69
+ renderHome?: (context: FluentWidgetRenderContext) => ReactNode;
70
+ renderPage?: (context: FluentWidgetRenderContext) => ReactNode;
71
+ tokens?: readonly FluentTokenDefinition[];
72
+ debugLogging?: boolean;
73
+ onSessionChange?: (session: FluentWidgetSession | null) => void;
74
+ };
75
+ ```
76
+
77
+ | Member | Type | Optional | Experimental | Description |
78
+ |---|---|---|---|---|
79
+ | `wallet` | `FluentExternalWalletState \| null` | yes | **yes** | An External wallet the host connects itself, a `FluentExternalWalletState` whose inline choices are `FluentWalletChoice`s; omit it to let the widget connect one. **Experimental.** May change or be removed in a minor release: a host that brings its own wallet connection is not a 0.6.0 commitment. |
80
+ | `config` | `FluentWidgetConfig` | no | no | |
81
+ | `privyAdapter` | `FluentPrivyAdapter` | yes | **yes** | Optional native Privy SDK bridge, a `FluentPrivyAdapter`, for a host that runs Privy's native SDK; requires Direct login. **Experimental.** May change or be removed in a minor release: the one provider seam of the widget, kept for hosts that run a native login SDK. |
82
+ | `mode` | `"home" \| "page"` | yes | no | |
83
+ | `connectButton` | `"fixed" \| "inline" \| false` | yes | no | Show the default connect/account control. - `"fixed"` (default) — top-right floating button - `"inline"` — same button, no fixed positioning (host places via CSS / wrapper) - `false` — hide; use `renderConnectButton`, `openConnect`, or `openAccount` |
84
+ | `renderConnectButton` | `(context: FluentWidgetConnectButtonRenderContext) => ReactNode` | yes | no | Replace the default connect button UI / placement entirely. |
85
+ | `renderHome` | `(context: FluentWidgetRenderContext) => ReactNode` | yes | no | |
86
+ | `renderPage` | `(context: FluentWidgetRenderContext) => ReactNode` | yes | no | |
87
+ | `tokens` | `readonly FluentTokenDefinition[]` | yes | no | Integrator tokens the widget lists beside its Default tokens; see `FluentTokenDefinition`. |
88
+ | `debugLogging` | `boolean` | yes | no | Print the widget's internal connect / smart-account / signing diagnostics to the console, and show the debug panel in `mode="home"`. Off by default; turn on only while debugging an integration. |
89
+ | `onSessionChange` | `(session: FluentWidgetSession \| null) => void` | yes | no | Called each time the widget writes its stored session: with the new `FluentWidgetSession` when a Fluent ID signs in by Direct login, and with `null` on a disconnect through the widget. It is not called for a session restored from storage on mount, nor when an External wallet connects; read the render context's `session` and `widget.account` for those. |
90
+
91
+ ### `FluentWidgetRenderContext`
92
+
93
+ *type*
94
+
95
+ What the widget hands an App's own content: the Widget session, the Widget API, the External
96
+ wallet, and the calls that open the widget's screens, disconnect, mint an Auth token and link
97
+ X. `renderHome` and `renderPage` receive it, and `useFluentWidget()` returns it.
98
+
99
+ ```ts declaration
100
+ export type FluentWidgetRenderContext = {
101
+ session: FluentWidgetSession | null;
102
+ userAvatarUrl?: string;
103
+ userXDisplayName?: string;
104
+ userGoogleName?: string;
105
+ wallet: FluentExternalWalletState | null;
106
+ widget: FluentBatchApi;
107
+ openConnect: () => void;
108
+ openAccount: () => void;
109
+ disconnect: () => Promise<void>;
110
+ hasConnectedAccount: boolean;
111
+ status: FluentWidgetStatus;
112
+ refreshBalances: () => void;
113
+ getAuthToken: () => Promise<string>;
114
+ linkX: () => Promise<FluentLinkXResult>;
115
+ };
116
+ ```
117
+
118
+ | Member | Type | Optional | Experimental | Description |
119
+ |---|---|---|---|---|
120
+ | `session` | `FluentWidgetSession \| null` | no | no | Who is signed in, or `null`: a `FluentWidgetSession`. Once `onSessionChange` has fired on this page, equal to (not the same object as) the last value it received; a session restored from storage is here before any callback. Connecting an External wallet neither writes nor clears it; read the connected account from `widget.account`. |
121
+ | `userAvatarUrl` | `string` | yes | no | The Account avatar's linked X picture; absent for an External wallet or `forceDefault`. |
122
+ | `userXDisplayName` | `string` | yes | no | The display name of the person's linked X account, the name X shows above the handle, not the handle. Absent when no X account is linked or X reports no name for it, and while an External wallet is connected without a Fluent ID. `avatar.forceDefault` does not hide it. |
123
+ | `userGoogleName` | `string` | yes | no | The name on the Google account linked to the person's Direct login. Absent when none is linked or Google reports no name for it, and while an External wallet is connected without a Fluent ID. `avatar.forceDefault` does not hide it. |
124
+ | `wallet` | `FluentExternalWalletState \| null` | no | **yes** | The External wallet as the widget sees it, a `FluentExternalWalletState` whose inline choices are `FluentWalletChoice`s, or `null`. **Experimental.** May change or be removed in a minor release: a host that brings its own wallet connection is not a 0.6.0 commitment. |
125
+ | `widget` | `FluentBatchApi` | no | no | The Widget API: the account, Batch operations, signatures and the current Gas payment. |
126
+ | `openConnect` | `() => void` | no | no | Opens the sign-in dialog, the same one the connect button opens. A click event passed to it is ignored, so it can be handed straight to `onClick`. |
127
+ | `openAccount` | `() => void` | no | no | Opens the account drawer, as the connect button does once a Widget account is connected. |
128
+ | `disconnect` | `() => Promise<void>` | no | no | Tear down the current session without going through the widget's account menu — the same teardown that menu's "Disconnect" runs. The session and the stored identity token are cleared before this resolves, so a host can await it before resetting its own state. It also asks the service to revoke the Service session, and any Service session that a `getAuthToken()` still out at the disconnect opens later, and resolves once those requests have been answered or have failed, so it can take as long as that `getAuthToken()` does. A failed revocation is not retried: the promise resolving does not prove the service ended the Service session. |
129
+ | `hasConnectedAccount` | `boolean` | no | no | Whether a Widget account, a Fluent ID or an External wallet, is connected now. `false` while a stored session is still being restored: branch on `status` to tell that apart. |
130
+ | `status` | `FluentWidgetStatus` | no | no | Connection state as a single value that is meaningful on every render — including the first, before a stored session has been reconciled. Branch on this rather than on `hasConnectedAccount` alone: `"restoring"` and `"disconnected"` both have `hasConnectedAccount === false`, and treating them alike shows a Connect button to users who are already signed in. The account's address is `widget.account.address`. |
131
+ | `refreshBalances` | `() => void` | no | no | Refetch the widget's on-chain balances. Transactions run through `widget.createBatchOp` refresh automatically; call this after a tx sent via an External wallet client (outside the widget's execution path). |
132
+ | `getAuthToken` | `() => Promise<string>` | no | no | A short-lived (5 min) Auth token, a Fluent-signed JWT for the connected person. Verify it on your backend against `<iss>/.well-known/jwks.json` (ES256), checking `iss`, `aud` (= your appId) and `exp`; `sub` is stable per person per App. Reused until `authTokenRenewalOffsetSeconds` before `exp`, then renewed; a renewal the service accepts asks the wallet for nothing. When the wallet is asked to sign: [guides/backend-auth.md](guides/backend-auth.md#renewal). External wallets: EOAs and deployed smart-contract wallets sign in; a not-yet-deployed smart account cannot (no ERC-6492). **Throws** `FluentAuthError`, its `code` one of: - `not_connected`: no Widget account is connected, or an External wallet has no client when the call has to sign the Sign-in challenge; - `login_credential_missing`: a Fluent ID's login left no credential in the page; - `origin_mismatch`: the Sign-in challenge names an origin other than the page's; - `request_failed`: the request did not reach the service, its answer carried no code or no token, or the External wallet refused to sign the Sign-in challenge; - `service_refused`: the service refused with a code this SDK does not name; - a code the service answered with: `unknown_app`, `app_not_auth_enabled`, `origin_not_allowed`, `origin_missing`, `bad_request`, `challenge_unknown`, `challenge_used`, `challenge_expired`, `app_mismatch`, `invalid_signature`, `signature_prefix_rejected`, `address_already_linked`, `invalid_login_credential`, `no_signer`, `rate_limited` or `internal`. A refused refresh credential is not among them: the call forgets it and signs in again within the same call, which can prompt the External wallet. Keep a `default` branch. |
133
+ | `linkX` | `() => Promise<FluentLinkXResult>` | no | no | Link an X account to the connected person, headless: no widget screen, no settings page, one call. Idempotent and re-enterable, because linking X needs an OAuth round trip that leaves the page. A person who already has X resolves `{ status: "linked", x }` without leaving the page. A person who has none resolves `{ status: "redirecting" }` once the navigation to X has started: the page is unloading, so nothing on it may wait for the link to finish. When the browser comes back, `useLinkX()` calls `linkX()` again on mount, and it resolves `linked`; nothing public tells a page that calls `linkX()` itself that it is a return from X. A link somebody else started in this tab, or a stale record of one, is discarded rather than resumed: the call does no work and rejects with `link_failed`; call again to start one for the signed-in person. An External wallet can be asked to sign before either result: [guides/link-x.md](guides/link-x.md) says when. **Throws** `FluentAuthError`, whose codes today are `user_rejected`, `linked_to_another_user`, `not_authenticated`, `bad_request` and `link_failed`; keep a `default` branch for any code a later release adds. |
134
+
135
+ ### `FluentWidgetConnectButtonRenderContext`
136
+
137
+ *type*
138
+
139
+ What `renderConnectButton` receives to draw its own connect button.
140
+
141
+ ```ts declaration
142
+ export type FluentWidgetConnectButtonRenderContext = {
143
+ connected: boolean;
144
+ pending: boolean;
145
+ addressLabel?: string;
146
+ userAvatarUrl?: string;
147
+ userXDisplayName?: string;
148
+ userGoogleName?: string;
149
+ onClick: () => void;
150
+ openConnect: () => void;
151
+ openAccount: () => void;
152
+ DefaultButton: () => ReactNode;
153
+ };
154
+ ```
155
+
156
+ | Member | Type | Optional | Experimental | Description |
157
+ |---|---|---|---|---|
158
+ | `connected` | `boolean` | no | no | |
159
+ | `pending` | `boolean` | no | no | True while a Fluent ID's smart account is being prepared after sign-in. |
160
+ | `addressLabel` | `string` | yes | no | |
161
+ | `userAvatarUrl` | `string` | yes | no | The Account avatar's linked X picture; absent for an External wallet or `forceDefault`. |
162
+ | `userXDisplayName` | `string` | yes | no | The person's X display name, the render context's `userXDisplayName`. |
163
+ | `userGoogleName` | `string` | yes | no | The person's Google name, the render context's `userGoogleName`. |
164
+ | `onClick` | `() => void` | no | no | |
165
+ | `openConnect` | `() => void` | no | no | |
166
+ | `openAccount` | `() => void` | no | no | |
167
+ | `DefaultButton` | `() => ReactNode` | no | no | |
168
+
169
+ ### `useFluentWidget`
170
+
171
+ *value*
172
+
173
+ Access the Fluent widget render context from any component rendered inside
174
+ `<FluentWidget>` (e.g. within `renderHome` / `renderPage`). Returns the same
175
+ object the render props receive — `session`, `widget`, `openConnect`, etc. —
176
+ so host apps no longer need to prop-drill it. The Widget API is
177
+ `useFluentWidget().widget`.
178
+
179
+ Throws if used outside `<FluentWidget>`.
180
+
181
+ **Example**
182
+
183
+ ```tsx
184
+ import { useFluentWidget } from "@fluent.xyz/connect";
185
+
186
+ const calls = [{ to: "0x000000000000000000000000000000000000dEaD", value: 1n, data: "0x" }] as const;
187
+
188
+ export function Send() {
189
+ const { widget, status } = useFluentWidget();
190
+ if (status !== "connected") return null;
191
+ return <button onClick={() => widget.createBatchOp({ calls }).execute()}>Send</button>;
192
+ }
193
+ ```
194
+
195
+ ```ts declaration
196
+ export function useFluentWidget(): FluentWidgetRenderContext { … }
197
+ ```
198
+
199
+ ### `FluentWidgetStatus`
200
+
201
+ *type*
202
+
203
+ Top-level connection state of the widget, safe to read on any render.
204
+
205
+ The distinction that matters is `"restoring"` vs `"disconnected"`: a session
206
+ restored from a previous visit is not known synchronously, so a host that
207
+ treats "not connected yet" as "no account" will render a Connect button at
208
+ users who do have a live session. Wait out `"restoring"` instead.
209
+
210
+ - `"restoring"` — a previous session may exist; nothing is decided yet.
211
+ - `"connecting"` — a sign-in the user started is in flight.
212
+ - `"connected"` — an account is available. Whether it can send transactions
213
+ *right now* is a separate question — see `widget.account.executionStatus`.
214
+ - `"disconnected"` — no account, and none is being restored or negotiated.
215
+
216
+ ```ts declaration
217
+ export type FluentWidgetStatus = "restoring" | "connecting" | "connected" | "disconnected";
218
+ ```
219
+
220
+ Literals: `connected`, `connecting`, `disconnected`, `restoring`.
221
+
222
+ ### `FluentWidgetSession`
223
+
224
+ *type*
225
+
226
+ What the widget tells an App about who is signed in: the Widget account's address and type,
227
+ and when the widget built that snapshot. Not a credential: an App proves who the person is
228
+ with an Auth token from `getAuthToken()`.
229
+
230
+ Only a Fluent ID's Direct login writes a session. Connecting an External wallet neither writes nor
231
+ clears it; read the connected account from `widget.account`.
232
+
233
+ ```ts declaration
234
+ export type FluentWidgetSession = {
235
+ account: {
236
+ address: Address;
237
+ type: FluentAccountType;
238
+ };
239
+ issuedAt: number;
240
+ };
241
+ ```
242
+
243
+ | Member | Type | Optional | Experimental | Description |
244
+ |---|---|---|---|---|
245
+ | `account` | `{ address: Address; type: FluentAccountType; }` | no | no | |
246
+ | `account.address` | `Address` | no | no | The Fluent ID's smart account address. |
247
+ | `account.type` | `FluentAccountType` | no | no | `"smart"`: today a session is only ever a Fluent ID's. `FluentAccountType` may gain values, so a `switch` over it keeps a `default` branch. |
248
+ | `issuedAt` | `number` | no | no | The local time the widget built the snapshot, in Unix seconds from the browser's clock; not a time the service attests. A session restored on a later page load keeps that time. |
249
+
250
+ ### `FluentWidgetAccount`
251
+
252
+ *type*
253
+
254
+ The Widget account as the Widget API reports it: its address and type, whether it is
255
+ connected and can send now, and what it can do.
256
+
257
+ ```ts declaration
258
+ export type FluentWidgetAccount = {
259
+ address?: Address;
260
+ connected: boolean;
261
+ executionReady: boolean;
262
+ executionStatus: FluentWidgetExecutionStatus;
263
+ executionError?: string;
264
+ type?: FluentAccountType;
265
+ capabilities: FluentAccountCapabilities;
266
+ };
267
+ ```
268
+
269
+ | Member | Type | Optional | Experimental | Description |
270
+ |---|---|---|---|---|
271
+ | `address` | `Address` | yes | no | The Widget account's address: the Fluent ID's, or the External wallet's. |
272
+ | `connected` | `boolean` | no | no | Whether a Widget account, a Fluent ID or an External wallet, is connected. |
273
+ | `executionReady` | `boolean` | no | no | Whether the Widget account can send now; `executionStatus` says why it cannot. |
274
+ | `executionStatus` | `FluentWidgetExecutionStatus` | no | no | Where sending stands, a `FluentWidgetExecutionStatus`. |
275
+ | `executionError` | `string` | yes | no | The message of the last failure to prepare the Fluent ID's account, if any: the reason an `executionStatus` of `"error"` gives. |
276
+ | `type` | `FluentAccountType` | yes | no | Active account kind, or undefined when nothing is connected. |
277
+ | `capabilities` | `FluentAccountCapabilities` | no | no | What the active account can do — lets hosts adapt UI without branching on `type`. |
278
+
279
+ ### `FluentAccountType`
280
+
281
+ *type*
282
+
283
+ How the connected account executes transactions.
284
+
285
+ ```ts declaration
286
+ export type FluentAccountType = "smart" | "eoa";
287
+ ```
288
+
289
+ Literals: `eoa`, `smart`.
290
+
291
+ ### `FluentAccountCapabilities`
292
+
293
+ *type*
294
+
295
+ What the Widget account can do, so a host adapts its UI without branching on its type.
296
+
297
+ ```ts declaration
298
+ export type FluentAccountCapabilities = {
299
+ atomicBatch: boolean;
300
+ erc20Gas: boolean;
301
+ };
302
+ ```
303
+
304
+ | Member | Type | Optional | Experimental | Description |
305
+ |---|---|---|---|---|
306
+ | `atomicBatch` | `boolean` | no | no | Multiple calls land in a single atomic transaction (smart account only). |
307
+ | `erc20Gas` | `boolean` | no | no | Gas can be paid in an ERC-20 (BLEND / USDnr) via the paymaster instead of native ETH — smart account only. This is NOT free/sponsored gas: the user still pays, just in a token. |
308
+
309
+ ### `FluentWidgetExecutionStatus`
310
+
311
+ *type*
312
+
313
+ Whether the Widget account can send now: `ready`, `disconnected`, `unavailable` (connected
314
+ but not ready yet) or `error` (see `FluentWidgetAccount.executionError`).
315
+
316
+ ```ts declaration
317
+ export type FluentWidgetExecutionStatus = "disconnected" | "ready" | "unavailable" | "error";
318
+ ```
319
+
320
+ Literals: `disconnected`, `error`, `ready`, `unavailable`.
321
+
322
+ ### `AccountAvatar`
323
+
324
+ *value*
325
+
326
+ The Account avatar: the person's linked X picture, else the host's default logo, else the
327
+ Fluent mark.
328
+
329
+ **Example**
330
+
331
+ ```tsx
332
+ import { AccountAvatar, useFluentWidget } from "@fluent.xyz/connect";
333
+
334
+ export function Avatar() {
335
+ const { userAvatarUrl } = useFluentWidget();
336
+ return <AccountAvatar userAvatarUrl={userAvatarUrl} />;
337
+ }
338
+ ```
339
+
340
+ ```ts declaration
341
+ export function AccountAvatar({ userAvatarUrl, defaultLogoUrl, className }: AccountAvatarProps) { … }
342
+ ```
343
+
344
+ ### `AccountAvatarProps`
345
+
346
+ *type*
347
+
348
+ The props of `AccountAvatar`.
349
+
350
+ ```ts declaration
351
+ export type AccountAvatarProps = {
352
+ userAvatarUrl?: string | null;
353
+ defaultLogoUrl?: string | null;
354
+ className?: string;
355
+ };
356
+ ```
357
+
358
+ | Member | Type | Optional | Experimental | Description |
359
+ |---|---|---|---|---|
360
+ | `userAvatarUrl` | `string \| null` | yes | no | The person's linked X picture, the render context's `userAvatarUrl`. Wins over `defaultLogoUrl`. |
361
+ | `defaultLogoUrl` | `string \| null` | yes | no | Host-supplied stand-in for the Fluent mark — a URL or a data URI. |
362
+ | `className` | `string` | yes | no | |
363
+
364
+ ## Config
365
+
366
+ ### `FluentWidgetConfig`
367
+
368
+ *type*
369
+
370
+ The configuration of one `<FluentWidget>`, fixed for the App's deployment.
371
+
372
+ ```ts declaration
373
+ export type FluentWidgetConfig = {
374
+ appId: string;
375
+ privyClientId: string;
376
+ clientId?: never;
377
+ partnerId?: never;
378
+ network: FluentWidgetNetwork;
379
+ appName?: string;
380
+ customOAuthRedirectUrl?: string;
381
+ enabledAuthMethods?: FluentWidgetAuthMethod[];
382
+ swapper?: {
383
+ enabled?: boolean;
384
+ integratorId?: string;
385
+ dstChainId?: string;
386
+ dstTokenAddress?: string;
387
+ };
388
+ gasPayment?: {
389
+ defaultToken?: FluentGasTokenSymbol;
390
+ sponsorship?: "auto" | "never";
391
+ ethValueByToken?: FluentGasPaymentEthRates;
392
+ };
393
+ execution?: FluentWidgetExecution;
394
+ quickSign?: {
395
+ whitelistAddresses?: readonly string[];
396
+ };
397
+ reputationEnabled?: boolean;
398
+ source?: string;
399
+ campaign?: string;
400
+ disableAnalytics?: boolean;
401
+ reconnectOnMount?: boolean;
402
+ sponsorshipUrl?: string;
403
+ authTokenRenewalOffsetSeconds?: number;
404
+ assets?: Partial<FluentWidgetAssets>;
405
+ avatar?: {
406
+ defaultLogoUrl?: string;
407
+ forceDefault?: boolean;
408
+ };
409
+ };
410
+ ```
411
+
412
+ | Member | Type | Optional | Experimental | Description |
413
+ |---|---|---|---|---|
414
+ | `appId` | `string` | no | no | The App's id (`app_<32 hex>`) — the same string the Fluent Dashboard shows and the token's `aud` carries. |
415
+ | `privyClientId` | `string` | no | **yes** | The Privy app client issued by Fluent for this App. Login configuration, not identity: it carries the allowed origins for Privy login, while `appId` is what sponsorship, auth and analytics speak. Required while login runs on Privy. **Experimental.** May change or be removed in a minor release: it exists while login runs on Privy, and goes when Fluent's own login replaces it. |
416
+ | `clientId` | `never` | yes | no | Removed in 0.2.0 — the type exists only so the error names the fix. |
417
+ | `partnerId` | `never` | yes | no | Renamed to `appId` in 0.3.0 — the type exists only so the error names the fix. |
418
+ | `network` | `FluentWidgetNetwork` | no | no | The Network the widget runs on. It picks the chain, the funds, the login app, the account project and the service, so the App names it: the widget reads no environment variable for it and has no default. |
419
+ | `appName` | `string` | yes | no | |
420
+ | `customOAuthRedirectUrl` | `string` | yes | **yes** | An HTTPS URL passed to the provider behind Direct login as its OAuth redirect URL. When to use it: [experimental.md](experimental.md#customoauthredirecturl). **Experimental.** May change or be removed in a minor release: it configures the redirect of the login provider the widget runs on today. |
421
+ | `enabledAuthMethods` | `FluentWidgetAuthMethod[]` | yes | no | Sign-in methods the sign-in dialog offers beside X, in the order given. Defaults to `["google", "email", "passkey"]` — all of them; name a shorter set to drop the rest, or `[]` to leave X as the only Fluent method. Sign-in with X is always offered and is not a value here. A method still has to be enabled for the App by Fluent — listing it here only decides whether its button is drawn. |
422
+ | `swapper` | `{ enabled?: boolean; integratorId?: string; dstChainId?: string; dstTokenAddress?: string; }` | yes | **yes** | The swap entry in the account drawer. **Experimental.** May change or be removed in a minor release while the defaults are measured; the defaults are the recommended setting. |
423
+ | `swapper.enabled` | `boolean` | yes | no | |
424
+ | `swapper.integratorId` | `string` | yes | no | |
425
+ | `swapper.dstChainId` | `string` | yes | no | |
426
+ | `swapper.dstTokenAddress` | `string` | yes | no | |
427
+ | `gasPayment` | `{ defaultToken?: FluentGasTokenSymbol; sponsorship?: "auto" \| "never"; ethValueByToken?: FluentGasPaymentEthRates; }` | yes | no | |
428
+ | `gasPayment.defaultToken` | `FluentGasTokenSymbol` | yes | no | Initial/fallback token. Defaults to ETH; a valid saved user choice wins. |
429
+ | `gasPayment.sponsorship` | `"auto" \| "never"` | yes | no | Native-gas sponsorship policy. Defaults to `auto`; `never` skips the paymaster. |
430
+ | `gasPayment.ethValueByToken` | `FluentGasPaymentEthRates` | yes | **yes** | What one unit of each Gas token is worth in ETH, a `FluentGasPaymentEthRates` keyed by `FluentGasTokenSymbol`, for the cost the widget shows beside each Gas token. **Experimental.** May change or be removed in a minor release while the defaults are measured; the defaults are the recommended setting. |
431
+ | `execution` | `FluentWidgetExecution` | yes | **yes** | How a Fluent ID's send is executed: a `FluentWidgetExecution`, each of whose sources is a `FluentWidgetExecutionSource`. Every field defaults to the fast path, which falls back to the bundler on its own: set a field to switch that one answer to the bundler for good. **Experimental.** May change or be removed in a minor release while the defaults are measured; the defaults are the recommended setting. |
432
+ | `quickSign` | `{ whitelistAddresses?: readonly string[]; }` | yes | no | |
433
+ | `quickSign.whitelistAddresses` | `readonly string[]` | yes | no | Call targets Quick sign may execute without the Review. With a list set, a Batch operation runs in Silent mode only when every call's `to` is on it; a single call to any other address shows the Review, even with Quick sign on. An empty list is honoured and stops Quick sign from silencing anything; omit the option to keep it covering every address. Compared case-insensitively. `signMessage` / `signTypedData` have no call target and are not scoped by this. |
434
+ | `reputationEnabled` | `boolean` | yes | no | `false` drops the Reputation tab from the account drawer — and with it the whole tab strip, since Home is then the only tab. The families request is never made. Default `true`. |
435
+ | `source` | `string` | yes | no | |
436
+ | `campaign` | `string` | yes | no | |
437
+ | `disableAnalytics` | `boolean` | yes | no | Turns off all analytics: PostHog is never initialised, nothing is sent or stored. |
438
+ | `reconnectOnMount` | `boolean` | yes | no | Restore injected wallets and WalletConnect by default; true restores all, false restores none. |
439
+ | `sponsorshipUrl` | `string` | yes | **yes** | Point the widget at a sponsorship service other than the network default. Local development only: the deployed URL is the one every real integration should use. **Experimental.** May change or be removed in a minor release while the defaults are measured; the defaults are the recommended setting. |
440
+ | `authTokenRenewalOffsetSeconds` | `number` | yes | no | `getAuthToken()` reuses a token until this many seconds before its `exp`, then fetches a fresh one (the renewal-offset pattern: MSAL's `tokenRenewalOffsetSeconds`, Go oauth2's `expiryDelta`). Default 30. Set 0 to drop the margin entirely: a token is then reused until `exp` itself, which is not the same as always fetching — it is the case the margin exists for, a token handed out a moment before it expires and rejected by the backend it is sent to. |
441
+ | `assets` | `Partial<FluentWidgetAssets>` | yes | no | Images for the widget; see `FluentWidgetAssets`. |
442
+ | `avatar` | `{ defaultLogoUrl?: string; forceDefault?: boolean; }` | yes | no | The account avatar shown on the connect button and in the account drawer. |
443
+ | `avatar.defaultLogoUrl` | `string` | yes | no | Image used when there is no X avatar to show — a URL or a data URI. Defaults to the Fluent mark. |
444
+ | `avatar.forceDefault` | `boolean` | yes | no | Always show `defaultLogoUrl`, even for users who signed in with X. Default `false` (the linked X picture wins when the person has one). |
445
+
446
+ ### `FluentWidgetNetwork`
447
+
448
+ *type*
449
+
450
+ Which of Fluent's two deployments the widget runs on.
451
+
452
+ ```ts declaration
453
+ export type FluentWidgetNetwork = "testnet" | "mainnet";
454
+ ```
455
+
456
+ Literals: `mainnet`, `testnet`.
457
+
458
+ ### `FluentWidgetAuthMethod`
459
+
460
+ *type*
461
+
462
+ A sign-in method the sign-in dialog can offer beside X. X is not on this list:
463
+ it is always offered and cannot be switched off.
464
+
465
+ ```ts declaration
466
+ export type FluentWidgetAuthMethod = "google" | "email" | "passkey";
467
+ ```
468
+
469
+ Literals: `email`, `google`, `passkey`.
470
+
471
+ ### `FluentWidgetAssets`
472
+
473
+ *type*
474
+
475
+ Images for the widget, each a URL or a data URI. Today the widget reads only `fluentLogo`,
476
+ which it passes to the provider behind Direct login as its logo; see `assets` in
477
+ [configuration.md](configuration.md).
478
+
479
+ ```ts declaration
480
+ export type FluentWidgetAssets = {
481
+ fluentLogo: string;
482
+ walletConnectIcon: string;
483
+ metamaskIcon: string;
484
+ coinbaseIcon: string;
485
+ };
486
+ ```
487
+
488
+ | Member | Type | Optional | Experimental | Description |
489
+ |---|---|---|---|---|
490
+ | `fluentLogo` | `string` | no | no | The Fluent mark. |
491
+ | `walletConnectIcon` | `string` | no | no | The WalletConnect icon. |
492
+ | `metamaskIcon` | `string` | no | no | The MetaMask icon. |
493
+ | `coinbaseIcon` | `string` | no | no | The Coinbase Wallet icon. |
494
+
495
+ ## Batch operations
496
+
497
+ ### `FluentBatchApi`
498
+
499
+ *type*
500
+
501
+ The Widget API: what the widget gives an App's code to act for the Widget account. Reached as
502
+ `widget` in the render context or from `useFluentWidget()`.
503
+
504
+ ```ts declaration
505
+ export type FluentBatchApi = FluentSignApi & {
506
+ account: FluentWidgetAccount;
507
+ signingMode: FluentSigningMode;
508
+ gasPayment: FluentWidgetGasPayment;
509
+ createBatchOp: (input: FluentBatchOperationInput) => FluentBatchOperation;
510
+ };
511
+ ```
512
+
513
+ | Member | Type | Optional | Experimental | Description |
514
+ |---|---|---|---|---|
515
+ | `signMessage` | `(params: { message: SignableMessage }) => Promise<Hex>` | no | no | EIP-191 signature. ERC-1271 (ERC-6492 before deployment) for a smart account, ECDSA for an External wallet. **Throws** `FluentReviewRejectedError` with `code` `signature_review_rejected` when the person dismisses the Review: always shown for an External wallet, and for a Fluent ID unless Quick sign is on. An External wallet's refusal in its own prompt rejects with the wallet's error. **Throws** `FluentAuthError` with `code` `not_connected` when no Widget account is connected or the External wallet has no client, and `root_signer_required` when neither of the Fluent ID's signing paths signs with its root Signer, a guard no configuration reaches today. (example below) |
516
+ | `signTypedData` | `< const typedData extends TypedData \| Record<string, unknown>, primaryType extends keyof typedData \| "EIP712Domain" = keyof typedData, >( typedData: TypedDataDefinition<typedData, primaryType>, ) => Promise<Hex>` | no | no | EIP-712 signature. ERC-1271 (ERC-6492 before deployment) for a smart account, ECDSA for an External wallet. **Throws** `FluentReviewRejectedError` with `code` `signature_review_rejected` when the person dismisses the Review, as for `signMessage`. **Throws** `FluentAuthError` with `code` `not_connected` or `root_signer_required`, as for `signMessage`. (example below) |
517
+ | `account` | `FluentWidgetAccount` | no | no | The Widget account: its address, type, readiness and capabilities. |
518
+ | `signingMode` | `FluentSigningMode` | no | no | How the widget signs by default: `"silent"` while the person's Quick sign is on. |
519
+ | `gasPayment` | `FluentWidgetGasPayment` | no | no | The Gas payment chosen in the widget, which `execute()` uses when given no `gasPayment`. |
520
+ | `createBatchOp` | `(input: FluentBatchOperationInput) => FluentBatchOperation` | no | no | Builds a Batch operation, encoding its calls now; `execute()` sends it. **Throws** `Error` when `calls` is empty, or when a call has neither `data` nor `abi` with `method`: a call that still names its function in 0.5's `functionName` is one. |
521
+
522
+ **`signMessage` example**
523
+
524
+ ```ts
525
+ import { useFluentWidget } from "@fluent.xyz/connect";
526
+
527
+ export function useSignGreeting() {
528
+ const { widget } = useFluentWidget();
529
+ return () => widget.signMessage({ message: "Sign in to Marketplace" });
530
+ }
531
+ ```
532
+
533
+ **`signTypedData` example**
534
+
535
+ ```ts
536
+ import { useFluentWidget } from "@fluent.xyz/connect";
537
+
538
+ const verifyingContract = "0x0000000000000000000000000000000000000001";
539
+ const order = { maker: "0x0000000000000000000000000000000000000002", price: 100n } as const;
540
+
541
+ export function useSignOrder() {
542
+ const { widget } = useFluentWidget();
543
+ return () =>
544
+ widget.signTypedData({
545
+ domain: { name: "Marketplace", version: "1", chainId: 20994, verifyingContract },
546
+ types: {
547
+ Order: [
548
+ { name: "maker", type: "address" },
549
+ { name: "price", type: "uint256" },
550
+ ],
551
+ },
552
+ primaryType: "Order",
553
+ message: order,
554
+ });
555
+ }
556
+ ```
557
+
558
+ ### `FluentBatchOperationInput`
559
+
560
+ *type*
561
+
562
+ What `widget.createBatchOp` takes: the calls of one Batch operation, and its Review title.
563
+
564
+ ```ts declaration
565
+ export type FluentBatchOperationInput = {
566
+ id?: string;
567
+ reviewTitle?: string;
568
+ calls: readonly FluentBatchCallInput[];
569
+ };
570
+ ```
571
+
572
+ | Member | Type | Optional | Experimental | Description |
573
+ |---|---|---|---|---|
574
+ | `id` | `string` | yes | no | |
575
+ | `reviewTitle` | `string` | yes | no | Heading of this Batch operation's Review (Fluent ID, Prompt mode). Defaults to the widget's own copy, "Confirm transaction". |
576
+ | `calls` | `readonly FluentBatchCallInput[]` | no | no | |
577
+
578
+ ### `FluentBatchCallInput`
579
+
580
+ *type*
581
+
582
+ One contract call of a Batch operation: either raw `data`, or an `abi` with the `method` to
583
+ encode and its `args`.
584
+
585
+ ```ts declaration
586
+ export type FluentBatchCallInput = {
587
+ id?: string;
588
+ label?: string;
589
+ to: Address;
590
+ value?: bigint;
591
+ data?: Hex;
592
+ abi?: Abi;
593
+ method?: string;
594
+ args?: readonly unknown[];
595
+ };
596
+ ```
597
+
598
+ | Member | Type | Optional | Experimental | Description |
599
+ |---|---|---|---|---|
600
+ | `id` | `string` | yes | no | |
601
+ | `label` | `string` | yes | no | |
602
+ | `to` | `Address` | no | no | |
603
+ | `value` | `bigint` | yes | no | Native ETH sent with the call, in wei. Defaults to `0n`. |
604
+ | `data` | `Hex` | yes | no | |
605
+ | `abi` | `Abi` | yes | no | |
606
+ | `method` | `string` | yes | no | The ABI function to encode, with `abi` and `args`, when `data` is not given. |
607
+ | `args` | `readonly unknown[]` | yes | no | |
608
+
609
+ ### `FluentBatchOperation`
610
+
611
+ *type*
612
+
613
+ A Batch operation `widget.createBatchOp` built: its calls, encoded, and `execute`, which sends
614
+ them for the Widget account.
615
+
616
+ ```ts declaration
617
+ export type FluentBatchOperation = {
618
+ id?: string;
619
+ reviewTitle?: string;
620
+ calls: readonly FluentBatchCallInput[];
621
+ encodedCalls: FluentEncodedBatchCall[];
622
+ canExecute: boolean;
623
+ execute: (options?: FluentBatchOperationExecuteOptions) => Promise<FluentExecuteResult>;
624
+ };
625
+ ```
626
+
627
+ | Member | Type | Optional | Experimental | Description |
628
+ |---|---|---|---|---|
629
+ | `id` | `string` | yes | no | `FluentBatchOperationInput.id`, copied. |
630
+ | `reviewTitle` | `string` | yes | no | `FluentBatchOperationInput.reviewTitle`, copied. |
631
+ | `calls` | `readonly FluentBatchCallInput[]` | no | no | The calls as the host passed them. |
632
+ | `encodedCalls` | `FluentEncodedBatchCall[]` | no | no | The same calls encoded, in order: what `execute()` sends. |
633
+ | `canExecute` | `boolean` | no | no | Whether the widget could send the operation when it was built: the Widget account ready, or able to prepare itself when `execute()` is called. Not updated afterwards; read `widget.account.executionReady` for the live value. |
634
+ | `execute` | `(options?: FluentBatchOperationExecuteOptions) => Promise<FluentExecuteResult>` | no | no | Executes the operation for the Widget account and resolves once it is included. **Throws** `FluentReviewRejectedError` with `code` `transaction_review_rejected` when the person dismisses the Review, which a Fluent ID shows in Prompt mode; an External wallet's refusal in its own prompt rejects with the wallet's error. **Throws** `FluentSponsorshipFallbackError` when a Fluent ID asked for Sponsorship, a sponsored submission failed, and the submission in which the account pays its own gas failed too; its `code` says why Sponsorship failed: `denied`, `unauthorized`, `unreachable` or `no_token`. A failure while waiting for an operation's inclusion is not wrapped: it rejects with its own error, and an operation whose wait failed was submitted. What else is not wrapped: [guides/sponsorship.md](guides/sponsorship.md#both-failed-fluentsponsorshipfallbackerror). **Throws** `FluentUserOperationGasError` (experimental) with `code` `invalid_policy` for a `skipEstimation` policy that cannot be used (other invalid `userOperationGas` values throw a plain `Error`), and `paymaster_gas_mismatch` when, with estimation skipped, the paymaster's authorization of a Gas token payment does not match the fixed gas limits. Under Sponsorship, a failed check of the paymaster's gas fails the sponsored submission instead, and the account pays its own gas. |
635
+
636
+ ### `FluentBatchOperationExecuteOptions`
637
+
638
+ *type*
639
+
640
+ The options of `FluentBatchOperation.execute`, every one optional.
641
+
642
+ ```ts declaration
643
+ export type FluentBatchOperationExecuteOptions = {
644
+ confirmation?: FluentSigningMode;
645
+ gasPayment?: FluentGasPayment;
646
+ userOperationGas?: FluentUserOperationGas;
647
+ };
648
+ ```
649
+
650
+ | Member | Type | Optional | Experimental | Description |
651
+ |---|---|---|---|---|
652
+ | `confirmation` | `FluentSigningMode` | yes | no | The `FluentSigningMode` of this operation. Defaults to the widget's `signingMode`, which follows the person's Quick sign. A `"silent"` operation with a call outside `quickSign.whitelistAddresses` is signed as `"prompt"`. Any value but `"silent"`, 0.5's `"always"` and `"session"` included, is `"prompt"`. Ignored for an External wallet. |
653
+ | `gasPayment` | `FluentGasPayment` | yes | no | How the gas of this operation is paid. Defaults to the Gas payment chosen in the widget. |
654
+ | `userOperationGas` | `FluentUserOperationGas` | yes | **yes** | Fluent ID gas limits, estimation opt-out or headroom: a `FluentUserOperationGas`, whose fixed limits are a `FluentFixedAccountGas` and a `FluentFixedPaymasterGas`. Ignored for External wallet sends. **Experimental.** May change or be removed in a minor release while the gas policy is measured; omitting it, which lets the widget estimate, is the recommended setting. |
655
+
656
+ ### `FluentEncodedBatchCall`
657
+
658
+ *type*
659
+
660
+ A Batch operation's call as it is sent: `data` encoded, `value` defaulted to `0n`.
661
+
662
+ ```ts declaration
663
+ export type FluentEncodedBatchCall = {
664
+ id?: string;
665
+ label?: string;
666
+ to: Address;
667
+ value: bigint;
668
+ data: Hex;
669
+ };
670
+ ```
671
+
672
+ | Member | Type | Optional | Experimental | Description |
673
+ |---|---|---|---|---|
674
+ | `id` | `string` | yes | no | |
675
+ | `label` | `string` | yes | no | |
676
+ | `to` | `Address` | no | no | |
677
+ | `value` | `bigint` | no | no | |
678
+ | `data` | `Hex` | no | no | |
679
+
680
+ ### `FluentExecuteResult`
681
+
682
+ *type*
683
+
684
+ Result of executing a batch operation.
685
+
686
+ ```ts declaration
687
+ export type FluentExecuteResult = {
688
+ hash: Hash;
689
+ hashes: Hash[];
690
+ receipt?: TransactionReceipt;
691
+ userOpHash?: Hash;
692
+ atomic: boolean;
693
+ sponsored: boolean | null;
694
+ paymaster?: Address;
695
+ timing?: FluentExecuteTiming;
696
+ };
697
+ ```
698
+
699
+ | Member | Type | Optional | Experimental | Description |
700
+ |---|---|---|---|---|
701
+ | `hash` | `Hash` | no | no | Primary transaction hash — the final/target call (e.g. deposit/withdraw). |
702
+ | `hashes` | `Hash[]` | no | no | All transaction hashes in order. One for a smart-account UserOp; one per call for an EOA. |
703
+ | `receipt` | `TransactionReceipt` | yes | no | Included receipt for hash (the final EOA call); not a finality guarantee. |
704
+ | `userOpHash` | `Hash` | yes | no | ERC-4337 operation hash when executing through a smart account. |
705
+ | `atomic` | `boolean` | no | no | True when all calls landed atomically (smart account), false for sequential EOA txs. |
706
+ | `sponsored` | `boolean \| null` | no | no | Whether the App's Sponsorship paid the gas for this operation, read back off the settled operation (which contract the EntryPoint charged) first: a refused Sponsorship falls back to the account paying its own gas, so a flag set from asking for Sponsorship would report the fallback as a success. `false` for a Gas token payment and always for an External wallet, which has no paymaster. When a Fluent ID's receipt names no paymaster, the way the operation was sent decides: `false` when it made no sponsored submission (the fallback, `sponsorship: "never"`, Sponsorship unavailable or not configured), and `null` after a sponsored submission, where nothing says who paid. |
707
+ | `paymaster` | `Address` | yes | **yes** | The paymaster a Fluent ID's receipt names: the Sponsorship paymaster or a Gas token's paymaster, when one paid. Undefined when the receipt carried no paymaster — `sponsored` is then `false`, or `null` after a sponsored submission — and always for an External wallet, which has no paymaster. **Experimental.** May change or be removed in a minor release while the numbers are measured. |
708
+ | `timing` | `FluentExecuteTiming` | yes | **yes** | Where this send's milliseconds went, as a `FluentExecuteTiming` whose raw instants are a `FluentExecuteTimingInstants`. Fluent ID only: an External wallet performs its prompt, its signing and its broadcast behind one `sendTransaction` await, so EIP-1193 exposes no truthful instant to put a boundary on. **Experimental.** May change or be removed in a minor release while the numbers are measured. |
709
+
710
+ ### `FluentGasPayment`
711
+
712
+ *type*
713
+
714
+ How one operation's gas is paid: a Gas token by symbol, or native ETH, and whether
715
+ Sponsorship is asked for.
716
+
717
+ ```ts declaration
718
+ export type FluentGasPayment = {
719
+ /**
720
+ * Gas token symbol. The widget resolves the ERC-20 address for the active
721
+ * network internally — callers never pass (or risk mistyping) an address.
722
+ * `"ETH"` means native gas (no ERC-20 paymaster).
723
+ */
724
+ symbol: FluentGasTokenSymbol;
725
+ /**
726
+ * Whether to ask the App's sponsorship paymaster to pay for this operation.
727
+ *
728
+ * `"auto"` tries Sponsorship, and if the paymaster refuses, resends with the account paying
729
+ * its own gas. `"never"` skips the paymaster outright, so the account pays from the first
730
+ * attempt and the result reports `sponsored: false`. What an omitted value means:
731
+ * [guides/sponsorship.md](guides/sponsorship.md#not-asking-sponsorship-never-and-gas-tokens).
732
+ *
733
+ * Ignored when `symbol` names an ERC-20: that token's own paymaster pays,
734
+ * and sponsorship is not in the picture.
735
+ */
736
+ sponsorship?: "auto" | "never";
737
+ } & (
738
+ | {
739
+ includeApproval: true;
740
+ approveAmount: bigint;
741
+ }
742
+ | {
743
+ includeApproval?: false;
744
+ approveAmount?: never;
745
+ }
746
+ );
747
+ ```
748
+
749
+ ### `FluentWidgetGasPayment`
750
+
751
+ *type*
752
+
753
+ The Gas payment chosen in the widget: the Gas token's symbol, its address and decimals.
754
+
755
+ ```ts declaration
756
+ export type FluentWidgetGasPayment = {
757
+ symbol: FluentGasTokenSymbol;
758
+ token?: Address;
759
+ decimals: number;
760
+ };
761
+ ```
762
+
763
+ | Member | Type | Optional | Experimental | Description |
764
+ |---|---|---|---|---|
765
+ | `symbol` | `FluentGasTokenSymbol` | no | no | |
766
+ | `token` | `Address` | yes | no | |
767
+ | `decimals` | `number` | no | no | |
768
+
769
+ ### `FluentGasTokenSymbol`
770
+
771
+ *type*
772
+
773
+ A symbol that can pay for gas. Deliberately `string`: which tokens are
774
+ payable is data on the token definitions now, not a fixed set of literals.
775
+
776
+ ```ts declaration
777
+ export type FluentGasTokenSymbol = string;
778
+ ```
779
+
780
+ ## Signing
781
+
782
+ ### `FluentSignApi`
783
+
784
+ *type*
785
+
786
+ The signatures of the Widget API, for the Widget account. A Fluent ID shows the Review in
787
+ Prompt mode and none in Silent mode; an External wallet always shows the Review, then its own
788
+ prompt.
789
+
790
+ ```ts declaration
791
+ export type FluentSignApi = {
792
+ signMessage: (params: { message: SignableMessage }) => Promise<Hex>;
793
+ signTypedData: <
794
+ const typedData extends TypedData | Record<string, unknown>,
795
+ primaryType extends keyof typedData | "EIP712Domain" = keyof typedData,
796
+ >(
797
+ typedData: TypedDataDefinition<typedData, primaryType>,
798
+ ) => Promise<Hex>;
799
+ };
800
+ ```
801
+
802
+ | Member | Type | Optional | Experimental | Description |
803
+ |---|---|---|---|---|
804
+ | `signMessage` | `(params: { message: SignableMessage }) => Promise<Hex>` | no | no | EIP-191 signature. ERC-1271 (ERC-6492 before deployment) for a smart account, ECDSA for an External wallet. **Throws** `FluentReviewRejectedError` with `code` `signature_review_rejected` when the person dismisses the Review: always shown for an External wallet, and for a Fluent ID unless Quick sign is on. An External wallet's refusal in its own prompt rejects with the wallet's error. **Throws** `FluentAuthError` with `code` `not_connected` when no Widget account is connected or the External wallet has no client, and `root_signer_required` when neither of the Fluent ID's signing paths signs with its root Signer, a guard no configuration reaches today. (example below) |
805
+ | `signTypedData` | `< const typedData extends TypedData \| Record<string, unknown>, primaryType extends keyof typedData \| "EIP712Domain" = keyof typedData, >( typedData: TypedDataDefinition<typedData, primaryType>, ) => Promise<Hex>` | no | no | EIP-712 signature. ERC-1271 (ERC-6492 before deployment) for a smart account, ECDSA for an External wallet. **Throws** `FluentReviewRejectedError` with `code` `signature_review_rejected` when the person dismisses the Review, as for `signMessage`. **Throws** `FluentAuthError` with `code` `not_connected` or `root_signer_required`, as for `signMessage`. (example below) |
806
+
807
+ **`signMessage` example**
808
+
809
+ ```ts
810
+ import { useFluentWidget } from "@fluent.xyz/connect";
811
+
812
+ export function useSignGreeting() {
813
+ const { widget } = useFluentWidget();
814
+ return () => widget.signMessage({ message: "Sign in to Marketplace" });
815
+ }
816
+ ```
817
+
818
+ **`signTypedData` example**
819
+
820
+ ```ts
821
+ import { useFluentWidget } from "@fluent.xyz/connect";
822
+
823
+ const verifyingContract = "0x0000000000000000000000000000000000000001";
824
+ const order = { maker: "0x0000000000000000000000000000000000000002", price: 100n } as const;
825
+
826
+ export function useSignOrder() {
827
+ const { widget } = useFluentWidget();
828
+ return () =>
829
+ widget.signTypedData({
830
+ domain: { name: "Marketplace", version: "1", chainId: 20994, verifyingContract },
831
+ types: {
832
+ Order: [
833
+ { name: "maker", type: "address" },
834
+ { name: "price", type: "uint256" },
835
+ ],
836
+ },
837
+ primaryType: "Order",
838
+ message: order,
839
+ });
840
+ }
841
+ ```
842
+
843
+ ### `FluentSigningMode`
844
+
845
+ *type*
846
+
847
+ How a Fluent ID signs: `"prompt"` shows the widget's Review first (Prompt mode), `"silent"`
848
+ signs with none (Silent mode), except that where the App set `quickSign.whitelistAddresses`, a
849
+ Batch operation with a call outside it is signed as `"prompt"`. An External wallet always
850
+ shows its own prompt.
851
+
852
+ ```ts declaration
853
+ export type FluentSigningMode = "prompt" | "silent";
854
+ ```
855
+
856
+ Literals: `prompt`, `silent`.
857
+
858
+ ## Auth and errors
859
+
860
+ ### `FluentAuthError`
861
+
862
+ *value*
863
+
864
+ A refused Auth token or X link. `code` is a `FluentAuthErrorCode`; `status` is the service's
865
+ HTTP status when the service refused it.
866
+
867
+ ```ts declaration
868
+ export class FluentAuthError extends Error {
869
+ constructor(
870
+ readonly code: FluentAuthErrorCode,
871
+ message: string,
872
+ readonly status?: number,
873
+ ) { … }
874
+ }
875
+ ```
876
+
877
+ | Member | Type | Optional | Experimental | Description |
878
+ |---|---|---|---|---|
879
+ | `code` | `FluentAuthErrorCode` | no | no | |
880
+ | `status` | `number` | yes | no | |
881
+
882
+ ### `FluentAuthErrorCode`
883
+
884
+ *type*
885
+
886
+ Why `getAuthToken()`, `linkX()`, or `widget.signMessage()` / `widget.signTypedData()` was
887
+ refused (the signatures throw `not_connected` and `root_signer_required`). The codes are the
888
+ SDK's own, named for the product rather than for a vendor or a mechanism: where the service
889
+ answers with a code of its own, the SDK maps it here before it reaches the App, and a service
890
+ code the SDK does not name reaches `getAuthToken()` as `service_refused` and `linkX()` as
891
+ `link_failed`. Keep a `default` branch in a
892
+ `switch` over them: a later release may add a code.
893
+
894
+ ```ts declaration
895
+ export type FluentAuthErrorCode =
896
+ // the service's codes, as the SDK names them
897
+ | "unknown_app"
898
+ | "app_not_auth_enabled"
899
+ | "origin_not_allowed"
900
+ | "origin_missing"
901
+ | "bad_request"
902
+ | "challenge_unknown"
903
+ | "challenge_used"
904
+ | "challenge_expired"
905
+ | "app_mismatch"
906
+ | "invalid_signature"
907
+ | "signature_prefix_rejected"
908
+ | "address_already_linked"
909
+ | "invalid_login_credential"
910
+ | "no_signer"
911
+ | "invalid_refresh_token"
912
+ | "refresh_token_reused"
913
+ | "rate_limited"
914
+ | "internal"
915
+ // client-side
916
+ | "not_connected"
917
+ | "root_signer_required"
918
+ | "login_credential_missing"
919
+ | "origin_mismatch"
920
+ | "request_failed"
921
+ // the service refused with a code this SDK does not name; the message carries that code
922
+ | "service_refused"
923
+ // client-side, linking an X account (`linkX()`)
924
+ | "not_authenticated"
925
+ | "user_rejected"
926
+ | "linked_to_another_user"
927
+ | "link_failed";
928
+ ```
929
+
930
+ Literals: `address_already_linked`, `app_mismatch`, `app_not_auth_enabled`, `bad_request`, `challenge_expired`, `challenge_unknown`, `challenge_used`, `internal`, `invalid_login_credential`, `invalid_refresh_token`, `invalid_signature`, `link_failed`, `linked_to_another_user`, `login_credential_missing`, `no_signer`, `not_authenticated`, `not_connected`, `origin_mismatch`, `origin_missing`, `origin_not_allowed`, `rate_limited`, `refresh_token_reused`, `request_failed`, `root_signer_required`, `service_refused`, `signature_prefix_rejected`, `unknown_app`, `user_rejected`.
931
+
932
+ ### `FluentWidgetConfigError`
933
+
934
+ *value*
935
+
936
+ A value in `FluentWidgetConfig` the widget refuses to start with.
937
+
938
+ Thrown when `<FluentWidget>` renders with a config it has not resolved yet: on its first
939
+ render, and again on any render that passes a new `config` object. So it surfaces at startup
940
+ where the integrator is looking rather than at the first send. The message names the option and
941
+ how to fix it; `code`, a `FluentWidgetConfigErrorCode`, is what to branch on.
942
+
943
+ **Example**
944
+
945
+ ```tsx
946
+ import { FluentWidgetConfigError } from "@fluent.xyz/connect";
947
+
948
+ export function WidgetBoundaryFallback({ error }: { error: unknown }) {
949
+ // More than one option is required, and the message names the one that is missing.
950
+ if (error instanceof FluentWidgetConfigError && error.code === "missing_option") {
951
+ return <p>The widget config is missing a required option: {error.message}</p>;
952
+ }
953
+ throw error;
954
+ }
955
+ ```
956
+
957
+ ```ts declaration
958
+ export class FluentWidgetConfigError extends Error {
959
+ readonly code: FluentWidgetConfigErrorCode;
960
+
961
+ constructor(code: FluentWidgetConfigErrorCode, message: string) { … }
962
+ }
963
+ ```
964
+
965
+ | Member | Type | Optional | Experimental | Description |
966
+ |---|---|---|---|---|
967
+ | `code` | `FluentWidgetConfigErrorCode` | no | no | |
968
+
969
+ ### `FluentWidgetConfigErrorCode`
970
+
971
+ *type*
972
+
973
+ Which value in `FluentWidgetConfig` was refused, for a host that branches rather than reads
974
+ the message.
975
+
976
+ ```ts declaration
977
+ export type FluentWidgetConfigErrorCode =
978
+ | "invalid_fee_source"
979
+ | "invalid_receipt_source"
980
+ | "invalid_chain_check_before_sign"
981
+ /** A required option is absent or empty. */
982
+ | "missing_option"
983
+ /** An option holds a value the widget cannot use. */
984
+ | "invalid_option"
985
+ /** An option an earlier release removed or renamed is still passed. */
986
+ | "removed_option";
987
+ ```
988
+
989
+ Literals: `invalid_chain_check_before_sign`, `invalid_fee_source`, `invalid_option`, `invalid_receipt_source`, `missing_option`, `removed_option`.
990
+
991
+ ### `FluentReviewRejectedError`
992
+
993
+ *value*
994
+
995
+ The person dismissed a Review (transaction or signature) instead of confirming it.
996
+
997
+ A class with a `code`, not a message, so a host branches on `code` and callers that translate
998
+ errors for another party — the iframe bridge maps it to EIP-1193 `4001` — recognise it
999
+ without parsing prose.
1000
+
1001
+ **Example**
1002
+
1003
+ ```ts
1004
+ import { FluentReviewRejectedError, type FluentBatchApi } from "@fluent.xyz/connect";
1005
+
1006
+ const calls = [{ to: "0x000000000000000000000000000000000000dEaD", value: 1n, data: "0x" }] as const;
1007
+
1008
+ export async function send(widget: FluentBatchApi) {
1009
+ try {
1010
+ await widget.createBatchOp({ calls }).execute();
1011
+ } catch (error) {
1012
+ if (error instanceof FluentReviewRejectedError) return; // the person said no
1013
+ throw error;
1014
+ }
1015
+ }
1016
+ ```
1017
+
1018
+ ```ts declaration
1019
+ export class FluentReviewRejectedError extends Error {
1020
+ readonly code: FluentReviewRejectedErrorCode;
1021
+
1022
+ constructor(readonly review: "transaction" | "signature") { … }
1023
+ }
1024
+ ```
1025
+
1026
+ | Member | Type | Optional | Experimental | Description |
1027
+ |---|---|---|---|---|
1028
+ | `code` | `FluentReviewRejectedErrorCode` | no | no | |
1029
+ | `review` | `"transaction" \| "signature"` | no | no | |
1030
+
1031
+ ### `FluentReviewRejectedErrorCode`
1032
+
1033
+ *type*
1034
+
1035
+ Which Review the person dismissed: a Batch operation's or a signature's.
1036
+
1037
+ ```ts declaration
1038
+ export type FluentReviewRejectedErrorCode =
1039
+ | "transaction_review_rejected"
1040
+ | "signature_review_rejected";
1041
+ ```
1042
+
1043
+ Literals: `signature_review_rejected`, `transaction_review_rejected`.
1044
+
1045
+ ### `FluentSponsorshipFallbackError`
1046
+
1047
+ *value*
1048
+
1049
+ Both the sponsored submission and the fallback, the account paying its own gas, failed.
1050
+ `code` (equal to `sponsorshipReason`) says why Sponsorship was refused: `no_token`, `denied`,
1051
+ `unauthorized` or `unreachable`, never `not_requested`. `fallbackError` is what the own-gas
1052
+ submission failed with, and `cause` the sponsored submission's error.
1053
+
1054
+ Neither is the error that was thrown. Each is a plain object `{ name, message, status? }`:
1055
+ `name` is the thrown error's name (`"Error"` for a thrown value that is not an `Error`),
1056
+ `message` the text of the innermost error along its `cause` chain that has any (an
1057
+ `AggregateError` gives the texts of its first four `errors`), and `status` the first integer
1058
+ `status` along that chain, such as an HTTP status, present only when there is one; the chain
1059
+ itself is not kept. A thrown value that cannot be read without an exception is summarized as
1060
+ `{ name: "Error", message: "[unreadable error]" }`.
1061
+
1062
+ In `message`, here and in each of the two, a balanced `{…}` or `[…]` span becomes `[body]`, a
1063
+ `scheme://` URL `[url]`, a `Bearer` token or a JWT `[token]`, a `did:` id or a UUID `[id]`, an
1064
+ email address `[email]`, and `0x` with 40 or 64 hex digits `[address]` or `[hash]`. Any other
1065
+ `0x` run of 40 or more hex digits becomes `[data 0x…]` with its first four bytes, and the
1066
+ reason of an `Error(string)` revert is decoded and redacted in the same way.
1067
+
1068
+ ```ts declaration
1069
+ export class FluentSponsorshipFallbackError extends Error {
1070
+ readonly code: FluentSponsorshipReason;
1071
+ readonly sponsorshipReason: FluentSponsorshipReason;
1072
+ readonly fallbackError: unknown;
1073
+
1074
+ constructor(params: {
1075
+ sponsorshipReason: FluentSponsorshipReason;
1076
+ sponsorshipError: unknown;
1077
+ fallbackError: unknown;
1078
+ }) { … }
1079
+ }
1080
+ ```
1081
+
1082
+ | Member | Type | Optional | Experimental | Description |
1083
+ |---|---|---|---|---|
1084
+ | `code` | `FluentSponsorshipReason` | no | no | |
1085
+ | `sponsorshipReason` | `FluentSponsorshipReason` | no | no | |
1086
+ | `fallbackError` | `unknown` | no | no | |
1087
+
1088
+ ### `FluentSponsorshipReason`
1089
+
1090
+ *type*
1091
+
1092
+ Why an operation was not sponsored, and the `code` of a `FluentSponsorshipFallbackError`.
1093
+ `not_requested` is the only one that is not a failure: the caller asked to pay its own gas,
1094
+ so the sponsorship paymaster was never contacted. For the same reason it is never the error's
1095
+ code, which is thrown only after a sponsored attempt failed: the error carries one of the
1096
+ other four.
1097
+
1098
+ ```ts declaration
1099
+ export type FluentSponsorshipReason =
1100
+ | "no_token"
1101
+ | "denied"
1102
+ | "unauthorized"
1103
+ | "unreachable"
1104
+ | "not_requested";
1105
+ ```
1106
+
1107
+ Literals: `denied`, `no_token`, `not_requested`, `unauthorized`, `unreachable`.
1108
+
1109
+ ## Link X
1110
+
1111
+ ### `useLinkX`
1112
+
1113
+ *value*
1114
+
1115
+ Linking X as a component sees it: the call, and what the last one did.
1116
+
1117
+ `redirecting` is the status a page is unlikely to render for long — it is set just before the
1118
+ browser leaves for X — and `linked` after a return is what the mount-time re-entry produces
1119
+ without the component asking for anything.
1120
+
1121
+ **Throws** From `linkX`, as the render context's `linkX()` does: a `FluentAuthError` whose `code`
1122
+ is today `not_authenticated`, `user_rejected`, `linked_to_another_user`, `bad_request` or
1123
+ `link_failed` (keep a `default` branch); the same error is kept in `error`.
1124
+
1125
+ **Example**
1126
+
1127
+ ```tsx
1128
+ import { useLinkX } from "@fluent.xyz/connect";
1129
+
1130
+ export function LinkXButton() {
1131
+ const { linkX, status, x, error } = useLinkX();
1132
+ if (x) return <span>Linked as @{x.handle}</span>;
1133
+ return (
1134
+ <button onClick={() => void linkX().catch(() => undefined)} disabled={status === "pending"}>
1135
+ {error ? `Retry (${error.code})` : "Link X"}
1136
+ </button>
1137
+ );
1138
+ }
1139
+ ```
1140
+
1141
+ ```ts declaration
1142
+ export function useLinkX(): {
1143
+ linkX: () => Promise<FluentLinkXResult>;
1144
+ status: FluentLinkXStatus;
1145
+ x: FluentXAccount | null;
1146
+ error: FluentAuthError | null;
1147
+ } { … }
1148
+ ```
1149
+
1150
+ ### `FluentLinkXStatus`
1151
+
1152
+ *type*
1153
+
1154
+ Where `useLinkX()`'s last link stands: `idle` before any, `pending` while one runs,
1155
+ `redirecting` just before the browser leaves for X, `linked` once the Linked X account is
1156
+ there, `error` when the last one was refused.
1157
+
1158
+ ```ts declaration
1159
+ export type FluentLinkXStatus = "idle" | "pending" | "redirecting" | "linked" | "error";
1160
+ ```
1161
+
1162
+ Literals: `error`, `idle`, `linked`, `pending`, `redirecting`.
1163
+
1164
+ ### `FluentLinkXResult`
1165
+
1166
+ *type*
1167
+
1168
+ What a `linkX()` resolves: `linked` with the Linked X account, or `redirecting` while the page
1169
+ leaves for X.
1170
+
1171
+ ```ts declaration
1172
+ export type FluentLinkXResult =
1173
+ | { status: "linked"; x: FluentXAccount }
1174
+ /** The page is leaving for X. Call linkX() again after the return; useLinkX() does it on mount. */
1175
+ | { status: "redirecting" };
1176
+ ```
1177
+
1178
+ ### `FluentXAccount`
1179
+
1180
+ *type*
1181
+
1182
+ One X account as the Fluent auth service reports it.
1183
+
1184
+ ```ts declaration
1185
+ export type FluentXAccount = {
1186
+ id: string;
1187
+ handle: string;
1188
+ avatarUrl: string;
1189
+ };
1190
+ ```
1191
+
1192
+ | Member | Type | Optional | Experimental | Description |
1193
+ |---|---|---|---|---|
1194
+ | `id` | `string` | no | no | |
1195
+ | `handle` | `string` | no | no | |
1196
+ | `avatarUrl` | `string` | no | no | |
1197
+
1198
+ ## Iframe
1199
+
1200
+ ### `useFluentIframeBridge`
1201
+
1202
+ *value*
1203
+
1204
+ Lets a page embedded in `iframeRef` use the account signed in here, over the
1205
+ JSON-RPC `postMessage` protocol `@ledgerhq/iframe-provider` speaks. The bridge lives
1206
+ while the component is mounted; the bridge states the chain and account before its
1207
+ first reply, and sign-in and sign-out reach the iframe as `accountsChanged`.
1208
+
1209
+ **Parameter** iframeRef The `<iframe>` the embedded page runs in; read on every message, so an
1210
+ element swapped in after mount is still answered.
1211
+
1212
+ **Parameter** options `allowedOrigin`, the one origin whose messages are answered.
1213
+
1214
+ **Throws** `Error`, from the effect that builds the bridge (so to the nearest error boundary),
1215
+ when `allowedOrigin` is not an `http:` or `https:` origin: `"*"` and a bare host are
1216
+ refused.
1217
+
1218
+ **Example**
1219
+
1220
+ ```tsx
1221
+ import { useFluentIframeBridge } from "@fluent.xyz/connect";
1222
+ import { useRef } from "react";
1223
+
1224
+ export function Marketplace() {
1225
+ const iframeRef = useRef<HTMLIFrameElement>(null);
1226
+ useFluentIframeBridge(iframeRef, { allowedOrigin: "https://market.example" });
1227
+ return <iframe ref={iframeRef} src="https://market.example/collection/cards" />;
1228
+ }
1229
+ ```
1230
+
1231
+ ```ts declaration
1232
+ export function useFluentIframeBridge(
1233
+ iframeRef: RefObject<FluentIframeElement | null>,
1234
+ { allowedOrigin }: UseFluentIframeBridgeOptions,
1235
+ ): void { … }
1236
+ ```
1237
+
1238
+ ### `UseFluentIframeBridgeOptions`
1239
+
1240
+ *type*
1241
+
1242
+ The options of `useFluentIframeBridge`.
1243
+
1244
+ ```ts declaration
1245
+ export type UseFluentIframeBridgeOptions = {
1246
+ allowedOrigin: string;
1247
+ };
1248
+ ```
1249
+
1250
+ | Member | Type | Optional | Experimental | Description |
1251
+ |---|---|---|---|---|
1252
+ | `allowedOrigin` | `string` | no | no | The exact origin the embedded page is served from. Messages from any other origin are dropped without a reply: this is the only origin check in the exchange. |
1253
+
1254
+ ### `FluentIframeElement`
1255
+
1256
+ *type*
1257
+
1258
+ The iframe element, reduced to the window the bridge replies to. Read on every
1259
+ message, so an element swapped in later is picked up without rebuilding the bridge.
1260
+
1261
+ ```ts declaration
1262
+ export type FluentIframeElement = {
1263
+ contentWindow: { postMessage: (message: unknown, targetOrigin: string) => void } | null;
1264
+ };
1265
+ ```
1266
+
1267
+ | Member | Type | Optional | Experimental | Description |
1268
+ |---|---|---|---|---|
1269
+ | `contentWindow` | `{ postMessage: (message: unknown, targetOrigin: string) => void } \| null` | no | no | |
1270
+ | `contentWindow.postMessage` | `(message: unknown, targetOrigin: string) => void` | no | no | |
1271
+
1272
+ ## Chains and tokens
1273
+
1274
+ ### `fluentMainnet`
1275
+
1276
+ *value*
1277
+
1278
+ Fluent mainnet (chain id 25363)
1279
+
1280
+ ```ts declaration
1281
+ export const fluentMainnet: Chain;
1282
+ ```
1283
+
1284
+ ### `fluentTestnet`
1285
+
1286
+ *value*
1287
+
1288
+ Fluent public testnet (chain id 20994)
1289
+
1290
+ ```ts declaration
1291
+ export const fluentTestnet: Chain;
1292
+ ```
1293
+
1294
+ ### `getFluentChainByChainId`
1295
+
1296
+ *value*
1297
+
1298
+ Looks up a Fluent chain by its EVM chain id, among the chains the registry knows: Fluent
1299
+ testnet (`20994`) and Fluent mainnet (`25363`).
1300
+
1301
+ **Parameter** chainId The EVM chain id, as a wallet or `eth_chainId` reports it.
1302
+
1303
+ **Returns** The chain's `FluentChainDefinition`, or `undefined` for any other chain id,
1304
+ an L1's included.
1305
+
1306
+ **Example**
1307
+
1308
+ ```ts
1309
+ import { getFluentChainByChainId } from "@fluent.xyz/connect";
1310
+
1311
+ export const explorer = getFluentChainByChainId(20994)?.blockExplorers.default.url;
1312
+ ```
1313
+
1314
+ ```ts declaration
1315
+ export function getFluentChainByChainId(
1316
+ chainId: number,
1317
+ ): FluentChainDefinition | undefined { … }
1318
+ ```
1319
+
1320
+ ### `getFluentChainForNetwork`
1321
+
1322
+ *value*
1323
+
1324
+ The viem chain of a Network, for a host's own chain config.
1325
+
1326
+ **Example**
1327
+
1328
+ ```ts
1329
+ import { getFluentChainForNetwork } from "@fluent.xyz/connect";
1330
+
1331
+ export const chain = getFluentChainForNetwork("mainnet"); // chain.id === 25363
1332
+ ```
1333
+
1334
+ ```ts declaration
1335
+ export function getFluentChainForNetwork(network: FluentWidgetNetwork): Chain { … }
1336
+ ```
1337
+
1338
+ ### `FluentChainDefinition`
1339
+
1340
+ *type*
1341
+
1342
+ One Fluent chain as the registry describes it: its ids, native currency, RPC and explorer
1343
+ endpoints, its L1 parent and its contracts. Declared rather than inferred from
1344
+ `fluentChainSchema`, so its shape is what this file says; `chainDefinitionMatchesSchema`
1345
+ below fails the build if the two drift apart.
1346
+
1347
+ ```ts declaration
1348
+ export type FluentChainDefinition = {
1349
+ id: string;
1350
+ name: string;
1351
+ chainId: number;
1352
+ testnet: boolean;
1353
+ nativeCurrency: { name: string; symbol: string; decimals: number };
1354
+ rpcUrls: { default: { http: string[]; webSocket?: string[] } };
1355
+ blockExplorers: { default: { name: string; url: string } };
1356
+ infoURL: string;
1357
+ faucets?: string[];
1358
+ parent?: { type: "L2"; chainId: number; bridgeUrl: string };
1359
+ contracts?: {
1360
+ fluentBridge?: { address: string; implementation?: string };
1361
+ nativeGateway?: { address: string; implementation?: string };
1362
+ erc20Gateway?: { address: string; implementation?: string };
1363
+ wethGateway?: { address: string; implementation?: string };
1364
+ universalTokenFactory?: { address: string; implementation?: string };
1365
+ paymentGateway?: { address: string; implementation?: string };
1366
+ peggedTokenPrecompile?: { address: string };
1367
+ };
1368
+ };
1369
+ ```
1370
+
1371
+ | Member | Type | Optional | Experimental | Description |
1372
+ |---|---|---|---|---|
1373
+ | `id` | `string` | no | no | The registry's own id: `"fluent-testnet"`, `"fluent-mainnet"`. |
1374
+ | `name` | `string` | no | no | |
1375
+ | `chainId` | `number` | no | no | |
1376
+ | `testnet` | `boolean` | no | no | |
1377
+ | `nativeCurrency` | `{ name: string; symbol: string; decimals: number }` | no | no | |
1378
+ | `nativeCurrency.name` | `string` | no | no | |
1379
+ | `nativeCurrency.symbol` | `string` | no | no | |
1380
+ | `nativeCurrency.decimals` | `number` | no | no | |
1381
+ | `rpcUrls` | `{ default: { http: string[]; webSocket?: string[] } }` | no | no | |
1382
+ | `rpcUrls.default` | `{ http: string[]; webSocket?: string[] }` | no | no | |
1383
+ | `rpcUrls.default.http` | `string[]` | no | no | |
1384
+ | `rpcUrls.default.webSocket` | `string[]` | yes | no | |
1385
+ | `blockExplorers` | `{ default: { name: string; url: string } }` | no | no | |
1386
+ | `blockExplorers.default` | `{ name: string; url: string }` | no | no | |
1387
+ | `blockExplorers.default.name` | `string` | no | no | |
1388
+ | `blockExplorers.default.url` | `string` | no | no | |
1389
+ | `infoURL` | `string` | no | no | |
1390
+ | `faucets` | `string[]` | yes | no | |
1391
+ | `parent` | `{ type: "L2"; chainId: number; bridgeUrl: string }` | yes | no | The L1 the chain settles to, and where its bridge is. |
1392
+ | `parent.type` | `"L2"` | no | no | |
1393
+ | `parent.chainId` | `number` | no | no | |
1394
+ | `parent.bridgeUrl` | `string` | no | no | |
1395
+ | `contracts` | `{ fluentBridge?: { address: string; implementation?: string }; nativeGateway?: { address: string; implementation?: string }; erc20Gateway?: { address: string; implementation?: string }; wethGateway?: { address: string; implementation?: string }; universalTokenFactory?: { address: string; implementation?: string }; paymentGateway?: { address: string; implementation?: string }; peggedTokenPrecompile?: { address: string }; }` | yes | no | Addresses of the chain's system contracts, each with its implementation when proxied. |
1396
+ | `contracts.fluentBridge` | `{ address: string; implementation?: string }` | yes | no | |
1397
+ | `contracts.fluentBridge.address` | `string` | no | no | |
1398
+ | `contracts.fluentBridge.implementation` | `string` | yes | no | |
1399
+ | `contracts.nativeGateway` | `{ address: string; implementation?: string }` | yes | no | |
1400
+ | `contracts.nativeGateway.address` | `string` | no | no | |
1401
+ | `contracts.nativeGateway.implementation` | `string` | yes | no | |
1402
+ | `contracts.erc20Gateway` | `{ address: string; implementation?: string }` | yes | no | |
1403
+ | `contracts.erc20Gateway.address` | `string` | no | no | |
1404
+ | `contracts.erc20Gateway.implementation` | `string` | yes | no | |
1405
+ | `contracts.wethGateway` | `{ address: string; implementation?: string }` | yes | no | |
1406
+ | `contracts.wethGateway.address` | `string` | no | no | |
1407
+ | `contracts.wethGateway.implementation` | `string` | yes | no | |
1408
+ | `contracts.universalTokenFactory` | `{ address: string; implementation?: string }` | yes | no | |
1409
+ | `contracts.universalTokenFactory.address` | `string` | no | no | |
1410
+ | `contracts.universalTokenFactory.implementation` | `string` | yes | no | |
1411
+ | `contracts.paymentGateway` | `{ address: string; implementation?: string }` | yes | no | |
1412
+ | `contracts.paymentGateway.address` | `string` | no | no | |
1413
+ | `contracts.paymentGateway.implementation` | `string` | yes | no | |
1414
+ | `contracts.peggedTokenPrecompile` | `{ address: string }` | yes | no | |
1415
+ | `contracts.peggedTokenPrecompile.address` | `string` | no | no | |
1416
+
1417
+ ### `FluentTokenDefinition`
1418
+
1419
+ *type*
1420
+
1421
+ A token a host adds to the list the widget shows: an Integrator token. It describes the token
1422
+ and grants nothing — whether a token can pay for gas is a property only Default tokens have
1423
+ (ADR 0001), so the widget would strip any such field from a host's token anyway.
1424
+
1425
+ ```ts declaration
1426
+ export type FluentTokenDefinition = {
1427
+ chainId: number;
1428
+ address?: Address;
1429
+ name: string;
1430
+ symbol: string;
1431
+ decimals: number;
1432
+ logoURI?: string;
1433
+ };
1434
+ ```
1435
+
1436
+ | Member | Type | Optional | Experimental | Description |
1437
+ |---|---|---|---|---|
1438
+ | `chainId` | `number` | no | no | The chain the token lives on. The widget does not filter by it: pass the Network's tokens. |
1439
+ | `address` | `Address` | yes | no | The token's contract address; absent for the chain's native token. |
1440
+ | `name` | `string` | no | no | |
1441
+ | `symbol` | `string` | no | no | |
1442
+ | `decimals` | `number` | no | no | |
1443
+ | `logoURI` | `string` | yes | no | An image for the token, a URL or a data URI. |
1444
+
1445
+ ## Experimental
1446
+
1447
+ ### `FluentPrivyAdapter`
1448
+
1449
+ *type* · **experimental**
1450
+
1451
+ Privy runtime supplied by a host using a native SDK. Its Provider owns session
1452
+ restoration, login and wallet RPC; web hosts keep the normal React SDK.
1453
+ Keep one stable adapter per runtime. Changing its Provider remounts descendants
1454
+ so React hooks from different SDKs never share a component lifetime.
1455
+
1456
+ **Experimental.** May change or be removed in a minor release: the one provider seam of the
1457
+ widget, kept for hosts that run a native login SDK.
1458
+
1459
+ ```ts declaration
1460
+ export type FluentPrivyAdapter = Pick<
1461
+ typeof web,
1462
+ | "PrivyProvider"
1463
+ | "Captcha"
1464
+ | "usePrivy"
1465
+ | "useSignMessage"
1466
+ | "useSignTypedData"
1467
+ | "useWallets"
1468
+ | "useIdentityToken"
1469
+ | "useUser"
1470
+ | "useLinkAccount"
1471
+ | "useLoginWithSiwe"
1472
+ | "useModalStatus"
1473
+ | "useCreateWallet"
1474
+ | "useLoginWithEmail"
1475
+ | "useLoginWithOAuth"
1476
+ | "useLoginWithPasskey"
1477
+ | "useLinkWithPasskey"
1478
+ >;
1479
+ ```
1480
+
1481
+ ### `FluentExternalWalletState`
1482
+
1483
+ *type* · **experimental**
1484
+
1485
+ An External wallet as the widget sees it: whether one is connected, its address, chain and
1486
+ client, and how to open, connect, switch and disconnect it. Its inline choices are
1487
+ `FluentWalletChoice`s.
1488
+
1489
+ **Experimental.** May change or be removed in a minor release: a host that brings its own wallet
1490
+ connection is not a 0.6.0 commitment.
1491
+
1492
+ ```ts declaration
1493
+ export type FluentExternalWalletState = {
1494
+ configured: boolean;
1495
+ connected: boolean;
1496
+ address?: string;
1497
+ chainId?: number;
1498
+ walletClient?: WalletClient;
1499
+ reconnecting?: boolean;
1500
+ choices?: readonly FluentWalletChoice[];
1501
+ connectChoice?: (id: string) => Promise<void>;
1502
+ open: () => void;
1503
+ disconnect: () => void;
1504
+ switchChain: (chainId: number) => Promise<void>;
1505
+ };
1506
+ ```
1507
+
1508
+ | Member | Type | Optional | Experimental | Description |
1509
+ |---|---|---|---|---|
1510
+ | `configured` | `boolean` | no | no | |
1511
+ | `connected` | `boolean` | no | no | |
1512
+ | `address` | `string` | yes | no | |
1513
+ | `chainId` | `number` | yes | no | |
1514
+ | `walletClient` | `WalletClient` | yes | no | |
1515
+ | `reconnecting` | `boolean` | yes | no | True while the wallet is being restored from a previous visit and neither `connected` nor "no wallet" is known yet. Optional so hosts supplying their own wallet state keep working; omitting it just means the widget reports `"disconnected"` slightly earlier during a reload. |
1516
+ | `choices` | `readonly FluentWalletChoice[]` | yes | no | Optional inline choices; hosts without them keep their existing open() picker. |
1517
+ | `connectChoice` | `(id: string) => Promise<void>` | yes | no | |
1518
+ | `open` | `() => void` | no | no | |
1519
+ | `disconnect` | `() => void` | no | no | |
1520
+ | `switchChain` | `(chainId: number) => Promise<void>` | no | no | |
1521
+
1522
+ ### `FluentWalletChoice`
1523
+
1524
+ *type* · **experimental**
1525
+
1526
+ One wallet the connect dialog offers inline, as a host's `FluentExternalWalletState` lists it.
1527
+
1528
+ **Experimental.** May change or be removed in a minor release: a host that brings its own wallet
1529
+ connection is not a 0.6.0 commitment.
1530
+
1531
+ ```ts declaration
1532
+ export type FluentWalletChoice = {
1533
+ id: string;
1534
+ name: string;
1535
+ icon?: string;
1536
+ handoff?: boolean;
1537
+ };
1538
+ ```
1539
+
1540
+ | Member | Type | Optional | Experimental | Description |
1541
+ |---|---|---|---|---|
1542
+ | `id` | `string` | no | no | |
1543
+ | `name` | `string` | no | no | |
1544
+ | `icon` | `string` | yes | no | |
1545
+ | `handoff` | `boolean` | yes | no | This connector opens an external wallet/QR surface. |
1546
+
1547
+ ### `FluentWidgetExecution`
1548
+
1549
+ *type* · **experimental**
1550
+
1551
+ `FluentWidgetConfig.execution`, every field optional.
1552
+
1553
+ **Experimental.** May change or be removed in a minor release while the defaults are measured;
1554
+ the defaults are the recommended setting.
1555
+
1556
+ ```ts declaration
1557
+ export type FluentWidgetExecution = {
1558
+ feeSource?: FluentWidgetExecutionSource;
1559
+ receiptSource?: FluentWidgetExecutionSource;
1560
+ chainCheckBeforeSign?: boolean;
1561
+ };
1562
+ ```
1563
+
1564
+ | Member | Type | Optional | Experimental | Description |
1565
+ |---|---|---|---|---|
1566
+ | `feeSource` | `FluentWidgetExecutionSource` | yes | **yes** | Where the fees of a user operation come from, a `FluentWidgetExecutionSource`. `chain` reads the widget chain's `eth_gasPrice` and caps `maxFeePerGas` 10 % above it; `bundler` takes the bundler's own gas price quote unchanged. Defaults to `chain`. **Experimental.** May change or be removed in a minor release while the defaults are measured; the defaults are the recommended setting. |
1567
+ | `receiptSource` | `FluentWidgetExecutionSource` | yes | **yes** | Where inclusion is read from, a `FluentWidgetExecutionSource`. `chain` polls the EntryPoint's `UserOperationEvent` with `eth_getLogs`; `bundler` polls `eth_getUserOperationReceipt`. Defaults to `chain`. **Experimental.** May change or be removed in a minor release while the defaults are measured; the defaults are the recommended setting. |
1568
+ | `chainCheckBeforeSign` | `boolean` | yes | **yes** | Whether the Signer's chain is read before every signature. The widget gives the Signer's provider its own chain as the only one, and the smart account checks the chain once when it is created, so the repeat costs a provider round trip per signature and switches nothing. Defaults to `false`. **Experimental.** May change or be removed in a minor release while the defaults are measured; the defaults are the recommended setting. |
1569
+
1570
+ ### `FluentWidgetExecutionSource`
1571
+
1572
+ *type* · **experimental**
1573
+
1574
+ Where a Fluent ID's send reads a value it could ask either side for: the widget chain's own
1575
+ RPC, or the bundler.
1576
+
1577
+ **Experimental.** May change or be removed in a minor release while the defaults are measured;
1578
+ the defaults are the recommended setting.
1579
+
1580
+ ```ts declaration
1581
+ export type FluentWidgetExecutionSource = "chain" | "bundler";
1582
+ ```
1583
+
1584
+ Literals: `bundler`, `chain`.
1585
+
1586
+ ### `FluentUserOperationGas`
1587
+
1588
+ *type* · **experimental**
1589
+
1590
+ Gas policy for a Fluent ID batch. Estimation is enabled unless `skipEstimation` is true.
1591
+ Skipping requires account limits. Omit both paymaster limits to use provider-authorized
1592
+ paymaster gas and calldata overhead within `preVerificationGas`; supply both to fix all gas.
1593
+ The fixed limits are a `FluentFixedAccountGas` and a `FluentFixedPaymasterGas`.
1594
+
1595
+ **Experimental.** May change or be removed in a minor release while the gas policy is measured;
1596
+ omitting it, which lets the widget estimate, is the recommended setting.
1597
+
1598
+ ```ts declaration
1599
+ export type FluentUserOperationGas =
1600
+ | (FluentFixedAccountGas & FluentFixedPaymasterGas & {
1601
+ /** Skip the account gas hook and bundler gas estimation. Defaults to false. */
1602
+ skipEstimation: true;
1603
+ callGasBuffer?: never;
1604
+ })
1605
+ | { skipEstimation?: false; callGasLimit: bigint; callGasBuffer?: never }
1606
+ | {
1607
+ skipEstimation?: false;
1608
+ callGasLimit?: never;
1609
+ callGasBuffer: {
1610
+ /** Extra percent of the bundler estimate, rounded up. Must be a nonnegative safe integer. */
1611
+ percentage?: number;
1612
+ /** Extra gas added after the percentage buffer. Must be nonnegative. */
1613
+ fixed?: bigint;
1614
+ };
1615
+ };
1616
+ ```
1617
+
1618
+ ### `FluentUserOperationGasError`
1619
+
1620
+ *value* · **experimental**
1621
+
1622
+ An invalid skip-estimation policy or paymaster authorization for different gas limits.
1623
+ `code`, a `FluentUserOperationGasErrorCode`, identifies the failure; `message` names the
1624
+ option or gas field to correct.
1625
+
1626
+ **Experimental.** May change or be removed in a minor release while the gas policy is measured;
1627
+ omitting it, which lets the widget estimate, is the recommended setting.
1628
+
1629
+ ```ts declaration
1630
+ export class FluentUserOperationGasError extends Error {
1631
+ constructor(readonly code: FluentUserOperationGasErrorCode, message: string) { … }
1632
+ }
1633
+ ```
1634
+
1635
+ | Member | Type | Optional | Experimental | Description |
1636
+ |---|---|---|---|---|
1637
+ | `code` | `FluentUserOperationGasErrorCode` | no | no | |
1638
+
1639
+ ### `FluentUserOperationGasErrorCode`
1640
+
1641
+ *type* · **experimental**
1642
+
1643
+ Reasons explicit gas preparation can fail before signing.
1644
+
1645
+ **Experimental.** May change or be removed in a minor release while the gas policy is measured;
1646
+ omitting it, which lets the widget estimate, is the recommended setting.
1647
+
1648
+ ```ts declaration
1649
+ export type FluentUserOperationGasErrorCode = "invalid_policy" | "paymaster_gas_mismatch";
1650
+ ```
1651
+
1652
+ Literals: `invalid_policy`, `paymaster_gas_mismatch`.
1653
+
1654
+ ### `FluentFixedAccountGas`
1655
+
1656
+ *type* · **experimental**
1657
+
1658
+ The account's own gas limits, all three fixed, for a `FluentUserOperationGas` that skips
1659
+ estimation.
1660
+
1661
+ **Experimental.** May change or be removed in a minor release while the gas policy is measured;
1662
+ omitting it, which lets the widget estimate, is the recommended setting.
1663
+
1664
+ ```ts declaration
1665
+ export type FluentFixedAccountGas = {
1666
+ callGasLimit: bigint;
1667
+ verificationGasLimit: bigint;
1668
+ preVerificationGas: bigint;
1669
+ };
1670
+ ```
1671
+
1672
+ | Member | Type | Optional | Experimental | Description |
1673
+ |---|---|---|---|---|
1674
+ | `callGasLimit` | `bigint` | no | no | Whole-batch execution budget, including any Gas token approval. Positive uint128. |
1675
+ | `verificationGasLimit` | `bigint` | no | no | Account validation and deployment budget. Positive uint128. |
1676
+ | `preVerificationGas` | `bigint` | no | no | Calldata overhead, or its ceiling with provider-owned paymaster gas. Positive uint256. |
1677
+
1678
+ ### `FluentFixedPaymasterGas`
1679
+
1680
+ *type* · **experimental**
1681
+
1682
+ The paymaster's gas limits for a `FluentUserOperationGas` that skips estimation: both, or
1683
+ neither to use the limits the paymaster authorizes.
1684
+
1685
+ **Experimental.** May change or be removed in a minor release while the gas policy is measured;
1686
+ omitting it, which lets the widget estimate, is the recommended setting.
1687
+
1688
+ ```ts declaration
1689
+ export type FluentFixedPaymasterGas = {
1690
+ paymasterVerificationGasLimit?: bigint;
1691
+ paymasterPostOpGasLimit?: bigint;
1692
+ };
1693
+ ```
1694
+
1695
+ | Member | Type | Optional | Experimental | Description |
1696
+ |---|---|---|---|---|
1697
+ | `paymasterVerificationGasLimit` | `bigint` | yes | no | Fixed validation budget, a positive uint128. Omit both paymaster limits to use its answer. |
1698
+ | `paymasterPostOpGasLimit` | `bigint` | yes | no | Fixed post-operation budget, a nonnegative uint128. Supplied together with validation. |
1699
+
1700
+ ### `FluentExecuteTiming`
1701
+
1702
+ *type* · **experimental**
1703
+
1704
+ Where one send's milliseconds went, stage by stage.
1705
+
1706
+ Two clocks, and the difference decides how these numbers may be read. `prepareMs`,
1707
+ `signMs`, `broadcastMs`, `retryMs` and `totalMs` are direct monotonic measurements on the
1708
+ client (`performance.now()`). `inclusionMs` and `detectMs` are *signed estimates* across the
1709
+ client's clock and the chain's: `block.timestamp` has one-second resolution and no relation
1710
+ to the browser's clock, so either may legitimately be negative when it is small, and neither
1711
+ is clamped — a clamp would turn a known skew into a silent zero. `instants` keeps the inputs,
1712
+ so the subtraction can be redone by whoever doubts it.
1713
+
1714
+ `totalMs` is measured, not summed: it runs from the start of the first submission to the
1715
+ instant the receipt was in hand, and excludes both the smart-account and authentication setup
1716
+ before the send and the block read after it. It does not equal the sum of the stages and must
1717
+ not be displayed as if it did.
1718
+
1719
+ Collected for every send, whatever `debugLogging` is set to — the numbers are the answer to
1720
+ "where did the four seconds go", which is a question a host asks in production. A failure
1721
+ inside the measuring code costs the stages it could not establish, never the send.
1722
+
1723
+ **Experimental.** May change or be removed in a minor release while the numbers are measured.
1724
+
1725
+ ```ts declaration
1726
+ export type FluentExecuteTiming = {
1727
+ prepareMs?: number;
1728
+ signMs?: number;
1729
+ broadcastMs?: number;
1730
+ inclusionMs?: number;
1731
+ detectMs?: number;
1732
+ retryMs: number;
1733
+ totalMs: number;
1734
+ instants: FluentExecuteTimingInstants;
1735
+ };
1736
+ ```
1737
+
1738
+ | Member | Type | Optional | Experimental | Description |
1739
+ |---|---|---|---|---|
1740
+ | `prepareMs` | `number` | yes | no | Building the UserOperation — nonce, gas estimate, paymaster — up to the signature request. Absent when the clock could not be read at that boundary: every stage here is absent rather than approximated, because a stage silently widened to cover its neighbours is worse than a stage the display can mark as unmeasured. |
1741
+ | `signMs` | `number` | yes | no | Producing the signature. Absent when the settled attempt never got that far. |
1742
+ | `broadcastMs` | `number` | yes | no | Handing the signed operation to the bundler. Absent when signing never finished. |
1743
+ | `inclusionMs` | `number` | yes | no | Bundler acceptance to the including block's timestamp: bundling plus block time. Signed estimate; absent when the including block could not be read. |
1744
+ | `detectMs` | `number` | yes | no | The including block's timestamp to the instant this client held the receipt: how long the inclusion took to notice. Signed estimate; absent when the including block could not be read. |
1745
+ | `retryMs` | `number` | no | no | Time spent on submissions that did not settle — a rejected sponsorship bearer, a refused sponsorship falling back to own gas — and on the token exchange between them. It belongs to no stage, is counted inside `totalMs`, and is `0` for a send that submitted once. |
1746
+ | `totalMs` | `number` | no | no | First submission to receipt in hand. Measured directly; never a sum of the stages. |
1747
+ | `instants` | `FluentExecuteTimingInstants` | no | no | The raw instants the signed estimates above were computed from. |
1748
+
1749
+ ### `FluentExecuteTimingInstants`
1750
+
1751
+ *type* · **experimental**
1752
+
1753
+ Absolute instants behind `FluentExecuteTiming`, kept so its signed estimates can be
1754
+ re-checked rather than believed. Epoch milliseconds (`Date.now()`), because the only other
1755
+ clock in the arithmetic — the including block's `timestamp` — is a wall clock too.
1756
+
1757
+ **Experimental.** May change or be removed in a minor release while the numbers are measured.
1758
+
1759
+ ```ts declaration
1760
+ export type FluentExecuteTimingInstants = {
1761
+ submittedAtEpochMs: number;
1762
+ broadcastedAtEpochMs: number;
1763
+ receivedAtEpochMs: number;
1764
+ blockTimestampEpochMs?: number;
1765
+ attempts: number;
1766
+ };
1767
+ ```
1768
+
1769
+ | Member | Type | Optional | Experimental | Description |
1770
+ |---|---|---|---|---|
1771
+ | `submittedAtEpochMs` | `number` | no | no | When the first submission attempt of this send began. |
1772
+ | `broadcastedAtEpochMs` | `number` | no | no | When the bundler accepted the operation that settled. |
1773
+ | `receivedAtEpochMs` | `number` | no | no | When that operation's receipt was in hand. |
1774
+ | `blockTimestampEpochMs` | `number` | yes | no | The including block's `timestamp`, in milliseconds. Absent exactly when `inclusionMs` and `detectMs` are absent: the block could not be read. |
1775
+ | `attempts` | `number` | no | no | How many operations were submitted; more than one means a retry or an own-gas fallback. |
1776
+
1777
+ ### `FluentGasPaymentEthRates`
1778
+
1779
+ *type* · **experimental**
1780
+
1781
+ What one unit of each Gas token is worth in ETH, as a decimal string, keyed by its
1782
+ `FluentGasTokenSymbol`.
1783
+
1784
+ **Experimental.** May change or be removed in a minor release while the defaults are measured;
1785
+ the defaults are the recommended setting.
1786
+
1787
+ ```ts declaration
1788
+ export type FluentGasPaymentEthRates = Partial<Record<FluentGasTokenSymbol, string>>;
1789
+ ```