@fluent.xyz/connect 0.7.2 → 0.8.1-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/dist/{batchOperation-CIcgSRv5.d.ts → batchOperation-B5Fd0-QX.d.ts} +90 -65
- package/dist/fluent-connect.css +1 -1
- package/dist/index.d.ts +245 -150
- package/dist/index.js +2318 -1238
- package/dist/index.js.map +1 -1
- package/dist/internal.d.ts +78 -28
- package/dist/internal.js +23 -33
- package/dist/internal.js.map +1 -1
- package/dist/polyfills/buffer.js.map +1 -1
- package/docs/api.md +223 -212
- package/docs/concepts.md +28 -0
- package/docs/configuration.md +5 -3
- package/docs/experimental.md +22 -0
- package/docs/getting-started.md +16 -1
- package/package.json +1 -1
|
@@ -3,7 +3,7 @@ import { Chain, SignableMessage, Hex, TypedData, TypedDataDefinition, Address, A
|
|
|
3
3
|
/** Which of Fluent's two deployments the widget runs on. */
|
|
4
4
|
type FluentWidgetNetwork = "testnet" | "mainnet";
|
|
5
5
|
/**
|
|
6
|
-
*
|
|
6
|
+
* Returns the Network an App's own setting names, for an App that reads it from its environment and
|
|
7
7
|
* passes it as `FluentWidgetConfig.network`: `"testnet"`, `"mainnet"`, `"dev"`, `"development"`,
|
|
8
8
|
* `"prod"` and `"production"`, trimmed and in any case; `undefined` for anything else, an empty
|
|
9
9
|
* value included. The widget itself reads no environment variable.
|
|
@@ -16,10 +16,19 @@ type FluentWidgetNetwork = "testnet" | "mainnet";
|
|
|
16
16
|
* ```
|
|
17
17
|
*/
|
|
18
18
|
declare function normalizeFluentWidgetNetwork(value: string | undefined | null): FluentWidgetNetwork | undefined;
|
|
19
|
-
/**
|
|
19
|
+
/**
|
|
20
|
+
* Reports whether the Network has a faucet: testnet does, mainnet does not.
|
|
21
|
+
*
|
|
22
|
+
* @example
|
|
23
|
+
* ```ts
|
|
24
|
+
* import { isFaucetNetwork } from "@fluent.xyz/connect/internal";
|
|
25
|
+
*
|
|
26
|
+
* const showFaucetLink = isFaucetNetwork("testnet"); // true
|
|
27
|
+
* ```
|
|
28
|
+
*/
|
|
20
29
|
declare function isFaucetNetwork(network: FluentWidgetNetwork): network is "testnet";
|
|
21
30
|
/**
|
|
22
|
-
*
|
|
31
|
+
* Returns the viem chain of a Network, for an App's own chain config.
|
|
23
32
|
*
|
|
24
33
|
* @example
|
|
25
34
|
* ```ts
|
|
@@ -29,12 +38,21 @@ declare function isFaucetNetwork(network: FluentWidgetNetwork): network is "test
|
|
|
29
38
|
* ```
|
|
30
39
|
*/
|
|
31
40
|
declare function getFluentChainForNetwork(network: FluentWidgetNetwork): Chain;
|
|
32
|
-
/**
|
|
41
|
+
/**
|
|
42
|
+
* Returns the Network's block explorer URL, or `undefined` when its chain names none.
|
|
43
|
+
*
|
|
44
|
+
* @example
|
|
45
|
+
* ```ts
|
|
46
|
+
* import { getFluentExplorerBaseUrl } from "@fluent.xyz/connect/internal";
|
|
47
|
+
*
|
|
48
|
+
* const explorer = getFluentExplorerBaseUrl("mainnet"); // "https://fluentscan.xyz"
|
|
49
|
+
* ```
|
|
50
|
+
*/
|
|
33
51
|
declare function getFluentExplorerBaseUrl(network: FluentWidgetNetwork): string | undefined;
|
|
34
52
|
|
|
35
53
|
/**
|
|
36
|
-
*
|
|
37
|
-
*
|
|
54
|
+
* The symbol of a Gas token. A plain `string`, because which tokens are Gas tokens is data on
|
|
55
|
+
* the token definitions, not a fixed set of literals.
|
|
38
56
|
*/
|
|
39
57
|
type FluentGasTokenSymbol = string;
|
|
40
58
|
/**
|
|
@@ -53,15 +71,15 @@ type FluentGasPaymentEthRates = Partial<Record<FluentGasTokenSymbol, string>>;
|
|
|
53
71
|
*/
|
|
54
72
|
type FluentSignApi = {
|
|
55
73
|
/**
|
|
56
|
-
* EIP-191
|
|
57
|
-
* External wallet.
|
|
74
|
+
* Signs `message` (EIP-191) for the Widget account: ERC-1271, or ERC-6492 before deployment,
|
|
75
|
+
* for a Fluent ID, and ECDSA for an External wallet.
|
|
58
76
|
*
|
|
59
77
|
* @throws `FluentReviewRejectedError` with `code` `signature_review_rejected` when the person
|
|
60
78
|
* dismisses the Review: always shown for an External wallet, and for a Fluent ID unless Quick
|
|
61
79
|
* sign is on. An External wallet's refusal in its own prompt rejects with the wallet's error.
|
|
62
80
|
* @throws `FluentAuthError` with `code` `not_connected` when no Widget account is connected or
|
|
63
81
|
* the External wallet has no client, and `root_signer_required` when neither of the Fluent
|
|
64
|
-
* ID's signing paths signs with its root Signer, a guard no configuration reaches
|
|
82
|
+
* ID's signing paths signs with its root Signer, a guard no widget configuration reaches.
|
|
65
83
|
*
|
|
66
84
|
* @example
|
|
67
85
|
* ```ts
|
|
@@ -77,8 +95,8 @@ type FluentSignApi = {
|
|
|
77
95
|
message: SignableMessage;
|
|
78
96
|
}) => Promise<Hex>;
|
|
79
97
|
/**
|
|
80
|
-
* EIP-712
|
|
81
|
-
* External wallet.
|
|
98
|
+
* Signs `typedData` (EIP-712) for the Widget account: ERC-1271, or ERC-6492 before deployment,
|
|
99
|
+
* for a Fluent ID, and ECDSA for an External wallet.
|
|
82
100
|
*
|
|
83
101
|
* @throws `FluentReviewRejectedError` with `code` `signature_review_rejected` when the person
|
|
84
102
|
* dismisses the Review, as for `signMessage`.
|
|
@@ -141,10 +159,13 @@ type FluentFixedPaymasterGas = {
|
|
|
141
159
|
paymasterPostOpGasLimit?: bigint;
|
|
142
160
|
};
|
|
143
161
|
/**
|
|
144
|
-
*
|
|
145
|
-
*
|
|
146
|
-
*
|
|
147
|
-
*
|
|
162
|
+
* The gas policy of a Fluent ID's Batch operation, in one of three shapes.
|
|
163
|
+
*
|
|
164
|
+
* `{ callGasLimit }` fixes the execution gas and estimates the rest; `{ callGasBuffer }` estimates
|
|
165
|
+
* and raises the execution gas by the buffer. `{ skipEstimation: true }` estimates nothing: it
|
|
166
|
+
* takes a `FluentFixedAccountGas` and either both paymaster limits of a
|
|
167
|
+
* `FluentFixedPaymasterGas` or neither, in which case the paymaster's authorized limits are used
|
|
168
|
+
* and `preVerificationGas` is the ceiling of its calldata overhead.
|
|
148
169
|
*
|
|
149
170
|
* @experimental May change or be removed in a minor release while the gas policy is measured;
|
|
150
171
|
* omitting it, which lets the widget estimate, is the recommended setting.
|
|
@@ -161,23 +182,25 @@ type FluentUserOperationGas = (FluentFixedAccountGas & FluentFixedPaymasterGas &
|
|
|
161
182
|
skipEstimation?: false;
|
|
162
183
|
callGasLimit?: never;
|
|
163
184
|
callGasBuffer: {
|
|
164
|
-
/** Extra percent of the
|
|
185
|
+
/** Extra percent of the estimated execution gas, rounded up. A nonnegative safe integer. */
|
|
165
186
|
percentage?: number;
|
|
166
|
-
/** Extra gas added after the percentage
|
|
187
|
+
/** Extra gas added after the percentage. A nonnegative uint128. */
|
|
167
188
|
fixed?: bigint;
|
|
168
189
|
};
|
|
169
190
|
};
|
|
170
191
|
/**
|
|
171
|
-
*
|
|
192
|
+
* The `code` of a `FluentUserOperationGasError`: `invalid_policy` for a `skipEstimation` policy
|
|
193
|
+
* that cannot be used, `paymaster_gas_mismatch` for a paymaster authorization whose gas limits
|
|
194
|
+
* are missing, out of range or differ from the policy's.
|
|
172
195
|
*
|
|
173
196
|
* @experimental May change or be removed in a minor release while the gas policy is measured;
|
|
174
197
|
* omitting it, which lets the widget estimate, is the recommended setting.
|
|
175
198
|
*/
|
|
176
199
|
type FluentUserOperationGasErrorCode = "invalid_policy" | "paymaster_gas_mismatch";
|
|
177
200
|
/**
|
|
178
|
-
*
|
|
179
|
-
*
|
|
180
|
-
*
|
|
201
|
+
* A `skipEstimation` policy that cannot be used, or a paymaster authorization whose gas limits
|
|
202
|
+
* that policy cannot accept. `code` names the failure; `message` names the option or gas field to
|
|
203
|
+
* correct.
|
|
181
204
|
*
|
|
182
205
|
* @experimental May change or be removed in a minor release while the gas policy is measured;
|
|
183
206
|
* omitting it, which lets the widget estimate, is the recommended setting.
|
|
@@ -192,15 +215,20 @@ declare class FluentUserOperationGasError extends Error {
|
|
|
192
215
|
* encode and its `args`.
|
|
193
216
|
*/
|
|
194
217
|
type FluentBatchCallInput = {
|
|
218
|
+
/** The host's own identifier for the call, copied to its `FluentEncodedBatchCall`. */
|
|
195
219
|
id?: string;
|
|
220
|
+
/** The call's name in the Review. Defaults to `method`, else "Contract call". */
|
|
196
221
|
label?: string;
|
|
197
222
|
to: Address;
|
|
198
223
|
/** Native ETH sent with the call, in wei. Defaults to `0n`. */
|
|
199
224
|
value?: bigint;
|
|
225
|
+
/** The encoded calldata. When given, `abi`, `method` and `args` are not read. */
|
|
200
226
|
data?: Hex;
|
|
227
|
+
/** The contract's ABI, to encode `method` with `args` when `data` is not given. */
|
|
201
228
|
abi?: Abi;
|
|
202
229
|
/** The ABI function to encode, with `abi` and `args`, when `data` is not given. */
|
|
203
230
|
method?: string;
|
|
231
|
+
/** The arguments of `method`. Defaults to `[]`. */
|
|
204
232
|
args?: readonly unknown[];
|
|
205
233
|
};
|
|
206
234
|
/** A Batch operation's call as it is sent: `data` encoded, `value` defaulted to `0n`. */
|
|
@@ -216,16 +244,15 @@ type FluentEncodedBatchCall = {
|
|
|
216
244
|
* but not ready yet) or `error` (see `FluentWidgetAccount.executionError`).
|
|
217
245
|
*/
|
|
218
246
|
type FluentWidgetExecutionStatus = "disconnected" | "ready" | "unavailable" | "error";
|
|
219
|
-
/**
|
|
247
|
+
/** The kind of Widget account: `"smart"` for a Fluent ID, `"eoa"` for an External wallet. */
|
|
220
248
|
type FluentAccountType = "smart" | "eoa";
|
|
221
249
|
/** What the Widget account can do, so a host adapts its UI without branching on its type. */
|
|
222
250
|
type FluentAccountCapabilities = {
|
|
223
|
-
/**
|
|
251
|
+
/** Whether a Batch operation's calls land in one atomic transaction: a Fluent ID only. */
|
|
224
252
|
atomicBatch: boolean;
|
|
225
253
|
/**
|
|
226
|
-
*
|
|
227
|
-
*
|
|
228
|
-
* still pays, just in a token.
|
|
254
|
+
* Whether gas can be paid in a Gas token instead of native ETH: a Fluent ID only. This is not
|
|
255
|
+
* Sponsorship: the account still pays, in the Gas token.
|
|
229
256
|
*/
|
|
230
257
|
erc20Gas: boolean;
|
|
231
258
|
};
|
|
@@ -247,9 +274,12 @@ type FluentWidgetAccount = {
|
|
|
247
274
|
* `executionStatus` of `"error"` gives.
|
|
248
275
|
*/
|
|
249
276
|
executionError?: string;
|
|
250
|
-
/**
|
|
277
|
+
/**
|
|
278
|
+
* The Widget account's kind. Undefined until a Fluent ID's smart account is ready or an
|
|
279
|
+
* External wallet is connected.
|
|
280
|
+
*/
|
|
251
281
|
type?: FluentAccountType;
|
|
252
|
-
/** What the
|
|
282
|
+
/** What the Widget account can do. */
|
|
253
283
|
capabilities: FluentAccountCapabilities;
|
|
254
284
|
};
|
|
255
285
|
/**
|
|
@@ -277,31 +307,21 @@ type FluentExecuteTimingInstants = {
|
|
|
277
307
|
/**
|
|
278
308
|
* Where one send's milliseconds went, stage by stage.
|
|
279
309
|
*
|
|
280
|
-
*
|
|
281
|
-
*
|
|
282
|
-
* client
|
|
283
|
-
*
|
|
284
|
-
*
|
|
285
|
-
*
|
|
286
|
-
*
|
|
287
|
-
*
|
|
288
|
-
* `totalMs` is measured, not summed: it runs from the start of the first submission to the
|
|
289
|
-
* instant the receipt was in hand, and excludes both the smart-account and authentication setup
|
|
290
|
-
* before the send and the block read after it. It does not equal the sum of the stages and must
|
|
291
|
-
* not be displayed as if it did.
|
|
292
|
-
*
|
|
293
|
-
* Collected for every send, whatever `debugLogging` is set to — the numbers are the answer to
|
|
294
|
-
* "where did the four seconds go", which is a question a host asks in production. A failure
|
|
295
|
-
* inside the measuring code costs the stages it could not establish, never the send.
|
|
310
|
+
* `prepareMs`, `signMs`, `broadcastMs`, `retryMs` and `totalMs` are measured on the client's
|
|
311
|
+
* monotonic clock (`performance.now()`). `inclusionMs` and `detectMs` are signed estimates across
|
|
312
|
+
* the client's clock and the chain's `block.timestamp`, which has one-second resolution: either
|
|
313
|
+
* may be negative when small, neither is clamped, and `instants` keeps their inputs. `totalMs`
|
|
314
|
+
* runs from the first submission to the receipt in hand, without the account and authentication
|
|
315
|
+
* setup before it or the block read after, and is not the sum of the stages. Collected for every
|
|
316
|
+
* send, whatever `debugLogging` is set to; a failure in the measuring code loses the stages it
|
|
317
|
+
* could not establish, not the send.
|
|
296
318
|
*
|
|
297
319
|
* @experimental May change or be removed in a minor release while the numbers are measured.
|
|
298
320
|
*/
|
|
299
321
|
type FluentExecuteTiming = {
|
|
300
322
|
/**
|
|
301
|
-
* Building the
|
|
302
|
-
* Absent when the clock could not be read at that boundary:
|
|
303
|
-
* than approximated, because a stage silently widened to cover its neighbours is worse than a
|
|
304
|
-
* stage the display can mark as unmeasured.
|
|
323
|
+
* Building the user operation (nonce, gas estimate, paymaster) up to the signature request.
|
|
324
|
+
* Absent when the clock could not be read at that boundary: no stage here is approximated.
|
|
305
325
|
*/
|
|
306
326
|
prepareMs?: number;
|
|
307
327
|
/** Producing the signature. Absent when the settled attempt never got that far. */
|
|
@@ -319,9 +339,9 @@ type FluentExecuteTiming = {
|
|
|
319
339
|
*/
|
|
320
340
|
detectMs?: number;
|
|
321
341
|
/**
|
|
322
|
-
* Time spent on submissions that did not settle
|
|
323
|
-
*
|
|
324
|
-
* no stage, is counted inside `totalMs`, and is `0` for
|
|
342
|
+
* Time spent on submissions that did not settle (a sponsored submission whose Auth token was
|
|
343
|
+
* refused, a refused Sponsorship falling back to own gas) and on the new Auth token between
|
|
344
|
+
* them. It belongs to no stage, is counted inside `totalMs`, and is `0` for one submission.
|
|
325
345
|
*/
|
|
326
346
|
retryMs: number;
|
|
327
347
|
/** First submission to receipt in hand. Measured directly; never a sum of the stages. */
|
|
@@ -329,17 +349,23 @@ type FluentExecuteTiming = {
|
|
|
329
349
|
/** The raw instants the signed estimates above were computed from. */
|
|
330
350
|
instants: FluentExecuteTimingInstants;
|
|
331
351
|
};
|
|
332
|
-
/**
|
|
352
|
+
/** The result of executing a Batch operation. */
|
|
333
353
|
type FluentExecuteResult = {
|
|
334
|
-
/**
|
|
354
|
+
/**
|
|
355
|
+
* The hash of the transaction holding the last call: a Fluent ID's one transaction, or an
|
|
356
|
+
* External wallet's last.
|
|
357
|
+
*/
|
|
335
358
|
hash: Hash;
|
|
336
|
-
/**
|
|
359
|
+
/** Every transaction hash, in order: one for a Fluent ID, one per call for an External wallet. */
|
|
337
360
|
hashes: Hash[];
|
|
338
|
-
/**
|
|
361
|
+
/** The receipt of `hash` once it is included; not a finality guarantee. */
|
|
339
362
|
receipt?: TransactionReceipt;
|
|
340
|
-
/** ERC-4337 operation hash
|
|
363
|
+
/** The ERC-4337 user operation hash, for a Fluent ID. */
|
|
341
364
|
userOpHash?: Hash;
|
|
342
|
-
/**
|
|
365
|
+
/**
|
|
366
|
+
* `true` when all calls landed in one transaction (a Fluent ID), `false` for an External
|
|
367
|
+
* wallet's one transaction per call.
|
|
368
|
+
*/
|
|
343
369
|
atomic: boolean;
|
|
344
370
|
/**
|
|
345
371
|
* Whether the App's Sponsorship paid the gas for this operation, read back off the settled
|
|
@@ -358,7 +384,7 @@ type FluentExecuteResult = {
|
|
|
358
384
|
* then `false`, or `null` after a sponsored submission — and always for an External wallet,
|
|
359
385
|
* which has no paymaster.
|
|
360
386
|
*
|
|
361
|
-
* @experimental May change or be removed in a minor release
|
|
387
|
+
* @experimental May change or be removed in a minor release.
|
|
362
388
|
*/
|
|
363
389
|
paymaster?: Address;
|
|
364
390
|
/**
|
|
@@ -379,6 +405,7 @@ type FluentWidgetGasPayment = {
|
|
|
379
405
|
};
|
|
380
406
|
/** What `widget.createBatchOp` takes: the calls of one Batch operation, and its Review title. */
|
|
381
407
|
type FluentBatchOperationInput = {
|
|
408
|
+
/** The host's own identifier for the operation, copied to `FluentBatchOperation.id`. */
|
|
382
409
|
id?: string;
|
|
383
410
|
/**
|
|
384
411
|
* Heading of this Batch operation's Review (Fluent ID, Prompt mode). Defaults to the
|
|
@@ -407,9 +434,8 @@ type FluentSigningMode = "prompt" | "silent";
|
|
|
407
434
|
*/
|
|
408
435
|
type FluentGasPayment = {
|
|
409
436
|
/**
|
|
410
|
-
* Gas token symbol
|
|
411
|
-
*
|
|
412
|
-
* `"ETH"` means native gas (no ERC-20 paymaster).
|
|
437
|
+
* The Gas token's symbol, whose address the widget resolves for the Network. `"ETH"` means
|
|
438
|
+
* native gas, with no Gas token paymaster.
|
|
413
439
|
*/
|
|
414
440
|
symbol: FluentGasTokenSymbol;
|
|
415
441
|
/**
|
|
@@ -420,8 +446,7 @@ type FluentGasPayment = {
|
|
|
420
446
|
* attempt and the result reports `sponsored: false`. What an omitted value means:
|
|
421
447
|
* [guides/sponsorship.md](guides/sponsorship.md#not-asking-sponsorship-never-and-gas-tokens).
|
|
422
448
|
*
|
|
423
|
-
* Ignored when `symbol` names
|
|
424
|
-
* and sponsorship is not in the picture.
|
|
449
|
+
* Ignored when `symbol` names a Gas token, whose own paymaster pays.
|
|
425
450
|
*/
|
|
426
451
|
sponsorship?: "auto" | "never";
|
|
427
452
|
} & ({
|
|
@@ -515,8 +540,8 @@ type FluentBatchApi = FluentSignApi & {
|
|
|
515
540
|
/**
|
|
516
541
|
* Builds a Batch operation, encoding its calls now; `execute()` sends it.
|
|
517
542
|
*
|
|
518
|
-
*
|
|
519
|
-
* `method
|
|
543
|
+
* Throws an `Error` when `calls` is empty, or when a call has neither `data` nor `abi` with
|
|
544
|
+
* `method`; a call naming its function in 0.5's `functionName` has neither.
|
|
520
545
|
*/
|
|
521
546
|
createBatchOp: (input: FluentBatchOperationInput) => FluentBatchOperation;
|
|
522
547
|
};
|