@fluent.xyz/connect 0.5.3 → 0.6.0-rc.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.
@@ -0,0 +1,248 @@
1
+ # Sponsorship
2
+
3
+ Sponsorship is the App paying the gas of a Fluent ID's Batch operation through Fluent's
4
+ sponsorship service. The widget asks for it per operation, and when it is refused the account
5
+ pays its own gas instead: that is the fallback. This guide follows one operation through each
6
+ outcome: sponsored, refused, both submissions failed, and not asked for. It ends with how to read
7
+ the result and a checklist for an operation that was not sponsored. Building and executing a
8
+ Batch operation is in [transactions.md](transactions.md); the terms are defined in
9
+ [concepts.md](../concepts.md).
10
+
11
+ ## Before you start
12
+
13
+ - **A Fluent ID.** Sponsorship applies to a Fluent ID's operations only. An External wallet is
14
+ never sponsored: each of its calls is a transaction paid from the wallet's own ETH, the
15
+ `gasPayment` option does not apply to it, and `sponsored` on its result is always `false`.
16
+ - **The App enabled for Sponsorship.** Ask Fluent to enable Sponsorship for the App. The widget
17
+ names the App to the sponsorship service by the `appId` of your config. When the service
18
+ refuses the App (HTTP 403), the operation falls back to the account's own ETH, and the widget
19
+ stops asking for Sponsorship on later operations until the `<FluentWidget>` is mounted again:
20
+ a page load, an unmount and remount, or a change of its `network`. Until then those
21
+ operations pay their own ETH from the first attempt, as if `sponsorship` were `"never"`.
22
+ - **Auth tokens enabled for the App, and the page origin registered on it.** The widget
23
+ authenticates each sponsored attempt with an Auth token for the person and the App, which it
24
+ obtains itself, from the same Service session as the token `getAuthToken()` returns. Your App
25
+ does not call `getAuthToken()` or pass a token for Sponsorship; for a Fluent ID, obtaining it
26
+ asks the person for no signature. When the token cannot be obtained, for example because Auth
27
+ tokens are not enabled for the App (`getAuthToken()` would reject with `FluentAuthError` and
28
+ `code` `app_not_auth_enabled`) or the page origin is not registered (`origin_not_allowed`), no
29
+ sponsored attempt is made and the account pays its own ETH. Nothing is latched: the next
30
+ operation tries to obtain a token again. See [backend-auth.md](backend-auth.md) and
31
+ [errors.md](../errors.md#fluentautherror).
32
+
33
+ ## The usual path: sponsored
34
+
35
+ With no options, a Fluent ID's operation asks for Sponsorship. Two settings decide it:
36
+
37
+ - The Gas payment is native ETH. `execute()` given no `gasPayment` uses the Gas payment chosen
38
+ in the widget (`widget.gasPayment`), which starts at the config's `gasPayment.defaultToken`,
39
+ ETH when unset, unless the person saved another choice.
40
+ - `sponsorship` is `"auto"`. The config's `gasPayment.sponsorship` is the App's default, and
41
+ `"auto"` when unset; `execute({ gasPayment: { symbol: "ETH", sponsorship } })` sets it for
42
+ one operation, and a `gasPayment` without `sponsorship` takes the config's value.
43
+
44
+ The widget then obtains the Auth token, asks the sponsorship service to pay, and submits the
45
+ operation. When the service refuses the Auth token itself (HTTP 401), the widget obtains a fresh
46
+ token once and tries once more. `execute()` resolves once the operation is included, and
47
+ `sponsored` is `true` when its receipt names a paymaster: that is how the result shows that
48
+ Sponsorship paid.
49
+
50
+ ## Refused: the account pays its own gas
51
+
52
+ When the sponsored submission fails, the widget submits the same calls again with the account
53
+ paying its own ETH. When that succeeds, `execute()` resolves and nothing is thrown. The
54
+ sponsored submission fails when:
55
+
56
+ - the sponsorship service refuses this operation;
57
+ - the service refuses the App (HTTP 403), which also stops later operations from asking;
58
+ - the service refuses the Auth token (HTTP 401), and the fresh token is refused too or cannot
59
+ be obtained;
60
+ - the service cannot be reached, or answers with another HTTP error;
61
+ - the operation itself fails before it is submitted, for example a call that reverts, which
62
+ fails the fallback as well (see the next section).
63
+
64
+ The account paid, so `sponsored` is not `true`. The result carries no reason for the refusal,
65
+ and the fallback needs enough ETH in the account to pay its gas.
66
+
67
+ ## Both failed: `FluentSponsorshipFallbackError`
68
+
69
+ When the sponsored submission fails and the own-gas submission fails too, `execute()` rejects
70
+ with a `FluentSponsorshipFallbackError`. Its `code` says why the sponsored submission failed:
71
+
72
+ - `unauthorized`: the service refused the App (HTTP 403) or the Auth token (HTTP 401, also
73
+ after one fresh token).
74
+ - `unreachable`: the request to the service failed with an HTTP status other than 401 and 403,
75
+ or with none.
76
+ - `no_token`: the service refused the Auth token, and obtaining a fresh one failed.
77
+ - `denied`: any other failure, such as the service refusing this operation, or the operation
78
+ itself failing, for example a call that reverts whoever pays.
79
+
80
+ `fallbackError` is what the own-gas submission failed with; read it first, since it says why the
81
+ account could not pay, for example too little ETH. `cause` is the sponsored submission's error.
82
+ Both are plain `{ name, message, status? }` objects, not the errors the submissions threw: their
83
+ `message` keeps the vendor's sentence with URLs, request bodies, addresses, hashes, tokens and
84
+ ids replaced by placeholders, and `status` is a status such as the HTTP one, present when the
85
+ error carried one ([the fields](../errors.md#fluentsponsorshipfallbackerror)).
86
+ Keep a `default` branch in any `switch` over `code`: a later release may add one. What to do for
87
+ each code is in [errors.md](../errors.md#fluentsponsorshipfallbackerror).
88
+
89
+ Only these two failed submissions make this error. Every other failure under Sponsorship
90
+ arrives as it was thrown:
91
+
92
+ - The operation's fee was refused in the sponsored submission, also after the widget's one
93
+ retry with a new fee quote. There is no fallback for it.
94
+ - Waiting for the receipt failed, of the sponsored operation or of the fallback. The operation
95
+ was submitted and can still be included.
96
+ - No sponsored submission was made, because no Auth token could be obtained or the widget had
97
+ stopped asking after an HTTP 403. The account paid its own ETH from the start.
98
+ - The operation was included and reverted: a plain `Error`, whoever paid.
99
+
100
+ ## Not asking: `sponsorship: "never"` and Gas tokens
101
+
102
+ - **`sponsorship: "never"`**, in the config's `gasPayment` or in `execute({ gasPayment })`:
103
+ with ETH as the Gas payment, the widget asks no sponsorship service and obtains no Auth token
104
+ for it. The account pays its own ETH from the first submission, and a failure arrives as it
105
+ was thrown. `sponsored` is not `true`.
106
+ - **A Gas token**, chosen by the person in the widget or passed as
107
+ `execute({ gasPayment: { symbol } })`: the account pays its gas in that Gas token, Sponsorship
108
+ is not asked for, and `sponsorship` is ignored. `sponsored` is always `false`. A `symbol` that
109
+ names no Gas token on the Network is paid in ETH, and then asks for Sponsorship like any ETH
110
+ operation.
111
+
112
+ ```ts
113
+ import type { FluentBatchOperation, FluentExecuteResult } from "@fluent.xyz/connect";
114
+
115
+ // Pays from the account's own ETH, without asking for Sponsorship.
116
+ export function executeWithOwnEth(operation: FluentBatchOperation): Promise<FluentExecuteResult> {
117
+ return operation.execute({ gasPayment: { symbol: "ETH", sponsorship: "never" } });
118
+ }
119
+ ```
120
+
121
+ ## Reading `sponsored`
122
+
123
+ `sponsored` on `FluentExecuteResult` is read from the included operation's receipt first. Only
124
+ when the receipt names no paymaster does the way the operation was submitted decide:
125
+
126
+ | `sponsored` | When |
127
+ |---|---|
128
+ | `true` | A Fluent ID, ETH as the Gas payment, and the receipt names a paymaster: Sponsorship paid. |
129
+ | `false` | Always for an External wallet. Always for a Fluent ID paying in a Gas token. For a Fluent ID paying in ETH, when the receipt names the account as the payer, or names no paymaster and the operation made no sponsored submission: the fallback (after a refused sponsored submission, an HTTP 403 or for lack of an Auth token), `sponsorship: "never"`, every operation after an HTTP 403, and an App with no Sponsorship configured. |
130
+ | `null` | A Fluent ID paying in ETH whose sponsored submission went through, and the receipt names no paymaster, so it does not say who paid. |
131
+
132
+ Treat only `true` as sponsored. `null` is not a refusal: a sponsored submission went through,
133
+ and the receipt does not name who paid. The experimental `paymaster` member names the paymaster
134
+ the receipt names; see [experimental.md](../experimental.md#paymaster-and-timing).
135
+
136
+ ## Example: a sponsored ETH transfer
137
+
138
+ The App sends 0.001 ETH from the Widget account and tells the person who paid the gas.
139
+
140
+ ```tsx
141
+ import {
142
+ FluentReviewRejectedError,
143
+ FluentSponsorshipFallbackError,
144
+ FluentWidget,
145
+ useFluentWidget,
146
+ type FluentWidgetConfig,
147
+ } from "@fluent.xyz/connect";
148
+ import { useState } from "react";
149
+ import { parseEther, type Address } from "viem";
150
+
151
+ const config: FluentWidgetConfig = {
152
+ appId: "app_0123456789abcdef0123456789abcdef",
153
+ privyClientId: "client-0123456789abcdef",
154
+ network: "testnet",
155
+ };
156
+
157
+ const recipient: Address = "0x2222222222222222222222222222222222222222";
158
+
159
+ function describeFallback(error: FluentSponsorshipFallbackError): string {
160
+ switch (error.code) {
161
+ case "denied":
162
+ return "Sponsorship refused this operation, and paying with your own ETH failed too.";
163
+ case "unauthorized":
164
+ return "Sponsorship refused this App or its Auth token, and your own ETH failed too.";
165
+ case "unreachable":
166
+ return "Sponsorship did not answer, and paying with your own ETH failed too.";
167
+ case "no_token":
168
+ return "No Auth token for Sponsorship, and paying with your own ETH failed too.";
169
+ default:
170
+ return "The operation could not be sent.";
171
+ }
172
+ }
173
+
174
+ function Transfer() {
175
+ const { widget, status } = useFluentWidget();
176
+ const [note, setNote] = useState("");
177
+
178
+ async function transfer() {
179
+ const operation = widget.createBatchOp({
180
+ reviewTitle: "Send 0.001 ETH",
181
+ // `data: "0x"` is required: a call with neither `data` nor `abi` and `method` is refused.
182
+ calls: [{ to: recipient, value: parseEther("0.001"), data: "0x" }],
183
+ });
184
+ try {
185
+ const result = await operation.execute();
186
+ if (result.sponsored === true) {
187
+ setNote(`Sent in ${result.hash}; the App paid the gas.`);
188
+ } else if (result.sponsored === false) {
189
+ setNote(`Sent in ${result.hash}; your account paid the gas.`);
190
+ } else {
191
+ setNote(`Sent in ${result.hash}; the receipt does not say who paid the gas.`);
192
+ }
193
+ } catch (error) {
194
+ if (error instanceof FluentReviewRejectedError) return; // the person said no
195
+ if (error instanceof FluentSponsorshipFallbackError) {
196
+ setNote(describeFallback(error));
197
+ return;
198
+ }
199
+ setNote(error instanceof Error ? error.message : "The transfer failed.");
200
+ }
201
+ }
202
+
203
+ if (status !== "connected") return <p>Connect to send.</p>;
204
+ return (
205
+ <div>
206
+ <button
207
+ type="button"
208
+ disabled={!widget.account.executionReady}
209
+ onClick={() => void transfer()}
210
+ >
211
+ Send 0.001 ETH
212
+ </button>
213
+ <p>{note}</p>
214
+ </div>
215
+ );
216
+ }
217
+
218
+ export function App() {
219
+ return <FluentWidget config={config} mode="page" renderPage={() => <Transfer />} />;
220
+ }
221
+ ```
222
+
223
+ ## Why was my operation not sponsored?
224
+
225
+ The result says only whether Sponsorship paid, not why it did not. Check, in order:
226
+
227
+ - **The Widget account is an External wallet.** It is never sponsored; `sponsored` is `false`.
228
+ - **A Gas token was the Gas payment.** The person may have chosen one in the widget, which
229
+ `execute()` uses when given no `gasPayment`; read `widget.gasPayment.symbol`. `sponsored` is
230
+ `false`.
231
+ - **`sponsorship` is `"never"`**, in the config's `gasPayment` or in the `gasPayment` passed to
232
+ `execute()`.
233
+ - **The App is not enabled for Sponsorship.** The service refused the App with HTTP 403, and the
234
+ widget stopped asking until the `<FluentWidget>` is mounted again. Ask Fluent to enable it for
235
+ your `appId`, then reload the page.
236
+ - **No Auth token could be obtained.** Auth tokens are not enabled for the App, or the page
237
+ origin is not registered on it. Call `getAuthToken()` and read the `FluentAuthError` `code` it
238
+ rejects with ([errors.md](../errors.md#fluentautherror)).
239
+ - **The sponsorship service refused this operation**, or could not be reached. The account paid
240
+ through the fallback, which resolves without an error; only a failed fallback carries a
241
+ `code`.
242
+ - **`sponsored` is `null`.** The operation made a sponsored submission and the receipt names no
243
+ paymaster, so it does not say who paid. An operation that made no sponsored submission
244
+ reports `false` instead.
245
+
246
+ With `debugLogging` on ([configuration.md](../configuration.md)), the widget prints a console
247
+ warning when the Auth token for a sponsored attempt cannot be obtained or the sponsored attempt
248
+ fails and the account pays its own gas.
@@ -0,0 +1,251 @@
1
+ # Executing Batch operations
2
+
3
+ A Batch operation is an ordered list of contract calls the widget executes for the Widget
4
+ account as one unit. It is the one way an App sends anything: there is no separate call for a
5
+ single transfer or a single contract call. This guide builds calls, executes them, chooses how
6
+ gas is paid, reads the result and handles rejections. The terms are defined in
7
+ [concepts.md](../concepts.md); every type named here is in [api.md](../api.md#fluentbatchapi).
8
+
9
+ How an operation lands depends on the account kind:
10
+
11
+ | Widget account | How the calls land | Review | Gas |
12
+ |---|---|---|---|
13
+ | Fluent ID | In one transaction, atomically: all calls apply or none does. | The widget's Review in Prompt mode, none in Silent mode: see [concepts.md](../concepts.md#prompt-mode-and-silent-mode). | Sponsorship, the account's own ETH or a Gas token. |
14
+ | External wallet | One transaction per call, in order, each awaited before the next. | No widget Review: the wallet handles each transaction with its own prompt. | The wallet's own ETH. |
15
+
16
+ ## Calls
17
+
18
+ Each call is a `FluentBatchCallInput`:
19
+
20
+ | Member | What it is |
21
+ |---|---|
22
+ | `to` | The contract or account the call targets. Required. |
23
+ | `abi`, `method`, `args` | The ABI, the name of the function to encode, and its arguments. |
24
+ | `data` | Raw calldata, used as given instead of `abi` and `method`. |
25
+ | `value` | Native ETH sent with the call, in wei. Defaults to `0n`. |
26
+ | `id`, `label` | Your own names for the call; the widget copies them into `encodedCalls`. |
27
+
28
+ A call needs either `data`, or both `abi` and `method`. The package has no transfer helper:
29
+ build a token transfer as an ERC-20 `transfer` call, with viem's `erc20Abi` and `parseUnits`,
30
+ and a native ETH transfer as a call with a `value` and empty `data`:
31
+
32
+ ```ts
33
+ import type { FluentBatchCallInput } from "@fluent.xyz/connect";
34
+ import { erc20Abi, parseEther, parseUnits, type Address } from "viem";
35
+
36
+ const token: Address = "0x1111111111111111111111111111111111111111";
37
+ const recipient: Address = "0x2222222222222222222222222222222222222222";
38
+
39
+ // 25 units of an ERC-20 with 18 decimals.
40
+ export const tokenTransfer: FluentBatchCallInput = {
41
+ to: token,
42
+ abi: erc20Abi,
43
+ method: "transfer",
44
+ args: [recipient, parseUnits("25", 18)],
45
+ };
46
+
47
+ // 0.01 ETH. `data: "0x"` is required: a call with neither `data` nor `abi` and `method` is
48
+ // refused when the operation is built.
49
+ export const ethTransfer: FluentBatchCallInput = {
50
+ to: recipient,
51
+ value: parseEther("0.01"),
52
+ data: "0x",
53
+ };
54
+ ```
55
+
56
+ ## Building and executing
57
+
58
+ `widget.createBatchOp({ calls })` builds a `FluentBatchOperation` and encodes its calls at once.
59
+ It throws a plain `Error` when `calls` is empty, or when a call has neither `data` nor `abi` with
60
+ `method`, so a mistake in a call surfaces before anything is shown to the person. The optional
61
+ `reviewTitle` is the heading of the operation's Review (Fluent ID, Prompt mode).
62
+
63
+ `execute(options?)` sends the operation for the Widget account and resolves once it is
64
+ included in a block. With no options, it follows `widget.signingMode` and the Gas payment
65
+ chosen in the widget; [Gas payment](#gas-payment) and
66
+ [concepts.md](../concepts.md#prompt-mode-and-silent-mode) cover the options.
67
+
68
+ Before offering the action, read the Widget account from `widget.account`:
69
+
70
+ - `executionReady` is `true` when the account can send now.
71
+ - `executionStatus` says why it cannot: `"disconnected"` when no Widget account can send, which
72
+ includes a Fluent ID still being prepared or whose account failed; `"unavailable"` or
73
+ `"error"` (with a reason in `executionError`) only for a connected External wallet whose client
74
+ is not ready. Keep a `default` branch in any `switch` over it.
75
+ - The operation's own `canExecute` is read once, when the operation is built, and is not
76
+ updated afterwards; read `widget.account.executionReady` for the live value.
77
+
78
+ When the Widget account is not ready, `execute()` first tries to prepare the Fluent ID, and
79
+ rejects with a plain `Error` when it cannot. With nobody connected, it opens the connect dialog
80
+ and rejects with a plain `Error`: call it again once the person is connected. In Prompt mode the
81
+ Review is shown before either.
82
+
83
+ A call that reverts rejects `execute()`. For a Fluent ID nothing of the operation applies; under
84
+ Sponsorship the rejection can be a `FluentSponsorshipFallbackError`
85
+ ([sponsorship.md](sponsorship.md)). For an External wallet the calls that landed before the
86
+ reverted one stay applied, and the calls after it are not sent.
87
+
88
+ ## Example: approve and deposit in one Batch operation
89
+
90
+ The App deposits 10 tokens into an ERC-4626 vault: an `approve` of the vault, then the vault's
91
+ `deposit`. For a Fluent ID the two calls land in one transaction, so the approval never lands
92
+ without the deposit. For an External wallet they are two transactions, two wallet prompts.
93
+
94
+ ```tsx
95
+ import {
96
+ FluentReviewRejectedError,
97
+ FluentWidget,
98
+ useFluentWidget,
99
+ type FluentWidgetConfig,
100
+ } from "@fluent.xyz/connect";
101
+ import { useState } from "react";
102
+ import { erc20Abi, parseAbi, parseUnits, type Address } from "viem";
103
+
104
+ const config: FluentWidgetConfig = {
105
+ appId: "app_0123456789abcdef0123456789abcdef",
106
+ privyClientId: "client-0123456789abcdef",
107
+ network: "testnet",
108
+ };
109
+
110
+ const asset: Address = "0x1111111111111111111111111111111111111111";
111
+ const vault: Address = "0x3333333333333333333333333333333333333333";
112
+ const vaultAbi = parseAbi([
113
+ "function deposit(uint256 assets, address receiver) returns (uint256 shares)",
114
+ ]);
115
+
116
+ function Deposit() {
117
+ const { widget, status } = useFluentWidget();
118
+ const [note, setNote] = useState("");
119
+ const { account } = widget;
120
+
121
+ async function deposit() {
122
+ const receiver = account.address;
123
+ if (!receiver) return;
124
+ const assets = parseUnits("10", 18);
125
+ const operation = widget.createBatchOp({
126
+ reviewTitle: "Deposit 10 tokens",
127
+ calls: [
128
+ { to: asset, abi: erc20Abi, method: "approve", args: [vault, assets] },
129
+ { to: vault, abi: vaultAbi, method: "deposit", args: [assets, receiver] },
130
+ ],
131
+ });
132
+ try {
133
+ const result = await operation.execute();
134
+ setNote(`Deposited in ${result.hash}`);
135
+ } catch (error) {
136
+ if (error instanceof FluentReviewRejectedError) return; // the person said no
137
+ setNote(error instanceof Error ? error.message : "The deposit failed.");
138
+ }
139
+ }
140
+
141
+ if (status !== "connected") return <p>Connect to deposit.</p>;
142
+ return (
143
+ <div>
144
+ <button type="button" disabled={!account.executionReady} onClick={() => void deposit()}>
145
+ Deposit 10 tokens
146
+ </button>
147
+ {account.executionReady ? null : <p>Your account cannot send yet.</p>}
148
+ <p>{note}</p>
149
+ </div>
150
+ );
151
+ }
152
+
153
+ export function App() {
154
+ return <FluentWidget config={config} mode="page" renderPage={() => <Deposit />} />;
155
+ }
156
+ ```
157
+
158
+ ## Gas payment
159
+
160
+ A Fluent ID's operation is paid in one of three ways. With **Sponsorship**, the App pays
161
+ through Fluent's sponsorship service; it is asked for on an operation paid in ETH unless
162
+ `sponsorship` is `"never"`. With **the account's own ETH**, the account pays: when Sponsorship
163
+ is not asked for, or as the fallback when it is refused. With **a Gas token**, the account pays
164
+ in one of the Gas tokens Fluent ships for the Network, and Sponsorship is not asked for. An
165
+ External wallet always pays its own ETH, and the `gasPayment` option does not apply to it.
166
+ Every Sponsorship outcome, the fallback and `FluentSponsorshipFallbackError` are in
167
+ [sponsorship.md](sponsorship.md).
168
+
169
+ `widget.gasPayment` is the Gas payment chosen in the widget, which `execute()` uses when given
170
+ no `gasPayment`; pass a `FluentGasPayment` to `execute()` to decide for one operation. With a
171
+ Gas token, `includeApproval: true` and an `approveAmount` (in the token's smallest unit) add an
172
+ approval of that amount for the Gas token's payment at the start of the operation.
173
+
174
+ Gas limits can be fixed by hand with the experimental `userOperationGas` option
175
+ ([experimental.md](../experimental.md#useroperationgas)); leaving it out lets the widget
176
+ estimate.
177
+
178
+ ## The result
179
+
180
+ `execute()` resolves with a `FluentExecuteResult`:
181
+
182
+ | Member | Fluent ID | External wallet |
183
+ |---|---|---|
184
+ | `hash` | The hash of the one transaction. | The hash of the last call's transaction. |
185
+ | `hashes` | `[hash]`. | One hash per call, in order. |
186
+ | `receipt` | The transaction's receipt, when present. | The last call's receipt. |
187
+ | `userOpHash` | The ERC-4337 operation hash. | Absent. |
188
+ | `atomic` | `true`. | `false`. |
189
+ | `sponsored` | See below. | `false`. |
190
+
191
+ `sponsored` says whether the App's Sponsorship paid, read from the included operation's
192
+ receipt and, when the receipt names no paymaster, from whether a sponsored submission was made:
193
+ treat only `true` as sponsored. When it is `false` and when `null`:
194
+ [sponsorship.md](sponsorship.md). The members `paymaster` and `timing` are experimental
195
+ ([experimental.md](../experimental.md#paymaster-and-timing)).
196
+
197
+ ## Rejections
198
+
199
+ Branch on the error's class with `instanceof`, then on its `code`, never on its message:
200
+
201
+ | Error | `code` | When |
202
+ |---|---|---|
203
+ | `FluentReviewRejectedError` | `"transaction_review_rejected"` | A Fluent ID in Prompt mode: the person dismissed the Review. |
204
+ | `FluentSponsorshipFallbackError` | `"denied"`, `"unauthorized"`, `"unreachable"`, `"no_token"` | A Fluent ID: the sponsored attempt and the fallback both failed. |
205
+ | `FluentUserOperationGasError` | see [errors.md](../errors.md#fluentuseroperationgaserror) | Experimental, with the `userOperationGas` option ([experimental.md](../experimental.md#useroperationgas)). |
206
+
207
+ An External wallet shows no widget Review: when the person refuses in the wallet's own prompt,
208
+ `execute()` rejects with the wallet's error, not with a `FluentReviewRejectedError`. Which
209
+ failures under Sponsorship become a `FluentSponsorshipFallbackError` and which arrive as they were
210
+ thrown: [sponsorship.md](sponsorship.md).
211
+ Keep a `default` branch in every `switch` over a `code`: a later release may add one.
212
+
213
+ ```ts
214
+ import {
215
+ FluentReviewRejectedError,
216
+ FluentSponsorshipFallbackError,
217
+ type FluentBatchOperation,
218
+ type FluentExecuteResult,
219
+ } from "@fluent.xyz/connect";
220
+
221
+ export async function executeOrExplain(
222
+ operation: FluentBatchOperation,
223
+ ): Promise<FluentExecuteResult | string> {
224
+ try {
225
+ return await operation.execute();
226
+ } catch (error) {
227
+ if (error instanceof FluentReviewRejectedError) {
228
+ switch (error.code) {
229
+ case "transaction_review_rejected":
230
+ return "You dismissed the operation.";
231
+ default:
232
+ return "You dismissed the request.";
233
+ }
234
+ }
235
+ if (error instanceof FluentSponsorshipFallbackError) {
236
+ switch (error.code) {
237
+ case "unreachable":
238
+ return "Sponsorship did not answer, and paying with your own ETH failed too.";
239
+ case "denied":
240
+ return "The sponsored attempt failed, and paying with your own ETH failed too.";
241
+ default:
242
+ return "The operation could not be sent.";
243
+ }
244
+ }
245
+ // A wallet's own refusal, or a failure outside a sponsored attempt.
246
+ return error instanceof Error ? error.message : "Something went wrong.";
247
+ }
248
+ }
249
+ ```
250
+
251
+ Every code and what to do about it: [errors.md](../errors.md).