@fluent.xyz/connect 0.7.1 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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
- * The Network an App's own setting names, for an App that reads it from its environment and
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
- /** Whether the Network has a faucet: testnet does, mainnet does not. */
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
- * The viem chain of a Network, for a host's own chain config.
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
- /** The Network's block explorer URL, or `undefined` when its chain names none. */
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
- * A symbol that can pay for gas. Deliberately `string`: which tokens are
37
- * payable is data on the token definitions now, not a fixed set of literals.
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 signature. ERC-1271 (ERC-6492 before deployment) for a smart account, ECDSA for an
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 today.
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 signature. ERC-1271 (ERC-6492 before deployment) for a smart account, ECDSA for an
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
- * Gas policy for a Fluent ID batch. Estimation is enabled unless `skipEstimation` is true.
145
- * Skipping requires account limits. Omit both paymaster limits to use provider-authorized
146
- * paymaster gas and calldata overhead within `preVerificationGas`; supply both to fix all gas.
147
- * The fixed limits are a `FluentFixedAccountGas` and a `FluentFixedPaymasterGas`.
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 bundler estimate, rounded up. Must be a nonnegative safe integer. */
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 buffer. Must be nonnegative. */
187
+ /** Extra gas added after the percentage. A nonnegative uint128. */
167
188
  fixed?: bigint;
168
189
  };
169
190
  };
170
191
  /**
171
- * Reasons explicit gas preparation can fail before signing.
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
- * An invalid skip-estimation policy or paymaster authorization for different gas limits.
179
- * `code`, a `FluentUserOperationGasErrorCode`, identifies the failure; `message` names the
180
- * option or gas field to correct.
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
- /** How the connected account executes transactions. */
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
- /** Multiple calls land in a single atomic transaction (smart account only). */
251
+ /** Whether a Batch operation's calls land in one atomic transaction: a Fluent ID only. */
224
252
  atomicBatch: boolean;
225
253
  /**
226
- * Gas can be paid in an ERC-20 (BLEND / USDnr) via the paymaster instead of
227
- * native ETH — smart account only. This is NOT free/sponsored gas: the user
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
- /** Active account kind, or undefined when nothing is connected. */
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 active account can do — lets hosts adapt UI without branching on `type`. */
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
- * Two clocks, and the difference decides how these numbers may be read. `prepareMs`,
281
- * `signMs`, `broadcastMs`, `retryMs` and `totalMs` are direct monotonic measurements on the
282
- * client (`performance.now()`). `inclusionMs` and `detectMs` are *signed estimates* across the
283
- * client's clock and the chain's: `block.timestamp` has one-second resolution and no relation
284
- * to the browser's clock, so either may legitimately be negative when it is small, and neither
285
- * is clamped — a clamp would turn a known skew into a silent zero. `instants` keeps the inputs,
286
- * so the subtraction can be redone by whoever doubts it.
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 UserOperation — nonce, gas estimate, paymaster — up to the signature request.
302
- * Absent when the clock could not be read at that boundary: every stage here is absent rather
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 — a rejected sponsorship bearer, a refused
323
- * sponsorship falling back to own gas — and on the token exchange between them. It belongs to
324
- * no stage, is counted inside `totalMs`, and is `0` for a send that submitted once.
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
- /** Result of executing a batch operation. */
352
+ /** The result of executing a Batch operation. */
333
353
  type FluentExecuteResult = {
334
- /** Primary transaction hash — the final/target call (e.g. deposit/withdraw). */
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
- /** All transaction hashes in order. One for a smart-account UserOp; one per call for an EOA. */
359
+ /** Every transaction hash, in order: one for a Fluent ID, one per call for an External wallet. */
337
360
  hashes: Hash[];
338
- /** Included receipt for hash (the final EOA call); not a finality guarantee. */
361
+ /** The receipt of `hash` once it is included; not a finality guarantee. */
339
362
  receipt?: TransactionReceipt;
340
- /** ERC-4337 operation hash when executing through a smart account. */
363
+ /** The ERC-4337 user operation hash, for a Fluent ID. */
341
364
  userOpHash?: Hash;
342
- /** True when all calls landed atomically (smart account), false for sequential EOA txs. */
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 while the numbers are measured.
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. The widget resolves the ERC-20 address for the active
411
- * network internally — callers never pass (or risk mistyping) an address.
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 an ERC-20: that token's own paymaster pays,
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
- * @throws `Error` when `calls` is empty, or when a call has neither `data` nor `abi` with
519
- * `method`: a call that still names its function in 0.5's `functionName` is one.
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
  };