How to Use Multi-Asset Tokens in the Cardano Node

How to use multi-asset tokens in the Cardano node

Prerequisites

This section is for advanced users who are proficient with the Cardano-node command line interface (CLI).

This section describes how to:

create new currencies and assets;
submit and send transactions containing multi-asset tokens;
send and receive token bundles;
manage your addresses and values.

Note: Users who do not need to create new assets (“token holders”) will be able to send and receive existing multi-asset tokens using a wallet such as Daedalus or Yoroi, and with no requirement to use any CLI commands.

To start, please ensure that you are familiar with setting up and operating the Cardano node. Alternatively, see instructions on how to start your node to submit the commands. You will not need to set up and start a full block producing node (“stake pool”), just a much simpler relay node. This node will need to connect to a Cardano network that is capable of processing native tokens (e.g., the native token pre-production environment (PPE), or the Cardano Mainnet once it has been upgraded).

How to configure a relay node to connect to the Cardano native tokens pre-production environment

This document describes how to interact with the node from a bash command line, but it is also possible to download and run the node as a docker image, which will involve less system configuration. The docker image is input-output/cardano-node - please ensure you have the latest version (1.24.x).

To configure a relay node to communicate with the pre-production environment for the Mary era, first build and install the node as described in https://github.com/input-output-hk/cardano-node, and then set up its configuration:

mkdir -p mary-ppe/config
cd mary-ppe
# download and save the configuration files to the config subdirectory

You may then use the following command from the mary-ppe directory to start the relay node. Note that you do not need to configure and run the node as a “stake pool” (block producing node):

export CARDANO_NODE_SOCKET_PATH=socket
 
cardano-node run --topology config/topology.json  
--database-path db --config config/config.json --port 3001 
--socket-path "$CARDANO_NODE_SOCKET_PATH"

The latest configuration files can be found here. You will need to download all the files that are associated with the launchpad cluster and copy them to your config subdirectory.

Once you have started the node, leave it running in its own terminal window (or run it in the background if you prefer).

Using the Cardano CLI

Once a relay node has been set up, the cardano-cli command can be used to interact with the network as usual:

cd mary-ppe
cardano-cli ...

Note that multi-asset support is provided as part of the Mary consensus era, so many commands will require the --mary-era flag:

cardano-cli ... --mary-era

Syntax of multi-asset values

The cardano-cli can specify multi-asset values in transaction outputs and when minting or burning tokens. The syntax for these values has been designed to be backwards-compatible with the previous ada-only syntax (address+lovelace):

ada values are defined as integer (INT) lovelace, e.g. 42 lovelace
multi-asset values can be defined as:
- INT policyid.assetname, e.g. 42 $MYPOLICY.myassetname
- INT policyid, e.g. 42 $MYPOLICY (No asset name specified)
- policyid.assetname, e.g $MYPOLICY.myassetname (This will mint only one of myassetname)
Multiple assets can be combined in the same multi-asset value using the + operator, e.g:

100 lovelace + 42 $MYPOLICY.foo + -2 $MYPOLICY.bar + 10 lovelace

How to create a transaction

The multi-asset syntax can be used in the following contexts:

cardano-cli transaction build-raw --tx-out="..."
cardano-cli transaction build-raw --mint="..."

The CLI command cardano-cli transaction build-raw creates the transaction body. The --tx-out option specifies the transaction output in the usual way (This is expressed as address+lovelace, where address is a Bech32-encoded address, and lovelace is the amount in lovelace), and the --mint option specifies the value to be minted or burnt.

Transaction outputs (TxOuts)

The syntax for TxOut values has been extended to include multi-asset tokens. These values can be specified in two different ways:

$address $value
${address}+${value}

(where address is a Cardano address and value is a value). The second form is provided for backwards compatibility with earlier versions of the node.

To receive tokens, you just need to specify any address. It is not necessary to use special addresses to hold multi-asset tokens.

Values

Lovelace values can be specified in two ways:

${quantity} lovelace (where quantity is a signed integer)
${quantity} (where quantity is a signed integer)

Values for other assets can be specified as:

${quantity} ${policyId}.${assetName}
${quantity} ${policyId}

Where quantity is a signed integer and policyId is a hex-encoded policy ID a script hash), and assetName is an alphanumeric asset name.

Negating individual values

Any individual value can be negated using the - prefix operator. For example:

-42 $MYPOLICY
-72191 $MYPOLICY.foo
-100
-920 lovelace

Combining individual values

Values can be combined using the binary operator +. For example:

42 lovelace + -1 (this would result in a Value of 41 lovelace)
20 $MYPOLICY + 12 $MYPOLICY.foo + -2 $MYPOLICY.bar
201 4$MYPOLICY.foo + 12 + -1 + 9 lovelace + 10 $MYPOLICY

To inspect the values in an address, you need to view a UTxO value using:

cardano-cli shelley query utxo --mary-era

This will show the content of any token bundles that you possess. You can choose to see a specific address using the --address $ADDRESS option:

cardano-cli shelley query utxo --address "$ADDRESS" --mary-era

Development Environments