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