Migration Guide

For a while now, the Stacks community has been working on a new standard for wallet-to-dapp communication. Stacks Connect and related projects now use standards like WBIPs and SIP-030 to allow wallets to communicate with dapps in a more simplified and flexible way.

Migration status Feel free to continue using Stacks Connect 7.x.x while things stabilize. The 7.x.x version may still be better supported by some wallets.

Legacy installs:

npm install @stacks/[email protected]

Deprecations

The following classes, methods, and types are deprecated in favor of the new request RPC methods:

• show... and open... methods

• authenticate method

• UserSession class and related functionality

• AppConfig class

• SessionOptions interface

• SessionData interface

• UserData interface

• SessionDataStore class

• InstanceDataStore class

• LocalStorageStore class

Backwards compatibility UserSession and AppConfig remain available in 8.x.x for caching addresses via loadUserData, but consider them temporary helpers while you migrate.

Migration steps

1

Update your @stacks/connect version

npm install @stacks/connect@latest

2

Replace legacy methods with request

Switch from showXyz, openXyz, and doXyz helpers to the generic request(method, params) API. The request function is async, so replace onFinish/onCancel callbacks with await or .then().catch() chains.

Examples:

• showConnect(), authenticate() → connect()

• useConnect().doContractCall({}) → request('stx_callContract', {})

• openContractDeploy() → request('stx_deployContract', {})

3

Use connect instead of showConnect / authenticate

connect() is an alias for request('getAddresses', { forceWalletSelect: true }) and caches the selected address in local storage by default.

4

Update authentication state management

• Replace UserSession.isSignedIn() with isConnected()

• Replace UserSession.signUserOut() with disconnect()

5

Remove legacy code

• Delete references to deprecated helpers (AppConfig, UserSession, etc.)

• Remove the @stacks/connect-react package

  • Manually reload components if you rely on local storage updates

  • Hooks are no longer required for Stacks Connect

• A new @stacks/react package is in development to simplify state tracking (transaction status, network changes, and more)

Address Access

Previously, the UserSession class was used to access the user's addresses and data, which abstracted away the underlying implementation details. 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. This manual approach makes the wallet interaction more transparent and customizable. 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.

Security note 8.x.x wallets return only the current network's address (previous versions returned both mainnet and testnet).