@fluent.xyz/connect 0.7.2 → 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/dist/{batchOperation-CIcgSRv5.d.ts → batchOperation-B5Fd0-QX.d.ts} +90 -65
- package/dist/fluent-connect.css +1 -1
- package/dist/index.d.ts +245 -150
- package/dist/index.js +1806 -1018
- package/dist/index.js.map +1 -1
- package/dist/internal.d.ts +78 -28
- package/dist/internal.js +18 -29
- package/dist/internal.js.map +1 -1
- package/dist/polyfills/buffer.js.map +1 -1
- package/docs/api.md +223 -212
- package/docs/concepts.md +8 -0
- package/docs/configuration.md +5 -3
- package/docs/experimental.md +22 -0
- package/docs/getting-started.md +16 -1
- package/package.json +1 -1
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
|
|
80
|
-
| `config` | `FluentWidgetConfig` | no | no |
|
|
81
|
-
| `privyAdapter` | `FluentPrivyAdapter` | yes | **yes** | Optional native Privy SDK bridge, a `FluentPrivyAdapter`, for
|
|
82
|
-
| `mode` | `"home" \| "page"` | yes | no |
|
|
83
|
-
| `connectButton` | `"fixed" \| "inline" \| false` | yes | no |
|
|
84
|
-
| `renderConnectButton` | `(context: FluentWidgetConnectButtonRenderContext) => ReactNode` | yes | no |
|
|
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 |
|
|
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:
|
|
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 |
|
|
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 |
|
|
131
|
-
| `refreshBalances` | `() => void` | no | no |
|
|
132
|
-
| `getAuthToken` | `() => Promise<string>` | no | no |
|
|
133
|
-
| `linkX` | `() => Promise<FluentLinkXResult>` | no | no |
|
|
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 |
|
|
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
|
-
|
|
174
|
-
|
|
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
|
|
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 = [
|
|
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
|
-
|
|
206
|
+
The widget's connection state, safe to read on any render.
|
|
204
207
|
|
|
205
|
-
The distinction that matters is `"restoring"`
|
|
206
|
-
|
|
207
|
-
|
|
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"
|
|
211
|
-
- `"connecting"
|
|
212
|
-
- `"connected"
|
|
213
|
-
|
|
214
|
-
- `"disconnected"
|
|
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
|
|
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"`:
|
|
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 |
|
|
277
|
-
| `capabilities` | `FluentAccountCapabilities` | no | no | What the
|
|
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
|
-
|
|
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 |
|
|
307
|
-
| `erc20Gas` | `boolean` | no | no |
|
|
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
|
|
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 |
|
|
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>`)
|
|
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 |
|
|
417
|
-
| `partnerId` | `never` | yes | no |
|
|
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
|
|
421
|
-
| `enabledAuthMethods` | `FluentWidgetAuthMethod[]` | yes | no |
|
|
422
|
-
| `swapper` | `{ enabled?: boolean; integratorId?: string; dstChainId?: string; dstTokenAddress?: string; }` | yes | **yes** | The
|
|
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 |
|
|
429
|
-
| `gasPayment.sponsorship` | `"auto" \| "never"` | yes | no |
|
|
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
|
|
434
|
-
| `reputationEnabled` | `boolean` | yes | no |
|
|
435
|
-
| `source` | `string` | yes | no |
|
|
436
|
-
| `campaign` | `string` | yes | no |
|
|
437
|
-
| `disableAnalytics` | `boolean` | yes | no | Turns off
|
|
438
|
-
| `reconnectOnMount` | `boolean` | yes | no |
|
|
439
|
-
| `sponsorshipUrl` | `string` | yes | **yes** |
|
|
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
|
|
443
|
-
| `avatar.defaultLogoUrl` | `string` | yes | no |
|
|
444
|
-
| `avatar.forceDefault` | `boolean` | yes | no |
|
|
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
|
-
|
|
463
|
-
|
|
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.
|
|
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
|
|
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
|
|
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.
|
|
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
|
-
|
|
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 |
|
|
702
|
-
| `hashes` | `Hash[]` | no | no |
|
|
703
|
-
| `receipt` | `TransactionReceipt` | yes | no |
|
|
704
|
-
| `userOpHash` | `Hash` | yes | no | ERC-4337 operation hash
|
|
705
|
-
| `atomic` | `boolean` | no | no |
|
|
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
|
|
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
|
|
728
|
-
*
|
|
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
|
|
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
|
-
|
|
783
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
896
|
-
refused
|
|
897
|
-
SDK's own, named for the product rather than for a vendor or a mechanism:
|
|
898
|
-
|
|
899
|
-
|
|
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
|
|
949
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
1007
|
-
errors for another party
|
|
1008
|
-
|
|
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 = [
|
|
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
|
-
|
|
1059
|
-
`code` (equal to `sponsorshipReason`) says why Sponsorship was
|
|
1060
|
-
`unauthorized` or `unreachable`, never `not_requested`.
|
|
1061
|
-
submission failed with, and `cause` the sponsored
|
|
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
|
-
|
|
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
|
|
1173
|
-
|
|
1174
|
-
|
|
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**
|
|
1177
|
-
|
|
1178
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
1260
|
-
JSON-RPC `postMessage` protocol `@ledgerhq/iframe-provider` speaks. The
|
|
1261
|
-
while the component is mounted
|
|
1262
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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.
|
|
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
|
|
1507
|
-
restoration, login and wallet RPC;
|
|
1508
|
-
Keep one stable adapter per runtime
|
|
1509
|
-
so
|
|
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
|
|
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.
|
|
1571
|
-
| `choices` | `readonly FluentWalletChoice[]` | yes | no |
|
|
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 |
|
|
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
|
-
|
|
1646
|
-
|
|
1647
|
-
|
|
1648
|
-
|
|
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 &
|
|
1656
|
-
|
|
1657
|
-
|
|
1658
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
1678
|
-
|
|
1679
|
-
|
|
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(
|
|
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
|
-
|
|
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
|
-
|
|
1762
|
-
|
|
1763
|
-
client
|
|
1764
|
-
|
|
1765
|
-
|
|
1766
|
-
|
|
1767
|
-
|
|
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
|
|
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
|
|
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
|
|