Opt-In to Receive an Algorand Asset with React
--
Algorand now has assets!
Great… so,
- what are these assets?
- how can I use them?
- what is this “opting in” ?
Algorand Standard Asset or ASA is a Layer-1 feature that enables the creation and representation of any asset, digitally on the Algorand blockchain. The benefits of implementing these sorts of asset management features into the base layer protocol is for the enhanced security, compatibility and efficiency guarantees that are offered for any Layer-1 Algorand transaction.
In this post, we are going to create an asset using goal
and then use React to “opt into” receiving the asset.goal
is the Algorand command line interface (CLI). The executable is installed alongside the algod
binary and is critical for interacting with the Algorand network.
Opt-In to Receive an Asset
The concept of opting in is similar to the spamming protection that comes from the minimum balance requirement of 100,000 microalgos for every registered account on the Algorand blockchain. Assets are identified by a unique uint64 (“Asset Index”) and are called “assets” in the code.
To receive an Algorand asset, you must explicitly opt in to receive the asset by sending a 0 amount of the asset to yourself (to the account wanting to receive the asset).
Holding an asset increases the size of your balance record. When you hold an asset, your balance record has an entry in its Assets map. map AssetIndex => AssetHolding
. Balance record is the row in the database associated with an algorand account. So having an asset increases the minimum balance requirement for your account by 0.1 ALGO’s. Having someone else increase your minimum balance would be a massive security compromise, so an account must elect to increase the size of their own balance record.
Configure your environment
Before we begin, make sure you’ve got a fully synced Algorand TestNet node. We always recommend using TestNet when developing your applications to replicate the real-world network behavior of MainNet. You can follow the getting started instructions on our developer documentation site. Once you’ve run the updater and have downloaded goal, navigate over to switching networks to get onto TestNet (the installation package defaults to MainNet).
Create a wallet
goal wallet new testWallet -d testnetnode
the -d
flag points to the data directory you are talking to.
This should prompt you for a password, a password confirmation and whether or not you’d like to see the backup phrase to the wallet.
Create an account
goal account new -d testnetnode
You can specify which wallet you’d like the account created in with the -w
flag followed by the wallet string. This is helpful if you have multiple wallets. You can also designate a wallet as your default wallet. In our case, our one wallet is our default wallet.
Run the command again to create a second account
goal account new -d testnetnode
Running goal account new
should return a “Created new account with address <address-string>” success message.
Let’s rename these accounts for a smoother user experience using the goal account rename
command.
goal account rename <current-account-name> Account-1 -d testnetnode
The <current-account-name> should be Unnamed-0 for the first account you created and Unnamed-1 for the second.
Run the same command for the second account and rename it no “Account-2”
goal account rename <current-account-name> Account-2 -d testnetnode
Both these commands should return success messages: “Renamed account ‘Unnamed-0’ to ‘Account-1” after running the first command and “Renamed account ‘Unnamed-1’ to ‘Account-2” after running the second command.
Let’s Create a Custom Asset on Algorand
To create an asset, you must run the goal asset
command and in this case we will be running goal asset create
.
Running goal asset create -h
will list out all the available commands within the create command.
When creating an asset, you can specify:
- total: how many units of this asset will be created
- defaultFrozen: do holdings of this asset start off frozen? Basically, whether user accounts will need to be unfrozen before transacting with the asset (this will be discussed in a later post)
- clawback, freeze, reserve, manager addresses (these will be discussed in a later post)
as well as metadata fields:
- name: name of the entire asset class (ALGO, USD, etc.)
- unitname: name of one unit of this asset (algo, dollar, etc.) — max 8 bytes
- asseturl: optional string pointing to a URL relating to the asset
- assetmetadata64: optional cryptographic hash commitment to some sort relating to the asset. 32 character length
Now let’s create an asset with name: “CorpABC”, unitname: “abc”, total: 100, creator: your-own-account.
goal asset create --name CorpABC --unitname abc --total 100 --creator Account-1 -d testnetnode
Now that the asset is created, run goal account list
to see the newly created asset under the creator — Account-1
We will now have Account-2 opt-in to receive this newly created asset by referencing the assetID. Some commands only require the asset name, not necessarily the ID. There can be multiple asset classes with the same name, so using an assetID is the most specific and recommended way to reference as asset.
Why use React?
ReactJS is a JavaScript framework primarily used for handling view layers for web and mobile apps. React’s main advantage and what we will be highlighting in this post is the fact that React easily allows a developer to create reusable UI components. React is highly versatile and can be used with a variety of other JavaScript libraries to build powerful applications. React is meant to be simple, fast and scalable — all the qualities that make for a pleasurable modern web application development experience.
The two main points to keep in mind for this post are:
- Everything is a component in React, like everything is an element in HTML. And components return exactly one DOM element
- Every component has a rendering method. Using JSX, anything wrapped in parens can convert HTML to JS created elements
The beautiful simplicity and speed of React is evident when working with the Document Object Model (DOM). Data gets handled in two ways in React: in state and in props. Whenever state changes on a component, the component will auto render and update the DOM if the state changes, if not — the component doesn't touch the DOM. React effectively manages the DOM for you. In React there are two types of DOMs. The virtual DOM is a representation of a UI kept in memory that is synced with the “real” DOM in a process called reconciliation. Whenever React renders components, it starts at the components tree and looks for changes from the virtual DOM to actual DOM and updates only affected nodes in the most efficient way. If nothing changes, React doesn’t touch the webpage.
Build an Opt-In Component with React
To opt-in to a receive an asset, we will first define the sendTransaction function call, which we will use as the “Opt-In” button, as well as the account which we extract using the mnemonicToSecretKey() method.
Using the mnemonic to derive the account address and other account parameters is not the recommended mechanism, but we will use the technique in this example for simplicity. Never share your account mnemonic with anyone!
Now define the transaction parameters and the assetID that you will be passing in. If you are familiar with Algorand transactions, this construction should look familiar.
Now we define the transaction object. Notice that the 6th parameter in the transaction is 0. This is the amount that is being transferred in the transaction.
You can refer to the JS SDK to see what makes up an asset transfer.
Now that the parameters have been defined, the transaction object has been created all that is left is to sign the transaction and broadcast (send) it to the network.
Below you’ll find the UI bit using a render prop. Render props are just a technique to share code between components. You can see our sendTransaction function on line 32 that is used for our “Opt-In” button.
The final component should look something like this. We will build out the rest of the components for this application in future posts. But this introduces the basic framework for using React with blockchain applications.
I am using the Account-2 that we created using goal
to opt-in to receive the abc asset that we created earlier. This executes with a success message that contains our transaction id and confirmation that the transaction was broadcasted.
You can run goal account list
again to confirm that the account you used to opt-in now has an entry in its Assets Map.