Skip to main content

Stacks Connect

Stacks Connect Reference

Stacks Connect is a frontend library that allows developers to build Stacks-ready web applications.

Quick start!

npm create stacks

What are the main use-cases of Stacks Connect?

  • Prompt a user to sign transactions with their Stacks wallet
  • Provide the web-app with the user's Stacks and Bitcoin addresses

Add Stacks Connect to your project​

1. Add the dependency​

Add the @stacks/connect dependency to your project using your favorite package manager.

npm install @stacks/connect

2. Creating AppConfig and UserSession​

Add a reusable UserSession instance to your project. This will allow your website to store authentication state in localStorage.

/* ./userSession.js */
import { AppConfig, UserSession } from '@stacks/connect';

const appConfig = new AppConfig(['store_write', 'publish_data']);
export const userSession = new UserSession({ appConfig }); // we will use this export from other files

3. Interacting with the wallet​

"Connect" aka authentication (showConnect)​

Connecting the wallet is a very simple form of authentication. This process gives the web-app information about a wallet account (selected by the user).

Connect Modal

The snippet below lets your web-app trigger the wallet to open and authenticate an account. If no wallet is installed, an informational modal will be displayed in the web-app.

import { showConnect } from '@stacks/connect';
import { userSession } from './userSession';

const myAppName = 'My Stacks Web-App'; // shown in wallet pop-up
const myAppIcon = window.location.origin + '/my_logo.png'; // shown in wallet pop-up

showConnect({
  userSession, // `userSession` from previous step, to access storage
  appDetails: {
    name: myAppName,
    icon: myAppIcon,
  },
  onFinish: () => {
    window.location.reload(); // WHEN user confirms pop-up
  },
  onCancel: () => {
    console.log('oops'); // WHEN user cancels/closes pop-up
  },
});

Sending STX (openSTXTransfer)​

Sending STX tokens is also possible through web-apps interacting with a user's wallet.

The snippet below will open the wallet to confirm and broadcast a smart-contract transaction. Here, we are sending 10000 micro-STX tokens to a recipient address.

import { openSTXTransfer } from '@stacks/connect';
import { StacksTestnet } from '@stacks/network';
import { AnchorMode, PostConditionMode } from '@stacks/transactions';
import { userSession } from './userSession';

openSTXTransfer({
  network: new StacksTestnet(), // which network to use; use `new StacksMainnet()` for mainnet
  anchorMode: AnchorMode.Any, // which type of block the tx should be mined in

  recipient: 'ST39MJ145BR6S8C315AG2BD61SJ16E208P1FDK3AK', // which address we are sending to
  amount: 10000, // tokens, denominated in micro-STX
  memo: 'Nr. 1337', // optional; a memo to help identify the tx

  onFinish: response => {
    // WHEN user confirms pop-up
    console.log(response.txid); // the response includes the txid of the transaction
  },
  onCancel: () => {
    // WHEN user cancels/closes pop-up
    console.log('User canceled');
  },
});

Calling Smart-Contracts (openContractCall)​

Calling smart-contracts lets users interact with the blockchain through transactions.

The snippet below will open the wallet to confirm and broadcast a smart-contract transaction. Here, we are passing our pick Alice to an imaginary deployed voting smart-contract.

import { openContractCall } from '@stacks/connect';
import { StacksTestnet } from '@stacks/network';
import { AnchorMode, PostConditionMode, stringUtf8CV } from '@stacks/transactions';
import { userSession } from './userSession';

const pick = stringUtf8CV('Alice');

openContractCall({
  network: new StacksTestnet(),
  anchorMode: AnchorMode.Any, // which type of block the tx should be mined in

  contractAddress: 'ST39MJ145BR6S8C315AG2BD61SJ16E208P1FDK3AK',
  contractName: 'example-contract',
  functionName: 'vote',
  functionArgs: [pick],

  postConditionMode: PostConditionMode.Deny, // whether the tx should fail when unexpected assets are transferred
  postConditions: [], // for an example using post-conditions, see next example

  onFinish: response => {
    // WHEN user confirms pop-up
  },
  onCancel: () => {
    // WHEN user cancels/closes pop-up
  },
});

Sending transactions with post-conditions (openContractCall)​

Consider the example above. Using post-conditions, a feature of the Stacks blockchain, we can ensure something happened after a transaction. Here, we could ensure that the recipient indeed receives a certain amount of STX.

import {
  PostConditionMode,
  FungibleConditionCode,
  makeStandardSTXPostCondition,
} from '@stacks/transactions';

// this post-condition ensures that our recipient receives at least 5000 STX tokens
const myPostCondition = makeStandardSTXPostCondition(
  'ST39MJ145BR6S8C315AG2BD61SJ16E208P1FDK3AK', // address of recipient
  FungibleConditionCode.GreaterEqual, // comparator
  5000000000 // relative amount to previous balance (denoted in micro-STX)
);

// passing to `openContractCall` options, e.g. modifying our previous example ...
  postConditionMode: PostConditionMode.Deny, // whether the tx should fail when unexpected assets are transferred
  postConditions: [ myPostCondition ],
// ...
note

For more examples on constructing different kinds of post-conditions read the Post-Conditions Guide of Stacks.js.

Post-Condition Modes​

If post-conditions postConditions: [ ... ] are specified, they will ALWAYS be checked by blockchain nodes. If ANY conditions fails, the transaction will fail.

The Post-Condition Mode only relates to transfers of assets, which were not specified in the postConditions.

  • PostConditionMode.Deny will fail the transaction if any unspecified assets are transferred
  • PostConditionMode.Allow will allow unspecified assets to be transferred
  • In both cases, all postConditions will be checked

Manual​

The following methods show the Connect modal (to select a wallet) and do a certain action: