@fluent.xyz/connect 0.5.2 → 0.6.0-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/INTEGRATION.md +43 -1429
- package/README.md +89 -285
- package/dist/fluent-connect.css +1 -1
- package/dist/index.d.ts +1024 -2885
- package/dist/index.js +9997 -8455
- package/dist/index.js.map +1 -1
- package/docs/api.md +1789 -0
- package/docs/concepts.md +126 -0
- package/docs/configuration.md +276 -0
- package/docs/errors.md +213 -0
- package/docs/experimental.md +247 -0
- package/docs/getting-started.md +336 -0
- package/docs/guides/backend-auth.md +176 -0
- package/docs/guides/iframe.md +108 -0
- package/docs/guides/link-x.md +166 -0
- package/docs/guides/signing.md +157 -0
- package/docs/guides/sponsorship.md +248 -0
- package/docs/guides/transactions.md +251 -0
- package/docs/upgrading-0.5.md +376 -0
- package/package.json +5 -2
|
@@ -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).
|