Hooks
Introduction
Breeze SDK offers around 10 custom hooks and all common CIP-30 wallet api functions under $wallet.
Customs
All custom-made functions was creating to make the developer's life easier, you can find all of them below, remember that those starting with $ are svelte stores, so you can use it anywhere in your application
Wallet API Originals
All the functions you can find inside the cardano-caniuse
wallet API will be there under $wallet store,
some of them are not listed here as our custom functions do better what they do, but feel free
to call them as you want, all they are available
useCardanoWallet
useCardanoWallet is a custom hook from the breezesdk library
that provides a set of methods for interacting with a Cardano wallet in your application.
When you call useCardanoWallet, it
returns the following functions and values:
list,connect,isconnected,disconnect,selected,wallet
These functions and values are reactive, meaning they will automatically update in response to changes in the wallet's state. This makes it easy to build applications that respond to changes in the wallet's state, you only need to import useCardanoWallet and destruct them.
+page.svelte
$list
$list is a svelte store that returns a list of available wallets, it mounts when your application loads as a reactive component, which means that the $list will be available in your application without the need to use any other function, by default, it returns and filters the correct objects under window.cardano.
You can use $list to create your own Connect Wallet button, while the Modal Wallet and
Dropdown Wallet components are available for you to use out of the box.
By making
yourself, you need to display the list of wallets for the user to pick and pass it to the
connect function when the user pick one.
By default, this is what you see when you call $list inside the svelte html
Then using #each from svelte you can itinerate over the arrays from $list, each array inside it is an array of two elements, the first element is a string (walletname) and the second element is the object with the wallet property (apiversion, enable, icon, etc), the below example uses this code
+page.svelte
connect
The connect function simple enable you to connect to a wallet by passing the name of the
wallet to the function, you can receive wallet names using $list and passing the first element value from the $list array to the connect function.
As an example code, you can see and try below how the connect function works.
+page.svelte
$isConnected
the $isConnected is a boolean svelte store, it will return true or false depending on
your wallet connection state, you must first try to connect your wallet usingconnect and passing a wallet name value from the $list array to the connect function.
Try below how the isConnected function works using a #if from svelte, with isConnected you can change the button to disconnect the wallet when the user is connected, you can add it to a modal, dropdown, tooltip, drawer or anything you want.
$isConnected: false
+page.svelte
disconnect
A function that cleans the svelte store values for selected,
wallet
and isConnected. it will erase everything from the store, so you can
call it when you want to disconnect the wallet from your application. Still, you can use
the
disconnect inside a custom function where
you can erase any data related to the authentication, as jwt tokens, cookies or localStorage
items.
As we have seen in the $isConnected block, the disconnect button can be used in a
conditional rendering block to display only when the user is connected, based on $isConnected value, in this case, the button will be displayed only when the user is connected.
By the purpose of this test, the connect function will now add a cookie and a localstorage item, and the custom disconnect will remove it, you can even add a router push to redirect the user to a specific page when the user disconnects, check the Application tab in the devtools to see the cookie and the localStorage item.
$isConnected: false
+page.svelte
$selected
After the user connection is, sometimes, required to remember the user what wallet is
connected and $selected store those values under $selected.name
and $selected.icon
It's possible to pass one or both options inside the conditional rendered block based
on $isConnected value, displaying the
name, icon, or both, as you can see in the example below.
$selected.name: undefined
+page.svelte
Introduction to $wallet
$wallet is a writable store that holds the current wallet instance, incorportaing custom
functions and new types to the commonwindow.cardano
object, here you can serialize, deserialize and get off-chain user information based on the wallet
object.
By importing $wallet you're open to use any method from cardano-caniuse
and breeze SDK custom functions, we will be using
DropdownWallet to execute examples.
$wallet.getNetworkId
Returns the network id of the currently connected account. 0 is testnet and 1 is mainnet but other networks can possibly be returned by wallets. Those other network ID values are not governed by this document. This result will stay the same unless the connected account has changed.
+page.svelte
$wallet.getUtxos
This returns, in cbor, the unspent transaction outputs from the connected wallet. If amount is undefined, this shall return a list of all UTXOs (unspent transaction outputs) controlled by the wallet. If amount is not undefined, this request shall be limited to just the UTXOs that are required to reach the combined ADA/multiasset value target specified in amount, and if this cannot be attained, undefined shall be returned. The results can be further paginated by paginate if it is not undefined. The wallet must have received or performed transactions to have any UTXOS.
+page.svelte
$wallet.getBalance
Returns the total balance available of the wallet in cbor format. This is the same as summing the results of $wallet.getUtxos(), but it is both useful to dApps and likely already maintained by the implementing wallet in a more efficient manner so it has been included in the API as well.
+page.svelte
$wallet.getUsedAddresses
Returns a list of all used (included in some on-chain transaction) addresses controlled by the wallet. The results can be further paginated by paginate if it is not undefined.
+page.svelte
$wallet.getChangeAddress
Returns an address owned by the wallet that should be used as a change address to return leftover assets during transaction creation back to the connected wallet. This can be used as a generic receive address as well.
+page.svelte
$wallet.getRewardAddresses
Returns the reward addresses owned by the wallet. This can return multiple addresses e.g. CIP-0018.
+page.svelte
$wallet.getAddress
This function first gets the raw change address from the API, then decodes it into bytes and converts it into a Cardano address. It then checks if the address is a valid base address and if it has a valid stake credential and stake key. Finally, it converts the address into the specified format and returns it.
Default is bech32, an address starting with addr1
| Format | Description |
|---|---|
| cbor | Return cbor encoded address |
| bytes | Return byte decoded address from cbor |
| stakehex | Return stakehex from bytes |
| stakekey | Return the stakekey from bytes |
| bech32 | Return bech32 (common) address from bytes |
+page.svelte
$wallet.getAssets
This function first gets the balance from the API in CBOR format, then decodes it into bytes and converts it to a readable value. It then checks if the value has a multiasset and throws an error if it doesn't. It then converts the multiasset into a JSON object and decodes the asset names into strings. It then creates a list of assets, each with a policy ID, hex name, asset name, and quantity. Finally, it filters the list of assets based on the specified type and returns the filtered list.
Remember that this is off-chain data from the assets, you must use a chain indexer to get the on-chain data, like metadata from the assets, you can try it using the hex value.
This function can't be empty, pass a type to filter the assets
| Type | Description |
|---|---|
| lovelace | Return the value in lovelace in the wallet |
| ada | Return the value of total available ada in the wallet |
| ft | Return the fungible tokens from the wallet |
| nft | Return the non-fungible tokens from the wallet |
| asset | Return all assets |
| handles | Return all handle.me from the wallet |
| policy | Return all assets filtered by policy, can be FTs or NFTs |
+page.svelte
getCardanoWallets
This function first checks if the `window` object and the `cardano` property on the `window` object exist. If they do, it gets the names of the wallets and filters and maps the entries of `window.cardano` to get the wallets. Finally, it resolves the promise with the wallets, under the hood, it filters unecessary objects injected by the cardano object and returns only the valid wallet names.
+page.svelte
enableCardanoWallet
This function first checks if the `window` object and the `cardano` property on the `window` object exist. if they do, it enables the wallet by passing the prop walletName to the wallet object. Finally, it resolves the promise with the wallet API.
We don't recommend you to use it directly, use connect instead.
Remember that by not using connect
from useCardanoWallet you will not be
able to use $selected or $isConnected, neither $wallet functions
+page.svelte