@fluent.xyz/connect 0.5.2 → 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 +9997 -8455
- 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
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
# Experimental API
|
|
2
|
+
|
|
3
|
+
> **Everything on this page is `@experimental`.** Each option, member and export below may
|
|
4
|
+
> change or be removed in a minor release. The rest of the API, every name [api.md](api.md)
|
|
5
|
+
> does not mark **experimental**, is kept after 0.6.0. Build on an experimental name only where
|
|
6
|
+
> you can follow its changes from release to release.
|
|
7
|
+
|
|
8
|
+
Each section says what the item does, its default, when to use it, and which account kind it
|
|
9
|
+
applies to: a Fluent ID, an External wallet, or both. The exact types are in [api.md](api.md).
|
|
10
|
+
|
|
11
|
+
| Name | Where it appears | Section |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| `privyAdapter`, `FluentPrivyAdapter` | `FluentWidgetProps` | [`privyAdapter`](#privyadapter) |
|
|
14
|
+
| `wallet`, `FluentExternalWalletState`, `FluentWalletChoice` | `FluentWidgetProps`, `FluentWidgetRenderContext` | [`wallet`](#wallet) |
|
|
15
|
+
| `execution`, `FluentWidgetExecution`, `FluentWidgetExecutionSource` | `FluentWidgetConfig` | [`execution`](#execution) |
|
|
16
|
+
| `userOperationGas`, `FluentUserOperationGas`, `FluentFixedAccountGas`, `FluentFixedPaymasterGas`, `FluentUserOperationGasError`, `FluentUserOperationGasErrorCode` | `FluentBatchOperationExecuteOptions` | [`userOperationGas`](#useroperationgas) |
|
|
17
|
+
| `paymaster`, `timing`, `FluentExecuteTiming`, `FluentExecuteTimingInstants` | `FluentExecuteResult` | [`paymaster` and `timing`](#paymaster-and-timing) |
|
|
18
|
+
| `gasPayment.ethValueByToken`, `FluentGasPaymentEthRates` | `FluentWidgetConfig` | [`gasPayment.ethValueByToken`](#gaspaymentethvaluebytoken) |
|
|
19
|
+
| `customOAuthRedirectUrl` | `FluentWidgetConfig` | [`customOAuthRedirectUrl`](#customoauthredirecturl) |
|
|
20
|
+
| `swapper` | `FluentWidgetConfig` | [`swapper`](#swapper) |
|
|
21
|
+
| `sponsorshipUrl` | `FluentWidgetConfig` | [`sponsorshipUrl`](#sponsorshipurl) |
|
|
22
|
+
| `privyClientId` | `FluentWidgetConfig` | [`privyClientId`](#privyclientid) |
|
|
23
|
+
|
|
24
|
+
## `privyAdapter`
|
|
25
|
+
|
|
26
|
+
`FluentWidgetProps.privyAdapter` takes a `FluentPrivyAdapter`: the provider component and the
|
|
27
|
+
hooks of Privy's React SDK, taken from the host's own runtime
|
|
28
|
+
([api.md](api.md#fluentprivyadapter)).
|
|
29
|
+
|
|
30
|
+
- **What it does**: the widget uses the adapter's provider and hooks in place of the web SDK it
|
|
31
|
+
bundles, so Direct login, its restore on a later page load and the Signer's signatures run
|
|
32
|
+
through the host's SDK.
|
|
33
|
+
- **Default**: none. Without it the widget uses its bundled web SDK, which is what a web App
|
|
34
|
+
needs.
|
|
35
|
+
- **When to use it**: only in a host that runs Privy's native SDK instead of the web one.
|
|
36
|
+
- **Applies to**: a Fluent ID, and an External wallet's `linkX()`. Connecting an External
|
|
37
|
+
wallet does not use it.
|
|
38
|
+
- **Keep it stable**: pass one adapter object for the life of the page. An adapter whose
|
|
39
|
+
provider component differs from the last one remounts everything the widget renders.
|
|
40
|
+
|
|
41
|
+
## `wallet`
|
|
42
|
+
|
|
43
|
+
`FluentWidgetProps.wallet` takes a `FluentExternalWalletState`: an External wallet the host
|
|
44
|
+
connects itself ([api.md](api.md#fluentexternalwalletstate)).
|
|
45
|
+
|
|
46
|
+
- **What it does**: the widget uses the host's state as its External wallet instead of
|
|
47
|
+
connecting one itself. The state says whether a wallet is `configured` and `connected`, its
|
|
48
|
+
`address`, `chainId` and `walletClient`, and gives the widget `open`, `disconnect` and
|
|
49
|
+
`switchChain` to call. `reconnecting` is `true` while a wallet from an earlier visit is being
|
|
50
|
+
restored; leaving it out makes the widget report `"disconnected"` a little earlier on a
|
|
51
|
+
reload.
|
|
52
|
+
- **Inline choices**: `choices` lists `FluentWalletChoice` entries (`id`, `name`, an optional
|
|
53
|
+
`icon`, and `handoff` for a wallet that opens its own window or a QR code) that the connect
|
|
54
|
+
dialog shows inline; the widget calls `connectChoice(id)` with the one picked. Without them
|
|
55
|
+
the host's `open()` picker is used ([api.md](api.md#fluentwalletchoice)).
|
|
56
|
+
- **Default**: none. Omitted, or `null`, the widget connects External wallets itself.
|
|
57
|
+
- **When to use it**: when the App already manages its own wallet connection and the widget
|
|
58
|
+
has to act for that same wallet.
|
|
59
|
+
- **Applies to**: an External wallet. An External wallet's Batch operation is executed through
|
|
60
|
+
`walletClient`, so the state needs `connected` set to `true` and a `walletClient` for one to be
|
|
61
|
+
sent.
|
|
62
|
+
|
|
63
|
+
`FluentWidgetRenderContext.wallet` (also on `useFluentWidget()`) is the External wallet state the
|
|
64
|
+
widget is using: the host's when the prop is passed, the widget's own otherwise
|
|
65
|
+
([api.md](api.md#fluentwidgetrendercontext)).
|
|
66
|
+
|
|
67
|
+
## `execution`
|
|
68
|
+
|
|
69
|
+
`FluentWidgetConfig.execution` takes a `FluentWidgetExecution`, every field optional
|
|
70
|
+
([api.md](api.md#fluentwidgetexecution)). Both sources are a `FluentWidgetExecutionSource`,
|
|
71
|
+
`"chain"` or `"bundler"` ([api.md](api.md#fluentwidgetexecutionsource)).
|
|
72
|
+
|
|
73
|
+
| Field | Default | What it sets |
|
|
74
|
+
|---|---|---|
|
|
75
|
+
| `feeSource` | `"chain"` | Where a Fluent ID's operation takes its fee quote from: the Fluent chain, or the bundler. |
|
|
76
|
+
| `receiptSource` | `"chain"` | Where the widget watches for the operation's inclusion: the Fluent chain, or the bundler. |
|
|
77
|
+
| `chainCheckBeforeSign` | `false` | `true` reads the Signer's chain before every signature, one extra round trip each. |
|
|
78
|
+
|
|
79
|
+
- **Default**: the values above, on both Networks. A `"chain"` source that fails falls back to
|
|
80
|
+
the bundler on its own, within the operation that needed it. The defaults are the recommended
|
|
81
|
+
setting.
|
|
82
|
+
- **When to use it**: leave it out. Set one field to `"bundler"` to take that one answer from
|
|
83
|
+
the bundler for every operation, for example while diagnosing slow operations with Fluent.
|
|
84
|
+
- **Applies to**: a Fluent ID. `chainCheckBeforeSign` covers both its Batch operations and its
|
|
85
|
+
`signMessage` and `signTypedData` signatures. An External wallet ignores `execution`.
|
|
86
|
+
- **Invalid values**: `<FluentWidget>` throws `FluentWidgetConfigError` from its render, with
|
|
87
|
+
`code` `invalid_fee_source`, `invalid_receipt_source` or `invalid_chain_check_before_sign`
|
|
88
|
+
([errors.md](errors.md#fluentwidgetconfigerror)).
|
|
89
|
+
|
|
90
|
+
## `userOperationGas`
|
|
91
|
+
|
|
92
|
+
`userOperationGas` is an option of `execute()`, on `FluentBatchOperationExecuteOptions`. It takes
|
|
93
|
+
a `FluentUserOperationGas`, one of three shapes ([api.md](api.md#fluentuseroperationgas)):
|
|
94
|
+
|
|
95
|
+
| Shape | What the widget does |
|
|
96
|
+
|---|---|
|
|
97
|
+
| `{ callGasLimit }` | Uses this execution gas limit for the whole Batch operation, any Gas token approval included, and estimates the rest. |
|
|
98
|
+
| `{ callGasBuffer: { percentage?, fixed? } }` | Estimates, then adds `percentage` percent (rounded up), then `fixed` gas. |
|
|
99
|
+
| `{ skipEstimation: true, ... }` | Estimates nothing: the App fixes the account's limits, and either fixes the paymaster's too or leaves them to the paymaster. |
|
|
100
|
+
|
|
101
|
+
With `skipEstimation: true`, the account's three limits are a `FluentFixedAccountGas`
|
|
102
|
+
(`callGasLimit`, `verificationGasLimit`, `preVerificationGas`, all required), and the
|
|
103
|
+
paymaster's two are a `FluentFixedPaymasterGas` (`paymasterVerificationGasLimit` and
|
|
104
|
+
`paymasterPostOpGasLimit`): pass both, or neither to use the limits the paymaster authorizes
|
|
105
|
+
([api.md](api.md#fluentfixedaccountgas), [api.md](api.md#fluentfixedpaymastergas)).
|
|
106
|
+
|
|
107
|
+
- **Default**: omitted, the widget estimates every limit. Omitting it is the recommended
|
|
108
|
+
setting.
|
|
109
|
+
- **When to use it**: a buffer when an operation's estimate runs short; fixed limits when the
|
|
110
|
+
App knows them and wants no estimate.
|
|
111
|
+
- **Applies to**: the policy's shape is checked at the start of every `execute()`, before the
|
|
112
|
+
Review, whatever the account kind, so an invalid shape rejects for an External wallet too. It
|
|
113
|
+
shapes only a Fluent ID's operation: an External wallet's operation ignores a valid policy.
|
|
114
|
+
- **Errors**: `execute()` rejects with `FluentUserOperationGasError`, whose `code` is a
|
|
115
|
+
`FluentUserOperationGasErrorCode` ([errors.md](errors.md#fluentuseroperationgaserror),
|
|
116
|
+
[api.md](api.md#fluentuseroperationgaserror)). A `skipEstimation` policy of the wrong shape is
|
|
117
|
+
`invalid_policy`. Two more checks of a `skipEstimation` policy run at submission, and only
|
|
118
|
+
when a paymaster pays: only one of the two paymaster limits is `invalid_policy`, and a
|
|
119
|
+
paymaster authorization that does not match the fixed limits is `paymaster_gas_mismatch`.
|
|
120
|
+
For a Gas token payment they reject. Under Sponsorship they fail the sponsored submission
|
|
121
|
+
instead, and the operation falls back to the account's own gas
|
|
122
|
+
([guides/sponsorship.md](guides/sponsorship.md)). An invalid `callGasLimit` or
|
|
123
|
+
`callGasBuffer` without `skipEstimation` rejects with a plain `Error`. Keep a `default` branch
|
|
124
|
+
in any `switch` over the code.
|
|
125
|
+
|
|
126
|
+
This component adds a fifth to the estimate and logs where the time went:
|
|
127
|
+
|
|
128
|
+
```tsx
|
|
129
|
+
import { useFluentWidget } from "@fluent.xyz/connect";
|
|
130
|
+
import { parseEther, type Address } from "viem";
|
|
131
|
+
|
|
132
|
+
const RECIPIENT: Address = "0x0000000000000000000000000000000000000001";
|
|
133
|
+
|
|
134
|
+
export function TipWithHeadroom() {
|
|
135
|
+
const { widget, status } = useFluentWidget();
|
|
136
|
+
if (status !== "connected") return null;
|
|
137
|
+
const tip = async () => {
|
|
138
|
+
const result = await widget
|
|
139
|
+
.createBatchOp({ calls: [{ to: RECIPIENT, value: parseEther("0.001"), data: "0x" }] })
|
|
140
|
+
.execute({ userOperationGas: { callGasBuffer: { percentage: 20 } } });
|
|
141
|
+
console.log(result.timing?.totalMs, result.paymaster);
|
|
142
|
+
};
|
|
143
|
+
return <button onClick={() => void tip()}>Tip 0.001 ETH</button>;
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## `paymaster` and `timing`
|
|
148
|
+
|
|
149
|
+
Two members of `FluentExecuteResult`, what `execute()` resolves with
|
|
150
|
+
([api.md](api.md#fluentexecuteresult)).
|
|
151
|
+
|
|
152
|
+
`paymaster` is the address of the contract that paid the operation's gas, read off a Fluent ID's
|
|
153
|
+
receipt: the Sponsorship paymaster or a Gas token's paymaster.
|
|
154
|
+
|
|
155
|
+
- **Absent**: always for an External wallet, whose `sponsored` is always `false`. For a Fluent
|
|
156
|
+
ID, whenever the receipt names no paymaster, which includes an operation the account paid for
|
|
157
|
+
itself; `sponsored` is then `false`, or `null` after a sponsored submission.
|
|
158
|
+
- **When to use it**: to log or check which contract paid. To know whether Sponsorship paid,
|
|
159
|
+
read the kept `sponsored` member instead.
|
|
160
|
+
|
|
161
|
+
`timing` is a `FluentExecuteTiming`: where one operation's milliseconds went
|
|
162
|
+
([api.md](api.md#fluentexecutetiming)).
|
|
163
|
+
|
|
164
|
+
- `prepareMs`, `signMs` and `broadcastMs` are measured on the page's clock, and each is absent
|
|
165
|
+
when the widget could not measure it. `retryMs` is the time spent on submissions that did not
|
|
166
|
+
settle, such as a refused Sponsorship before the fallback, and is `0` for an operation
|
|
167
|
+
submitted once.
|
|
168
|
+
- `inclusionMs` and `detectMs` are signed estimates across the page's clock and the chain's,
|
|
169
|
+
so either can be negative when it is small. Both are absent when the including block could
|
|
170
|
+
not be read.
|
|
171
|
+
- `totalMs` runs from the first submission to the receipt. It is measured, not summed, and does
|
|
172
|
+
not equal the sum of the parts.
|
|
173
|
+
- `instants`, a `FluentExecuteTimingInstants`, keeps the epoch-millisecond instants and the
|
|
174
|
+
number of `attempts` the estimates were computed from
|
|
175
|
+
([api.md](api.md#fluentexecutetiminginstants)).
|
|
176
|
+
- **Absent**: always for an External wallet, whose wallet does its prompt, signing and
|
|
177
|
+
broadcast in one call; and for a Fluent ID when the page's clock could not be read.
|
|
178
|
+
- **When to use it**: for logs and latency dashboards. It is collected for every Fluent ID
|
|
179
|
+
operation, whatever `debugLogging` is set to.
|
|
180
|
+
|
|
181
|
+
## `gasPayment.ethValueByToken`
|
|
182
|
+
|
|
183
|
+
`FluentWidgetConfig.gasPayment.ethValueByToken` takes a `FluentGasPaymentEthRates`: what one
|
|
184
|
+
unit of each Gas token is worth in ETH, as a decimal string, keyed by its `FluentGasTokenSymbol`
|
|
185
|
+
([api.md](api.md#fluentgaspaymentethrates)).
|
|
186
|
+
|
|
187
|
+
- **What it does**: sets the rates behind the cost the widget shows beside each Gas token.
|
|
188
|
+
- **Default**: the widget works the rates out from the USD prices it reads for the Gas tokens,
|
|
189
|
+
where it has them, with ETH at `"1"`. A rate set here wins over the derived one for its
|
|
190
|
+
symbol; the others stay derived. The defaults are the recommended setting.
|
|
191
|
+
- **When to use it**: when the costs the widget shows for a Gas token are wrong for your App.
|
|
192
|
+
- **Applies to**: a Fluent ID, the only account kind that pays in a Gas token. An External
|
|
193
|
+
wallet pays its gas in ETH.
|
|
194
|
+
|
|
195
|
+
## `customOAuthRedirectUrl`
|
|
196
|
+
|
|
197
|
+
`FluentWidgetConfig.customOAuthRedirectUrl` is passed to the provider behind Direct login as
|
|
198
|
+
its OAuth redirect URL ([api.md](api.md#fluentwidgetconfig)). The widget reads it nowhere else.
|
|
199
|
+
|
|
200
|
+
- **Default**: omitted, no redirect URL is passed.
|
|
201
|
+
- **When to use it**: in a Capacitor or other native app, where an OAuth return has to land on a
|
|
202
|
+
Universal Link that the host app handles.
|
|
203
|
+
- **Requirements**: an absolute HTTPS URL, with no credentials, query string or fragment.
|
|
204
|
+
Anything else makes `<FluentWidget>` throw `FluentWidgetConfigError` with `code`
|
|
205
|
+
`invalid_option` ([errors.md](errors.md#fluentwidgetconfigerror)); a blank string counts as
|
|
206
|
+
omitted. The exact URL must also be registered with Fluent among the allowed redirects of the
|
|
207
|
+
App's login client.
|
|
208
|
+
- **Applies to**: the OAuth flows of the provider behind Direct login. Which of them return to
|
|
209
|
+
this URL is the provider's to decide, not the widget's.
|
|
210
|
+
|
|
211
|
+
## `swapper`
|
|
212
|
+
|
|
213
|
+
`FluentWidgetConfig.swapper` sets up the on-ramp that the account drawer's Get USDnr button
|
|
214
|
+
opens: `enabled`, `integratorId`, `dstChainId` and `dstTokenAddress`
|
|
215
|
+
([api.md](api.md#fluentwidgetconfig)).
|
|
216
|
+
|
|
217
|
+
- **Default**: `enabled` is `true`, and the other three are Fluent's own: the on-ramp buys
|
|
218
|
+
USDnr on Fluent mainnet. The defaults are the recommended setting.
|
|
219
|
+
- **When to use it**: `enabled: false` turns the on-ramp off; Get USDnr is then disabled, with
|
|
220
|
+
"Not configured for this app" on hover.
|
|
221
|
+
- **Applies to**: a Fluent ID on mainnet. The on-ramp delivers to the Fluent ID's address, so
|
|
222
|
+
Get USDnr is disabled while no Fluent ID is connected. On testnet, Get USDnr mints testnet
|
|
223
|
+
USDnr instead and `swapper` is not read.
|
|
224
|
+
|
|
225
|
+
## `sponsorshipUrl`
|
|
226
|
+
|
|
227
|
+
`FluentWidgetConfig.sponsorshipUrl` points the widget at a sponsorship service other than the
|
|
228
|
+
Network's own ([api.md](api.md#fluentwidgetconfig)).
|
|
229
|
+
|
|
230
|
+
- **Default**: the deployed sponsorship service of the configured Network.
|
|
231
|
+
- **When to use it**: local development of the sponsorship service only. Every real
|
|
232
|
+
integration uses the default.
|
|
233
|
+
- **Applies to**: Sponsorship of a Fluent ID's operations. An External wallet is never
|
|
234
|
+
sponsored.
|
|
235
|
+
|
|
236
|
+
## `privyClientId`
|
|
237
|
+
|
|
238
|
+
`FluentWidgetConfig.privyClientId` is the login client Fluent issues for the App, a `client-…`
|
|
239
|
+
value ([api.md](api.md#fluentwidgetconfig)). It carries the origins allow-listed for Direct
|
|
240
|
+
login; `appId` is what names the App for Sponsorship, Auth tokens and analytics.
|
|
241
|
+
|
|
242
|
+
- **Default**: none. It is required today although it is marked experimental: it exists while
|
|
243
|
+
login runs on the current provider, and goes when Fluent's own login replaces it.
|
|
244
|
+
- **Errors**: `<FluentWidget>` throws `FluentWidgetConfigError` with `code` `missing_option`
|
|
245
|
+
when it is absent or empty, and `invalid_option` when it does not start with `client-`, an
|
|
246
|
+
`app_…` id included ([errors.md](errors.md#fluentwidgetconfigerror)).
|
|
247
|
+
- **Applies to**: every App, whatever account kind its users connect.
|
|
@@ -0,0 +1,336 @@
|
|
|
1
|
+
# Getting started
|
|
2
|
+
|
|
3
|
+
This guide takes a React App from nothing to a mounted widget that reads the Widget account. It
|
|
4
|
+
covers what to ask Fluent for, the install, the styles, the Network, mounting `<FluentWidget>`,
|
|
5
|
+
the connect button, reading the account, and debugging. The terms it uses (Fluent ID, External
|
|
6
|
+
wallet, Widget account, Widget session) are defined in [concepts.md](concepts.md); every option
|
|
7
|
+
of `config` is in [configuration.md](configuration.md).
|
|
8
|
+
|
|
9
|
+
## What you need from Fluent
|
|
10
|
+
|
|
11
|
+
Ask Fluent for these before you write any code:
|
|
12
|
+
|
|
13
|
+
- **`appId`**: the App's id, `app_` followed by 32 lowercase hex characters, as the Fluent
|
|
14
|
+
Dashboard shows it.
|
|
15
|
+
- **`privyClientId`**: the login client Fluent issues for the App, a `client-…` value. It is
|
|
16
|
+
required today and is marked experimental, because it goes away when Fluent's own login
|
|
17
|
+
replaces it ([experimental.md](experimental.md#privyclientid)).
|
|
18
|
+
- **Your page origins allow-listed for Direct login**: Direct login happens in the App's own
|
|
19
|
+
page, so every origin the App is served from, a development origin included, has to be
|
|
20
|
+
allow-listed for the App's login client beforehand.
|
|
21
|
+
- **For `getAuthToken()`, Sponsorship, `linkX()` and User settings**: Auth tokens enabled for
|
|
22
|
+
the App, and each page origin that calls it registered on the App. Without them
|
|
23
|
+
`getAuthToken()` rejects with `FluentAuthError` and `code` `app_not_auth_enabled` or
|
|
24
|
+
`origin_not_allowed` ([errors.md](errors.md#fluentautherror)), a Fluent ID's operations are not
|
|
25
|
+
sponsored, `linkX()` cannot complete a link, and a person's User settings are neither loaded
|
|
26
|
+
nor saved. See [guides/backend-auth.md](guides/backend-auth.md).
|
|
27
|
+
- **For Sponsorship, the App enabled for Sponsorship**: without it a Fluent ID's operations are
|
|
28
|
+
not sponsored ([guides/sponsorship.md](guides/sponsorship.md)).
|
|
29
|
+
|
|
30
|
+
## Install
|
|
31
|
+
|
|
32
|
+
Install the package and its peer dependencies:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
pnpm add @fluent.xyz/connect @tanstack/react-query react react-dom viem wagmi
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
The peers are `@tanstack/react-query` 5, `react` and `react-dom` 18 or later, `viem` 2 and
|
|
39
|
+
`wagmi` 2. They are peers rather than dependencies so that your App and the widget resolve one
|
|
40
|
+
copy of each: the `viem` types the Widget API takes and returns (an `Address`, a `Hex`, an
|
|
41
|
+
`Abi`) are the ones your own code imports.
|
|
42
|
+
|
|
43
|
+
You do not need a `QueryClientProvider`. The widget mounts a TanStack Query client of its own.
|
|
44
|
+
When your App mounts its own `QueryClientProvider` around `<FluentWidget>`, the content your
|
|
45
|
+
`renderPage` or `renderHome` returns is rendered under your client again, so a query your App
|
|
46
|
+
prefetched or hydrated is read from your cache; the widget's own queries stay on its client.
|
|
47
|
+
|
|
48
|
+
You do not need a `Buffer` polyfill either. Importing `@fluent.xyz/connect` defines
|
|
49
|
+
`globalThis.Buffer` when the page has none, and leaves an existing one in place.
|
|
50
|
+
|
|
51
|
+
## Styles
|
|
52
|
+
|
|
53
|
+
Import the widget's stylesheet once, in your App's entry module:
|
|
54
|
+
|
|
55
|
+
```tsx
|
|
56
|
+
import "@fluent.xyz/connect/styles.css";
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Network
|
|
60
|
+
|
|
61
|
+
`config.network` names the Network the widget runs on: `"testnet"` or `"mainnet"`. It is
|
|
62
|
+
required and has no default, and the widget reads no environment variable for it. Rendering
|
|
63
|
+
`<FluentWidget>` with no `network` throws `FluentWidgetConfigError` with `code`
|
|
64
|
+
`missing_option`; a value other than the two throws it with `code` `invalid_option`
|
|
65
|
+
([errors.md](errors.md#fluentwidgetconfigerror)). The error is thrown during the render, so the
|
|
66
|
+
nearest error boundary catches it.
|
|
67
|
+
|
|
68
|
+
The Network is chosen once per deployment of the App, and choosing it is your App's own code.
|
|
69
|
+
Pass the literal each deployment runs on: for example one config module per deployment, each
|
|
70
|
+
with its own literal, or a build-time constant of your own that your code checks is exactly
|
|
71
|
+
`"testnet"` or `"mainnet"` before it reaches `config`. Do not map an unknown value to one of the
|
|
72
|
+
two: a production build with a misspelled value would then run on the wrong Network.
|
|
73
|
+
|
|
74
|
+
```ts
|
|
75
|
+
import type { FluentWidgetConfig } from "@fluent.xyz/connect";
|
|
76
|
+
|
|
77
|
+
// config.testnet.ts; the mainnet deployment's module passes network: "mainnet".
|
|
78
|
+
export const config: FluentWidgetConfig = {
|
|
79
|
+
appId: "app_0123456789abcdef0123456789abcdef",
|
|
80
|
+
privyClientId: "client-0123456789abcdef",
|
|
81
|
+
network: "testnet",
|
|
82
|
+
};
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Keep `config` stable: a module constant, as here, or a memo. The widget resolves `config` again
|
|
86
|
+
on every render that passes a new object, and such a render can throw too.
|
|
87
|
+
|
|
88
|
+
## Mount the widget
|
|
89
|
+
|
|
90
|
+
`<FluentWidget>` renders the connect button, the connect dialog and the account drawer, and
|
|
91
|
+
hands your App's content the widget's render context. `mode` picks which of your two render
|
|
92
|
+
functions it calls:
|
|
93
|
+
|
|
94
|
+
- `mode="home"`, the default, calls `renderHome`.
|
|
95
|
+
- `mode="page"` calls `renderPage`.
|
|
96
|
+
|
|
97
|
+
Each receives the render context, a `FluentWidgetRenderContext`. Any component rendered inside
|
|
98
|
+
that content can read the same object with `useFluentWidget()`, so you do not have to pass it
|
|
99
|
+
down. `useFluentWidget()` throws an `Error` when it is called outside the content of
|
|
100
|
+
`<FluentWidget>`, the button `renderConnectButton` returns included: that button receives its
|
|
101
|
+
own context, described below.
|
|
102
|
+
|
|
103
|
+
```tsx
|
|
104
|
+
import "@fluent.xyz/connect/styles.css";
|
|
105
|
+
import { FluentWidget, useFluentWidget, type FluentWidgetConfig } from "@fluent.xyz/connect";
|
|
106
|
+
|
|
107
|
+
const config: FluentWidgetConfig = {
|
|
108
|
+
appId: "app_0123456789abcdef0123456789abcdef",
|
|
109
|
+
privyClientId: "client-0123456789abcdef",
|
|
110
|
+
network: "testnet",
|
|
111
|
+
};
|
|
112
|
+
|
|
113
|
+
function Dashboard() {
|
|
114
|
+
const { status, widget } = useFluentWidget();
|
|
115
|
+
if (status !== "connected") return <p>Connect to continue.</p>;
|
|
116
|
+
return <p>Your account: {widget.account.address}</p>;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
export function Root() {
|
|
120
|
+
return <FluentWidget config={config} mode="page" renderPage={() => <Dashboard />} />;
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
## The connect button
|
|
125
|
+
|
|
126
|
+
`connectButton` decides where the widget's own button goes:
|
|
127
|
+
|
|
128
|
+
- `"fixed"`, the default: a floating button at the top right of the page.
|
|
129
|
+
- `"inline"`: the same button without fixed positioning, for your own layout to place.
|
|
130
|
+
- `false`: no button; open the widget's screens yourself.
|
|
131
|
+
|
|
132
|
+
The button opens the connect dialog while no Widget account is connected, and toggles the
|
|
133
|
+
account drawer once one is.
|
|
134
|
+
|
|
135
|
+
To draw your own button in that place, pass `renderConnectButton`. It receives a
|
|
136
|
+
`FluentWidgetConnectButtonRenderContext`: `connected`, `pending` (true while a Fluent ID's
|
|
137
|
+
account is being prepared), `addressLabel` (once connected, the shortened
|
|
138
|
+
address, or `"Connected"`), `userAvatarUrl`, `userXDisplayName` and `userGoogleName` (the same
|
|
139
|
+
values as the render context's, see [Account name](#account-name)), `onClick` (what the default
|
|
140
|
+
button does on click),
|
|
141
|
+
`openConnect`, `openAccount`, and `DefaultButton`, which renders the widget's own button. When
|
|
142
|
+
`renderConnectButton` returns `null` or `undefined`, the widget falls back to the button
|
|
143
|
+
`connectButton` names.
|
|
144
|
+
|
|
145
|
+
```tsx
|
|
146
|
+
import { FluentWidget, type FluentWidgetConfig } from "@fluent.xyz/connect";
|
|
147
|
+
|
|
148
|
+
const config: FluentWidgetConfig = {
|
|
149
|
+
appId: "app_0123456789abcdef0123456789abcdef",
|
|
150
|
+
privyClientId: "client-0123456789abcdef",
|
|
151
|
+
network: "testnet",
|
|
152
|
+
};
|
|
153
|
+
|
|
154
|
+
export function Root() {
|
|
155
|
+
return (
|
|
156
|
+
<FluentWidget
|
|
157
|
+
config={config}
|
|
158
|
+
renderConnectButton={({ connected, onClick, DefaultButton }) =>
|
|
159
|
+
connected ? (
|
|
160
|
+
<DefaultButton />
|
|
161
|
+
) : (
|
|
162
|
+
<button type="button" onClick={onClick}>
|
|
163
|
+
Connect
|
|
164
|
+
</button>
|
|
165
|
+
)
|
|
166
|
+
}
|
|
167
|
+
renderHome={() => <main>Your App</main>}
|
|
168
|
+
/>
|
|
169
|
+
);
|
|
170
|
+
}
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
With `connectButton={false}`, open the screens from your own content with the render context's
|
|
174
|
+
`openConnect` (the connect dialog) and `openAccount` (the account drawer). `openConnect` ignores
|
|
175
|
+
a click event passed to it, so it can be handed straight to `onClick`. The example after the
|
|
176
|
+
next section shows both.
|
|
177
|
+
|
|
178
|
+
## Reading the account
|
|
179
|
+
|
|
180
|
+
The render context, and `useFluentWidget()`, tell your App who is connected:
|
|
181
|
+
|
|
182
|
+
- **`status`**, a `FluentWidgetStatus`: `"restoring"` (a session from a previous visit may
|
|
183
|
+
exist and nothing is decided yet), `"connecting"` (a Fluent ID's login is done and its account
|
|
184
|
+
is being prepared, after a Direct login or on a restore), `"connected"` (a Widget account is
|
|
185
|
+
connected) or `"disconnected"`. Branch on `status`, not on `hasConnectedAccount` alone:
|
|
186
|
+
`hasConnectedAccount` is `false` both while a stored session is being restored and when
|
|
187
|
+
nobody is connected, and treating the two alike shows a Connect button to a person who is
|
|
188
|
+
already connected.
|
|
189
|
+
- **`hasConnectedAccount`**: whether a Widget account, a Fluent ID or an External wallet, is
|
|
190
|
+
connected now.
|
|
191
|
+
- **`widget.account`**, a `FluentWidgetAccount`: `address` (the Fluent ID's address, or the
|
|
192
|
+
External wallet's; `undefined` while there is none), `type` (`"smart"` for a Fluent ID whose
|
|
193
|
+
account is ready, `"eoa"` for a connected External wallet, `undefined` otherwise),
|
|
194
|
+
`executionReady` (whether the account can send now), `executionStatus` (`"ready"`, or why it
|
|
195
|
+
cannot send: `"disconnected"`, which is also what a Fluent ID still being prepared, or whose
|
|
196
|
+
account failed, reads; `"unavailable"` or `"error"` only for a connected External wallet whose
|
|
197
|
+
client is not ready), and `capabilities` (`atomicBatch` and `erc20Gas`, both `true` only for a
|
|
198
|
+
Fluent ID). While no External wallet is connected, `address` falls back to the address of the
|
|
199
|
+
stored Widget session, so it can be set while `status` is not `"connected"`: branch on
|
|
200
|
+
`status` before you use it.
|
|
201
|
+
- **`session`**, a `FluentWidgetSession` or `null`: the Widget session, which holds the Fluent ID's
|
|
202
|
+
`account` (`address` and `type`) and `issuedAt`. It is `null` until a Fluent ID connects, and
|
|
203
|
+
an External wallet never sets it: read an External wallet from `widget.account`. A session
|
|
204
|
+
stored on a previous visit is in `session` from the first render, without any callback, and
|
|
205
|
+
stays there until a disconnect through the widget or a new Direct login replaces it, even while
|
|
206
|
+
`status` is `"disconnected"` or only an External wallet is connected. The session is not a
|
|
207
|
+
credential; to prove who the person is to your backend, use an Auth token
|
|
208
|
+
([guides/backend-auth.md](guides/backend-auth.md)).
|
|
209
|
+
|
|
210
|
+
```tsx
|
|
211
|
+
import { useFluentWidget } from "@fluent.xyz/connect";
|
|
212
|
+
|
|
213
|
+
export function AccountBar() {
|
|
214
|
+
const { status, widget, openConnect, openAccount } = useFluentWidget();
|
|
215
|
+
switch (status) {
|
|
216
|
+
case "connected":
|
|
217
|
+
return (
|
|
218
|
+
<button type="button" onClick={openAccount}>
|
|
219
|
+
{widget.account.address ?? "Connected"}
|
|
220
|
+
</button>
|
|
221
|
+
);
|
|
222
|
+
case "disconnected":
|
|
223
|
+
return (
|
|
224
|
+
<button type="button" onClick={openConnect}>
|
|
225
|
+
Connect
|
|
226
|
+
</button>
|
|
227
|
+
);
|
|
228
|
+
default:
|
|
229
|
+
// "restoring", "connecting", and any status a later release adds.
|
|
230
|
+
return <span>Loading…</span>;
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
Keep a `default` branch in any `switch` over `status` or another code or status union: a later
|
|
236
|
+
release may add a value.
|
|
237
|
+
|
|
238
|
+
A Fluent ID can sign without the widget's Review, under Quick sign: see
|
|
239
|
+
[concepts.md](concepts.md#prompt-mode-and-silent-mode).
|
|
240
|
+
|
|
241
|
+
`onSessionChange` is called each time the widget writes its Widget session: with the new
|
|
242
|
+
`FluentWidgetSession` when a Fluent ID connects by Direct login, and with `null` on a disconnect
|
|
243
|
+
through the widget. It is not called for a session restored from storage when the widget mounts,
|
|
244
|
+
nor when an External wallet connects; read `session` and `widget.account` from the render
|
|
245
|
+
context for those. One exception: when a restored login has no matching stored session, the
|
|
246
|
+
widget writes a new one after it mounts and calls `onSessionChange` with it.
|
|
247
|
+
|
|
248
|
+
```tsx
|
|
249
|
+
import {
|
|
250
|
+
FluentWidget,
|
|
251
|
+
type FluentWidgetConfig,
|
|
252
|
+
type FluentWidgetSession,
|
|
253
|
+
} from "@fluent.xyz/connect";
|
|
254
|
+
|
|
255
|
+
const config: FluentWidgetConfig = {
|
|
256
|
+
appId: "app_0123456789abcdef0123456789abcdef",
|
|
257
|
+
privyClientId: "client-0123456789abcdef",
|
|
258
|
+
network: "testnet",
|
|
259
|
+
};
|
|
260
|
+
|
|
261
|
+
function handleSessionChange(session: FluentWidgetSession | null) {
|
|
262
|
+
console.info(session ? `Connected: ${session.account.address}` : "Disconnected");
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
export function Root() {
|
|
266
|
+
return (
|
|
267
|
+
<FluentWidget
|
|
268
|
+
config={config}
|
|
269
|
+
onSessionChange={handleSessionChange}
|
|
270
|
+
renderHome={({ status }) => <p>Status: {status}</p>}
|
|
271
|
+
/>
|
|
272
|
+
);
|
|
273
|
+
}
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
### Account name
|
|
277
|
+
|
|
278
|
+
The render context, `useFluentWidget()` and the context `renderConnectButton` receives carry the
|
|
279
|
+
names the person is known by: `userXDisplayName`, the display name of their linked X account (the
|
|
280
|
+
name X shows above the handle, not the handle), and `userGoogleName`, the name on the Google
|
|
281
|
+
account linked to their Direct login. Each is `undefined` when no such account is linked or it
|
|
282
|
+
reports no name, and while an External wallet is connected without a Fluent ID.
|
|
283
|
+
`avatar.forceDefault` hides the Account avatar's picture only and leaves both names in place.
|
|
284
|
+
Neither is a fallback for the other: a person with Google linked and no X account has no X
|
|
285
|
+
display name, so pick your own order.
|
|
286
|
+
|
|
287
|
+
```tsx
|
|
288
|
+
import { useFluentWidget } from "@fluent.xyz/connect";
|
|
289
|
+
|
|
290
|
+
export function Greeting() {
|
|
291
|
+
const { userXDisplayName, userGoogleName } = useFluentWidget();
|
|
292
|
+
const name = userXDisplayName ?? userGoogleName;
|
|
293
|
+
return <span>{name ? `Hi, ${name}` : "Hi"}</span>;
|
|
294
|
+
}
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
## Debugging
|
|
298
|
+
|
|
299
|
+
`debugLogging` prints the widget's connect, account and signing diagnostics to the browser
|
|
300
|
+
console, and in `mode="home"` also shows the widget's debug panel. It is off by default; turn it
|
|
301
|
+
on only while debugging an integration.
|
|
302
|
+
|
|
303
|
+
```tsx
|
|
304
|
+
import { FluentWidget, type FluentWidgetConfig } from "@fluent.xyz/connect";
|
|
305
|
+
|
|
306
|
+
const config: FluentWidgetConfig = {
|
|
307
|
+
appId: "app_0123456789abcdef0123456789abcdef",
|
|
308
|
+
privyClientId: "client-0123456789abcdef",
|
|
309
|
+
network: "testnet",
|
|
310
|
+
};
|
|
311
|
+
|
|
312
|
+
export function Root() {
|
|
313
|
+
return <FluentWidget config={config} debugLogging renderHome={() => <main>Your App</main>} />;
|
|
314
|
+
}
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
When the widget refuses its `config`, the error's message names the option and how to fix it,
|
|
318
|
+
and its `code` is listed in [errors.md](errors.md#fluentwidgetconfigerror).
|
|
319
|
+
|
|
320
|
+
## Checklist
|
|
321
|
+
|
|
322
|
+
- `appId` and `privyClientId` from Fluent, and every page origin allow-listed for Direct login.
|
|
323
|
+
- For `getAuthToken()`, Sponsorship, `linkX()` and User settings: Auth tokens enabled for the
|
|
324
|
+
App and each calling origin registered.
|
|
325
|
+
- For Sponsorship: the App enabled for Sponsorship.
|
|
326
|
+
- `@fluent.xyz/connect` and all five peers installed.
|
|
327
|
+
- `@fluent.xyz/connect/styles.css` imported once.
|
|
328
|
+
- `network` passed as a literal per deployment, never defaulted.
|
|
329
|
+
- `config` kept stable: a module constant or a memo.
|
|
330
|
+
- `useFluentWidget()` called only inside the content `renderPage` or `renderHome` returns.
|
|
331
|
+
- UI branched on `status`, with a `default` branch.
|
|
332
|
+
- `debugLogging` off in production.
|
|
333
|
+
|
|
334
|
+
Next: send a Batch operation ([guides/transactions.md](guides/transactions.md)), request a
|
|
335
|
+
signature ([guides/signing.md](guides/signing.md)), or verify the person on your backend
|
|
336
|
+
([guides/backend-auth.md](guides/backend-auth.md)).
|