@fluent.xyz/connect 0.7.2 → 0.8.1-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/docs/concepts.md CHANGED
@@ -81,6 +81,26 @@ once per `execute()` call:
81
81
 
82
82
  The option itself is in [configuration.md](configuration.md).
83
83
 
84
+ ## User tokens
85
+
86
+ The Tokens tab of the account drawer lists the Default tokens, the App's Integrator tokens
87
+ (`tokens` in [configuration.md](configuration.md#fluentwidgetprops)) and the person's User
88
+ tokens, and ends with an Add token row that opens the add form. The form takes one contract
89
+ address on the current Network, reads the token's symbol, name and decimals from that contract,
90
+ and shows them with the full address before the person confirms: the metadata comes from the
91
+ contract, never from typed input. Adding is refused for an address that is not a contract or
92
+ holds no token, for a token already on the list under any Token source, and past 50 User tokens
93
+ on one Network. A symbol another Display token already carries is allowed, after a warning that
94
+ anyone can deploy a token with someone else's symbol. A User token is labelled "Added by you" in
95
+ the list, and its row's menu removes it.
96
+
97
+ User tokens are part of the person's User settings, read and saved on the service with an Auth
98
+ token; while the widget has not yet read that person's settings, an add lands in this browser's
99
+ storage instead. The service's refusal of an add is shown under the address field, and of a
100
+ removal next to the list; neither reaches your app. An External wallet keeps User tokens the same
101
+ way, through the Service session its `getAuthToken()` row above describes, although Quick sign and
102
+ the Gas token do not apply to it.
103
+
84
104
  ## What the Swap page can do on mainnet
85
105
 
86
106
  The drawer's Swap page deposits from Ethereum into the user's Fluent smart
@@ -91,6 +111,14 @@ account swaps what landed, on Fluent, through FluxFlow. The user signs the bridg
91
111
  alone; once the deposit lands, the swap is priced and sent without a second
92
112
  press, from whichever drawer page the user is on.
93
113
 
114
+ On mainnet a deposit of USDC is an **Order deposit** where the Order deposit
115
+ service quotes one: the External wallet approves USDC and opens one order on
116
+ Ethereum, and a solver pays USDnr to the Fluent account. The page shows the
117
+ solver's fee and what arrives before the user signs. When the service has no
118
+ quote, or cannot be reached, the page converts USDC to USDnr on Ethereum and
119
+ sends that over the bridge instead. The service's URL is the experimental
120
+ `orderDepositUrl` option ([experimental.md](experimental.md#orderdepositurl)).
121
+
94
122
  The page connects the External wallet that holds the funds by itself, on both
95
123
  networks. A desktop browser offers the wallet extensions it announces; a phone
96
124
  offers MetaMask, Trust Wallet and Rainbow, each opened through a link that
@@ -85,9 +85,10 @@ The two chains are exported as [`fluentTestnet`](api.md#fluenttestnet) and
85
85
 
86
86
  **`enabledAuthMethods`**. The Auth methods the connect dialog offers beside X, in the order
87
87
  given: any of `"google"`, `"email"` and `"passkey"`. X is always offered and is not a value here.
88
- The default is `["google", "email", "passkey"]`; a shorter list drops the rest, and `[]` leaves X
89
- alone. Unknown values and duplicates are dropped. An Auth method also has to be enabled for the
90
- App by Fluent: listing it here only decides whether its button is drawn.
88
+ The default is `["google", "email"]`: a passkey is offered only when the list names it, a shorter
89
+ list drops the rest, and `[]` leaves X alone. Unknown values and duplicates are dropped. An Auth
90
+ method also has to be enabled for the App by Fluent: listing it here only decides whether its
91
+ button is drawn.
91
92
 
92
93
  - `invalid_option` when it is not a list or another iterable. `null` counts as unset and gives
93
94
  the default; a non-empty string is read character by character, so every value is dropped and
@@ -182,6 +183,7 @@ find it; what it does is in [experimental.md](experimental.md):
182
183
  - `gasPayment.ethValueByToken`: [experimental.md](experimental.md#gaspaymentethvaluebytoken)
183
184
  - `execution`: [experimental.md](experimental.md#execution)
184
185
  - `sponsorshipUrl`: [experimental.md](experimental.md#sponsorshipurl)
186
+ - `orderDepositUrl`: [experimental.md](experimental.md#orderdepositurl)
185
187
  - `privyClientId`, which is required: [experimental.md](experimental.md#privyclientid)
186
188
 
187
189
  ### Removed options
@@ -19,6 +19,7 @@ applies to: a Fluent ID, an External wallet, or both. The exact types are in [ap
19
19
  | `customOAuthRedirectUrl` | `FluentWidgetConfig` | [`customOAuthRedirectUrl`](#customoauthredirecturl) |
20
20
  | `swapper` | `FluentWidgetConfig` | [`swapper`](#swapper) |
21
21
  | `sponsorshipUrl` | `FluentWidgetConfig` | [`sponsorshipUrl`](#sponsorshipurl) |
22
+ | `orderDepositUrl` | `FluentWidgetConfig` | [`orderDepositUrl`](#orderdepositurl) |
22
23
  | `privyClientId` | `FluentWidgetConfig` | [`privyClientId`](#privyclientid) |
23
24
 
24
25
  ## `privyAdapter`
@@ -240,6 +241,27 @@ Network's own ([api.md](api.md#fluentwidgetconfig)).
240
241
  - **Applies to**: Sponsorship of a Fluent ID's operations. An External wallet is never
241
242
  sponsored.
242
243
 
244
+ ## `orderDepositUrl`
245
+
246
+ `FluentWidgetConfig.orderDepositUrl` points the widget at an Order deposit service other than
247
+ the Network's own: the base URL its quote and order requests go to
248
+ ([api.md](api.md#fluentwidgetconfig)).
249
+
250
+ - **What it does**: on the Swap page a USDC deposit is sent as one order on Ethereum when the
251
+ service quotes it, and a solver pays USDnr to the Fluent account. When the service has no
252
+ quote, or cannot be reached, USDC is converted to USDnr on Ethereum and crosses over the
253
+ bridge, as it did before this option existed. The Activity list reads the wallet's orders
254
+ from the same service.
255
+ - **Default**: the Order deposit service of the configured Network on mainnet. Testnet has
256
+ none, and USDC cannot be deposited there.
257
+ - **When to use it**: local development of the service only. An empty string turns Order
258
+ deposits off. Every real integration uses the default.
259
+ - **Errors**: `<FluentWidget>` throws `FluentWidgetConfigError` with `code` `invalid_option`
260
+ when the value is not a string, or is not an absolute `http(s)` URL without a query or a
261
+ fragment ([errors.md](errors.md#fluentwidgetconfigerror)).
262
+ - **Applies to**: a deposit of USDC from an External wallet on Ethereum, whichever account kind
263
+ receives it.
264
+
243
265
  ## `privyClientId`
244
266
 
245
267
  `FluentWidgetConfig.privyClientId` is the login client Fluent issues for the App, a `client-…`
@@ -134,6 +134,21 @@ export function Root() {
134
134
  }
135
135
  ```
136
136
 
137
+ ## Server-side rendering
138
+
139
+ `<FluentWidget>` renders on a server. The render context it hands your content there is the
140
+ `restoring` status with no session and no wallet — a server cannot know what this browser has
141
+ stored — and the real state arrives after hydration, which is why
142
+ [Reading the account](#reading-the-account) says to branch on `status`. A route that renders
143
+ the widget server-side returns markup rather than an error, with no client-only island and no
144
+ `ssr.noExternal`. The package's own suite renders it with `renderToString` in plain Node
145
+ (`test/serverRender.node.test.ts`).
146
+
147
+ For the Next.js App Router, both entries carry `"use client"`, so a Server Component may import
148
+ the package. Function props cannot cross a React Server Components boundary, though — and
149
+ `renderPage`, `renderHome`, `renderConnectButton` and `onSessionChange` are function props — so
150
+ mount the widget from a Client Component of your own and compose your pages below it.
151
+
137
152
  ## The connect button
138
153
 
139
154
  `connectButton` decides where the widget's own button goes:
@@ -344,7 +359,7 @@ stay empty, history does not load, Sponsorship is refused.
344
359
  | Bundler and paymaster (ZeroDev) | `rpc.zerodev.app` | `rpc.zerodev.app` |
345
360
  | USD prices: Coinbase and CoinGecko first, DefiLlama for what they leave unanswered | `api.coinbase.com`, `api.coingecko.com`, `coins.llama.fi` | the same three |
346
361
  | Transaction history (the explorer's API) | `testnet.fluentscan.xyz` | `fluentscan.xyz` |
347
- | Bridge: the Ethereum RPC, the deposit indexer, the Hyperlane explorer | `ethereum-sepolia-rpc.publicnode.com`, `api.gblend.xyz`, `api.hyperlane.xyz` | `ethereum-rpc.publicnode.com`, `eth.llamarpc.com`, `eth.drpc.org`, `api.fluent.xyz`, `api.hyperlane.xyz` |
362
+ | Bridge: the Ethereum RPC, the deposit indexer, the Hyperlane explorer and, on mainnet, the Order deposit service | `ethereum-sepolia-rpc.publicnode.com`, `api.gblend.xyz`, `api.hyperlane.xyz` | `ethereum-rpc.publicnode.com`, `eth.llamarpc.com`, `eth.drpc.org`, `api.fluent.xyz`, `api.hyperlane.xyz`, `portal.fluent.xyz` |
348
363
  | Pre-funding a new Fluent ID (faucet) | `eco-faucet-api.fluent.xyz` | not used |
349
364
 
350
365
  The SDKs the widget embeds reach their own hosts, and their documentation is the list to
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fluent.xyz/connect",
3
- "version": "0.7.2",
3
+ "version": "0.8.1-rc.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",