@fluent.xyz/connect 0.6.0-rc.2 → 0.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/fluent-connect.css +1 -1
- package/dist/fonts/LICENSE-Inter.txt +93 -0
- package/dist/fonts/inter-latin-ext-wght-normal.woff2 +0 -0
- package/dist/fonts/inter-latin-wght-normal.woff2 +0 -0
- package/dist/index.d.ts +35 -4
- package/dist/index.js +401 -324
- package/dist/index.js.map +1 -1
- package/docs/api.md +51 -4
- package/docs/configuration.md +2 -3
- package/docs/errors.md +14 -1
- package/docs/experimental.md +1 -1
- package/docs/guides/transactions.md +12 -3
- package/package.json +4 -3
package/docs/api.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
<!-- Generated by `pnpm --filter @fluent.xyz/connect docs:api` from the TSDoc in `src`;
|
|
4
4
|
do not edit by hand. -->
|
|
5
5
|
|
|
6
|
-
Every export of `@fluent.xyz/connect`:
|
|
6
|
+
Every export of `@fluent.xyz/connect`: 65 names, 15 values and 50 types. A name or member marked **experimental** may change or be removed in a minor release; [experimental.md](experimental.md) explains each one. Every other name is kept after 0.6.0.
|
|
7
7
|
|
|
8
8
|
Each export shows its TSDoc, its declaration (a function's body left out), the literals of a union of strings, and a table of its members, nested members by their dotted path; a union of object types shows its members in its declaration instead.
|
|
9
9
|
|
|
@@ -13,7 +13,7 @@ Each export shows its TSDoc, its declaration (a function's body left out), the l
|
|
|
13
13
|
- [Config](#config): `FluentWidgetConfig`, `FluentWidgetNetwork`, `FluentWidgetAuthMethod`, `FluentWidgetAssets`
|
|
14
14
|
- [Batch operations](#batch-operations): `FluentBatchApi`, `FluentBatchOperationInput`, `FluentBatchCallInput`, `FluentBatchOperation`, `FluentBatchOperationExecuteOptions`, `FluentEncodedBatchCall`, `FluentExecuteResult`, `FluentGasPayment`, `FluentWidgetGasPayment`, `FluentGasTokenSymbol`
|
|
15
15
|
- [Signing](#signing): `FluentSignApi`, `FluentSigningMode`
|
|
16
|
-
- [Auth and errors](#auth-and-errors): `FluentAuthError`, `FluentAuthErrorCode`, `FluentWidgetConfigError`, `FluentWidgetConfigErrorCode`, `FluentReviewRejectedError`, `FluentReviewRejectedErrorCode`, `FluentSponsorshipFallbackError`, `FluentSponsorshipReason`
|
|
16
|
+
- [Auth and errors](#auth-and-errors): `FluentAuthError`, `FluentAuthErrorCode`, `FluentWidgetConfigError`, `FluentWidgetConfigErrorCode`, `FluentReviewRejectedError`, `FluentReviewRejectedErrorCode`, `FluentSponsorshipFallbackError`, `FluentSponsorshipReason`, `FluentGasPaymentError`, `FluentGasPaymentErrorCode`
|
|
17
17
|
- [Link X](#link-x): `useLinkX`, `FluentLinkXStatus`, `FluentLinkXResult`, `FluentXAccount`
|
|
18
18
|
- [Iframe](#iframe): `useFluentIframeBridge`, `UseFluentIframeBridgeOptions`, `FluentIframeElement`
|
|
19
19
|
- [Chains and tokens](#chains-and-tokens): `fluentMainnet`, `fluentTestnet`, `getFluentChainByChainId`, `getFluentChainForNetwork`, `FluentChainDefinition`, `FluentTokenDefinition`
|
|
@@ -431,7 +431,7 @@ export type FluentWidgetConfig = {
|
|
|
431
431
|
| `execution` | `FluentWidgetExecution` | yes | **yes** | How a Fluent ID's send is executed: a `FluentWidgetExecution`, each of whose sources is a `FluentWidgetExecutionSource`. Every field defaults to the fast path, which falls back to the bundler on its own: set a field to switch that one answer to the bundler for good. **Experimental.** May change or be removed in a minor release while the defaults are measured; the defaults are the recommended setting. |
|
|
432
432
|
| `quickSign` | `{ whitelistAddresses?: readonly string[]; }` | yes | no | |
|
|
433
433
|
| `quickSign.whitelistAddresses` | `readonly string[]` | yes | no | Call targets Quick sign may execute without the Review. With a list set, a Batch operation runs in Silent mode only when every call's `to` is on it; a single call to any other address shows the Review, even with Quick sign on. An empty list is honoured and stops Quick sign from silencing anything; omit the option to keep it covering every address. Compared case-insensitively. `signMessage` / `signTypedData` have no call target and are not scoped by this. |
|
|
434
|
-
| `reputationEnabled` | `boolean` | yes | no | `false` drops the Reputation tab
|
|
434
|
+
| `reputationEnabled` | `boolean` | yes | no | `false` drops the Reputation tab that follows Tokens and Activity in the account drawer. The families request is never made. Default `true`. |
|
|
435
435
|
| `source` | `string` | yes | no | |
|
|
436
436
|
| `campaign` | `string` | yes | no | |
|
|
437
437
|
| `disableAnalytics` | `boolean` | yes | no | Turns off all analytics: PostHog is never initialised, nothing is sent or stored. |
|
|
@@ -631,7 +631,7 @@ export type FluentBatchOperation = {
|
|
|
631
631
|
| `calls` | `readonly FluentBatchCallInput[]` | no | no | The calls as the host passed them. |
|
|
632
632
|
| `encodedCalls` | `FluentEncodedBatchCall[]` | no | no | The same calls encoded, in order: what `execute()` sends. |
|
|
633
633
|
| `canExecute` | `boolean` | no | no | Whether the widget could send the operation when it was built: the Widget account ready, or able to prepare itself when `execute()` is called. Not updated afterwards; read `widget.account.executionReady` for the live value. |
|
|
634
|
-
| `execute` | `(options?: FluentBatchOperationExecuteOptions) => Promise<FluentExecuteResult>` | no | no | Executes the operation for the Widget account and resolves once it is included. **Throws** `FluentReviewRejectedError` with `code` `transaction_review_rejected` when the person dismisses the Review, which a Fluent ID shows in Prompt mode; an External wallet's refusal in its own prompt rejects with the wallet's error. **Throws** `FluentSponsorshipFallbackError` when a Fluent ID asked for Sponsorship, a sponsored submission failed, and the submission in which the account pays its own gas failed too; its `code` says why Sponsorship failed: `denied`, `unauthorized`, `unreachable` or `no_token`. A failure while waiting for an operation's inclusion is not wrapped: it rejects with its own error, and an operation whose wait failed was submitted. What else is not wrapped: [guides/sponsorship.md](guides/sponsorship.md#both-failed-fluentsponsorshipfallbackerror). **Throws** `FluentUserOperationGasError` (experimental) with `code` `invalid_policy` for a `skipEstimation` policy that cannot be used (other invalid `userOperationGas` values throw a plain `Error`), and `paymaster_gas_mismatch` when, with estimation skipped, the paymaster's authorization of a Gas token payment does not match the fixed gas limits. Under Sponsorship, a failed check of the paymaster's gas fails the sponsored submission instead, and the account pays its own gas. |
|
|
634
|
+
| `execute` | `(options?: FluentBatchOperationExecuteOptions) => Promise<FluentExecuteResult>` | no | no | Executes the operation for the Widget account and resolves once it is included. **Throws** `FluentReviewRejectedError` with `code` `transaction_review_rejected` when the person dismisses the Review, which a Fluent ID shows in Prompt mode; an External wallet's refusal in its own prompt rejects with the wallet's error. **Throws** `FluentSponsorshipFallbackError` when a Fluent ID asked for Sponsorship, a sponsored submission failed, and the submission in which the account pays its own gas failed too; its `code` says why Sponsorship failed: `denied`, `unauthorized`, `unreachable` or `no_token`. A failure while waiting for an operation's inclusion is not wrapped: it rejects with its own error, and an operation whose wait failed was submitted. What else is not wrapped: [guides/sponsorship.md](guides/sponsorship.md#both-failed-fluentsponsorshipfallbackerror). **Throws** `FluentUserOperationGasError` (experimental) with `code` `invalid_policy` for a `skipEstimation` policy that cannot be used (other invalid `userOperationGas` values throw a plain `Error`), and `paymaster_gas_mismatch` when, with estimation skipped, the paymaster's authorization of a Gas token payment does not match the fixed gas limits. Under Sponsorship, a failed check of the paymaster's gas fails the sponsored submission instead, and the account pays its own gas. **Throws** `FluentGasPaymentError` with `code` `paymaster_unavailable` when a Fluent ID's operation is paid in a Gas token and the address of the paymaster to approve it to cannot be read; nothing has been signed or sent. |
|
|
635
635
|
|
|
636
636
|
### `FluentBatchOperationExecuteOptions`
|
|
637
637
|
|
|
@@ -714,6 +714,13 @@ export type FluentExecuteResult = {
|
|
|
714
714
|
How one operation's gas is paid: a Gas token by symbol, or native ETH, and whether
|
|
715
715
|
Sponsorship is asked for.
|
|
716
716
|
|
|
717
|
+
Without `includeApproval`, the widget adds the approval of the Gas token to its ERC-20
|
|
718
|
+
paymaster at the start of the operation when the account's allowance is below the threshold:
|
|
719
|
+
1 USDnr when the allowance is below 0.1 USDnr, 10 BLEND when it is below 1 BLEND. An
|
|
720
|
+
allowance that cannot be read counts as none. `includeApproval: true` with an `approveAmount`
|
|
721
|
+
approves that amount instead, whatever the allowance. Either way the Review lists the
|
|
722
|
+
operation's own calls, and nothing is added for `"ETH"` or for an External wallet.
|
|
723
|
+
|
|
717
724
|
```ts declaration
|
|
718
725
|
export type FluentGasPayment = {
|
|
719
726
|
/**
|
|
@@ -736,7 +743,9 @@ export type FluentGasPayment = {
|
|
|
736
743
|
sponsorship?: "auto" | "never";
|
|
737
744
|
} & (
|
|
738
745
|
| {
|
|
746
|
+
/** Approves `approveAmount` to the paymaster whatever the allowance, for a Gas token. */
|
|
739
747
|
includeApproval: true;
|
|
748
|
+
/** In the Gas token's smallest unit. */
|
|
740
749
|
approveAmount: bigint;
|
|
741
750
|
}
|
|
742
751
|
| {
|
|
@@ -1106,6 +1115,44 @@ export type FluentSponsorshipReason =
|
|
|
1106
1115
|
|
|
1107
1116
|
Literals: `denied`, `no_token`, `not_requested`, `unauthorized`, `unreachable`.
|
|
1108
1117
|
|
|
1118
|
+
### `FluentGasPaymentError`
|
|
1119
|
+
|
|
1120
|
+
*value*
|
|
1121
|
+
|
|
1122
|
+
A Gas token payment the widget could not prepare. Thrown by `execute()` of a Fluent ID's Batch
|
|
1123
|
+
operation paid in a Gas token, before any signature is requested and before anything is sent,
|
|
1124
|
+
so the operation can be tried again as it is. `code`, a `FluentGasPaymentErrorCode`,
|
|
1125
|
+
identifies the failure; `cause` holds the error of the failed request when there was one.
|
|
1126
|
+
|
|
1127
|
+
```ts declaration
|
|
1128
|
+
export class FluentGasPaymentError extends Error {
|
|
1129
|
+
constructor(
|
|
1130
|
+
readonly code: FluentGasPaymentErrorCode,
|
|
1131
|
+
message: string,
|
|
1132
|
+
options?: { cause?: unknown },
|
|
1133
|
+
) { … }
|
|
1134
|
+
}
|
|
1135
|
+
```
|
|
1136
|
+
|
|
1137
|
+
| Member | Type | Optional | Experimental | Description |
|
|
1138
|
+
|---|---|---|---|---|
|
|
1139
|
+
| `code` | `FluentGasPaymentErrorCode` | no | no | |
|
|
1140
|
+
|
|
1141
|
+
### `FluentGasPaymentErrorCode`
|
|
1142
|
+
|
|
1143
|
+
*type*
|
|
1144
|
+
|
|
1145
|
+
Why a `FluentGasPaymentError` was thrown. `paymaster_unavailable`: the request for the address
|
|
1146
|
+
of the paymaster that charges Gas tokens on the operation's Network failed, or its answer held
|
|
1147
|
+
no address, so the widget has no spender to approve the Gas token to. Keep a `default` branch
|
|
1148
|
+
in a `switch` over it: a later release may add a code.
|
|
1149
|
+
|
|
1150
|
+
```ts declaration
|
|
1151
|
+
export type FluentGasPaymentErrorCode = "paymaster_unavailable";
|
|
1152
|
+
```
|
|
1153
|
+
|
|
1154
|
+
Literals: `paymaster_unavailable`.
|
|
1155
|
+
|
|
1109
1156
|
## Link X
|
|
1110
1157
|
|
|
1111
1158
|
### `useLinkX`
|
package/docs/configuration.md
CHANGED
|
@@ -145,9 +145,8 @@ drawer and the External wallet choices of the connect dialog keep their own imag
|
|
|
145
145
|
|
|
146
146
|
### Account drawer
|
|
147
147
|
|
|
148
|
-
**`reputationEnabled`**. `false` drops the Reputation tab
|
|
149
|
-
|
|
150
|
-
`true`.
|
|
148
|
+
**`reputationEnabled`**. `false` drops the Reputation tab that follows Tokens and Activity in the
|
|
149
|
+
account drawer; the widget then makes no reputation request. Default `true`.
|
|
151
150
|
|
|
152
151
|
**`swapper`** is experimental: see [experimental.md](experimental.md#swapper).
|
|
153
152
|
|
package/docs/errors.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Errors
|
|
2
2
|
|
|
3
|
-
Every error the widget hands an App on purpose is an instance of one of
|
|
3
|
+
Every error the widget hands an App on purpose is an instance of one of six classes, each with
|
|
4
4
|
a string `code`. This page lists every code of each class, the call that throws it today, what it
|
|
5
5
|
means and what to do. The [API reference](api.md#auth-and-errors) holds the declarations.
|
|
6
6
|
|
|
@@ -202,6 +202,19 @@ sponsored submission signs too, once the paymaster has answered, so a Signer's r
|
|
|
202
202
|
reaches `cause` the same way, with the code `denied`; that case was read from viem's code, not
|
|
203
203
|
measured.
|
|
204
204
|
|
|
205
|
+
## `FluentGasPaymentError`
|
|
206
|
+
|
|
207
|
+
A Fluent ID's Batch operation paid in a Gas token could not be prepared. Before the operation is
|
|
208
|
+
signed, the widget reads the address of the paymaster that charges Gas tokens, because the
|
|
209
|
+
approval it may add to the operation names that paymaster as the spender. It throws before any
|
|
210
|
+
signature is requested and before anything is sent, so the same operation can be tried again.
|
|
211
|
+
`cause` holds the error of the failed request when there was one. An External wallet pays its own
|
|
212
|
+
gas and never throws it.
|
|
213
|
+
|
|
214
|
+
| `code` | Thrown by | What it means | What to do |
|
|
215
|
+
|---|---|---|---|
|
|
216
|
+
| `paymaster_unavailable` | `execute()` | The request for the paymaster's address on the operation's Network failed, or its answer held no address, so the widget has no spender to approve the Gas token to. | Try again later, or pay in ETH (`gasPayment: { symbol: "ETH" }`). |
|
|
217
|
+
|
|
205
218
|
## `FluentUserOperationGasError`
|
|
206
219
|
|
|
207
220
|
*Experimental*: may change or be removed in a minor release, with the `userOperationGas` option
|
package/docs/experimental.md
CHANGED
|
@@ -94,7 +94,7 @@ a `FluentUserOperationGas`, one of three shapes ([api.md](api.md#fluentuseropera
|
|
|
94
94
|
|
|
95
95
|
| Shape | What the widget does |
|
|
96
96
|
|---|---|
|
|
97
|
-
| `{ callGasLimit }` | Uses this execution gas limit for the whole Batch operation
|
|
97
|
+
| `{ callGasLimit }` | Uses this execution gas limit for the whole Batch operation and estimates the rest; the gas of a Gas token approval, explicit or the one the widget adds automatically, is spent inside this limit. |
|
|
98
98
|
| `{ callGasBuffer: { percentage?, fixed? } }` | Estimates, then adds `percentage` percent (rounded up), then `fixed` gas. |
|
|
99
99
|
| `{ skipEstimation: true, ... }` | Estimates nothing: the App fixes the account's limits, and either fixes the paymaster's too or leaves them to the paymaster. |
|
|
100
100
|
|
|
@@ -167,9 +167,18 @@ Every Sponsorship outcome, the fallback and `FluentSponsorshipFallbackError` are
|
|
|
167
167
|
[sponsorship.md](sponsorship.md).
|
|
168
168
|
|
|
169
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.
|
|
171
|
-
|
|
172
|
-
|
|
170
|
+
no `gasPayment`; pass a `FluentGasPayment` to `execute()` to decide for one operation.
|
|
171
|
+
|
|
172
|
+
A Gas token is charged by its paymaster only up to the account's allowance to it, so an operation
|
|
173
|
+
paid in a Gas token can start with an approval of that paymaster. Without `includeApproval`, the
|
|
174
|
+
widget adds the approval automatically when the allowance is short: 1 USDnr when the USDnr
|
|
175
|
+
allowance is below 0.1 USDnr, and 10 BLEND when the BLEND allowance is below 1 BLEND. An
|
|
176
|
+
allowance the widget cannot read counts as none, and when ZeroDev cannot name the paymaster,
|
|
177
|
+
`execute()` rejects before anything is signed, with an error whose `name` is
|
|
178
|
+
`FluentGasPaymentError` and whose `code` is `paymaster_unavailable`. With `includeApproval: true` and an
|
|
179
|
+
`approveAmount` (in the token's smallest unit), the operation starts with an approval of that
|
|
180
|
+
amount instead, whatever the allowance. The Review lists the operation's own calls, not the
|
|
181
|
+
approval, and an operation paid in ETH or sent by an External wallet gets none.
|
|
173
182
|
|
|
174
183
|
Gas limits can be fixed by hand with the experimental `userOperationGas` option
|
|
175
184
|
([experimental.md](../experimental.md#useroperationgas)); leaving it out lets the widget
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fluent.xyz/connect",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.1",
|
|
4
4
|
"description": "Fluent Connect React widget \u2014 Privy login, ZeroDev smart account, batch operations, and wallet UI",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -54,9 +54,10 @@
|
|
|
54
54
|
"scripts": {
|
|
55
55
|
"build": "pnpm run build:js && pnpm run build:css",
|
|
56
56
|
"build:js": "tsup",
|
|
57
|
-
"build:css": "tailwindcss -i ./src/styles/globals.css -o ./dist/fluent-connect.css --minify",
|
|
57
|
+
"build:css": "tailwindcss -i ./src/styles/globals.css -o ./dist/fluent-connect.css --minify && pnpm run copy:fonts",
|
|
58
|
+
"copy:fonts": "node -e \"require('node:fs').cpSync('src/styles/fonts', 'dist/fonts', { recursive: true })\"",
|
|
58
59
|
"dev": "tsup --watch --clean=false",
|
|
59
|
-
"dev:css": "tailwindcss -i ./src/styles/globals.css -o ./dist/fluent-connect.css --watch=always",
|
|
60
|
+
"dev:css": "pnpm run copy:fonts && tailwindcss -i ./src/styles/globals.css -o ./dist/fluent-connect.css --watch=always",
|
|
60
61
|
"typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.lock.json && tsc --noEmit -p tsconfig.docs.json",
|
|
61
62
|
"test": "vitest run",
|
|
62
63
|
"test:kernel-signature": "FLUENT_KERNEL_SIGNATURE_TEST=1 vitest run src/widget/kernelSignature.fork.test.ts",
|