Package @stacks/connect

@stacks/connect npm

🐎 Getting Started

1. Add the dependency

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

npm install @stacks/connect
pnpm install @stacks/connect
yarn add @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).

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 ],
// ...

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

🛠 Advanced

Opening a specific wallet

By default, @stacks/connect will defer to the window.StacksProvider object to interact with wallets. However, if multiple wallets are installed, they might interfere with each other. To avoid this, you can specify which wallet to use in the wallet interaction methods.

// This will open only the Hiro Wallet
authenticate({ ...opts }, HiroWalletProvider);
openPsbtRequestPopup({ ...opts }, HiroWalletProvider);
openProfileUpdateRequestPopup({ ...opts }, HiroWalletProvider);
openSignatureRequestPopup({ ...opts }, HiroWalletProvider);
openStructuredDataSignatureRequestPopup({ ...opts }, HiroWalletProvider);

🤔 Pitfalls

  • Connect can currently not set manual nonces, since this is not supported by wallets.
  • For some projects it might be necessary to also install the regenerator-runtime package. npm install --save-dev regenerator-runtime. This is a build issue of older versions of @stacks/connect.

📚 Method Parameters

A glossary of the most common options of openSTXTransfer and openContractCall

openSTXTransfer Required

Description Type Example
recipient The recipient (STX principal) address string 'ST39MJ145BR6S8C315AG2BD61SJ16E208P1FDK3AK'
amount The amount (in micro-STX) to transfer Integer (e.g. number, bigint) 10000

openContractCall Required

Description Type Example
contractAddress The (STX contract) address of the smart contract string 'ST39MJ145BR6S8C315AG2BD61SJ16E208P1FDK3AK'
contractName The contract name string 'example-contract'
functionName The contract function name string 'vote'
functionArgs The contract function arguments Array of Clarity Values [], [uintCV(100)]

Optional

Default Description Type Example
network Mainnet The network to broadcast the transaction to StacksNetwork new StacksMainnet()
anchorMode Any The type of block the transaction should be mined in AnchorMode Enum AnchorMode.OnChainOnly
memo Empty '' The memo field (used for additional data) string 'a memo'
fee Handled by Wallet The transaction fee (the wallet will estimate fees as well) Integer (e.g. number, bigint) 1000
postConditionMode Deny The post condition mode, i.e. whether to allow unspecified asset transfer PostConditionMode PostConditionMode.Allow
postConditions Empty [] The list of post conditions to check, regardless of postConditionMode PostCondition[]
onFinish No-op The callback function to run after broadcasting the transaction Function (receiving response)
onCancel No-op The callback function to run after the user cancels/closes the wallet Function

Index

Enumerations

Classes

Interfaces

Type Aliases

Variables

Functions

Generated using TypeDoc