Connect is a JavaScript library for building web applications connected to Stacks.

@stacks/connect • @stacks/connect-react • @stacks/connect-ui

🛬 Migration Guide

Welcome to the new Stacks Connect! ✨ Read the @stacks/connect docs for more information.

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.

⚠️ 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

Note

To make migrating easier, the familiar UserSession & AppConfig class still exists and is semi-backwards compatible for the 8.x.x release. It will "cache" the user's address in local storage and allow access to it via the loadUserData method (as previously done).

🪪 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. This means the developer needs to manually manage the currently connected user's address in e.g. local storage, jotai, etc.

import { request } from '@stacks/connect';

// `getAddresses` is often a permission-granting method, so we consider this the "connect" step.

const addresses = await request('getAddresses');
const addresses = await request({ forceWalletSelect: true }, 'getAddresses');

See more methods in the @stacks/connect documentation.

---

⚡️ Installation

Use your favorite package manager to install @stacks/connect in your project. Follow the Getting Started section of the @stacks/connect README.

Or use one of our starter-templates to bootstrap a fresh project already including connect using the command-line locally via npm create stacks

📦 Packages

This repository includes three packages:

• @stacks/connect: The one-stop-shop tool for letting web-apps interact with Stacks web wallets.
• @stacks/connect-react: A wrapper library for making @stacks/connect use in React even easier
• @stacks/connect-ui: A web-component UI for displaying an intro modal in Stacks web-apps during authentication (used in the background by @stacks/connect).

🛠️ Wallet Implementation Guide

Wallets implement a "Provider" interface. The latest spec uses a simple JS Object exposing a .request(method: string, params?: object) method.

Pseudo-code:

window.MyProvider = {
  async request(method, params) {
    // Somehow communicate with the wallet (e.g. via events)

    // Recommendation: Create a JSON RPC 2.0 request object
    // https://www.jsonrpc.org/specification

    return Promise.resolve({
      // Respond with a JSON RPC 2.0 response object
      id: crypto.randomUUID(), // required, same as request
      jsonrpc: '2.0', // required

      // `.result` is required on success
      result: {
        // object matching specified RPC methods
      },

      // `.error` is required on error
      error: {
        // Use existing codes from https://www.jsonrpc.org/specification#error_object
        code: number, // required, integer
        message: string, // recommended, single sentence
        data: object, // optional
      },
    });
  },
  isMyWallet: true, // optional, a way of identifying the wallet for developers
};

window.wbip_providers = window.wbip_providers || [];
window.wbip_providers.push({
  // `WbipProvider` type
    /** The global "path" of the provider (e.g. `"MyProvider"` if registered at `window.MyProvider`) */
  id: 'MyProvider',
  /** The name of the provider, as displayed to the user */
  name: 'My Wallet';
  /** The data URL of an image to show (e.g. `data:image/png;base64,iVBORw0...`) @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs */
  icon?: 'data:image/png;base64,iVBORw0...';
  /** Web URL of the provider */
  webUrl?: 'https://mywallet.example.com';

  // Addional URLs
  chromeWebStoreUrl?: string;
  mozillaAddOnsUrl?: string;
  googlePlayStoreUrl?: string;
  iOSAppStoreUrl?: string;
});

JSON RPC 2.0

Wallets may add their own unstandardized methods. However, the minimum recommended methods are:

• getAddresses WBIP
• sendTransfer WBIP
• signPsbt WBIP
• stx_getAddresses SIP-030
• stx_transferStx SIP-030
• stx_callContract SIP-030
• stx_signMessage SIP-030
• stx_signStructuredMessage SIP-030

---

    

🎁 Contribute

Development of this product happens in the open on GitHub, and we are grateful to the community for contributing bugfixes and improvements. Read below to learn how you can take part in improving the product.

Code of Conduct

Please read our Code of conduct since we expect project participants to adhere to it.

Contributing Guide

Read our contributing guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes.