@fluent.xyz/connect 0.6.3 → 0.7.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.
- package/README.md +2 -0
- package/dist/batchOperation-CIcgSRv5.d.ts +524 -0
- package/dist/fluent-connect.css +1 -1
- package/dist/index.d.ts +6 -507
- package/dist/index.js +197 -154
- package/dist/index.js.map +1 -1
- package/dist/internal.d.ts +293 -0
- package/dist/internal.js +4781 -0
- package/dist/internal.js.map +1 -0
- package/docs/api.md +3 -3
- package/docs/concepts.md +5 -0
- package/docs/errors.md +7 -6
- package/docs/guides/transactions.md +8 -8
- package/docs/internal.md +109 -0
- package/docs/upgrading-0.5.md +40 -8
- package/package.json +5 -1
package/README.md
CHANGED
|
@@ -107,6 +107,8 @@ release may add a value. Every code is listed in [docs/errors.md](docs/errors.md
|
|
|
107
107
|
- [docs/experimental.md](docs/experimental.md): what may change or be removed in a minor
|
|
108
108
|
release.
|
|
109
109
|
- [docs/api.md](docs/api.md): the reference of every export.
|
|
110
|
+
- [docs/internal.md](docs/internal.md): the Internal entry, `@fluent.xyz/connect/internal`, the
|
|
111
|
+
helpers the widget is built from, promised nothing.
|
|
110
112
|
|
|
111
113
|
Upgrading from 0.5: [docs/upgrading-0.5.md](docs/upgrading-0.5.md)
|
|
112
114
|
|
|
@@ -0,0 +1,524 @@
|
|
|
1
|
+
import { Chain, SignableMessage, Hex, TypedData, TypedDataDefinition, Address, Abi, Hash, TransactionReceipt } from 'viem';
|
|
2
|
+
|
|
3
|
+
/** Which of Fluent's two deployments the widget runs on. */
|
|
4
|
+
type FluentWidgetNetwork = "testnet" | "mainnet";
|
|
5
|
+
/**
|
|
6
|
+
* The Network an App's own setting names, for an App that reads it from its environment and
|
|
7
|
+
* passes it as `FluentWidgetConfig.network`: `"testnet"`, `"mainnet"`, `"dev"`, `"development"`,
|
|
8
|
+
* `"prod"` and `"production"`, trimmed and in any case; `undefined` for anything else, an empty
|
|
9
|
+
* value included. The widget itself reads no environment variable.
|
|
10
|
+
*
|
|
11
|
+
* @example
|
|
12
|
+
* ```ts
|
|
13
|
+
* import { normalizeFluentWidgetNetwork } from "@fluent.xyz/connect/internal";
|
|
14
|
+
*
|
|
15
|
+
* const network = normalizeFluentWidgetNetwork("Production") ?? "testnet";
|
|
16
|
+
* ```
|
|
17
|
+
*/
|
|
18
|
+
declare function normalizeFluentWidgetNetwork(value: string | undefined | null): FluentWidgetNetwork | undefined;
|
|
19
|
+
/** Whether the Network has a faucet: testnet does, mainnet does not. */
|
|
20
|
+
declare function isFaucetNetwork(network: FluentWidgetNetwork): network is "testnet";
|
|
21
|
+
/**
|
|
22
|
+
* The viem chain of a Network, for a host's own chain config.
|
|
23
|
+
*
|
|
24
|
+
* @example
|
|
25
|
+
* ```ts
|
|
26
|
+
* import { getFluentChainForNetwork } from "@fluent.xyz/connect";
|
|
27
|
+
*
|
|
28
|
+
* export const chain = getFluentChainForNetwork("mainnet"); // chain.id === 25363
|
|
29
|
+
* ```
|
|
30
|
+
*/
|
|
31
|
+
declare function getFluentChainForNetwork(network: FluentWidgetNetwork): Chain;
|
|
32
|
+
/** The Network's block explorer URL, or `undefined` when its chain names none. */
|
|
33
|
+
declare function getFluentExplorerBaseUrl(network: FluentWidgetNetwork): string | undefined;
|
|
34
|
+
|
|
35
|
+
/**
|
|
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.
|
|
38
|
+
*/
|
|
39
|
+
type FluentGasTokenSymbol = string;
|
|
40
|
+
/**
|
|
41
|
+
* What one unit of each Gas token is worth in ETH, as a decimal string, keyed by its
|
|
42
|
+
* `FluentGasTokenSymbol`.
|
|
43
|
+
*
|
|
44
|
+
* @experimental May change or be removed in a minor release while the defaults are measured;
|
|
45
|
+
* the defaults are the recommended setting.
|
|
46
|
+
*/
|
|
47
|
+
type FluentGasPaymentEthRates = Partial<Record<FluentGasTokenSymbol, string>>;
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* The signatures of the Widget API, for the Widget account. A Fluent ID shows the Review in
|
|
51
|
+
* Prompt mode and none in Silent mode; an External wallet always shows the Review, then its own
|
|
52
|
+
* prompt.
|
|
53
|
+
*/
|
|
54
|
+
type FluentSignApi = {
|
|
55
|
+
/**
|
|
56
|
+
* EIP-191 signature. ERC-1271 (ERC-6492 before deployment) for a smart account, ECDSA for an
|
|
57
|
+
* External wallet.
|
|
58
|
+
*
|
|
59
|
+
* @throws `FluentReviewRejectedError` with `code` `signature_review_rejected` when the person
|
|
60
|
+
* dismisses the Review: always shown for an External wallet, and for a Fluent ID unless Quick
|
|
61
|
+
* sign is on. An External wallet's refusal in its own prompt rejects with the wallet's error.
|
|
62
|
+
* @throws `FluentAuthError` with `code` `not_connected` when no Widget account is connected or
|
|
63
|
+
* 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.
|
|
65
|
+
*
|
|
66
|
+
* @example
|
|
67
|
+
* ```ts
|
|
68
|
+
* import { useFluentWidget } from "@fluent.xyz/connect";
|
|
69
|
+
*
|
|
70
|
+
* export function useSignGreeting() {
|
|
71
|
+
* const { widget } = useFluentWidget();
|
|
72
|
+
* return () => widget.signMessage({ message: "Sign in to Marketplace" });
|
|
73
|
+
* }
|
|
74
|
+
* ```
|
|
75
|
+
*/
|
|
76
|
+
signMessage: (params: {
|
|
77
|
+
message: SignableMessage;
|
|
78
|
+
}) => Promise<Hex>;
|
|
79
|
+
/**
|
|
80
|
+
* EIP-712 signature. ERC-1271 (ERC-6492 before deployment) for a smart account, ECDSA for an
|
|
81
|
+
* External wallet.
|
|
82
|
+
*
|
|
83
|
+
* @throws `FluentReviewRejectedError` with `code` `signature_review_rejected` when the person
|
|
84
|
+
* dismisses the Review, as for `signMessage`.
|
|
85
|
+
* @throws `FluentAuthError` with `code` `not_connected` or `root_signer_required`, as for
|
|
86
|
+
* `signMessage`.
|
|
87
|
+
*
|
|
88
|
+
* @example
|
|
89
|
+
* ```ts
|
|
90
|
+
* import { useFluentWidget } from "@fluent.xyz/connect";
|
|
91
|
+
*
|
|
92
|
+
* const verifyingContract = "0x0000000000000000000000000000000000000001";
|
|
93
|
+
* const order = { maker: "0x0000000000000000000000000000000000000002", price: 100n } as const;
|
|
94
|
+
*
|
|
95
|
+
* export function useSignOrder() {
|
|
96
|
+
* const { widget } = useFluentWidget();
|
|
97
|
+
* return () =>
|
|
98
|
+
* widget.signTypedData({
|
|
99
|
+
* domain: { name: "Marketplace", version: "1", chainId: 20994, verifyingContract },
|
|
100
|
+
* types: {
|
|
101
|
+
* Order: [
|
|
102
|
+
* { name: "maker", type: "address" },
|
|
103
|
+
* { name: "price", type: "uint256" },
|
|
104
|
+
* ],
|
|
105
|
+
* },
|
|
106
|
+
* primaryType: "Order",
|
|
107
|
+
* message: order,
|
|
108
|
+
* });
|
|
109
|
+
* }
|
|
110
|
+
* ```
|
|
111
|
+
*/
|
|
112
|
+
signTypedData: <const typedData extends TypedData | Record<string, unknown>, primaryType extends keyof typedData | "EIP712Domain" = keyof typedData>(typedData: TypedDataDefinition<typedData, primaryType>) => Promise<Hex>;
|
|
113
|
+
};
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* The account's own gas limits, all three fixed, for a `FluentUserOperationGas` that skips
|
|
117
|
+
* estimation.
|
|
118
|
+
*
|
|
119
|
+
* @experimental May change or be removed in a minor release while the gas policy is measured;
|
|
120
|
+
* omitting it, which lets the widget estimate, is the recommended setting.
|
|
121
|
+
*/
|
|
122
|
+
type FluentFixedAccountGas = {
|
|
123
|
+
/** Whole-batch execution budget, including any Gas token approval. Positive uint128. */
|
|
124
|
+
callGasLimit: bigint;
|
|
125
|
+
/** Account validation and deployment budget. Positive uint128. */
|
|
126
|
+
verificationGasLimit: bigint;
|
|
127
|
+
/** Calldata overhead, or its ceiling with provider-owned paymaster gas. Positive uint256. */
|
|
128
|
+
preVerificationGas: bigint;
|
|
129
|
+
};
|
|
130
|
+
/**
|
|
131
|
+
* The paymaster's gas limits for a `FluentUserOperationGas` that skips estimation: both, or
|
|
132
|
+
* neither to use the limits the paymaster authorizes.
|
|
133
|
+
*
|
|
134
|
+
* @experimental May change or be removed in a minor release while the gas policy is measured;
|
|
135
|
+
* omitting it, which lets the widget estimate, is the recommended setting.
|
|
136
|
+
*/
|
|
137
|
+
type FluentFixedPaymasterGas = {
|
|
138
|
+
/** Fixed validation budget, a positive uint128. Omit both paymaster limits to use its answer. */
|
|
139
|
+
paymasterVerificationGasLimit?: bigint;
|
|
140
|
+
/** Fixed post-operation budget, a nonnegative uint128. Supplied together with validation. */
|
|
141
|
+
paymasterPostOpGasLimit?: bigint;
|
|
142
|
+
};
|
|
143
|
+
/**
|
|
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`.
|
|
148
|
+
*
|
|
149
|
+
* @experimental May change or be removed in a minor release while the gas policy is measured;
|
|
150
|
+
* omitting it, which lets the widget estimate, is the recommended setting.
|
|
151
|
+
*/
|
|
152
|
+
type FluentUserOperationGas = (FluentFixedAccountGas & FluentFixedPaymasterGas & {
|
|
153
|
+
/** Skip the account gas hook and bundler gas estimation. Defaults to false. */
|
|
154
|
+
skipEstimation: true;
|
|
155
|
+
callGasBuffer?: never;
|
|
156
|
+
}) | {
|
|
157
|
+
skipEstimation?: false;
|
|
158
|
+
callGasLimit: bigint;
|
|
159
|
+
callGasBuffer?: never;
|
|
160
|
+
} | {
|
|
161
|
+
skipEstimation?: false;
|
|
162
|
+
callGasLimit?: never;
|
|
163
|
+
callGasBuffer: {
|
|
164
|
+
/** Extra percent of the bundler estimate, rounded up. Must be a nonnegative safe integer. */
|
|
165
|
+
percentage?: number;
|
|
166
|
+
/** Extra gas added after the percentage buffer. Must be nonnegative. */
|
|
167
|
+
fixed?: bigint;
|
|
168
|
+
};
|
|
169
|
+
};
|
|
170
|
+
/**
|
|
171
|
+
* Reasons explicit gas preparation can fail before signing.
|
|
172
|
+
*
|
|
173
|
+
* @experimental May change or be removed in a minor release while the gas policy is measured;
|
|
174
|
+
* omitting it, which lets the widget estimate, is the recommended setting.
|
|
175
|
+
*/
|
|
176
|
+
type FluentUserOperationGasErrorCode = "invalid_policy" | "paymaster_gas_mismatch";
|
|
177
|
+
/**
|
|
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.
|
|
181
|
+
*
|
|
182
|
+
* @experimental May change or be removed in a minor release while the gas policy is measured;
|
|
183
|
+
* omitting it, which lets the widget estimate, is the recommended setting.
|
|
184
|
+
*/
|
|
185
|
+
declare class FluentUserOperationGasError extends Error {
|
|
186
|
+
readonly code: FluentUserOperationGasErrorCode;
|
|
187
|
+
constructor(code: FluentUserOperationGasErrorCode, message: string);
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/**
|
|
191
|
+
* One contract call of a Batch operation: either raw `data`, or an `abi` with the `method` to
|
|
192
|
+
* encode and its `args`.
|
|
193
|
+
*/
|
|
194
|
+
type FluentBatchCallInput = {
|
|
195
|
+
id?: string;
|
|
196
|
+
label?: string;
|
|
197
|
+
to: Address;
|
|
198
|
+
/** Native ETH sent with the call, in wei. Defaults to `0n`. */
|
|
199
|
+
value?: bigint;
|
|
200
|
+
data?: Hex;
|
|
201
|
+
abi?: Abi;
|
|
202
|
+
/** The ABI function to encode, with `abi` and `args`, when `data` is not given. */
|
|
203
|
+
method?: string;
|
|
204
|
+
args?: readonly unknown[];
|
|
205
|
+
};
|
|
206
|
+
/** A Batch operation's call as it is sent: `data` encoded, `value` defaulted to `0n`. */
|
|
207
|
+
type FluentEncodedBatchCall = {
|
|
208
|
+
id?: string;
|
|
209
|
+
label?: string;
|
|
210
|
+
to: Address;
|
|
211
|
+
value: bigint;
|
|
212
|
+
data: Hex;
|
|
213
|
+
};
|
|
214
|
+
/**
|
|
215
|
+
* Whether the Widget account can send now: `ready`, `disconnected`, `unavailable` (connected
|
|
216
|
+
* but not ready yet) or `error` (see `FluentWidgetAccount.executionError`).
|
|
217
|
+
*/
|
|
218
|
+
type FluentWidgetExecutionStatus = "disconnected" | "ready" | "unavailable" | "error";
|
|
219
|
+
/** How the connected account executes transactions. */
|
|
220
|
+
type FluentAccountType = "smart" | "eoa";
|
|
221
|
+
/** What the Widget account can do, so a host adapts its UI without branching on its type. */
|
|
222
|
+
type FluentAccountCapabilities = {
|
|
223
|
+
/** Multiple calls land in a single atomic transaction (smart account only). */
|
|
224
|
+
atomicBatch: boolean;
|
|
225
|
+
/**
|
|
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.
|
|
229
|
+
*/
|
|
230
|
+
erc20Gas: boolean;
|
|
231
|
+
};
|
|
232
|
+
/**
|
|
233
|
+
* The Widget account as the Widget API reports it: its address and type, whether it is
|
|
234
|
+
* connected and can send now, and what it can do.
|
|
235
|
+
*/
|
|
236
|
+
type FluentWidgetAccount = {
|
|
237
|
+
/** The Widget account's address: the Fluent ID's, or the External wallet's. */
|
|
238
|
+
address?: Address;
|
|
239
|
+
/** Whether a Widget account, a Fluent ID or an External wallet, is connected. */
|
|
240
|
+
connected: boolean;
|
|
241
|
+
/** Whether the Widget account can send now; `executionStatus` says why it cannot. */
|
|
242
|
+
executionReady: boolean;
|
|
243
|
+
/** Where sending stands, a `FluentWidgetExecutionStatus`. */
|
|
244
|
+
executionStatus: FluentWidgetExecutionStatus;
|
|
245
|
+
/**
|
|
246
|
+
* The message of the last failure to prepare the Fluent ID's account, if any: the reason an
|
|
247
|
+
* `executionStatus` of `"error"` gives.
|
|
248
|
+
*/
|
|
249
|
+
executionError?: string;
|
|
250
|
+
/** Active account kind, or undefined when nothing is connected. */
|
|
251
|
+
type?: FluentAccountType;
|
|
252
|
+
/** What the active account can do — lets hosts adapt UI without branching on `type`. */
|
|
253
|
+
capabilities: FluentAccountCapabilities;
|
|
254
|
+
};
|
|
255
|
+
/**
|
|
256
|
+
* Absolute instants behind `FluentExecuteTiming`, kept so its signed estimates can be
|
|
257
|
+
* re-checked rather than believed. Epoch milliseconds (`Date.now()`), because the only other
|
|
258
|
+
* clock in the arithmetic — the including block's `timestamp` — is a wall clock too.
|
|
259
|
+
*
|
|
260
|
+
* @experimental May change or be removed in a minor release while the numbers are measured.
|
|
261
|
+
*/
|
|
262
|
+
type FluentExecuteTimingInstants = {
|
|
263
|
+
/** When the first submission attempt of this send began. */
|
|
264
|
+
submittedAtEpochMs: number;
|
|
265
|
+
/** When the bundler accepted the operation that settled. */
|
|
266
|
+
broadcastedAtEpochMs: number;
|
|
267
|
+
/** When that operation's receipt was in hand. */
|
|
268
|
+
receivedAtEpochMs: number;
|
|
269
|
+
/**
|
|
270
|
+
* The including block's `timestamp`, in milliseconds. Absent exactly when `inclusionMs` and
|
|
271
|
+
* `detectMs` are absent: the block could not be read.
|
|
272
|
+
*/
|
|
273
|
+
blockTimestampEpochMs?: number;
|
|
274
|
+
/** How many operations were submitted; more than one means a retry or an own-gas fallback. */
|
|
275
|
+
attempts: number;
|
|
276
|
+
};
|
|
277
|
+
/**
|
|
278
|
+
* Where one send's milliseconds went, stage by stage.
|
|
279
|
+
*
|
|
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.
|
|
296
|
+
*
|
|
297
|
+
* @experimental May change or be removed in a minor release while the numbers are measured.
|
|
298
|
+
*/
|
|
299
|
+
type FluentExecuteTiming = {
|
|
300
|
+
/**
|
|
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.
|
|
305
|
+
*/
|
|
306
|
+
prepareMs?: number;
|
|
307
|
+
/** Producing the signature. Absent when the settled attempt never got that far. */
|
|
308
|
+
signMs?: number;
|
|
309
|
+
/** Handing the signed operation to the bundler. Absent when signing never finished. */
|
|
310
|
+
broadcastMs?: number;
|
|
311
|
+
/**
|
|
312
|
+
* Bundler acceptance to the including block's timestamp: bundling plus block time. Signed
|
|
313
|
+
* estimate; absent when the including block could not be read.
|
|
314
|
+
*/
|
|
315
|
+
inclusionMs?: number;
|
|
316
|
+
/**
|
|
317
|
+
* The including block's timestamp to the instant this client held the receipt: how long the
|
|
318
|
+
* inclusion took to notice. Signed estimate; absent when the including block could not be read.
|
|
319
|
+
*/
|
|
320
|
+
detectMs?: number;
|
|
321
|
+
/**
|
|
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.
|
|
325
|
+
*/
|
|
326
|
+
retryMs: number;
|
|
327
|
+
/** First submission to receipt in hand. Measured directly; never a sum of the stages. */
|
|
328
|
+
totalMs: number;
|
|
329
|
+
/** The raw instants the signed estimates above were computed from. */
|
|
330
|
+
instants: FluentExecuteTimingInstants;
|
|
331
|
+
};
|
|
332
|
+
/** Result of executing a batch operation. */
|
|
333
|
+
type FluentExecuteResult = {
|
|
334
|
+
/** Primary transaction hash — the final/target call (e.g. deposit/withdraw). */
|
|
335
|
+
hash: Hash;
|
|
336
|
+
/** All transaction hashes in order. One for a smart-account UserOp; one per call for an EOA. */
|
|
337
|
+
hashes: Hash[];
|
|
338
|
+
/** Included receipt for hash (the final EOA call); not a finality guarantee. */
|
|
339
|
+
receipt?: TransactionReceipt;
|
|
340
|
+
/** ERC-4337 operation hash when executing through a smart account. */
|
|
341
|
+
userOpHash?: Hash;
|
|
342
|
+
/** True when all calls landed atomically (smart account), false for sequential EOA txs. */
|
|
343
|
+
atomic: boolean;
|
|
344
|
+
/**
|
|
345
|
+
* Whether the App's Sponsorship paid the gas for this operation, read back off the settled
|
|
346
|
+
* operation (which contract the EntryPoint charged) first: a refused Sponsorship falls back
|
|
347
|
+
* to the account paying its own gas, so a flag set from asking for Sponsorship would report
|
|
348
|
+
* the fallback as a success. `false` for a Gas token payment and always for an External
|
|
349
|
+
* wallet, which has no paymaster. When a Fluent ID's receipt names no paymaster, the way the
|
|
350
|
+
* operation was sent decides: `false` when it made no sponsored submission (the fallback,
|
|
351
|
+
* `sponsorship: "never"`, Sponsorship unavailable or not configured), and `null` after a
|
|
352
|
+
* sponsored submission, where nothing says who paid.
|
|
353
|
+
*/
|
|
354
|
+
sponsored: boolean | null;
|
|
355
|
+
/**
|
|
356
|
+
* The paymaster a Fluent ID's receipt names: the Sponsorship paymaster or a Gas token's
|
|
357
|
+
* paymaster, when one paid. Undefined when the receipt carried no paymaster — `sponsored` is
|
|
358
|
+
* then `false`, or `null` after a sponsored submission — and always for an External wallet,
|
|
359
|
+
* which has no paymaster.
|
|
360
|
+
*
|
|
361
|
+
* @experimental May change or be removed in a minor release while the numbers are measured.
|
|
362
|
+
*/
|
|
363
|
+
paymaster?: Address;
|
|
364
|
+
/**
|
|
365
|
+
* Where this send's milliseconds went, as a `FluentExecuteTiming` whose raw instants are a
|
|
366
|
+
* `FluentExecuteTimingInstants`. Fluent ID only: an External wallet performs its prompt, its
|
|
367
|
+
* signing and its broadcast behind one `sendTransaction` await, so EIP-1193 exposes no
|
|
368
|
+
* truthful instant to put a boundary on.
|
|
369
|
+
*
|
|
370
|
+
* @experimental May change or be removed in a minor release while the numbers are measured.
|
|
371
|
+
*/
|
|
372
|
+
timing?: FluentExecuteTiming;
|
|
373
|
+
};
|
|
374
|
+
/** The Gas payment chosen in the widget: the Gas token's symbol, its address and decimals. */
|
|
375
|
+
type FluentWidgetGasPayment = {
|
|
376
|
+
symbol: FluentGasTokenSymbol;
|
|
377
|
+
token?: Address;
|
|
378
|
+
decimals: number;
|
|
379
|
+
};
|
|
380
|
+
/** What `widget.createBatchOp` takes: the calls of one Batch operation, and its Review title. */
|
|
381
|
+
type FluentBatchOperationInput = {
|
|
382
|
+
id?: string;
|
|
383
|
+
/**
|
|
384
|
+
* Heading of this Batch operation's Review (Fluent ID, Prompt mode). Defaults to the
|
|
385
|
+
* widget's own copy, "Confirm transaction".
|
|
386
|
+
*/
|
|
387
|
+
reviewTitle?: string;
|
|
388
|
+
calls: readonly FluentBatchCallInput[];
|
|
389
|
+
};
|
|
390
|
+
/**
|
|
391
|
+
* How a Fluent ID signs: `"prompt"` shows the widget's Review first (Prompt mode), `"silent"`
|
|
392
|
+
* signs with none (Silent mode), except that where the App set `quickSign.whitelistAddresses`, a
|
|
393
|
+
* Batch operation with a call outside it is signed as `"prompt"`. An External wallet always
|
|
394
|
+
* shows its own prompt.
|
|
395
|
+
*/
|
|
396
|
+
type FluentSigningMode = "prompt" | "silent";
|
|
397
|
+
/**
|
|
398
|
+
* How one operation's gas is paid: a Gas token by symbol, or native ETH, and whether
|
|
399
|
+
* Sponsorship is asked for.
|
|
400
|
+
*
|
|
401
|
+
* Without `includeApproval`, the widget adds the approval of the Gas token to its ERC-20
|
|
402
|
+
* paymaster at the start of the operation when the account's allowance is below the threshold:
|
|
403
|
+
* 1 USDnr when the allowance is below 0.1 USDnr, 10 BLEND when it is below 1 BLEND. An
|
|
404
|
+
* allowance that cannot be read counts as none. `includeApproval: true` with an `approveAmount`
|
|
405
|
+
* approves that amount instead, whatever the allowance. Either way the Review lists the
|
|
406
|
+
* operation's own calls, and nothing is added for `"ETH"` or for an External wallet.
|
|
407
|
+
*/
|
|
408
|
+
type FluentGasPayment = {
|
|
409
|
+
/**
|
|
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).
|
|
413
|
+
*/
|
|
414
|
+
symbol: FluentGasTokenSymbol;
|
|
415
|
+
/**
|
|
416
|
+
* Whether to ask the App's sponsorship paymaster to pay for this operation.
|
|
417
|
+
*
|
|
418
|
+
* `"auto"` tries Sponsorship, and if the paymaster refuses, resends with the account paying
|
|
419
|
+
* its own gas. `"never"` skips the paymaster outright, so the account pays from the first
|
|
420
|
+
* attempt and the result reports `sponsored: false`. What an omitted value means:
|
|
421
|
+
* [guides/sponsorship.md](guides/sponsorship.md#not-asking-sponsorship-never-and-gas-tokens).
|
|
422
|
+
*
|
|
423
|
+
* Ignored when `symbol` names an ERC-20: that token's own paymaster pays,
|
|
424
|
+
* and sponsorship is not in the picture.
|
|
425
|
+
*/
|
|
426
|
+
sponsorship?: "auto" | "never";
|
|
427
|
+
} & ({
|
|
428
|
+
/** Approves `approveAmount` to the paymaster whatever the allowance, for a Gas token. */
|
|
429
|
+
includeApproval: true;
|
|
430
|
+
/** In the Gas token's smallest unit. */
|
|
431
|
+
approveAmount: bigint;
|
|
432
|
+
} | {
|
|
433
|
+
includeApproval?: false;
|
|
434
|
+
approveAmount?: never;
|
|
435
|
+
});
|
|
436
|
+
/** The options of `FluentBatchOperation.execute`, every one optional. */
|
|
437
|
+
type FluentBatchOperationExecuteOptions = {
|
|
438
|
+
/**
|
|
439
|
+
* The `FluentSigningMode` of this operation. Defaults to the widget's `signingMode`, which
|
|
440
|
+
* follows the person's Quick sign. A `"silent"` operation with a call outside
|
|
441
|
+
* `quickSign.whitelistAddresses` is signed as `"prompt"`. Any value but `"silent"`, 0.5's
|
|
442
|
+
* `"always"` and `"session"` included, is `"prompt"`. Ignored for an External wallet.
|
|
443
|
+
*/
|
|
444
|
+
confirmation?: FluentSigningMode;
|
|
445
|
+
/** How the gas of this operation is paid. Defaults to the Gas payment chosen in the widget. */
|
|
446
|
+
gasPayment?: FluentGasPayment;
|
|
447
|
+
/**
|
|
448
|
+
* Fluent ID gas limits, estimation opt-out or headroom: a `FluentUserOperationGas`, whose
|
|
449
|
+
* fixed limits are a `FluentFixedAccountGas` and a `FluentFixedPaymasterGas`. Ignored for
|
|
450
|
+
* External wallet sends.
|
|
451
|
+
*
|
|
452
|
+
* @experimental May change or be removed in a minor release while the gas policy is measured;
|
|
453
|
+
* omitting it, which lets the widget estimate, is the recommended setting.
|
|
454
|
+
*/
|
|
455
|
+
userOperationGas?: FluentUserOperationGas;
|
|
456
|
+
};
|
|
457
|
+
/**
|
|
458
|
+
* A Batch operation `widget.createBatchOp` built: its calls, encoded, and `execute`, which sends
|
|
459
|
+
* them for the Widget account.
|
|
460
|
+
*/
|
|
461
|
+
type FluentBatchOperation = {
|
|
462
|
+
/** `FluentBatchOperationInput.id`, copied. */
|
|
463
|
+
id?: string;
|
|
464
|
+
/** `FluentBatchOperationInput.reviewTitle`, copied. */
|
|
465
|
+
reviewTitle?: string;
|
|
466
|
+
/** The calls as the host passed them. */
|
|
467
|
+
calls: readonly FluentBatchCallInput[];
|
|
468
|
+
/** The same calls encoded, in order: what `execute()` sends. */
|
|
469
|
+
encodedCalls: FluentEncodedBatchCall[];
|
|
470
|
+
/**
|
|
471
|
+
* Whether the widget could send the operation when it was built: the Widget account ready, or
|
|
472
|
+
* able to prepare itself when `execute()` is called. Not updated afterwards; read
|
|
473
|
+
* `widget.account.executionReady` for the live value.
|
|
474
|
+
*/
|
|
475
|
+
canExecute: boolean;
|
|
476
|
+
/**
|
|
477
|
+
* Executes the operation for the Widget account and resolves once it is included.
|
|
478
|
+
*
|
|
479
|
+
* @throws `FluentReviewRejectedError` with `code` `transaction_review_rejected` when the
|
|
480
|
+
* person dismisses the Review, which a Fluent ID shows in Prompt mode; an External wallet's
|
|
481
|
+
* refusal in its own prompt rejects with the wallet's error.
|
|
482
|
+
* @throws `FluentSponsorshipFallbackError` when a Fluent ID asked for Sponsorship, a sponsored
|
|
483
|
+
* submission failed, and the submission in which the account pays its own gas failed too;
|
|
484
|
+
* its `code` says why Sponsorship failed: `denied`, `unauthorized`, `unreachable` or
|
|
485
|
+
* `no_token`. A failure while waiting for an operation's inclusion is not wrapped: it rejects
|
|
486
|
+
* with its own error, and an operation whose wait failed was submitted. What else is not
|
|
487
|
+
* wrapped: [guides/sponsorship.md](guides/sponsorship.md#both-failed-fluentsponsorshipfallbackerror).
|
|
488
|
+
* @throws `FluentUserOperationGasError` (experimental) with `code` `invalid_policy` for a
|
|
489
|
+
* `skipEstimation` policy that cannot be used (other invalid `userOperationGas` values throw a
|
|
490
|
+
* plain `Error`), and `paymaster_gas_mismatch` when, with estimation skipped,
|
|
491
|
+
* the paymaster's authorization of a Gas token payment does not match the fixed gas limits.
|
|
492
|
+
* Under Sponsorship, a failed check of the paymaster's gas fails the sponsored submission
|
|
493
|
+
* instead, and the account pays its own gas.
|
|
494
|
+
* @throws `FluentGasPaymentError` when a Fluent ID's operation is paid in a Gas token and
|
|
495
|
+
* cannot be prepared; nothing has been signed or sent. Its `code` is `paymaster_unavailable`
|
|
496
|
+
* when the address of the paymaster to approve the Gas token to cannot be read,
|
|
497
|
+
* `insufficient_gas_token` when the paymaster's simulation of the operation cannot charge the
|
|
498
|
+
* fee in the Gas token, and `paymaster_rejected` when the paymaster refuses to charge the fee in
|
|
499
|
+
* the Gas token for another reason. The account's balance of the Gas token is not read first:
|
|
500
|
+
* the operation may acquire the fee itself.
|
|
501
|
+
*/
|
|
502
|
+
execute: (options?: FluentBatchOperationExecuteOptions) => Promise<FluentExecuteResult>;
|
|
503
|
+
};
|
|
504
|
+
/**
|
|
505
|
+
* The Widget API: what the widget gives an App's code to act for the Widget account. Reached as
|
|
506
|
+
* `widget` in the render context or from `useFluentWidget()`.
|
|
507
|
+
*/
|
|
508
|
+
type FluentBatchApi = FluentSignApi & {
|
|
509
|
+
/** The Widget account: its address, type, readiness and capabilities. */
|
|
510
|
+
account: FluentWidgetAccount;
|
|
511
|
+
/** How the widget signs by default: `"silent"` while the person's Quick sign is on. */
|
|
512
|
+
signingMode: FluentSigningMode;
|
|
513
|
+
/** The Gas payment chosen in the widget, which `execute()` uses when given no `gasPayment`. */
|
|
514
|
+
gasPayment: FluentWidgetGasPayment;
|
|
515
|
+
/**
|
|
516
|
+
* Builds a Batch operation, encoding its calls now; `execute()` sends it.
|
|
517
|
+
*
|
|
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.
|
|
520
|
+
*/
|
|
521
|
+
createBatchOp: (input: FluentBatchOperationInput) => FluentBatchOperation;
|
|
522
|
+
};
|
|
523
|
+
|
|
524
|
+
export { type FluentWidgetGasPayment as A, getFluentChainForNetwork as B, type FluentBatchCallInput as F, type FluentWidgetNetwork as a, type FluentGasTokenSymbol as b, type FluentGasPaymentEthRates as c, type FluentAccountType as d, type FluentBatchApi as e, type FluentAccountCapabilities as f, getFluentExplorerBaseUrl as g, type FluentBatchOperation as h, isFaucetNetwork as i, type FluentBatchOperationExecuteOptions as j, type FluentBatchOperationInput as k, type FluentEncodedBatchCall as l, type FluentExecuteResult as m, normalizeFluentWidgetNetwork as n, type FluentExecuteTiming as o, type FluentExecuteTimingInstants as p, type FluentFixedAccountGas as q, type FluentFixedPaymasterGas as r, type FluentGasPayment as s, type FluentSignApi as t, type FluentSigningMode as u, type FluentUserOperationGas as v, FluentUserOperationGasError as w, type FluentUserOperationGasErrorCode as x, type FluentWidgetAccount as y, type FluentWidgetExecutionStatus as z };
|