@fluent.xyz/connect 0.4.0 → 0.4.2
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 +1242 -0
- package/README.md +125 -7
- package/dist/fluent-connect.css +1 -1
- package/dist/index.d.ts +433 -21
- package/dist/index.js +3269 -658
- package/dist/index.js.map +1 -1
- package/package.json +5 -3
package/README.md
CHANGED
|
@@ -69,11 +69,29 @@ App's identity — sponsorship, auth and analytics speak it — and must be the
|
|
|
69
69
|
value the Fluent Dashboard shows; the widget throws on any other shape. `privyClientId` is
|
|
70
70
|
login configuration: the Privy app client carrying your allowed origins.
|
|
71
71
|
|
|
72
|
+
For Capacitor social login, use `authMode: "direct"` and pass
|
|
73
|
+
`customOAuthRedirectUrl: "https://app.example.com/auth/ios/callback"` in `config`.
|
|
74
|
+
This forwards an HTTPS Universal Link callback to Privy; the host must configure
|
|
75
|
+
the dashboard allowlists, iOS Associated Domains, and callback handling.
|
|
76
|
+
See [Capacitor OAuth setup](https://github.com/fluentlabs-xyz/fluent-connect-sdk/blob/devel/packages/connect/INTEGRATION.md#capacitor-oauth).
|
|
77
|
+
|
|
72
78
|
> Upgrading from 0.2.x? `partnerId` was renamed to `appId` in 0.3.0 and the id value changed
|
|
73
79
|
> from `partner_…` to `app_…`; passing `partnerId` throws with the same hint. Migrating from
|
|
74
80
|
> `clientId`? That option is gone: the value it held is now `privyClientId`.
|
|
75
81
|
|
|
76
|
-
|
|
82
|
+
### Auth mode
|
|
83
|
+
|
|
84
|
+
> **Hosted mode is deprecated.** `authMode: "hosted"` is no longer supported and will be
|
|
85
|
+
> removed in 0.5.0 — use `authMode: "direct"`. The config default is still `"hosted"`, so
|
|
86
|
+
> leaving `authMode` out opts your app into the deprecated mode: set it explicitly, as the
|
|
87
|
+
> example above does.
|
|
88
|
+
|
|
89
|
+
`authMode: "direct"` renders Fluent's own sign-in dialog inside your page and requires your
|
|
90
|
+
origin registered on the Privy app client behind your `privyClientId`. `authMode: "hosted"`
|
|
91
|
+
(deprecated) opens the Fluent authorize popup and needs no origin allow-listing; a Fluent ID
|
|
92
|
+
signed in that way has its Privy session on the authorize page rather than in yours, so
|
|
93
|
+
`signMessage`, `signTypedData` and `linkX()` reject there with `hosted_not_supported`, and so
|
|
94
|
+
does `getAuthToken()` for a Fluent ID.
|
|
77
95
|
|
|
78
96
|
### Authenticating your backend
|
|
79
97
|
|
|
@@ -81,11 +99,16 @@ login configuration: the Privy app client carrying your allowed origins.
|
|
|
81
99
|
Fluent Connect. Send it to your backend once and issue your own session; verify it with the keys
|
|
82
100
|
at `<iss>/.well-known/jwks.json` — `iss` is the API host root, not `/api/v1` — and check `iss`,
|
|
83
101
|
`aud` (your `appId`) and `exp`. `sub` is stable per user per app. `addresses` is present only
|
|
84
|
-
when your app has the `addresses` scope.
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
102
|
+
when your app has the `addresses` scope. A Fluent ID needs `authMode: "direct"`: in hosted mode
|
|
103
|
+
it rejects with `FluentAuthError` code `hosted_not_supported`. An external wallet gets a token in
|
|
104
|
+
either mode — an EOA or a deployed contract wallet signs in; a counterfactual smart account
|
|
105
|
+
cannot (no ERC-6492).
|
|
106
|
+
The token renews itself silently for both account types — against a service that issues the
|
|
107
|
+
refresh credential this release expects, an external wallet signs once, when the session opens,
|
|
108
|
+
not once per token; against a deployment that answers without one there is nothing to renew from,
|
|
109
|
+
and every expired token costs another signature. The session and what holding it costs are in
|
|
110
|
+
[`INTEGRATION.md` §8](INTEGRATION.md#8-auth-modes). See `apps/auth-demo` for a browser-side
|
|
111
|
+
verifier.
|
|
89
112
|
|
|
90
113
|
Brand images (logo, wallet icons) ship inside the package as bundled data URLs — you do not need a `/fluent-assets` folder.
|
|
91
114
|
|
|
@@ -97,7 +120,13 @@ By default the connect control floats top-right (`connectButton="fixed"`). To pl
|
|
|
97
120
|
// Hide the default control and use your own CTA
|
|
98
121
|
<FluentWidget
|
|
99
122
|
connectButton={false}
|
|
100
|
-
config={{
|
|
123
|
+
config={{
|
|
124
|
+
appId: "app_…",
|
|
125
|
+
privyClientId: "client-…",
|
|
126
|
+
network: "testnet",
|
|
127
|
+
appName: "My App",
|
|
128
|
+
authMode: "direct",
|
|
129
|
+
}}
|
|
101
130
|
mode="page"
|
|
102
131
|
renderPage={({ openConnect, openAccount, hasConnectedAccount }) => (
|
|
103
132
|
<button type="button" onClick={hasConnectedAccount ? openAccount : openConnect}>
|
|
@@ -119,6 +148,95 @@ By default the connect control floats top-right (`connectButton="fixed"`). To pl
|
|
|
119
148
|
/>
|
|
120
149
|
```
|
|
121
150
|
|
|
151
|
+
### Sending a transaction
|
|
152
|
+
|
|
153
|
+
Everything your app sends goes through one call: `widget.createBatchOp({...}).execute()`.
|
|
154
|
+
`widget` comes from the render context (`renderPage` / `renderHome`) or from
|
|
155
|
+
`useFluentWidget()` anywhere below `<FluentWidget>`; `useWidget()` returns it on its own. The
|
|
156
|
+
widget routes a Fluent ID (one UserOperation, all calls atomic) and an external wallet (one
|
|
157
|
+
transaction per call, each confirmed in the wallet) itself, so your app never branches on the
|
|
158
|
+
account type.
|
|
159
|
+
|
|
160
|
+
```tsx
|
|
161
|
+
import { useFluentWidget } from "@fluent.xyz/connect";
|
|
162
|
+
import { erc20Abi, exchangeAbi } from "./abi";
|
|
163
|
+
|
|
164
|
+
function BuyButton({ token, exchange, price, orderId }) {
|
|
165
|
+
const { widget } = useFluentWidget();
|
|
166
|
+
|
|
167
|
+
async function onBuy() {
|
|
168
|
+
// Guard first: `execute()` rejects when the session cannot execute, and
|
|
169
|
+
// `widget.account.executionError` is the message to show when it is not ready.
|
|
170
|
+
if (!widget.account.executionReady) return;
|
|
171
|
+
|
|
172
|
+
const { hash, atomic } = await widget
|
|
173
|
+
.createBatchOp({
|
|
174
|
+
id: "buy-order",
|
|
175
|
+
reviewTitle: "Approve + buy",
|
|
176
|
+
calls: [
|
|
177
|
+
{ to: token, abi: erc20Abi, method: "approve", args: [exchange, price] },
|
|
178
|
+
{ to: exchange, abi: exchangeAbi, method: "buy", args: [orderId] },
|
|
179
|
+
],
|
|
180
|
+
})
|
|
181
|
+
.execute();
|
|
182
|
+
// atomic === true → both calls landed in a single UserOperation (Fluent ID)
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
return (
|
|
186
|
+
<button type="button" onClick={onBuy} disabled={!widget.account.executionReady}>
|
|
187
|
+
Buy
|
|
188
|
+
</button>
|
|
189
|
+
);
|
|
190
|
+
}
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
`calls` is the only required field: `reviewTitle` is the heading of the Fluent review modal
|
|
194
|
+
and `id` is a label for your own bookkeeping. Each call carries either `abi` + `method` +
|
|
195
|
+
`args` or raw `data`, and `to` can be any contract. `createBatchOp` itself throws straight
|
|
196
|
+
away on an empty `calls` array, or on a call that has neither `data` nor `abi` + `method`.
|
|
197
|
+
|
|
198
|
+
`execute()` resolves once the transaction is included, with `hash`, every hash in order as
|
|
199
|
+
`hashes`, `atomic`, `sponsored`, the `receipt` for `hash`, and `userOpHash` for a
|
|
200
|
+
smart-account operation. It rejects when the session cannot execute (the message is
|
|
201
|
+
`widget.account.executionError`), when the user dismisses the Fluent review
|
|
202
|
+
(`FluentReviewRejectedError`, message `User rejected Fluent transaction review`), when the
|
|
203
|
+
wallet rejects a call, and when a call reverts — a sequential external-wallet batch stops at
|
|
204
|
+
the call that reverted. Who pays the gas, how to force a gas token, and what each stage costs
|
|
205
|
+
in time: [`INTEGRATION.md` §7](INTEGRATION.md#7-sending-a-transaction).
|
|
206
|
+
|
|
207
|
+
### Execution gas headroom
|
|
208
|
+
|
|
209
|
+
For smart-account batches whose execution cost can change between estimation and
|
|
210
|
+
inclusion, set `userOperationGas` on `execute()`:
|
|
211
|
+
|
|
212
|
+
```ts
|
|
213
|
+
await widget.createBatchOp({ calls }).execute({
|
|
214
|
+
userOperationGas: {
|
|
215
|
+
callGasBuffer: { percentage: 50, fixed: 50_000n },
|
|
216
|
+
},
|
|
217
|
+
});
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
This example sets `callGasLimit` to `ceil(estimate × 1.5) + 50,000`. The estimate
|
|
221
|
+
covers the complete UserOperation, including account deployment and any gas-token
|
|
222
|
+
approval prepended by the widget. The buffer is applied during normal gas
|
|
223
|
+
preparation, before final paymaster authorization and signing, without adding an
|
|
224
|
+
estimation request. Paymaster adapters that previously supplied data only once
|
|
225
|
+
are called again to authorize the final gas limit. The same policy
|
|
226
|
+
applies to sponsored, account-paid, and ERC-20 gas, including sponsorship fallback.
|
|
227
|
+
|
|
228
|
+
Alternatively, supply a known execution limit with
|
|
229
|
+
`userOperationGas: { callGasLimit: 600_000n }`. Use either `callGasLimit` or
|
|
230
|
+
`callGasBuffer`. Percentages must be nonnegative safe integers; fixed gas must be
|
|
231
|
+
a nonnegative bigint, and the final limit must fit a positive uint128. Defaults
|
|
232
|
+
keep the existing estimation behavior. These options apply only to smart-account
|
|
233
|
+
UserOperations; external EOA transactions keep their wallet's gas estimation.
|
|
234
|
+
|
|
235
|
+
Choose headroom for your application's execution paths and paymaster limits.
|
|
236
|
+
Headroom increases the maximum gas budget and does not guarantee execution if
|
|
237
|
+
state changes. An included outer transaction can still contain a failed
|
|
238
|
+
UserOperation; the widget continues to reject that failed execution.
|
|
239
|
+
|
|
122
240
|
## Styles
|
|
123
241
|
|
|
124
242
|
Import the package CSS once in your app entry:
|