@fluent.xyz/connect 0.7.1 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/api.md CHANGED
@@ -28,6 +28,10 @@ Each export shows its TSDoc, its declaration (a function's body left out), the l
28
28
  The Fluent Connect widget: the connect button, the sign-in dialog, the account drawer and the
29
29
  Widget API, provided to the App's own content rendered through `renderHome` or `renderPage`.
30
30
 
31
+ Renders on a server: the render context there is the `restoring` status with no session and
32
+ no wallet, and the real state arrives after hydration — see the getting-started guide's
33
+ server-side rendering section.
34
+
31
35
  **Throws** `FluentWidgetConfigError` from a render when `config` cannot be used, its `code`
32
36
  `missing_option`, `invalid_option` or `removed_option` with the option named in its message,
33
37
  or, for the experimental `execution`, `invalid_fee_source`, `invalid_receipt_source` or
@@ -76,16 +80,16 @@ export type FluentWidgetProps = {
76
80
 
77
81
  | Member | Type | Optional | Experimental | Description |
78
82
  |---|---|---|---|---|
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 | |
83
+ | `wallet` | `FluentExternalWalletState \| null` | yes | **yes** | An External wallet the App 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: an App that brings its own wallet connection is not a 0.6.0 commitment. |
84
+ | `config` | `FluentWidgetConfig` | no | no | The widget's configuration; keep the object stable, since a new one is resolved again. |
85
+ | `privyAdapter` | `FluentPrivyAdapter` | yes | **yes** | Optional native Privy SDK bridge, a `FluentPrivyAdapter`, for an App 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 Apps that run a native login SDK. |
86
+ | `mode` | `"home" \| "page"` | yes | no | Which render prop the widget renders: `"home"` (the default) renders `renderHome`, `"page"` renders `renderPage`. With `debugLogging` on, `"home"` also shows the debug panel. |
87
+ | `connectButton` | `"fixed" \| "inline" \| false` | yes | no | Where the widget's own connect button goes. - `"fixed"` (default): floating at the top right of the page. - `"inline"`: the same button without fixed positioning, for the App's layout to place. - `false`: hidden; use `renderConnectButton`, `openConnect` or `openAccount`. |
88
+ | `renderConnectButton` | `(context: FluentWidgetConnectButtonRenderContext) => ReactNode` | yes | no | A function that draws the App's own connect button in place of the widget's; when it returns `null` or `undefined`, `connectButton` applies instead. |
89
+ | `renderHome` | `(context: FluentWidgetRenderContext) => ReactNode` | yes | no | The App's content in `mode="home"`, given the render context. |
90
+ | `renderPage` | `(context: FluentWidgetRenderContext) => ReactNode` | yes | no | The App's content in `mode="page"`, given the render context. |
87
91
  | `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. |
92
+ | `debugLogging` | `boolean` | yes | no | Whether the widget prints its connect, smart-account and signing diagnostics to the console and shows the debug panel in `mode="home"`. Off by default; turn it on only while debugging an integration. |
89
93
  | `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
94
 
91
95
  ### `FluentWidgetRenderContext`
@@ -121,16 +125,16 @@ export type FluentWidgetRenderContext = {
121
125
  | `userAvatarUrl` | `string` | yes | no | The Account avatar's linked X picture; absent for an External wallet or `forceDefault`. |
122
126
  | `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
127
  | `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. |
128
+ | `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: an App that brings its own wallet connection is not a 0.6.0 commitment. |
125
129
  | `widget` | `FluentBatchApi` | no | no | The Widget API: the account, Batch operations, signatures and the current Gas payment. |
126
130
  | `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
131
  | `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. |
132
+ | `disconnect` | `() => Promise<void>` | no | no | Disconnects the Widget account, the same teardown the account menu's "Disconnect" runs. The Widget session and the stored identity token are cleared before it resolves, so an App 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
133
  | `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, and the wallet menu reads them itself when it opens and every 10 seconds while it stays open; call this to show a tx sent via an External wallet client (outside the widget's execution path) before the next scheduled read. |
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
+ | `status` | `FluentWidgetStatus` | no | no | The connection state as one value, meaningful on every render including the first, before a stored session has been restored. Branch on it rather than on `hasConnectedAccount` alone: `"restoring"` and `"disconnected"` both have `hasConnectedAccount === false`, and treating them alike shows a Connect button to a person who is signed in. The account's address is `widget.account.address`. |
135
+ | `refreshBalances` | `() => void` | no | no | Refetches the widget's on-chain balances. A Batch operation run through `widget.createBatchOp` refreshes them itself, and the account drawer reads them when it opens and every 10 seconds while it stays open; call this to show a transaction sent through an External wallet's own client, outside the widget, before the next read. |
136
+ | `getAuthToken` | `() => Promise<string>` | no | no | Returns 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. |
137
+ | `linkX` | `() => Promise<FluentLinkXResult>` | no | no | Links 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
138
 
135
139
  ### `FluentWidgetConnectButtonRenderContext`
136
140
 
@@ -155,35 +159,34 @@ export type FluentWidgetConnectButtonRenderContext = {
155
159
 
156
160
  | Member | Type | Optional | Experimental | Description |
157
161
  |---|---|---|---|---|
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 | |
162
+ | `connected` | `boolean` | no | no | Whether a Widget account is connected, the render context's `hasConnectedAccount`. |
163
+ | `pending` | `boolean` | no | no | `true` while a Fluent ID is signed in and its smart account is still being prepared. |
164
+ | `addressLabel` | `string` | yes | no | The connected account's shortened address, or `"Connected"` while the address is not known; absent while no Widget account is connected. |
161
165
  | `userAvatarUrl` | `string` | yes | no | The Account avatar's linked X picture; absent for an External wallet or `forceDefault`. |
162
166
  | `userXDisplayName` | `string` | yes | no | The person's X display name, the render context's `userXDisplayName`. |
163
167
  | `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
+ | `onClick` | `() => void` | no | no | What the widget's own button does on a click: toggles the drawer or opens sign-in. |
169
+ | `openConnect` | `() => void` | no | no | The render context's `openConnect`. |
170
+ | `openAccount` | `() => void` | no | no | The render context's `openAccount`. |
171
+ | `DefaultButton` | `() => ReactNode` | no | no | The widget's own connect button, to render inside a custom one or beside it. |
168
172
 
169
173
  ### `useFluentWidget`
170
174
 
171
175
  *value*
172
176
 
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`.
177
+ Returns the render context of the enclosing `<FluentWidget>`: the object `renderHome` and
178
+ `renderPage` receive, with the Widget API as its `widget`.
178
179
 
179
- Throws if used outside `<FluentWidget>`.
180
+ Throws an `Error` when called outside `<FluentWidget>`.
180
181
 
181
182
  **Example**
182
183
 
183
184
  ```tsx
184
185
  import { useFluentWidget } from "@fluent.xyz/connect";
185
186
 
186
- const calls = [{ to: "0x000000000000000000000000000000000000dEaD", value: 1n, data: "0x" }] as const;
187
+ const calls = [
188
+ { to: "0x000000000000000000000000000000000000dEaD", value: 1n, data: "0x" },
189
+ ] as const;
187
190
 
188
191
  export function Send() {
189
192
  const { widget, status } = useFluentWidget();
@@ -200,18 +203,17 @@ export function useFluentWidget(): FluentWidgetRenderContext { … }
200
203
 
201
204
  *type*
202
205
 
203
- Top-level connection state of the widget, safe to read on any render.
206
+ The widget's connection state, safe to read on any render.
204
207
 
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.
208
+ The distinction that matters is `"restoring"` against `"disconnected"`: a sign-in kept from a
209
+ previous visit is not known synchronously, so an App that treats "not connected yet" as "no
210
+ account" shows a Connect button to people who are still signed in. Wait out `"restoring"`.
209
211
 
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.
212
+ - `"restoring"`: a previous sign-in may exist; nothing is decided yet.
213
+ - `"connecting"`: a Connect the user started is in flight.
214
+ - `"connected"`: a Widget account is available. Whether it can send right now is
215
+ `widget.account.executionStatus`.
216
+ - `"disconnected"`: no Widget account, and none is being restored or connected.
215
217
 
216
218
  ```ts declaration
217
219
  export type FluentWidgetStatus = "restoring" | "connecting" | "connected" | "disconnected";
@@ -227,8 +229,8 @@ What the widget tells an App about who is signed in: the Widget account's addres
227
229
  and when the widget built that snapshot. Not a credential: an App proves who the person is
228
230
  with an Auth token from `getAuthToken()`.
229
231
 
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
+ Only a Fluent ID's Direct login writes a session. Connecting an External wallet neither writes
233
+ nor clears it; read the connected account from `widget.account`.
232
234
 
233
235
  ```ts declaration
234
236
  export type FluentWidgetSession = {
@@ -244,7 +246,7 @@ export type FluentWidgetSession = {
244
246
  |---|---|---|---|---|
245
247
  | `account` | `{ address: Address; type: FluentAccountType; }` | no | no | |
246
248
  | `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. |
249
+ | `account.type` | `FluentAccountType` | no | no | `"smart"`: only a Fluent ID's Direct login writes a session. `FluentAccountType` may gain values, so a `switch` over it keeps a `default` branch. |
248
250
  | `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
251
 
250
252
  ### `FluentWidgetAccount`
@@ -273,14 +275,14 @@ export type FluentWidgetAccount = {
273
275
  | `executionReady` | `boolean` | no | no | Whether the Widget account can send now; `executionStatus` says why it cannot. |
274
276
  | `executionStatus` | `FluentWidgetExecutionStatus` | no | no | Where sending stands, a `FluentWidgetExecutionStatus`. |
275
277
  | `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
+ | `type` | `FluentAccountType` | yes | no | The Widget account's kind. Undefined until a Fluent ID's smart account is ready or an External wallet is connected. |
279
+ | `capabilities` | `FluentAccountCapabilities` | no | no | What the Widget account can do. |
278
280
 
279
281
  ### `FluentAccountType`
280
282
 
281
283
  *type*
282
284
 
283
- How the connected account executes transactions.
285
+ The kind of Widget account: `"smart"` for a Fluent ID, `"eoa"` for an External wallet.
284
286
 
285
287
  ```ts declaration
286
288
  export type FluentAccountType = "smart" | "eoa";
@@ -303,8 +305,8 @@ export type FluentAccountCapabilities = {
303
305
 
304
306
  | Member | Type | Optional | Experimental | Description |
305
307
  |---|---|---|---|---|
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
+ | `atomicBatch` | `boolean` | no | no | Whether a Batch operation's calls land in one atomic transaction: a Fluent ID only. |
309
+ | `erc20Gas` | `boolean` | no | no | Whether gas can be paid in a Gas token instead of native ETH: a Fluent ID only. This is not Sponsorship: the account still pays, in the Gas token. |
308
310
 
309
311
  ### `FluentWidgetExecutionStatus`
310
312
 
@@ -323,8 +325,8 @@ Literals: `disconnected`, `error`, `ready`, `unavailable`.
323
325
 
324
326
  *value*
325
327
 
326
- The Account avatar: the person's linked X picture, else the host's default logo, else the
327
- Fluent mark.
328
+ The Account avatar: the person's linked X picture, else the App's default logo, else the
329
+ Fluent mark. An image that fails to load falls back to the Fluent mark until the URL changes.
328
330
 
329
331
  **Example**
330
332
 
@@ -358,8 +360,8 @@ export type AccountAvatarProps = {
358
360
  | Member | Type | Optional | Experimental | Description |
359
361
  |---|---|---|---|---|
360
362
  | `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
+ | `defaultLogoUrl` | `string \| null` | yes | no | The App's stand-in for the Fluent mark: a URL or a data URI. |
364
+ | `className` | `string` | yes | no | Classes added to the Fluent mark when it is drawn; the image does not take them. |
363
365
 
364
366
  ## Config
365
367
 
@@ -400,6 +402,7 @@ export type FluentWidgetConfig = {
400
402
  disableAnalytics?: boolean;
401
403
  reconnectOnMount?: boolean;
402
404
  sponsorshipUrl?: string;
405
+ orderDepositUrl?: string;
403
406
  authTokenRenewalOffsetSeconds?: number;
404
407
  assets?: Partial<FluentWidgetAssets>;
405
408
  avatar?: {
@@ -411,37 +414,38 @@ export type FluentWidgetConfig = {
411
414
 
412
415
  | Member | Type | Optional | Experimental | Description |
413
416
  |---|---|---|---|---|
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. |
417
+ | `appId` | `string` | no | no | The App's id (`app_<32 hex>`): the string the Fluent Dashboard shows and an Auth token's `aud` carries. |
415
418
  | `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. |
419
+ | `clientId` | `never` | yes | no | Not an option: typed so that a config passing it is refused with a message naming `appId`. |
420
+ | `partnerId` | `never` | yes | no | Not an option: typed so that a config passing it is refused with a message naming `appId`. |
418
421
  | `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. |
422
+ | `appName` | `string` | yes | no | The App's name, shown in the connect dialog and on the Review. |
423
+ | `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. |
424
+ | `enabledAuthMethods` | `FluentWidgetAuthMethod[]` | yes | no | The Auth methods the connect dialog offers beside X, in the order given: any of `"google"`, `"email"` and `"passkey"`. Defaults to `["google", "email"]`; name `"passkey"` to offer it, a shorter set to drop the rest, or `[]` to leave X as the only one. 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. |
425
+ | `swapper` | `{ enabled?: boolean; integratorId?: string; dstChainId?: string; dstTokenAddress?: string; }` | yes | **yes** | The USDnr on-ramp, run by Swapper Finance, that the account drawer offers. It is offered only when `enabled` is `true` and the other three fields are non-empty. **Experimental.** May change or be removed in a minor release while the defaults are measured; the defaults are the recommended setting. |
426
+ | `swapper.enabled` | `boolean` | yes | no | Whether the on-ramp is offered. Defaults to `true`. |
427
+ | `swapper.integratorId` | `string` | yes | no | The Swapper Finance integrator id. Defaults to Fluent's own. |
428
+ | `swapper.dstChainId` | `string` | yes | no | The chain the on-ramp delivers to, a decimal chain id. Defaults to `"25363"`, mainnet. |
429
+ | `swapper.dstTokenAddress` | `string` | yes | no | The token the on-ramp delivers. Defaults to USDnr on mainnet. |
430
+ | `gasPayment` | `{ defaultToken?: FluentGasTokenSymbol; sponsorship?: "auto" \| "never"; ethValueByToken?: FluentGasPaymentEthRates; }` | yes | no | How the widget pays gas: its default Gas token, Sponsorship and the rates it shows. |
431
+ | `gasPayment.defaultToken` | `FluentGasTokenSymbol` | yes | no | The Gas token the widget charges until the person chooses one. Defaults to ETH; the person's own choice wins when it names a Gas token of the Network. |
432
+ | `gasPayment.sponsorship` | `"auto" \| "never"` | yes | no | Whether a Gas payment in native ETH asks for Sponsorship: `"auto"` asks, `"never"` does not and the account pays its own gas. Defaults to `"auto"`; a Batch operation's own `gasPayment.sponsorship` wins over it. |
430
433
  | `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
434
  | `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 that follows Tokens and Activity in the account drawer. 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. |
435
+ | `quickSign` | `{ whitelistAddresses?: readonly string[]; }` | yes | no | How far Quick sign reaches for this App. |
436
+ | `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 skipping any Review; omit the option to keep it covering every address. Compared case-insensitively. `signMessage` and `signTypedData` have no call target and are not scoped by this. |
437
+ | `reputationEnabled` | `boolean` | yes | no | Whether the account drawer has its Reputation tab, after Tokens and Activity. `false` drops the tab, and the widget requests no families. Defaults to `true`. |
438
+ | `source` | `string` | yes | no | The `source` every analytics event carries. Defaults to `"fluent_connect_widget"`. |
439
+ | `campaign` | `string` | yes | no | The `campaign` every analytics event carries; unset, the events carry none. |
440
+ | `disableAnalytics` | `boolean` | yes | no | Turns off analytics: PostHog is not initialised and nothing is sent or stored, and the External wallet connector's own analytics is off. Defaults to `false`. |
441
+ | `reconnectOnMount` | `boolean` | yes | no | Which External wallets reconnect on page load. Unset, injected wallets and WalletConnect do; `true` reconnects every connector, `false` none. |
442
+ | `sponsorshipUrl` | `string` | yes | **yes** | A sponsorship service other than the Network's own, for local development: the deployed service is the one every App uses. **Experimental.** May change or be removed in a minor release while the defaults are measured; the defaults are the recommended setting. |
443
+ | `orderDepositUrl` | `string` | yes | **yes** | An Order deposit service other than the Network's own, for local development: the base URL its quote and order requests go to. An empty string turns Order deposits off, and USDC then crosses through the swap facility and the bridge. The deployed service is the one every App uses. **Experimental.** May change or be removed in a minor release while the defaults are measured; the defaults are the recommended setting. |
440
444
  | `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
445
  | `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). |
446
+ | `avatar` | `{ defaultLogoUrl?: string; forceDefault?: boolean; }` | yes | no | The Account avatar, shown on the connect button and in the account drawer. |
447
+ | `avatar.defaultLogoUrl` | `string` | yes | no | The image the Account avatar shows when there is no linked X picture to show, a URL or a data URI. Defaults to the Fluent mark. |
448
+ | `avatar.forceDefault` | `boolean` | yes | no | Whether the Account avatar always shows the default image, even for a person with a Linked X account. Defaults to `false`: the linked X picture wins when there is one. |
445
449
 
446
450
  ### `FluentWidgetNetwork`
447
451
 
@@ -459,8 +463,8 @@ Literals: `mainnet`, `testnet`.
459
463
 
460
464
  *type*
461
465
 
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.
466
+ An Auth method the connect dialog can offer beside X. X is not on this list: it is always
467
+ offered and cannot be switched off.
464
468
 
465
469
  ```ts declaration
466
470
  export type FluentWidgetAuthMethod = "google" | "email" | "passkey";
@@ -472,8 +476,8 @@ Literals: `email`, `google`, `passkey`.
472
476
 
473
477
  *type*
474
478
 
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
479
+ Images for the widget, each a URL or a data URI. Of an App's `assets` the widget reads only
480
+ `fluentLogo`, which it passes to the provider behind Direct login as its logo; see `assets` in
477
481
  [configuration.md](configuration.md).
478
482
 
479
483
  ```ts declaration
@@ -512,12 +516,12 @@ export type FluentBatchApi = FluentSignApi & {
512
516
 
513
517
  | Member | Type | Optional | Experimental | Description |
514
518
  |---|---|---|---|---|
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) |
519
+ | `signMessage` | `(params: { message: SignableMessage }) => Promise<Hex>` | no | no | Signs `message` (EIP-191) for the Widget account: ERC-1271, or ERC-6492 before deployment, for a Fluent ID, and 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 widget configuration reaches. (example below) |
520
+ | `signTypedData` | `< const typedData extends TypedData \| Record<string, unknown>, primaryType extends keyof typedData \| "EIP712Domain" = keyof typedData, >( typedData: TypedDataDefinition<typedData, primaryType>, ) => Promise<Hex>` | no | no | Signs `typedData` (EIP-712) for the Widget account: ERC-1271, or ERC-6492 before deployment, for a Fluent ID, and 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
521
  | `account` | `FluentWidgetAccount` | no | no | The Widget account: its address, type, readiness and capabilities. |
518
522
  | `signingMode` | `FluentSigningMode` | no | no | How the widget signs by default: `"silent"` while the person's Quick sign is on. |
519
523
  | `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. |
524
+ | `createBatchOp` | `(input: FluentBatchOperationInput) => FluentBatchOperation` | no | no | Builds a Batch operation, encoding its calls now; `execute()` sends it. Throws an `Error` when `calls` is empty, or when a call has neither `data` nor `abi` with `method`; a call naming its function in 0.5's `functionName` has neither. |
521
525
 
522
526
  **`signMessage` example**
523
527
 
@@ -571,7 +575,7 @@ export type FluentBatchOperationInput = {
571
575
 
572
576
  | Member | Type | Optional | Experimental | Description |
573
577
  |---|---|---|---|---|
574
- | `id` | `string` | yes | no | |
578
+ | `id` | `string` | yes | no | The host's own identifier for the operation, copied to `FluentBatchOperation.id`. |
575
579
  | `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
580
  | `calls` | `readonly FluentBatchCallInput[]` | no | no | |
577
581
 
@@ -597,14 +601,14 @@ export type FluentBatchCallInput = {
597
601
 
598
602
  | Member | Type | Optional | Experimental | Description |
599
603
  |---|---|---|---|---|
600
- | `id` | `string` | yes | no | |
601
- | `label` | `string` | yes | no | |
604
+ | `id` | `string` | yes | no | The host's own identifier for the call, copied to its `FluentEncodedBatchCall`. |
605
+ | `label` | `string` | yes | no | The call's name in the Review. Defaults to `method`, else "Contract call". |
602
606
  | `to` | `Address` | no | no | |
603
607
  | `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 | |
608
+ | `data` | `Hex` | yes | no | The encoded calldata. When given, `abi`, `method` and `args` are not read. |
609
+ | `abi` | `Abi` | yes | no | The contract's ABI, to encode `method` with `args` when `data` is not given. |
606
610
  | `method` | `string` | yes | no | The ABI function to encode, with `abi` and `args`, when `data` is not given. |
607
- | `args` | `readonly unknown[]` | yes | no | |
611
+ | `args` | `readonly unknown[]` | yes | no | The arguments of `method`. Defaults to `[]`. |
608
612
 
609
613
  ### `FluentBatchOperation`
610
614
 
@@ -681,7 +685,7 @@ export type FluentEncodedBatchCall = {
681
685
 
682
686
  *type*
683
687
 
684
- Result of executing a batch operation.
688
+ The result of executing a Batch operation.
685
689
 
686
690
  ```ts declaration
687
691
  export type FluentExecuteResult = {
@@ -698,13 +702,13 @@ export type FluentExecuteResult = {
698
702
 
699
703
  | Member | Type | Optional | Experimental | Description |
700
704
  |---|---|---|---|---|
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. |
705
+ | `hash` | `Hash` | no | no | The hash of the transaction holding the last call: a Fluent ID's one transaction, or an External wallet's last. |
706
+ | `hashes` | `Hash[]` | no | no | Every transaction hash, in order: one for a Fluent ID, one per call for an External wallet. |
707
+ | `receipt` | `TransactionReceipt` | yes | no | The receipt of `hash` once it is included; not a finality guarantee. |
708
+ | `userOpHash` | `Hash` | yes | no | The ERC-4337 user operation hash, for a Fluent ID. |
709
+ | `atomic` | `boolean` | no | no | `true` when all calls landed in one transaction (a Fluent ID), `false` for an External wallet's one transaction per call. |
706
710
  | `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. |
711
+ | `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. |
708
712
  | `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
713
 
710
714
  ### `FluentGasPayment`
@@ -724,9 +728,8 @@ operation's own calls, and nothing is added for `"ETH"` or for an External walle
724
728
  ```ts declaration
725
729
  export type FluentGasPayment = {
726
730
  /**
727
- * Gas token symbol. The widget resolves the ERC-20 address for the active
728
- * network internally — callers never pass (or risk mistyping) an address.
729
- * `"ETH"` means native gas (no ERC-20 paymaster).
731
+ * The Gas token's symbol, whose address the widget resolves for the Network. `"ETH"` means
732
+ * native gas, with no Gas token paymaster.
730
733
  */
731
734
  symbol: FluentGasTokenSymbol;
732
735
  /**
@@ -737,8 +740,7 @@ export type FluentGasPayment = {
737
740
  * attempt and the result reports `sponsored: false`. What an omitted value means:
738
741
  * [guides/sponsorship.md](guides/sponsorship.md#not-asking-sponsorship-never-and-gas-tokens).
739
742
  *
740
- * Ignored when `symbol` names an ERC-20: that token's own paymaster pays,
741
- * and sponsorship is not in the picture.
743
+ * Ignored when `symbol` names a Gas token, whose own paymaster pays.
742
744
  */
743
745
  sponsorship?: "auto" | "never";
744
746
  } & (
@@ -779,8 +781,8 @@ export type FluentWidgetGasPayment = {
779
781
 
780
782
  *type*
781
783
 
782
- A symbol that can pay for gas. Deliberately `string`: which tokens are
783
- payable is data on the token definitions now, not a fixed set of literals.
784
+ The symbol of a Gas token. A plain `string`, because which tokens are Gas tokens is data on
785
+ the token definitions, not a fixed set of literals.
784
786
 
785
787
  ```ts declaration
786
788
  export type FluentGasTokenSymbol = string;
@@ -810,8 +812,8 @@ export type FluentSignApi = {
810
812
 
811
813
  | Member | Type | Optional | Experimental | Description |
812
814
  |---|---|---|---|---|
813
- | `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) |
814
- | `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) |
815
+ | `signMessage` | `(params: { message: SignableMessage }) => Promise<Hex>` | no | no | Signs `message` (EIP-191) for the Widget account: ERC-1271, or ERC-6492 before deployment, for a Fluent ID, and 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 widget configuration reaches. (example below) |
816
+ | `signTypedData` | `< const typedData extends TypedData \| Record<string, unknown>, primaryType extends keyof typedData \| "EIP712Domain" = keyof typedData, >( typedData: TypedDataDefinition<typedData, primaryType>, ) => Promise<Hex>` | no | no | Signs `typedData` (EIP-712) for the Widget account: ERC-1271, or ERC-6492 before deployment, for a Fluent ID, and 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) |
815
817
 
816
818
  **`signMessage` example**
817
819
 
@@ -870,8 +872,8 @@ Literals: `prompt`, `silent`.
870
872
 
871
873
  *value*
872
874
 
873
- A refused Auth token or X link. `code` is a `FluentAuthErrorCode`; `status` is the service's
874
- HTTP status when the service refused it.
875
+ A refused Auth token request, X link or signature. `code` is a `FluentAuthErrorCode`;
876
+ `status` is the service's HTTP status when the service refused it.
875
877
 
876
878
  ```ts declaration
877
879
  export class FluentAuthError extends Error {
@@ -892,13 +894,12 @@ export class FluentAuthError extends Error {
892
894
 
893
895
  *type*
894
896
 
895
- Why `getAuthToken()`, `linkX()`, or `widget.signMessage()` / `widget.signTypedData()` was
896
- refused (the signatures throw `not_connected` and `root_signer_required`). The codes are the
897
- SDK's own, named for the product rather than for a vendor or a mechanism: where the service
898
- answers with a code of its own, the SDK maps it here before it reaches the App, and a service
899
- code the SDK does not name reaches `getAuthToken()` as `service_refused` and `linkX()` as
900
- `link_failed`. Keep a `default` branch in a
901
- `switch` over them: a later release may add a code.
897
+ The reason `getAuthToken()`, `linkX()`, `widget.signMessage()` or `widget.signTypedData()`
898
+ was refused; the two signing calls throw only `not_connected` and `root_signer_required`.
899
+ The codes are the SDK's own, named for the product rather than for a vendor or a mechanism:
900
+ the SDK maps a service's code to one of them before it reaches the App, and a service code
901
+ the SDK does not name reaches `getAuthToken()` as `service_refused` and `linkX()` as
902
+ `link_failed`. Keep a `default` branch in a `switch` over them: a later release may add one.
902
903
 
903
904
  ```ts declaration
904
905
  export type FluentAuthErrorCode =
@@ -945,8 +946,8 @@ Literals: `address_already_linked`, `app_mismatch`, `app_not_auth_enabled`, `bad
945
946
  A value in `FluentWidgetConfig` the widget refuses to start with.
946
947
 
947
948
  Thrown when `<FluentWidget>` renders with a config it has not resolved yet: on its first
948
- render, and again on any render that passes a new `config` object. So it surfaces at startup
949
- where the integrator is looking rather than at the first send. The message names the option and
949
+ render, and again on any render that passes a new `config` object, so it surfaces at startup
950
+ rather than at the first send. The message names the option and
950
951
  how to fix it; `code`, a `FluentWidgetConfigErrorCode`, is what to branch on.
951
952
 
952
953
  **Example**
@@ -979,13 +980,16 @@ export class FluentWidgetConfigError extends Error {
979
980
 
980
981
  *type*
981
982
 
982
- Which value in `FluentWidgetConfig` was refused, for a host that branches rather than reads
983
+ Which value in `FluentWidgetConfig` was refused, for an App that branches rather than reads
983
984
  the message.
984
985
 
985
986
  ```ts declaration
986
987
  export type FluentWidgetConfigErrorCode =
988
+ /** `execution.feeSource` is neither `"chain"` nor `"bundler"`. */
987
989
  | "invalid_fee_source"
990
+ /** `execution.receiptSource` is neither `"chain"` nor `"bundler"`. */
988
991
  | "invalid_receipt_source"
992
+ /** `execution.chainCheckBeforeSign` is not a boolean. */
989
993
  | "invalid_chain_check_before_sign"
990
994
  /** A required option is absent or empty. */
991
995
  | "missing_option"
@@ -1001,18 +1005,20 @@ Literals: `invalid_chain_check_before_sign`, `invalid_fee_source`, `invalid_opti
1001
1005
 
1002
1006
  *value*
1003
1007
 
1004
- The person dismissed a Review (transaction or signature) instead of confirming it.
1008
+ A Review the person dismissed instead of confirming it: a Batch operation's or a signature's.
1005
1009
 
1006
- A class with a `code`, not a message, so a host branches on `code` and callers that translate
1007
- errors for another party — the iframe bridge maps it to EIP-1193 `4001` — recognise it
1008
- without parsing prose.
1010
+ A class with a `code`, not a message, so an App branches on `code` and callers that translate
1011
+ errors for another party (the Iframe bridge maps it to EIP-1193 `4001`) recognise it without
1012
+ parsing prose.
1009
1013
 
1010
1014
  **Example**
1011
1015
 
1012
1016
  ```ts
1013
1017
  import { FluentReviewRejectedError, type FluentBatchApi } from "@fluent.xyz/connect";
1014
1018
 
1015
- const calls = [{ to: "0x000000000000000000000000000000000000dEaD", value: 1n, data: "0x" }] as const;
1019
+ const calls = [
1020
+ { to: "0x000000000000000000000000000000000000dEaD", value: 1n, data: "0x" },
1021
+ ] as const;
1016
1022
 
1017
1023
  export async function send(widget: FluentBatchApi) {
1018
1024
  try {
@@ -1055,10 +1061,11 @@ Literals: `signature_review_rejected`, `transaction_review_rejected`.
1055
1061
 
1056
1062
  *value*
1057
1063
 
1058
- Both the sponsored submission and the fallback, the account paying its own gas, failed.
1059
- `code` (equal to `sponsorshipReason`) says why Sponsorship was refused: `no_token`, `denied`,
1060
- `unauthorized` or `unreachable`, never `not_requested`. `fallbackError` is what the own-gas
1061
- submission failed with, and `cause` the sponsored submission's error.
1064
+ A Fluent ID's operation whose sponsored submission failed, and whose fallback, the account
1065
+ paying its own gas, failed too. `code` (equal to `sponsorshipReason`) says why Sponsorship was
1066
+ refused: `no_token`, `denied`, `unauthorized` or `unreachable`, never `not_requested`.
1067
+ `fallbackError` is what the own-gas submission failed with, and `cause` the sponsored
1068
+ submission's error.
1062
1069
 
1063
1070
  Neither is the error that was thrown. Each is a plain object `{ name, message, status? }`:
1064
1071
  `name` is the thrown error's name (`"Error"` for a thrown value that is not an `Error`),
@@ -1099,10 +1106,13 @@ export class FluentSponsorshipFallbackError extends Error {
1099
1106
  *type*
1100
1107
 
1101
1108
  Why an operation was not sponsored, and the `code` of a `FluentSponsorshipFallbackError`.
1109
+ `no_token`: no Auth token could be had for the operation. `unauthorized`: the sponsorship
1110
+ service answered HTTP 401 or 403. `unreachable`: the request failed with another HTTP status
1111
+ or none. `denied`: any other failure of the sponsored submission, a policy denial included.
1102
1112
  `not_requested` is the only one that is not a failure: the caller asked to pay its own gas,
1103
1113
  so the sponsorship paymaster was never contacted. For the same reason it is never the error's
1104
1114
  code, which is thrown only after a sponsored attempt failed: the error carries one of the
1105
- other four.
1115
+ other four. See `docs/errors.md` for each code's conditions.
1106
1116
 
1107
1117
  ```ts declaration
1108
1118
  export type FluentSponsorshipReason =
@@ -1167,15 +1177,20 @@ Literals: `insufficient_gas_token`, `paymaster_rejected`, `paymaster_unavailable
1167
1177
 
1168
1178
  *value*
1169
1179
 
1170
- Linking X as a component sees it: the call, and what the last one did.
1180
+ Returns `linkX()` for a component that links X, with what its last call did: `status`, the
1181
+ Linked X account as `x`, and `error`.
1171
1182
 
1172
- `redirecting` is the status a page is unlikely to render for long — it is set just before the
1173
- browser leaves for X — and `linked` after a return is what the mount-time re-entry produces
1174
- without the component asking for anything.
1183
+ `redirecting` is set just before the browser leaves for X, so a page rarely renders it for
1184
+ long. On the return from X the hook calls `linkX()` again on mount, without the component
1185
+ asking, and that call sets `linked`.
1175
1186
 
1176
- **Throws** From `linkX`, as the render context's `linkX()` does: a `FluentAuthError` whose `code`
1177
- is today `not_authenticated`, `user_rejected`, `linked_to_another_user`, `bad_request` or
1178
- `link_failed` (keep a `default` branch); the same error is kept in `error`.
1187
+ **Throws** `FluentAuthError` from the `linkX` it returns, as the render context's `linkX()` does,
1188
+ with `code` `not_authenticated` when no Fluent ID or External wallet is connected or the
1189
+ wallet's client is not ready, `user_rejected` when the person declines at X or a signature the
1190
+ link needs, `linked_to_another_user` when that X account belongs to another person,
1191
+ `bad_request` when the service refuses the request body, and `link_failed` for anything
1192
+ else. The same error is kept in `error`; keep a `default` branch for a code a later release
1193
+ adds.
1179
1194
 
1180
1195
  **Example**
1181
1196
 
@@ -1226,7 +1241,7 @@ leaves for X.
1226
1241
  ```ts declaration
1227
1242
  export type FluentLinkXResult =
1228
1243
  | { status: "linked"; x: FluentXAccount }
1229
- /** The page is leaving for X. Call linkX() again after the return; useLinkX() does it on mount. */
1244
+ /** The page is leaving for X. Call `linkX()` again after the return; `useLinkX()` does. */
1230
1245
  | { status: "redirecting" };
1231
1246
  ```
1232
1247
 
@@ -1234,7 +1249,7 @@ export type FluentLinkXResult =
1234
1249
 
1235
1250
  *type*
1236
1251
 
1237
- One X account as the Fluent auth service reports it.
1252
+ One X account as the Fluent service reports it.
1238
1253
 
1239
1254
  ```ts declaration
1240
1255
  export type FluentXAccount = {
@@ -1246,9 +1261,9 @@ export type FluentXAccount = {
1246
1261
 
1247
1262
  | Member | Type | Optional | Experimental | Description |
1248
1263
  |---|---|---|---|---|
1249
- | `id` | `string` | no | no | |
1250
- | `handle` | `string` | no | no | |
1251
- | `avatarUrl` | `string` | no | no | |
1264
+ | `id` | `string` | no | no | The X account's id. |
1265
+ | `handle` | `string` | no | no | The X account's handle. |
1266
+ | `avatarUrl` | `string` | no | no | The URL of the X account's picture, which the Account avatar shows. |
1252
1267
 
1253
1268
  ## Iframe
1254
1269
 
@@ -1256,20 +1271,18 @@ export type FluentXAccount = {
1256
1271
 
1257
1272
  *value*
1258
1273
 
1259
- Lets a page embedded in `iframeRef` use the account signed in here, over the
1260
- JSON-RPC `postMessage` protocol `@ledgerhq/iframe-provider` speaks. The bridge lives
1261
- while the component is mounted; the bridge states the chain and account before its
1262
- first reply, and sign-in and sign-out reach the iframe as `accountsChanged`.
1274
+ Opens the Iframe bridge: the page embedded in `iframeRef` uses the Widget account as its
1275
+ wallet, over the JSON-RPC `postMessage` protocol `@ledgerhq/iframe-provider` speaks. The
1276
+ bridge lives while the component is mounted, states the chain and account before its first
1277
+ reply, and sends each connect and disconnect to the iframe as `accountsChanged`.
1278
+
1279
+ Throws an `Error`, from the effect that builds the bridge and so to the nearest error
1280
+ boundary, when `allowedOrigin` is not an `http:` or `https:` origin: `"*"` and a bare host
1281
+ are refused.
1263
1282
 
1264
1283
  **Parameter** iframeRef The `<iframe>` the embedded page runs in; read on every message, so an
1265
1284
  element swapped in after mount is still answered.
1266
1285
 
1267
- **Parameter** options `allowedOrigin`, the one origin whose messages are answered.
1268
-
1269
- **Throws** `Error`, from the effect that builds the bridge (so to the nearest error boundary),
1270
- when `allowedOrigin` is not an `http:` or `https:` origin: `"*"` and a bare host are
1271
- refused.
1272
-
1273
1286
  **Example**
1274
1287
 
1275
1288
  ```tsx
@@ -1330,7 +1343,7 @@ export type FluentIframeElement = {
1330
1343
 
1331
1344
  *value*
1332
1345
 
1333
- Fluent mainnet (chain id 25363)
1346
+ The viem chain of Fluent mainnet, chain id `25363`.
1334
1347
 
1335
1348
  ```ts declaration
1336
1349
  export const fluentMainnet: Chain;
@@ -1340,7 +1353,7 @@ export const fluentMainnet: Chain;
1340
1353
 
1341
1354
  *value*
1342
1355
 
1343
- Fluent public testnet (chain id 20994)
1356
+ The viem chain of Fluent testnet, chain id `20994`.
1344
1357
 
1345
1358
  ```ts declaration
1346
1359
  export const fluentTestnet: Chain;
@@ -1367,16 +1380,14 @@ export const explorer = getFluentChainByChainId(20994)?.blockExplorers.default.u
1367
1380
  ```
1368
1381
 
1369
1382
  ```ts declaration
1370
- export function getFluentChainByChainId(
1371
- chainId: number,
1372
- ): FluentChainDefinition | undefined { … }
1383
+ export function getFluentChainByChainId(chainId: number): FluentChainDefinition | undefined { … }
1373
1384
  ```
1374
1385
 
1375
1386
  ### `getFluentChainForNetwork`
1376
1387
 
1377
1388
  *value*
1378
1389
 
1379
- The viem chain of a Network, for a host's own chain config.
1390
+ Returns the viem chain of a Network, for an App's own chain config.
1380
1391
 
1381
1392
  **Example**
1382
1393
 
@@ -1395,9 +1406,7 @@ export function getFluentChainForNetwork(network: FluentWidgetNetwork): Chain {
1395
1406
  *type*
1396
1407
 
1397
1408
  One Fluent chain as the registry describes it: its ids, native currency, RPC and explorer
1398
- endpoints, its L1 parent and its contracts. Declared rather than inferred from
1399
- `fluentChainSchema`, so its shape is what this file says; `chainDefinitionMatchesSchema`
1400
- below fails the build if the two drift apart.
1409
+ endpoints, its L1 parent and its contracts.
1401
1410
 
1402
1411
  ```ts declaration
1403
1412
  export type FluentChainDefinition = {
@@ -1503,13 +1512,14 @@ export type FluentTokenDefinition = {
1503
1512
 
1504
1513
  *type* · **experimental**
1505
1514
 
1506
- Privy runtime supplied by a host using a native SDK. Its Provider owns session
1507
- restoration, login and wallet RPC; web hosts keep the normal React SDK.
1508
- Keep one stable adapter per runtime. Changing its Provider remounts descendants
1509
- so React hooks from different SDKs never share a component lifetime.
1515
+ The Privy runtime an App that runs a native Privy SDK passes as `privyAdapter`, in place of
1516
+ `@privy-io/react-auth`. Its `PrivyProvider` owns session restoration, login and wallet RPC; an
1517
+ App on the web passes none. Keep one stable adapter per runtime: a change of its
1518
+ `PrivyProvider` remounts everything below it, so hooks of two SDKs never share a component
1519
+ lifetime.
1510
1520
 
1511
1521
  **Experimental.** May change or be removed in a minor release: the one provider seam of the
1512
- widget, kept for hosts that run a native login SDK.
1522
+ widget, kept for Apps that run a native login SDK.
1513
1523
 
1514
1524
  ```ts declaration
1515
1525
  export type FluentPrivyAdapter = Pick<
@@ -1562,17 +1572,17 @@ export type FluentExternalWalletState = {
1562
1572
 
1563
1573
  | Member | Type | Optional | Experimental | Description |
1564
1574
  |---|---|---|---|---|
1565
- | `configured` | `boolean` | no | no | |
1566
- | `connected` | `boolean` | no | no | |
1567
- | `address` | `string` | yes | no | |
1568
- | `chainId` | `number` | yes | no | |
1569
- | `walletClient` | `WalletClient` | yes | no | |
1570
- | `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. |
1571
- | `choices` | `readonly FluentWalletChoice[]` | yes | no | Optional inline choices; hosts without them keep their existing open() picker. |
1572
- | `connectChoice` | `(id: string) => Promise<void>` | yes | no | |
1573
- | `open` | `() => void` | no | no | |
1574
- | `disconnect` | `() => void` | no | no | |
1575
- | `switchChain` | `(chainId: number) => Promise<void>` | no | no | |
1575
+ | `configured` | `boolean` | no | no | Whether an External wallet can be connected at all; `false` disables its row in the connect dialog. |
1576
+ | `connected` | `boolean` | no | no | Whether an External wallet is connected. |
1577
+ | `address` | `string` | yes | no | The connected wallet's address. |
1578
+ | `chainId` | `number` | yes | no | The chain the connected wallet reports. |
1579
+ | `walletClient` | `WalletClient` | yes | no | The client the widget signs and sends through, once the client's account is `address`. |
1580
+ | `reconnecting` | `boolean` | yes | no | True while the wallet is being restored from a previous visit and neither `connected` nor "no wallet" is known yet. Without it the widget can report `"disconnected"` during a reload before the wallet is back. |
1581
+ | `choices` | `readonly FluentWalletChoice[]` | yes | no | The wallets the connect dialog offers inline. Without them, or without `connectChoice`, the dialog calls `open` instead. |
1582
+ | `connectChoice` | `(id: string) => Promise<void>` | yes | no | Connects the wallet of the `FluentWalletChoice` with this `id`. |
1583
+ | `open` | `() => void` | no | no | Opens the host's own wallet picker. |
1584
+ | `disconnect` | `() => void` | no | no | Disconnects the External wallet. |
1585
+ | `switchChain` | `(chainId: number) => Promise<void>` | no | no | Asks the wallet to switch to `chainId`; the widget calls it before using the wallet. |
1576
1586
 
1577
1587
  ### `FluentWalletChoice`
1578
1588
 
@@ -1594,10 +1604,10 @@ export type FluentWalletChoice = {
1594
1604
 
1595
1605
  | Member | Type | Optional | Experimental | Description |
1596
1606
  |---|---|---|---|---|
1597
- | `id` | `string` | no | no | |
1598
- | `name` | `string` | no | no | |
1599
- | `icon` | `string` | yes | no | |
1600
- | `handoff` | `boolean` | yes | no | This connector opens an external wallet/QR surface. |
1607
+ | `id` | `string` | no | no | What `connectChoice` is called with when the user picks this wallet. |
1608
+ | `name` | `string` | no | no | The wallet's name, shown on its button. |
1609
+ | `icon` | `string` | yes | no | The URL of the wallet's icon; without it the button shows a generic wallet icon. |
1610
+ | `handoff` | `boolean` | yes | no | Whether this wallet opens a surface of its own, such as a WalletConnect QR code: the connect dialog then closes before connecting it instead of showing its wait screen. |
1601
1611
 
1602
1612
  ### `FluentWidgetExecution`
1603
1613
 
@@ -1642,29 +1652,33 @@ Literals: `bundler`, `chain`.
1642
1652
 
1643
1653
  *type* · **experimental**
1644
1654
 
1645
- Gas policy for a Fluent ID batch. Estimation is enabled unless `skipEstimation` is true.
1646
- Skipping requires account limits. Omit both paymaster limits to use provider-authorized
1647
- paymaster gas and calldata overhead within `preVerificationGas`; supply both to fix all gas.
1648
- The fixed limits are a `FluentFixedAccountGas` and a `FluentFixedPaymasterGas`.
1655
+ The gas policy of a Fluent ID's Batch operation, in one of three shapes.
1656
+
1657
+ `{ callGasLimit }` fixes the execution gas and estimates the rest; `{ callGasBuffer }` estimates
1658
+ and raises the execution gas by the buffer. `{ skipEstimation: true }` estimates nothing: it
1659
+ takes a `FluentFixedAccountGas` and either both paymaster limits of a
1660
+ `FluentFixedPaymasterGas` or neither, in which case the paymaster's authorized limits are used
1661
+ and `preVerificationGas` is the ceiling of its calldata overhead.
1649
1662
 
1650
1663
  **Experimental.** May change or be removed in a minor release while the gas policy is measured;
1651
1664
  omitting it, which lets the widget estimate, is the recommended setting.
1652
1665
 
1653
1666
  ```ts declaration
1654
1667
  export type FluentUserOperationGas =
1655
- | (FluentFixedAccountGas & FluentFixedPaymasterGas & {
1656
- /** Skip the account gas hook and bundler gas estimation. Defaults to false. */
1657
- skipEstimation: true;
1658
- callGasBuffer?: never;
1659
- })
1668
+ | (FluentFixedAccountGas &
1669
+ FluentFixedPaymasterGas & {
1670
+ /** Skip the account gas hook and bundler gas estimation. Defaults to false. */
1671
+ skipEstimation: true;
1672
+ callGasBuffer?: never;
1673
+ })
1660
1674
  | { skipEstimation?: false; callGasLimit: bigint; callGasBuffer?: never }
1661
1675
  | {
1662
1676
  skipEstimation?: false;
1663
1677
  callGasLimit?: never;
1664
1678
  callGasBuffer: {
1665
- /** Extra percent of the bundler estimate, rounded up. Must be a nonnegative safe integer. */
1679
+ /** Extra percent of the estimated execution gas, rounded up. A nonnegative safe integer. */
1666
1680
  percentage?: number;
1667
- /** Extra gas added after the percentage buffer. Must be nonnegative. */
1681
+ /** Extra gas added after the percentage. A nonnegative uint128. */
1668
1682
  fixed?: bigint;
1669
1683
  };
1670
1684
  };
@@ -1674,16 +1688,19 @@ export type FluentUserOperationGas =
1674
1688
 
1675
1689
  *value* · **experimental**
1676
1690
 
1677
- An invalid skip-estimation policy or paymaster authorization for different gas limits.
1678
- `code`, a `FluentUserOperationGasErrorCode`, identifies the failure; `message` names the
1679
- option or gas field to correct.
1691
+ A `skipEstimation` policy that cannot be used, or a paymaster authorization whose gas limits
1692
+ that policy cannot accept. `code` names the failure; `message` names the option or gas field to
1693
+ correct.
1680
1694
 
1681
1695
  **Experimental.** May change or be removed in a minor release while the gas policy is measured;
1682
1696
  omitting it, which lets the widget estimate, is the recommended setting.
1683
1697
 
1684
1698
  ```ts declaration
1685
1699
  export class FluentUserOperationGasError extends Error {
1686
- constructor(readonly code: FluentUserOperationGasErrorCode, message: string) { … }
1700
+ constructor(
1701
+ readonly code: FluentUserOperationGasErrorCode,
1702
+ message: string,
1703
+ ) { … }
1687
1704
  }
1688
1705
  ```
1689
1706
 
@@ -1695,7 +1712,9 @@ export class FluentUserOperationGasError extends Error {
1695
1712
 
1696
1713
  *type* · **experimental**
1697
1714
 
1698
- Reasons explicit gas preparation can fail before signing.
1715
+ The `code` of a `FluentUserOperationGasError`: `invalid_policy` for a `skipEstimation` policy
1716
+ that cannot be used, `paymaster_gas_mismatch` for a paymaster authorization whose gas limits
1717
+ are missing, out of range or differ from the policy's.
1699
1718
 
1700
1719
  **Experimental.** May change or be removed in a minor release while the gas policy is measured;
1701
1720
  omitting it, which lets the widget estimate, is the recommended setting.
@@ -1758,22 +1777,14 @@ export type FluentFixedPaymasterGas = {
1758
1777
 
1759
1778
  Where one send's milliseconds went, stage by stage.
1760
1779
 
1761
- Two clocks, and the difference decides how these numbers may be read. `prepareMs`,
1762
- `signMs`, `broadcastMs`, `retryMs` and `totalMs` are direct monotonic measurements on the
1763
- client (`performance.now()`). `inclusionMs` and `detectMs` are *signed estimates* across the
1764
- client's clock and the chain's: `block.timestamp` has one-second resolution and no relation
1765
- to the browser's clock, so either may legitimately be negative when it is small, and neither
1766
- is clamped — a clamp would turn a known skew into a silent zero. `instants` keeps the inputs,
1767
- so the subtraction can be redone by whoever doubts it.
1768
-
1769
- `totalMs` is measured, not summed: it runs from the start of the first submission to the
1770
- instant the receipt was in hand, and excludes both the smart-account and authentication setup
1771
- before the send and the block read after it. It does not equal the sum of the stages and must
1772
- not be displayed as if it did.
1773
-
1774
- Collected for every send, whatever `debugLogging` is set to — the numbers are the answer to
1775
- "where did the four seconds go", which is a question a host asks in production. A failure
1776
- inside the measuring code costs the stages it could not establish, never the send.
1780
+ `prepareMs`, `signMs`, `broadcastMs`, `retryMs` and `totalMs` are measured on the client's
1781
+ monotonic clock (`performance.now()`). `inclusionMs` and `detectMs` are signed estimates across
1782
+ the client's clock and the chain's `block.timestamp`, which has one-second resolution: either
1783
+ may be negative when small, neither is clamped, and `instants` keeps their inputs. `totalMs`
1784
+ runs from the first submission to the receipt in hand, without the account and authentication
1785
+ setup before it or the block read after, and is not the sum of the stages. Collected for every
1786
+ send, whatever `debugLogging` is set to; a failure in the measuring code loses the stages it
1787
+ could not establish, not the send.
1777
1788
 
1778
1789
  **Experimental.** May change or be removed in a minor release while the numbers are measured.
1779
1790
 
@@ -1792,12 +1803,12 @@ export type FluentExecuteTiming = {
1792
1803
 
1793
1804
  | Member | Type | Optional | Experimental | Description |
1794
1805
  |---|---|---|---|---|
1795
- | `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. |
1806
+ | `prepareMs` | `number` | yes | no | Building the user operation (nonce, gas estimate, paymaster) up to the signature request. Absent when the clock could not be read at that boundary: no stage here is approximated. |
1796
1807
  | `signMs` | `number` | yes | no | Producing the signature. Absent when the settled attempt never got that far. |
1797
1808
  | `broadcastMs` | `number` | yes | no | Handing the signed operation to the bundler. Absent when signing never finished. |
1798
1809
  | `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. |
1799
1810
  | `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. |
1800
- | `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. |
1811
+ | `retryMs` | `number` | no | no | Time spent on submissions that did not settle (a sponsored submission whose Auth token was refused, a refused Sponsorship falling back to own gas) and on the new Auth token between them. It belongs to no stage, is counted inside `totalMs`, and is `0` for one submission. |
1801
1812
  | `totalMs` | `number` | no | no | First submission to receipt in hand. Measured directly; never a sum of the stages. |
1802
1813
  | `instants` | `FluentExecuteTimingInstants` | no | no | The raw instants the signed estimates above were computed from. |
1803
1814