Skip to content

Commit 218422e

Browse files
janniksjanniks
authored
docs: update connect support (#978)
Co-authored-by: janniks <janniks@users.noreply.github.com>
1 parent fb7e4f2 commit 218422e

File tree

4 files changed

+317
-6
lines changed

4 files changed

+317
-6
lines changed

‎content/docs/stacks/connect/guides/migration.mdx‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
title: 'Migration Guide'
3+
description: 'How to migrate from v7.x.x to v8.x.x of @stacks/connect'
4+
---
5+
6+
import { Steps, Step } from 'fumadocs-ui/components/steps'
7+
8+
9+
For a while now, the Stacks community has been working on a new standard for wallet-to-dapp communication.
10+
Stacks Connect and related projects now use standards like [WBIPs](https://wbips.netlify.app/) and [SIP-030](https://github.com/janniks/sips/blob/main/sips/sip-030/sip-030-wallet-interface.md) to allow wallets to communicate with dapps in a more simplified and flexible way.
11+
12+
<Callout title="Migration Status">
13+
Please be patient during this latest migration.
14+
There has been a long-running effort together with wallets to modernize and move forward the Stacks web ecosystem.
15+
It is now culminating in [SIP-030](https://github.com/janniks/sips/blob/main/sips/sip-030/sip-030-wallet-interface.md) and the new `request` method in Stacks Connect `8.x.x`.
16+
Bear with us during this migration.
17+
Wallets are still working through some bugs, details, and improvements.
18+
19+
_Feel free to continue using Stacks Connect `7.x.x` while things stabilize._
20+
The `7.x.x` version may still be more well supported by some wallets.
21+
22+
For the legacy version of `@stacks/connect` using JWT tokens, you can use:
23+
24+
```sh
25+
npm install @stacks/connect@7.10.1
26+
```
27+
28+
</Callout>
29+
30+
## Deprecations
31+
32+
The following classes, methods, and types are deprecated in favor of the new `request` RPC methods:
33+
34+
- `show...` and `open...` methods
35+
- `authenticate` method
36+
- `UserSession` class and related functionality
37+
- `AppConfig` class
38+
- `SessionOptions` interface
39+
- `SessionData` interface
40+
- `UserData` interface
41+
- `SessionDataStore` class
42+
- `InstanceDataStore` class
43+
- `LocalStorageStore` class
44+
45+
<Callout title="Backwards Compatibility">
46+
To make migrating easier, the familiar `UserSession` & `AppConfig` class still exists and is semi-backwards compatible for the `8.x.x` release.
47+
It will "cache" the user's address in local storage and allow access to it via the `loadUserData` method (as previously done).
48+
</Callout>
49+
50+
## Migration Steps
51+
52+
To update from `<=7.x.x` to latest/`8.x.x`, follow these steps:
53+
54+
<Steps>
55+
<Step title="Update your @stacks/connect version">
56+
```sh
57+
npm install @stacks/connect@latest
58+
```
59+
</Step>
60+
61+
<Step title="Replace Legacy Methods with request">
62+
Switch from `showXyz`, `openXyz`, `doXyz` methods to the `request` method:
63+
64+
- `request` follows the pattern `request(method: string, params: object)`, see [Usage](#usage) for more details
65+
- `request` is an async function, so replace the `onFinish` and `onCancel` callbacks with `.then().catch()` or `try & await`
66+
67+
Examples:
68+
- `showConnect()`, `authenticate()` → `connect()`
69+
- `useConnect().doContractCall({})` → `request("stx_callContract", {})`
70+
- `openContractDeploy()` → `request("stx_deployContract", {})`
71+
</Step>
72+
73+
<Step title="Use Connect Instead of ShowConnect/Authenticate">
74+
Switch from `showConnect` or `authenticate` to `connect()` methods:
75+
76+
- `connect()` is an alias for `request({forceWalletSelect: true}, 'getAddresses')`
77+
- `connect()` by default caches the user's address in local storage
78+
</Step>
79+
80+
<Step title="Update Authentication State Management">
81+
- Switch from `UserSession.isSignedIn()` to `isConnected()`
82+
- Switch from `UserSession.signUserOut()` to `disconnect()`
83+
</Step>
84+
85+
<Step title="Remove Legacy Code">
86+
- Remove code referencing deprecated methods (`AppConfig`, `UserSession`, etc.)
87+
- Remove the `@stacks/connect-react` package
88+
- You may need to manually reload a component to see local storage updates
89+
- No custom hooks are needed to use Stacks Connect anymore
90+
- We are working on a new `@stacks/react` package that will make usage even easier in the future (e.g., tracking transaction status, reloading components when a connection is established, updating the page when the network changes, and more)
91+
</Step>
92+
</Steps>
93+
94+
## Address Access
95+
96+
Previously, the `UserSession` class was used to access the user's addresses and data, which abstracted away the underlying implementation details.
97+
Now, the `request` method is used to directly interact with the wallet, giving developers more explicit control and clarity over what's happening under the hood.
98+
This manual approach makes the wallet interaction more transparent and customizable.
99+
Developers can manually manage the currently connected user's address in e.g. local storage, jotai, etc. or use the `connect()`/`request()` method to cache the address in local storage.
100+
101+
<Callout title="Security Note">
102+
For security reasons, the `8.x.x` release only returns the current network's address (where previously both mainnet and testnet addresses were returned).
103+
</Callout>

‎content/docs/stacks/connect/meta.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,9 @@
55
"---Stacks Connect---",
66
"index",
77
"quickstart",
8+
"support",
89
"---Guides---",
10+
"guides/migration",
911
"guides/authenticate-users",
1012
"guides/broadcast-transactions",
1113
"guides/sign-messages",

‎content/docs/stacks/connect/packages/connect.mdx‎

Lines changed: 58 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,10 @@ import { InlineCode } from '@/components/inline-code';
1515

1616
Stacks Connect enables you to authenticate your users and connect your app to their wallet. This reference contains more detailed information on how you can authenticate users, sign and broadcast transactions on their behalf, and enable users to sign messages.
1717

18+
<Callout title="Migration Note">
19+
Please be patient during the migration to version 8.x.x. There has been a long-running effort together with wallets to modernize the Stacks web ecosystem, culminating in [SIP-030](https://github.com/janniks/sips/blob/main/sips/sip-030/sip-030-wallet-interface.md) and the new `request` method in Stacks Connect 8.x.x. For the legacy version of `@stacks/connect` using JWT tokens, please use version 7.10.1. See the [Migration Guide](/docs/stacks/connect/guides/migration) for more details.
20+
</Callout>
21+
1822
### Installation
1923

2024
```package-install
@@ -72,7 +76,7 @@ const response = await request({ forceWalletSelect: true }, 'getAddresses');
7276
### Available methods
7377

7478
- [getAddresses](#getaddresses)
75-
- [sendTransfer](#sendtransfer)
79+
- [sendTransfer](#sendtransfer)
7680
- [signPsbt](#signpsbt)
7781
- [stx_getAddresses](#stx_getaddresses)
7882
- [stx_getAccounts](#stx_getaccounts)
@@ -259,11 +263,41 @@ const response = await request('stx_signStructuredMessage', {
259263
// }
260264
```
261265

266+
### Error Handling
267+
268+
The `request` method returns a Promise, allowing you to handle errors using standard Promise-based error handling patterns. You can use either `try/catch` with `async/await` or the `.catch()` method with Promise chains.
269+
270+
#### Using try/catch with async/await
271+
272+
```typescript
273+
import { request } from '@stacks/connect';
274+
275+
try {
276+
const response = await request('stx_transferStx', {
277+
amount: '1000',
278+
recipient: 'SP2MF04VAGYHGAZWGTEDW5VYCPDWWSY08Z1QFNDSN',
279+
});
280+
// SUCCESS
281+
console.log('Transaction successful:', response.txid);
282+
} catch (error) {
283+
// ERROR
284+
console.error('Wallet returned an error:', error);
285+
}
286+
```
287+
288+
### Compatibility
289+
290+
The `request` method by default adds a layer of auto-compatibility for different wallet providers. This is meant to unify the interface where wallet providers may not implement methods and results the same way.
291+
292+
<Callout title="Wallet Support">
293+
For a complete list of wallet compatibility and support status, see the [Wallet Support](/docs/stacks/connect/support) page.
294+
</Callout>
295+
262296
### Advanced Usage
263297

264298
#### request
265299

266-
The request method is called with an optional options object as the first parameter:
300+
The `request` method is called with an optional options object as the first parameter:
267301

268302
```typescript
269303
import { request } from '@stacks/connect';
@@ -272,10 +306,14 @@ import { request } from '@stacks/connect';
272306
const response = await request(
273307
{
274308
provider?: StacksProvider; // Custom provider to use for the request
275-
defaultProviders?: WbipProvider[]; // Default wallets to display in modal
309+
276310
forceWalletSelect?: boolean; // Force user to select a wallet (default: false)
277311
persistWalletSelect?: boolean; // Persist selected wallet (default: true)
278312
enableOverrides?: boolean; // Enable provider compatibility (default: true)
313+
enableLocalStorage?: boolean; // Store address in local storage (default: true)
314+
315+
defaultProviders?: WbipProvider[]; // Default wallets to display in modal
316+
approvedProviderIds?: string[]; // List of approved provider IDs to show in modal
279317
},
280318
'method',
281319
params
@@ -285,10 +323,24 @@ const response = await request(
285323
const response = await request('method', params);
286324
```
287325

288-
<Callout type="info">
326+
<Callout title="Provider Compatibility">
289327
The `enableOverrides` option enables automatic compatibility fixes for different wallet providers. For example, it handles converting numeric types between string and number formats as needed by different wallets, and remaps certain method names to match wallet-specific implementations. This ensures consistent behavior across different wallet providers without requiring manual adjustments.
290328
</Callout>
291329

330+
<Callout title="Approved Providers">
331+
The `approvedProviderIds` option allows you to filter which wallet providers are shown in the connect modal. This is useful when you want to limit the available wallet options to specific providers. For example, you might only want to support Leather wallet:
332+
333+
```typescript
334+
connect({ approvedProviderIds: ['LeatherProvider'] });
335+
```
336+
337+
Or multiple specific wallets:
338+
339+
```typescript
340+
connect({ approvedProviderIds: ['LeatherProvider', 'xverse'] });
341+
```
342+
</Callout>
343+
292344
#### requestRaw
293345

294346
The `requestRaw` method provides direct access to wallet providers without the additional features of `request`:
@@ -299,6 +351,6 @@ import { requestRaw } from '@stacks/connect';
299351
const response = await requestRaw(provider, 'method', params);
300352
```
301353

302-
<Callout type="info">
303-
`requestRaw` bypasses the UI wallet selector and other features that come with `request`, such as automatic compatibility across different providers. Use this when you need more manual control over the wallet interaction process.
354+
<Callout title="Raw Request">
355+
`requestRaw` bypasses the UI wallet selector, automatic provider compatibility fixes, and other features that come with `request`. Use this when you need more manual control over the wallet interaction process.
304356
</Callout>

‎content/docs/stacks/connect/support.mdx‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
title: 'Wallet Support'
3+
description: 'Compatibility information for different wallet providers'
4+
---
5+
6+
import {
7+
Table,
8+
TableBody,
9+
TableCell,
10+
TableHead,
11+
TableHeader,
12+
TableRow
13+
} from "@/components/ui/table";
14+
15+
This page provides detailed information about which methods and events are supported by different wallet providers in the Stacks ecosystem.
16+
17+
## Method Compatibility
18+
19+
<Table>
20+
<TableHeader>
21+
<TableRow>
22+
<TableHead>Method</TableHead>
23+
<TableHead>Leather</TableHead>
24+
<TableHead>Xverse-like</TableHead>
25+
</TableRow>
26+
</TableHeader>
27+
<TableBody>
28+
<TableRow>
29+
<TableCell><code>getAddresses</code></TableCell>
30+
<TableCell>🟡 No support for experimental purposes</TableCell>
31+
<TableCell>🟡 Use <code>wallet_connect</code> instead</TableCell>
32+
</TableRow>
33+
<TableRow>
34+
<TableCell><code>sendTransfer</code></TableCell>
35+
<TableCell>🟡 Expects <code>amount</code> as string</TableCell>
36+
<TableCell>🟡 Expects <code>amount</code> as number</TableCell>
37+
</TableRow>
38+
<TableRow>
39+
<TableCell><code>signPsbt</code></TableCell>
40+
<TableCell>🟡 Uses signing index array only</TableCell>
41+
<TableCell>🟡 Uses <code>signInputs</code> record instead of array</TableCell>
42+
</TableRow>
43+
<TableRow>
44+
<TableCell><code>stx_getAddresses</code></TableCell>
45+
<TableCell>🟢</TableCell>
46+
<TableCell>🔴</TableCell>
47+
</TableRow>
48+
<TableRow>
49+
<TableCell><code>stx_getAccounts</code></TableCell>
50+
<TableCell>🔴</TableCell>
51+
<TableCell>🟢</TableCell>
52+
</TableRow>
53+
<TableRow>
54+
<TableCell><code>stx_getNetworks</code></TableCell>
55+
<TableCell>🔴</TableCell>
56+
<TableCell>🔴</TableCell>
57+
</TableRow>
58+
<TableRow>
59+
<TableCell><code>stx_transferStx</code></TableCell>
60+
<TableCell>🟢</TableCell>
61+
<TableCell>🟢</TableCell>
62+
</TableRow>
63+
<TableRow>
64+
<TableCell><code>stx_transferSip10Ft</code></TableCell>
65+
<TableCell>🟢</TableCell>
66+
<TableCell>🔴</TableCell>
67+
</TableRow>
68+
<TableRow>
69+
<TableCell><code>stx_transferSip9Nft</code></TableCell>
70+
<TableCell>🟢</TableCell>
71+
<TableCell>🔴</TableCell>
72+
</TableRow>
73+
<TableRow>
74+
<TableCell><code>stx_callContract</code></TableCell>
75+
<TableCell>🟡 Hex-encoded Clarity values only</TableCell>
76+
<TableCell>🟡 Hex-encoded Clarity values only, no support for <code>postConditions</code></TableCell>
77+
</TableRow>
78+
<TableRow>
79+
<TableCell><code>stx_deployContract</code></TableCell>
80+
<TableCell>🟡 Hex-encoded Clarity values only</TableCell>
81+
<TableCell>🟡 Hex-encoded Clarity values only, no support for <code>postConditions</code></TableCell>
82+
</TableRow>
83+
<TableRow>
84+
<TableCell><code>stx_signTransaction</code></TableCell>
85+
<TableCell>🟡 Hex-encoded Clarity values only</TableCell>
86+
<TableCell>🟡 Hex-encoded Clarity values only</TableCell>
87+
</TableRow>
88+
<TableRow>
89+
<TableCell><code>stx_signMessage</code></TableCell>
90+
<TableCell>🟡 Hex-encoded Clarity values only</TableCell>
91+
<TableCell>🟡 Hex-encoded Clarity values only</TableCell>
92+
</TableRow>
93+
<TableRow>
94+
<TableCell><code>stx_signStructuredMessage</code></TableCell>
95+
<TableCell>🟡 Hex-encoded Clarity values only</TableCell>
96+
<TableCell>🟡 Hex-encoded Clarity values only</TableCell>
97+
</TableRow>
98+
<TableRow>
99+
<TableCell><code>stx_updateProfile</code></TableCell>
100+
<TableCell>🔴</TableCell>
101+
<TableCell>🔴</TableCell>
102+
</TableRow>
103+
</TableBody>
104+
</Table>
105+
106+
## Event Compatibility
107+
108+
<Table>
109+
<TableHeader>
110+
<TableRow>
111+
<TableHead>Event</TableHead>
112+
<TableHead>Leather</TableHead>
113+
<TableHead>Xverse</TableHead>
114+
</TableRow>
115+
</TableHeader>
116+
<TableBody>
117+
<TableRow>
118+
<TableCell><code>stx_accountChange</code></TableCell>
119+
<TableCell>🔴</TableCell>
120+
<TableCell>🔴</TableCell>
121+
</TableRow>
122+
<TableRow>
123+
<TableCell><code>stx_networkChange</code></TableCell>
124+
<TableCell>🔴</TableCell>
125+
<TableCell>🔴</TableCell>
126+
</TableRow>
127+
</TableBody>
128+
</Table>
129+
130+
**Legend**
131+
132+
- 🔴 No support (yet)
133+
- 🟡 Partial support
134+
- 🟢 Supported
135+
136+
## Compatibility Layer
137+
138+
The `request` method in `@stacks/connect` adds a layer of auto-compatibility for different wallet providers. This helps unify the interface where wallet providers may implement methods and results differently.
139+
140+
| Method | Status | Notes |
141+
| --------------------------- | ------ | ---------------------------------------------------------------------------------------------------- |
142+
| `getAddresses` | 🔵 | Maps to `wallet_connect` for Xverse-like wallets |
143+
| `sendTransfer` | 🔵 | Converts `amount` to number for Xverse, string for Leather |
144+
| `signPsbt` | 🟡 | Transforms PSBT format for Leather (base64 to hex) with lossy restructure of `signInputs` |
145+
| `stx_getAddresses` | 🔵 | Maps to `wallet_connect` for Xverse-like wallets |
146+
| `stx_callContract` | 🔵 | Transforms Clarity values to hex-encoded format for compatibility |
147+
| `stx_deployContract` | 🔵 | Transforms Clarity values to hex-encoded format for compatibility |
148+
| `stx_signTransaction` | 🔵 | Transforms Clarity values to hex-encoded format for compatibility |
149+
| `stx_signMessage` | 🔵 | Transforms Clarity values to hex-encoded format for compatibility |
150+
| `stx_signStructuredMessage` | 🔵 | Transforms Clarity values to hex-encoded format for compatibility |
151+
152+
- 🟢 No overrides needed for any wallet
153+
- 🔵 Has compatibility overrides that maintain functionality
154+
- 🟡 Has breaking overrides that may lose some information

0 commit comments

Comments
 (0)