Using Element Practical Use Case

Issued Assets

Building with Elements and Liquid Network

Issued Assets

In this section, you will learn how to use the Issued Assets feature of Elements.

Issued Assets enable multiple types of assets to be issued and transferred between Elements network participants. Any node on the network can issue its own assets. Issuances may represent fungible ownership of any asset, including vouchers, coupons, currencies, deposits, bonds, shares, and other similar items. Issued Assets opens the door for building trustless exchanges, options, and other advanced smart contracts involving self-issued assets.

An Issued Asset also benefits from Confidential Transactions, and they can be reissued by anyone holding the associated token.

The first step is that we'll need access to two Elements nodes, which we'll call e1 and e2. The nodes have had their blockchains reset, and the default asset split between them.

The two nodes are on the same local network and are connected to each other; therefore, they share the same transactions in their transaction mempools and identical blockchains. Although they are running on the same machine, it is worth noting that they do not share the same actual blockchain files. Each node manages its own local copy of the blockchain, which contains the same transaction history because they are in consensus and adhere to the same protocol rules as each other.

Let's start by checking each node's view of the existing asset issuances on the network.

This is done using the listissuances command.

e1-cli listissuances

e2-cli listissuances

As you can see, both nodes show the same issuance history. They both display one asset, the initial issuance of 21 million Bitcoin, which were created on chain initialization. You can see the hex ID of the asset in the results of running the command above, as well as the label assigned to the asset, which is 'bitcoin'.

It is worth noting that the default asset is always given a label when the chain is initialized. When you issue your own assets, you can set labels for them yourself, which we'll be doing shortly. Before we can do that, we need to issue our own asset.

We'll have e1 issue the new asset. This is done using the issueasset command.

e1-cli issueasset 100 1 false

issueasset accepts 3 parameters.

The amount of the new asset to issue is 100. The amount of tokens to create (tokens are used to reissue amounts of an asset), of which we chose 1. The final parameter tells Elements to either create the asset issuance as blinded or unblinded. We'll use 'unblinded' as we want to view the issuance amounts from e2 in a minute, so we'll enter 'false'.

Running the command returns data about the issuance. These include the transaction ID, which you can copy for later use, the unique hex value of the asset, and the unique hex value of the asset's token.

Generate a block to confirm the issuance transaction.

e1-cli -generate 1

Run the listissuances command against e1 again.

e1-cli listissuances

That shows us that e1 is now aware of 2 issuances, the initial issuance of Bitcoin and our newly issued asset, of which we can see 100. Note the hex value of the new asset and that there is no associated asset label, unlike the one for the bitcoin issuance.

Check e2's list of known issuances again.

e2-cli listissuances

That shows us that e2 is not aware of the asset issuance e1 made. It can only see the initial issuance of bitcoin that it could already see.

This is because e2 is unaware of, and is not watching, the address to which the new asset was sent when it was issued by e1.

It is worth noting that even though e2 can not see the issuance itself, e1 could still send e2 some of the asset. The new asset would then show up as an available balance in e2's wallet, even though it is not aware of the original issuance.

To enable e2 to view the actual issuance (and therefore the amount issued), we need to add the address to e2 as a watched address.

To do this, we need to determine the address to which the asset was sent. For this, we will use the transaction ID we copied earlier and have e1 retrieve the transaction details so we can find the correct address to add to the wallet watch list of e2.

e1-cli gettransaction <the-issuance-transaction-id>

Scrolling up past the hex of the transaction data, you will see the address that received 100 of our new asset, identified by its hex value.

Take the address and copy it so we can import it into e2.

Now let's import that address into e2. To do this, we use the importaddress command.

e2-cli importaddress <the-issued-to-address>

If we now check e2's list of issuances.

e2-cli listissuances

You can see that our newly issued asset is now included in the list. The e2 node is also able to determine the amount of the asset that was issued, along with the amount of the associated token, as the issuance was an unblinded issuance. To enable the use of asset ID to name mapping within Elements, first stop Elements.

e1-cli stop

Then restart it with an additional parameter that maps an asset's hex to the provided label. This enables the node to display data about the asset to us in a more human-readable format. You can add this to the end of elements. If you prefer, you can simply omit the argument to the daemon each time you start it. For example:

assetdir=5186d0bc8ed15e6ef85571bd2d8070573adf0e06fd4507082694526975ce4f35:My new asset (MNA)

But we will use the argument method here.

e1-dae -assetdir=<assetid-here>:<name-of-the-new-asset>

Querying the node for a list of issuances again.

e1-cli listissuances

That indicates that the mapping of the asset's hex value to its label is functioning correctly. Checking again on the e2 node's list of issuances.

e2-cli listissuances

You can see that the e2 node does not have access to this label, because labels are only available to the node that sets them. Indeed, we can assign a different label to the same asset hex on e2 than we did on e1. First, stop the e2 node.

e2-cli stop

Restarting with a different label assigned to the hex of our new asset.

e2-dae -assetdir=<assetid-here>:<another-name-for-the-new-asset>

Listing issuances from e2.

e2-cli listissuances

Asset labels are local to each node; only the hex of the asset is recognised by other nodes on the network.

The mapping of label to asset hex is useful when carrying out actions such as transactions and wallet balance queries, as it allows a shorthand way to refer to an asset. For example, if we wanted to send some of our new asset (an amount of 10) from e1 to e2 without using the label.

First, we need to get an address to send the asset to.

e2-cli getnewaddress

Then use the sendtoaddress command.

e1-cli sendtoaddress <address> 10 "" "" false false 1 UNSET false <asset-id-here>

Confirm the transaction by generating a block.

generate 1

Checking the asset was received on e2.

e2-cli getwalletinfo

We can see that the asset was indeed received.

Note that e2 maps the hex of the asset received and displays it using its own label. An easier way to do the same thing would be to use e1's asset label when sending.

e1-cli sendtoaddress <address> 10 "" "" false false 1 UNSET false <name-of-the-new-asset>

Behind the scenes, Elements maps local labels to hex values to help simplify the use of issued assets.

In this section, we have seen how to issue and label assets. In the next section, we will examine the process of reissuing and destroying amounts of an issued asset.