mirror of https://github.com/lukechilds/docs.git
Patrick Gray
4 years ago
committed by
Patrick Gray
Patrick Gray
9 changed files with 645 additions and 6 deletions
|
After Width: | Height: | Size: 59 KiB |
@ -0,0 +1,619 @@ |
|||
--- |
|||
title: Heystack app |
|||
description: Interacting with the wallet and smart contracts from a React application |
|||
tags: |
|||
- example-app |
|||
images: |
|||
large: /images/pages/heystack-app.svg |
|||
--- |
|||
|
|||
## Introduction |
|||
|
|||
This example application demonstrates important features of the Stacks blockchain, and is a case study for how a frontend |
|||
web application can interact with a Clarity smart contract. The full source of the application is provided, this page |
|||
highlights important code snippets and design patterns to help you learn how to develop your own Stacks application. |
|||
|
|||
This app highlights the following platform features: |
|||
|
|||
- Authenticating users with the web wallet |
|||
- Using a smart contract to store data on the blockchain |
|||
- Minting new fungible tokens with a [SIP-010][] compliant smart contract |
|||
- Creating and monitoring transactions on the Stacks blockchain using [Stacks.js][] |
|||
|
|||
You can access the [online version][heystack] of the Heystack app to interact with it. The source for Heystack is also |
|||
available on [Github][heystack_gh]. This page assumes some familiarity with [React][]. |
|||
|
|||
## Heystack overview |
|||
|
|||
Heystack is a web application for chatting with other Stacks users. The application uses the [Stacks web wallet][] to |
|||
authenticate users in the frontend. When a user logs in to Heystack, they're given a genesis amount of $HEY fungible |
|||
tokens, which allows them to send and like messages on the platform. |
|||
|
|||
Heystack is powered by Clarity smart contracts so each message is a transaction on the Stacks blockchain. Each time a |
|||
user sends a message on the platform, they must sign the message with the [Stacks web wallet][] (or another compatible |
|||
wallet) and pay a small gas fee in STX. A user spends a $HEY token to send every message, and recieves a $HEY token for |
|||
every like that their messages receive. |
|||
|
|||
## Review smart contracts |
|||
|
|||
Heystack depends on two smart contracts to execute the backend functions of the app on the Stacks blockchain: a contract |
|||
for handling the messaging content, and a contract for minting and distributing the $HEY token. |
|||
|
|||
### Content contract |
|||
|
|||
The `hey.clar` contract provides two primary functions for the application, one to publish content to |
|||
the blockchain and another to like a piece of content based on its ID. This section reviews the implementation of |
|||
these primary functions, but is not a comprehensive discussion of the contract. |
|||
|
|||
In order to accomplish the two primary functions, the contract relies on a data variable `content-index` and two |
|||
[data maps][], `like-state` and `publisher-state` which contain the number of likes a piece of content has received, and |
|||
the principal address of the account that published the content. |
|||
|
|||
Note that all variables are defined at the top of the contract, which is a requirement of the Clarity language. These |
|||
include constants such as the `contract-creator`, error codes, and a treasury address. |
|||
|
|||
```clarity |
|||
;; |
|||
;; Data maps and vars |
|||
(define-data-var content-index uint u0) |
|||
|
|||
(define-read-only (get-content-index) |
|||
(ok (var-get content-index)) |
|||
) |
|||
|
|||
(define-map like-state |
|||
{ content-index: uint } |
|||
{ likes: uint } |
|||
) |
|||
|
|||
(define-map publisher-state |
|||
{ content-index: uint } |
|||
{ publisher: principal } |
|||
) |
|||
``` |
|||
|
|||
Read-only functions provide a method for getting the like count of a piece of content, and getting the principal address |
|||
of the message publisher. |
|||
|
|||
```clarity |
|||
(define-read-only (get-like-count (id uint)) |
|||
;; Checks map for like count of given id |
|||
;; defaults to 0 likes if no entry found |
|||
(ok (default-to { likes: u0 } (map-get? like-state { content-index: id }))) |
|||
) |
|||
|
|||
(define-read-only (get-message-publisher (id uint)) |
|||
;; Checks map for like count of given id |
|||
;; defaults to 0 likes if no entry found |
|||
(ok (unwrap-panic (get publisher (map-get? publisher-state { content-index: id })))) |
|||
``` |
|||
|
|||
The `get-like-count` method accepts a content ID and returns the number of likes associated with that content. The |
|||
method uses the [`default-to`][] function to return `0` if the content ID isn't found in the map of likes. |
|||
|
|||
The `get-message-publisher` method accepts a content ID and returns the principal address of the content publisher. The |
|||
method uses the [`unwrap-panic`][] function to halt execution of the method if the principal address isn't found in |
|||
the map of publishers. |
|||
|
|||
The two primary public methods are the `send-message` and `like-message` functions. These methods allow the contract |
|||
caller to store a message on the blockchain (creating entries in the data maps for the message sender and the number |
|||
of likes). Note that the message itself isn't stored in a contract variable, the frontend application reads the content |
|||
of the message directly from the transaction on the blockchain. |
|||
|
|||
```clarity |
|||
;; |
|||
;; Public functions |
|||
(define-public (send-message (content (string-utf8 140))) |
|||
(let ((id (unwrap! (increment-content-index) (err u0)))) |
|||
(print { content: content, publisher: tx-sender, index: id }) |
|||
(map-set like-state |
|||
{ content-index: id } |
|||
{ likes: u0 } |
|||
) |
|||
(map-set publisher-state |
|||
{ content-index: id } |
|||
{ publisher: tx-sender } |
|||
) |
|||
(transfer-hey u1 HEY_TREASURY) |
|||
) |
|||
) |
|||
``` |
|||
|
|||
The `send-message` method accepts a utf-8 string with a maximum length of 140 characters. The method defines an internal |
|||
variable `id` using the `let` function and assigns the next content ID to that variable by calling the |
|||
`increment-contract-index` method of the contract. The value assignment of this variable is bound by the [`unwrap!`][] |
|||
function, which returns an error and exits the control-flow if the `increment-contract-index` function isn't |
|||
successfully called. |
|||
|
|||
The method then assigns `u0` likes to the content in the `like-state` data map, and adds the principal address to the |
|||
`publisher-state` data map using the [`map-set`][] function. Finally, the private method `transfer-hey` is called to |
|||
transfer 1 $HEY token from the message sender to the $HEY treasury address stored in the `HEY_TREASURY` constant. |
|||
|
|||
```clarity |
|||
(define-public (like-message (id uint)) |
|||
(begin |
|||
;; cannot like content that doesn't exist |
|||
(asserts! (>= (var-get content-index) id) (err ERR_CANNOT_LIKE_NON_EXISTENT_CONTENT)) |
|||
;; transfer 1 HEY to the principal that created the content |
|||
(map-set like-state |
|||
{ content-index: id } |
|||
{ likes: (+ u1 (get likes (unwrap! (get-like-count id) (err u0)))) } |
|||
) |
|||
(transfer-hey u1 (unwrap-panic (get-message-publisher id))) |
|||
) |
|||
) |
|||
``` |
|||
|
|||
The `like-message` method accepts a content ID. The method checks that the ID is lower than the current content ID using |
|||
the [`asserts!`][] function, to verify that the provided ID is a valid ID. If the [`asserts!`][] assessment is `false`, |
|||
the method returns an error code. If the ID is valid, the method performs a [`map-set`][] to look up the content in the |
|||
`like-state` data map and add a like to the value stored in the map. Once again, the [`unwrap!`][] function is used to |
|||
ensure that an invalid value isn't stored in the map. |
|||
|
|||
The `hey.clar` contract provides some additional functions for working with the $HEY token contract, discussed in the |
|||
next section. |
|||
|
|||
### Token contract |
|||
|
|||
Heystack creates a native fungible token for use in the application. When a user authenticates with Heystack, they're |
|||
automatically eligible to claim 100 $HEY tokens to allow them to start messaging. |
|||
|
|||
[SIP-010][] defines the fungible token standard on Stacks, which allows Stacks compatible wallets to handle fungible |
|||
tokens through a set of standardized methods. SIP-010 defines 7 traits that a fungible token contract must have in order |
|||
to be compliant: |
|||
|
|||
- `transfer`: method for transferring the token from one principal to another |
|||
- `get-name`: returns the human-readable name of the token |
|||
- `get-symbol`: returns the ticker symbol of the token |
|||
- `get-decimals`: returns number of decimal places in the token |
|||
- `get-balance`: return the balance of a given principal |
|||
- `get-total-supply`: returns the total supply of the token |
|||
- `get-token-uri`: returns an optional string that resolves to a valid URI for the token's metadata. |
|||
|
|||
In Clarity, a contract can declare that it intends to implement a set of standard traits. |
|||
|
|||
```clarity |
|||
|
|||
;; Implement the `ft-trait` trait defined in the `ft-trait` contract |
|||
;; https://github.com/hstove/stacks-fungible-token |
|||
(impl-trait 'ST3J2GVMMM2R07ZFBJDWTYEYAR8FZH5WKDTFJ9AHA.ft-trait.sip-010-trait) |
|||
``` |
|||
|
|||
The [`impl-trait`][] function asserts that the smart contract is fully implementing a given set of traits defined by the |
|||
argument. Like variable definitions, `impl-trait` must be declared at the top of a smart contract definition. |
|||
|
|||
-> The contract address for SIP-010 trait definition is different depending on which network (mainnet, testnet, etc.) |
|||
your contract is deployed on. See the standard for the current addresses of the standard traits. |
|||
|
|||
The `hey-token.clar` contract implements the required 7 traits of [SIP-010][], and one additional method, the |
|||
`gift-tokens` method, that allows a principal to request tokens from the contract. |
|||
|
|||
```clarity |
|||
(define-public (gift-tokens (recipient principal)) |
|||
(begin |
|||
(asserts! (is-eq tx-sender recipient) (err u0)) |
|||
(ft-mint? hey-token u1 recipient) |
|||
) |
|||
) |
|||
``` |
|||
|
|||
## Authentication |
|||
|
|||
Authentication is handled through the [`@stacks/connect-react`][] and [`@stacks/auth`][] packages, which interact with |
|||
compatible Stacks wallet extensions and provide methods for interacting with a user session respectively. [Jotai][] |
|||
provides application state management. |
|||
|
|||
The [connect wallet button component][] implements the interface with the Stacks web wallet through the |
|||
[`@stacks/connect-react`][] package. |
|||
|
|||
```tsx |
|||
import { Button } from '@components/button'; |
|||
import React from 'react'; |
|||
import { useConnect } from '@stacks/connect-react'; |
|||
import { ButtonProps } from '@stacks/ui'; |
|||
import { useLoading } from '@hooks/use-loading'; |
|||
import { LOADING_KEYS } from '@store/ui'; |
|||
|
|||
export const ConnectWalletButton: React.FC<ButtonProps> = props => { |
|||
const { doOpenAuth } = useConnect(); |
|||
const { isLoading, setIsLoading } = useLoading(LOADING_KEYS.AUTH); |
|||
return ( |
|||
<Button |
|||
isLoading={isLoading} |
|||
onClick={() => { |
|||
void setIsLoading(true); |
|||
doOpenAuth(); |
|||
}} |
|||
{...props} |
|||
> |
|||
Connect wallet |
|||
</Button> |
|||
); |
|||
}; |
|||
``` |
|||
|
|||
Once connected, [`/src/store/auth.ts`][] populates the user session data into the Jotai store, allowing the application |
|||
to access the user information. |
|||
|
|||
You can see in the [welcome panel component][] how the presence or absence of stored user data is used to display the |
|||
wallet connect button or the signed in view. |
|||
|
|||
```tsx |
|||
... |
|||
const UserSection = memo((props: StackProps) => { |
|||
const { user } = useUser(); |
|||
|
|||
return ( |
|||
<Stack |
|||
alignItems="center" |
|||
justifyContent="center" |
|||
flexGrow={1} |
|||
spacing="loose" |
|||
textAlign="center" |
|||
{...props} |
|||
> |
|||
{!user ? <SignedOutView /> : <SignedInView onClick={() => console.log('click')} />} |
|||
</Stack> |
|||
); |
|||
}); |
|||
... |
|||
``` |
|||
|
|||
### Token faucet |
|||
|
|||
The `use-claim-hey.ts` file provides a React hook for interacting with the token faucet of the Clarity smart contract. |
|||
|
|||
```ts |
|||
import { useLoading } from '@hooks/use-loading'; |
|||
import { LOADING_KEYS } from '@store/ui'; |
|||
import { useConnect } from '@stacks/connect-react'; |
|||
import { useNetwork } from '@hooks/use-network'; |
|||
import { useCallback } from 'react'; |
|||
import { useHeyContract } from '@hooks/use-hey-contract'; |
|||
import { REQUEST_FUNCTION } from '@common/constants'; |
|||
import { principalCV } from '@stacks/transactions/dist/clarity/types/principalCV'; |
|||
import { useCurrentAddress } from '@hooks/use-current-address'; |
|||
|
|||
export function useHandleClaimHey() { |
|||
const address = useCurrentAddress(); |
|||
const { setIsLoading } = useLoading(LOADING_KEYS.CLAIM_HEY); |
|||
const { doContractCall } = useConnect(); |
|||
const [contractAddress, contractName] = useHeyContract(); |
|||
const network = useNetwork(); |
|||
|
|||
const onFinish = useCallback(() => { |
|||
void setIsLoading(false); |
|||
}, [setIsLoading]); |
|||
|
|||
const onCancel = useCallback(() => { |
|||
void setIsLoading(false); |
|||
}, [setIsLoading]); |
|||
|
|||
return useCallback(() => { |
|||
void setIsLoading(true); |
|||
void doContractCall({ |
|||
contractAddress, |
|||
contractName, |
|||
functionName: REQUEST_FUNCTION, |
|||
functionArgs: [principalCV(address)], |
|||
onFinish, |
|||
onCancel, |
|||
network, |
|||
stxAddress: address, |
|||
}); |
|||
}, [setIsLoading, onFinish, network, onCancel, address, doContractCall]); |
|||
} |
|||
``` |
|||
|
|||
The [`@stacks/connect-react`][] package exports the `doContractCall` method, which interacts with the smart contract on |
|||
the blockchain. There are more examples of transaction calls in the next section. It's important to note that it's |
|||
necessary to convert Javascript types to Clarity types using the types exported by the [`@stacks/transactions`][] package. |
|||
Further discussion of this conversion is in the [Clarity types in Javascript][] section. |
|||
|
|||
## Transactions |
|||
|
|||
Since messages in Heystack are transactions against a Clarity smart contract, the application must be able to create |
|||
transactions and read their content from the blockchain. The following sections highlight code snippets that perform |
|||
Clarity transactions and read both completed and pending transactions from the Stacks blockchain. |
|||
|
|||
### Issuing transactions |
|||
|
|||
The two primary functions of the `hey.clar` smart contract are publishing a message and accepting a like on an already |
|||
published message. The [`src/hooks/use-publish-hey.ts`][] file implements the frontend method for calling the smart |
|||
contract on the blockchain with the appropriate values. |
|||
|
|||
```ts |
|||
... |
|||
return useCallback( |
|||
(content: string, _onFinish: () => void) => { |
|||
void setShowPendingOverlay(true); |
|||
void setIsLoading(true); |
|||
|
|||
void doContractCall({ |
|||
contractAddress, |
|||
contractName, |
|||
functionName: MESSAGE_FUNCTION, |
|||
functionArgs: [ |
|||
stringUtf8CV(content), |
|||
attachmentUri !== '' ? someCV(stringUtf8CV(attachmentUri)) : noneCV(), |
|||
], |
|||
onFinish: () => { |
|||
_onFinish(); |
|||
onFinish(); |
|||
}, |
|||
postConditions: [ |
|||
createFungiblePostCondition( |
|||
address, |
|||
FungibleConditionCode.Equal, |
|||
new BN(1), |
|||
createAssetInfo(contractAddress, 'hey-token', 'hey-token') |
|||
), |
|||
], |
|||
onCancel, |
|||
network, |
|||
stxAddress: address, |
|||
}); |
|||
}, |
|||
[setIsLoading, onFinish, network, onCancel, address, doContractCall] |
|||
); |
|||
... |
|||
``` |
|||
|
|||
The frontend uses the `doContractCall` function from the [`@stacks/connect-react`][] package to perform the call to the |
|||
Clarity smart contract. In order to support the mapping of [Javascript types to Clarity types][], helpers exported from |
|||
the [`@stacks/transactions`][] package are used as arguments to the contract call. |
|||
|
|||
Note that the contract call also create post conditions to verify that a single $HEY token is transferred by the |
|||
execution of the contract call. Post conditions are a powerful feature of Clarity that can be used to prevent |
|||
rug-pulling and other detrimental behavior by smart contracts. |
|||
|
|||
### Reading transactions |
|||
|
|||
Heystack achieves pseudo-real-time messaging by reading both confirmed and pending transactions from the blockchain. |
|||
Pending transactions are read from the mempool, whereas confirmed transactions are read directly from the chain. The |
|||
[`src/store/hey.ts`][] file contains the implementation of both. |
|||
|
|||
```ts |
|||
... |
|||
export const heyTransactionsAtom = atomWithQuery<ContractCallTransaction[], string>(get => ({ |
|||
queryKey: ['hey-txs'], |
|||
...(defaultOptions as any), |
|||
refetchInterval: 500, |
|||
queryFn: async (): Promise<ContractCallTransaction[]> => { |
|||
const client = get(accountsClientAtom); |
|||
const txClient = get(transactionsClientAtom); |
|||
|
|||
const txs = await client.getAccountTransactions({ |
|||
limit: 50, |
|||
principal: HEY_CONTRACT, |
|||
}); |
|||
const txids = (txs as TransactionResults).results |
|||
.filter( |
|||
tx => |
|||
tx.tx_type === 'contract_call' && |
|||
tx.contract_call.function_name === MESSAGE_FUNCTION && |
|||
tx.tx_status === 'success' |
|||
) |
|||
.map(tx => tx.tx_id); |
|||
|
|||
const final = await Promise.all(txids.map(async txId => txClient.getTransactionById({ txId }))); |
|||
return final as ContractCallTransaction[]; |
|||
}, |
|||
})); |
|||
... |
|||
``` |
|||
|
|||
The `getAccountTransactions` from the `AccountsApi` object exported by [`@stacks/blockchain-api-client`][] is used to |
|||
read confirmed blockchain transactions against the `hey.clar` contract from the Stacks API. The list of transactions |
|||
returned by the API is filtered to only transactions representing a call to the message function that was successful, |
|||
and then mapped to an array of transaction IDs. |
|||
|
|||
Finally, the array of IDs is used to read each full transaction from the blockchain using the `getTransactionsById` |
|||
method from the `TransactionsApi` object exported by the [`@stacks/blockchain-api-client`][] package. |
|||
|
|||
Pending transactions are read from the mempool in a similar implementation. |
|||
|
|||
```ts |
|||
export const pendingTxsAtom = atomWithQuery<Heystack[], string>(get => ({ |
|||
queryKey: ['hey-pending-txs'], |
|||
refetchInterval: 1000, |
|||
...(defaultOptions as any), |
|||
queryFn: async (): Promise<Heystack[]> => { |
|||
const client = get(transactionsClientAtom); |
|||
|
|||
const txs = await client.getMempoolTransactionList({ limit: 96 }); |
|||
const heyTxs = (txs as MempoolTransactionListResponse).results |
|||
.filter( |
|||
tx => |
|||
tx.tx_type === 'contract_call' && |
|||
tx.contract_call.contract_id === HEY_CONTRACT && |
|||
tx.contract_call.function_name === MESSAGE_FUNCTION && |
|||
tx.tx_status === 'pending' |
|||
) |
|||
.map(tx => tx.tx_id); |
|||
|
|||
const final = await Promise.all(heyTxs.map(async txId => client.getTransactionById({ txId }))); |
|||
|
|||
return ( |
|||
(final as ContractCallTransaction[]).map(tx => { |
|||
const attachment = tx.contract_call.function_args?.[1].repr |
|||
.replace(`(some u"`, '') |
|||
.slice(0, -1); |
|||
|
|||
return { |
|||
sender: tx.sender_address, |
|||
content: tx.contract_call.function_args?.[0].repr |
|||
.replace(`u"`, '') |
|||
.slice(0, -1) as string, |
|||
id: tx.tx_id, |
|||
attachment: attachment === 'non' ? undefined : attachment, |
|||
timestamp: (tx as any).receipt_time, |
|||
isPending: true, |
|||
}; |
|||
}) || [] |
|||
); |
|||
}, |
|||
})); |
|||
``` |
|||
|
|||
Pending transactions are read from the mempool using the `getMempoolTransactionList` method from the `TransactionsApi` |
|||
exported by [`@stacks/blockchain-api-client`][]. Similar to confirmed transactions, the returned array is filtered to |
|||
a list of IDs, and then used to generate an array of full transactions. |
|||
|
|||
Because of differences in the data structure of the pending transactions vs. confirmed transactions, the pending |
|||
transaction list must be standardized before being returned. |
|||
|
|||
Note that for the low stakes of a messaging app, pending transactions can be treated as likely permanent state |
|||
transitions. For applications implementing higher stakes business logic (such as the transfer of representations |
|||
of value) it would be more appropriate to wait to display confirmed transactions. |
|||
|
|||
### Clarity types in Javascript |
|||
|
|||
In order to create transactions to call functions in Clarity contracts, the [`@stacks/transactions`][] package exports |
|||
classes that make it easy to construct well-typed Clarity values in Javascript. According to the Clarity language |
|||
specification, Clarity has the following types: |
|||
|
|||
- `(tuple (key-name-0 key-type 0) (key-name-1 key-type-1) ...)` - a typed tuple with named fields |
|||
- `(list max-len entry-type)` - a list of maximum length `max-len`, with entries of type `entry-type` |
|||
- `(response ok-type err-type)` - object used by public functions to commit their state changes or abort |
|||
- `(optional some-type)` - an option type for objects that can be either `(some-value)` or `none` |
|||
- `(buff max-len)` - byte buffer of maximum length |
|||
- `principal` - object representing a principal address (contract or standard) |
|||
- `bool` - boolean value (`true` or `false`) |
|||
- `int` - signed 128-bit integer |
|||
- `uint` - unsigned 128-bit integer |
|||
|
|||
To support these types in Javascript, [`@stacks/transactions`][] exports the following helpers: |
|||
|
|||
```ts |
|||
// construct boolean clarity values |
|||
const t = trueCV(); |
|||
const f = falseCV(); |
|||
|
|||
// construct optional clarity values |
|||
const nothing = noneCV(); |
|||
const something = someCV(t); |
|||
|
|||
// construct a buffer clarity value from an existing Buffer |
|||
const buffer = Buffer.from('foo'); |
|||
const bufCV = bufferCV(buffer); |
|||
|
|||
// construct signed and unsigned integer clarity values |
|||
const i = intCV(-10); |
|||
const u = uintCV(10); |
|||
|
|||
// construct principal clarity values |
|||
const address = 'SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B'; |
|||
const contractName = 'contract-name'; |
|||
const spCV = standardPrincipalCV(address); |
|||
const cpCV = contractPrincipalCV(address, contractName); |
|||
|
|||
// construct response clarity values |
|||
const errCV = responseErrorCV(trueCV()); |
|||
const okCV = responseOkCV(falseCV()); |
|||
|
|||
// construct tuple clarity values |
|||
const tupCV = tupleCV({ |
|||
a: intCV(1), |
|||
b: trueCV(), |
|||
c: falseCV(), |
|||
}); |
|||
|
|||
// construct list clarity values |
|||
const l = listCV([trueCV(), falseCV()]); |
|||
``` |
|||
|
|||
You should use these helpers when calling Clarity contracts with Javascript to avoid failed contract calls due to bad |
|||
typing. |
|||
|
|||
## Reading BNS names |
|||
|
|||
An important feature of Stacks is the [Blockchain Naming System][] (BNS). BNS allows users to register a human-readable |
|||
identity to their account, that can act as both a username and a web address. |
|||
|
|||
Names registered to a user can be read from a Stacks API endpoint, as demonstrated in [`src/store/names.ts`][]. |
|||
|
|||
-> Due to ecosystem limitations, it's currently uncommon for BNS names to be registered on any testnet. For the purpose |
|||
of demonstration, Heystack looks for BNS names against the user's mainnet wallet address. |
|||
|
|||
```ts |
|||
export const namesAtom = atomFamily((address: string) => |
|||
atom(async get => { |
|||
if (!address || address === '') return; |
|||
const network = get(mainnetNetworkAtom); |
|||
if (!network) return null; |
|||
|
|||
const local = getLocalNames(network.coreApiUrl, address); |
|||
|
|||
if (local) { |
|||
const [names, timestamp] = local; |
|||
const now = Date.now(); |
|||
const isStale = now - timestamp > STALE_TIME; |
|||
if (!isStale) return names; |
|||
} |
|||
|
|||
try { |
|||
const names = await fetchNamesByAddress({ |
|||
networkUrl: network.coreApiUrl, |
|||
address, |
|||
}); |
|||
if (names?.length) { |
|||
setLocalNames(network.coreApiUrl, address, [names, Date.now()]); |
|||
} |
|||
return names || []; |
|||
} catch (e) { |
|||
console.error(e); |
|||
return []; |
|||
} |
|||
}) |
|||
); |
|||
``` |
|||
|
|||
In order to reduce network traffic, Heystack also caches names in the browser's local storage. |
|||
|
|||
A common design pattern in Stacks 2.0 apps is to check if a user has a registered BNS name (only 1 name can be tied to |
|||
an account) and display that name in the app where appropriate. If the user doesn't own a BNS name, the wallet address |
|||
is used as a stand in. Often, the wallet address is truncated to avoid displaying an overly long string. |
|||
|
|||
The account name component in [`src/components/user-area.tsx`][] demonstrates this design pattern: |
|||
|
|||
```tsx |
|||
... |
|||
const AccountNameComponent = memo(() => { |
|||
const { user } = useUser(); |
|||
const address = useCurrentMainnetAddress(); |
|||
const names = useAccountNames(address); |
|||
const name = names?.[0]; |
|||
return <Text mb="tight">{name || user?.username || truncateMiddle(address)}</Text>; |
|||
}); |
|||
... |
|||
``` |
|||
|
|||
[heystack]: https://heystack.xyz |
|||
[stacks.js]: https://github.com/blockstack/stacks.js |
|||
[stacks web wallet]: https://www.hiro.so/wallet/install-web |
|||
[react]: https://reactjs.org/ |
|||
[heystack_gh]: https://github.com/blockstack/heystack |
|||
[data maps]: /references/language-functions#define-map |
|||
[`default-to`]: /references/language-functions#default-to |
|||
[`asserts!`]: /references/language-functions#asserts |
|||
[`unwrap-panic`]: /references/language-functions#unwrap-panic |
|||
[`unwrap!`]: /references/language-functions#unwrap |
|||
[`map-set`]: /references/language-functions#map-set |
|||
[sip-010]: https://github.com/hstove/sips/blob/feat/sip-10-ft/sips/sip-010/sip-010-fungible-token-standard.md |
|||
[`impl-trait`]: /references/language-functions#impl-trait |
|||
[`@stacks/connect-react`]: https://github.com/blockstack/connect#readme |
|||
[`@stacks/auth`]: https://github.com/blockstack/stacks.js/tree/master/packages/auth |
|||
[jotai]: https://github.com/pmndrs/jotai |
|||
[connect wallet button component]: https://github.com/blockstack/heystack/blob/main/src/components/connect-wallet-button.tsx |
|||
[welcome panel component]: https://github.com/blockstack/heystack/blob/63ce30f4f6de7a9c846fcdba3acbb6c7b82b83e3/src/components/welcome-panel.tsx#L102 |
|||
[`/src/store/auth.ts`]: https://github.com/blockstack/heystack/blob/main/src/store/auth.ts |
|||
[clarity types in javascript]: /build-apps/examples/heystack#clarity-types-in-javascript |
|||
[`@stacks/transactions`]: https://github.com/blockstack/stacks.js/tree/master/packages/transactions#constructing-clarity-values |
|||
[blockchain naming system]: /build-apps/references/bns |
|||
[`src/store/names.ts`]: https://github.com/blockstack/heystack/blob/main/src/store/names.ts |
|||
[javascript types to clarity types]: /build-apps/examples/heystack#clarity-types-in-javascript |
|||
[`@stacks/blockchain-api-client`]: https://github.com/blockstack/stacks-blockchain-api/tree/master/client |
|||
[`src/common/hooks/use-publish-hey.ts`]: https://github.com/blockstack/heystack/blob/main/src/common/hooks/use-publish-hey.ts |
|||
[`src/store/hey.ts`]: https://github.com/blockstack/heystack/blob/main/src/store/hey.ts |
|||
[`src/components/user-area.tsx`]: https://github.com/blockstack/heystack/blob/22e4e9020f8bbb404e8c1e36f32f000050f90818/src/components/user-area.tsx#L62 |
|||
Loading…
Reference in new issue