Use Taproot Assets to mint, send, receive and burn assets on the Bitcoin blockchain.
Command Line Interface
When running tapd as part of litd (integrated mode), you will need to specify that you are connecting to the litd process when executing tapcli commands from the command line interface. This has to include the tls.cert and port 8443. Unless you are running on mainnet, the network has to be specified as well.
tapcli --tlscertpath ~/.lit/tls.cert --rpcserver=localhost:8443 --network=testnet assets list
Future sample commands will omit these details for simplicity.
Preparation
Taproot Assets allows you to mint both collectible and normal assets. In this guide we will mint normal assets, meaning an asset that is divisible into equal parts. Before we can get started, we will have to decide on the parameters for our asset.
Type
An asset can be either set to normal or collectible. A normal asset is divisible into parts of equal value.
Name
An asset requires a name. Uniqueness cannot be enforced over this name, so it can’t be used to uniquely identify the asset.
Supply
The total supply of your asset. Don’t forget to consider decimal places!
Decimal display
The number of decimal places your asset will have. Two decimal places would allow only for cents, while six decimal places would allow for micro-units. Too few decimal places can result in rounding errors when transferring assets over the Lightning Network. You can choose up to 12 decimal places.
If you want to mint 1 million units of an asset, each divisible into one thousand pieces, you will have to choose a total supply of 1,000,000,000.
Meta Data
You can associate your asset with additional metadata. This data can be added in the form of a string (--meta_bytes), a file on disk (--meta_file_path), and be either in opaque or json form (--meta_type)
Grouped Asset
For grouped assets the total supply can later be inflated, while ungrouped assets have a permanently fixed supply.
Minting Assets
Use tapcli to begin minting your first asset. We are minting a normal asset and we'll allow ourselves to increase the supply of this asset in the future by setting the --new_grouped_asset flag. The total supply will be 1,000 units, each divisible into 1,000 sub-units. For the decimal display to take effect, the meta_type needs to be set to json and a json will need to be supplied, either as a file or as a string. As of now there is no “official” format for what this json file should look like or what it should contain.
tapcli assets mint --type normal --name beefbux --supply 1000000 --decimal_display 3 --meta_bytes '{"hello":true}' --meta_type json --new_grouped_asset
This will add your asset to a minting queue called a batch, which allows multiple assets to be created in a single minting transaction. This saves fees and conserves blockspace. To execute the batch and publish your mint transaction to the blockchain run:
tapcli assets mint finalize
You will be given a batch_txid, which will have to be included in a block before you can spend your newly created assets. You can also inspect the newly created asset(s) by calling the command
The output of this command can be explained as follows:
version: The asset protocol version with which this asset was created
genesis_point: The first input of the minting transaction
name: The name of the asset as defined at its creation
meta_hash: The metadata as defined at its creation
asset_id: The asset ID is a digest of the information found under asset_genesis in the format sha256(genesis_outpoint || asset_tag || asset_meta || output_index || asset_type).
asset_type: Whether an asset is “normal” or a collectible
output_index: The output of the minting transaction where the asset will be anchored. This is set to 0 while the transaction confirms
amount: The quantity of this asset held by you
lock_time: An asset can be locked in time, similar to a bitcoin script
relative_lock_time: Relative locktime, analogous to bitcoin script
script version: The script protocol version with which the script was created
script_key: The script key associated with the asset
script_key_is_local: Whether you hold the key associated with this script.
asset_group:
raw_group_key: If the asset belongs to an asset group, its key will be listed here
tweaked_group_key: The tweaked key is needed to later issue more assets of this group
asset_witness: The witness (e.g. signature) used to prove that this asset was issued by the owner of the group key
chain_anchor:
anchor_tx: The raw minting transaction
anchor_txid: The hash of the minting transaction
anchor_block_hash: The hash of the block that the minting transaction was included in. This is set to zeros as the transaction is unconfirmed
anchor_outpoint: The outpoint on the bitcoin blockchain that holds the asset
internal_key: The Taproot key that holds the outpoint containing the asset
merkle_root: The merkle root of the tree that includes the asset
tapscript_sibling: The taproot leaf to the left or right of the leaf committing to the asset. It is used to calculate the merkle root
prev_witnesses: Signatures and data related to previous transfers of this asset
is_spent: Whether this asset has been spent
lease_owner: Similar to leased UTXOs in LND, tapd allows specific UTXOs to be "held" for a certain amount of time, for example while waiting for signatures or channel opens. This prevents the UTXO from being accidentally spent by another process.
lease_expiry: When the UTXO becomes available again for spending.
is_burn: Whether the asset has been burned.
script_key_declared_known: used for Lightning Network channels
script_key_has_script_path: used for Lightning Network channels
decimal_display: The number of decimal places configured for this asset.
Assets that were minted with the flag --new_grouped_asset do not have a fixed supply. A new batch of this asset can be minted later in a way that the two assets are considered of the same asset group, and therefore fungible.
Note: At the moment it is not possible to spend two assets with different asset IDs, even if they belong to the same asset group.
To increase the supply of such an asset, we will need its tweaked_group_key.
tapcli assets mint --type normal --name beefbux --supply 100000 --decimal_display 3 --meta_type json --grouped_asset --group_key 025234364112f83ea7ee8e35f061d625df82ee07e443835107947e3bb53e8e9bfc
We again have to publish the new mint transaction with:
tapcli assets mint finalize
You can also specify a custom fee rate (in sat/vB) using the flag --sat_per_vbyte
Now we can check our groups. They are ordered by their tweaked group key.
To inspect your balances, run tapcli assets balance. To show the cumulative balance across asset groups, run tapcli assets balance --by_group
Synchronizing with a universe
Taproot Assets uses universes to communicate information about which assets exist and where in the blockchain they are anchored. A universe can be thought of as a virtual mempool, an explorer, or a repository.
Your node will sync with the universe whenever you create a new Taproot Assets address with an unknown asset ID, or when specifically instructed to. This requires an asset ID or a group key.
On testnet, you can use testnet.universe.lightning.finance:10029, or you can run your own universe.
Upon successful sync, information about existing assets should be retrieved, alongside their issuance proofs.
Generating Taproot Assets addresses
As soon as your minted assets have one confirmation on the blockchain, you are able to send them. To send assets, you will need the recipient’s Taproot Assets address. This Taproot Assets address is specific to an asset and amount, so to generate an address, the recipient needs to know an asset’s asset_id, as well as be synced to the issuer’s universe. Taproot Assets address reuse should be avoided.
When generating a Taproot Assets address, the receiver will create their expected Merkle trees, and tweak a Taproot key with it. The resulting key is converted to a Taproot address, where the receiver waits for an incoming transaction.
To generate a Taproot Assets address requesting 21 beefbux, use the following command from the tapd instance of the receiver:
tapcli addrs new --asset_id b9ae86f52dcbdee7ea78e86b26320819c44c2f4f8a91b9c055ca0af4c4d1b22b --amt 21
encoded: The bech32 encoded Taproot Assets address.
asset_id: The asset ID of the asset that the address corresponds to.
asset_type: Whether an asset is fungible, or a collectible.
amount: The requested amount of this asset.
group_key: If a key is set here, this asset is part of an asset group, meaning the issuer can expand its supply.
script_key: This key identifies the script that defines how an asset may be transferred.
internal_key: The key that holds the asset.
tapscript_sibing: Used when sending assets to custom scripts.
taproot_output_key: The key that is going to hold the Taproot output once it is received.
proof_courier_addr: The mailbox over which the asset proofs are being delivered.
asset_version: The version of the asset.
You’ll also be able to inspect this address again anytime with the command tapcli addrs query
Sending an asset
To send the asset, run the command below from the tapd instance of the sender. This will generate the appropriate Merkle trees for the recipient and their change outputs, sign the Taproot Assets transaction with their internal Taproot Assets key and publish the Bitcoin transaction. Note that you cannot send unconfirmed assets.
You will notice the testnet3 transaction id (bd311ca4dbd68c6717ed4656efe7beb9ff843abe50bf58aaf3b25325c0f098aa) has two inputs. One input is the newly minted asset (easily identifiable by its 1000 sat amount), while the other is from LND’s internal wallet. This second input is used to pay the onchain fees. The output from tapcli as seen above will only show the one input and two outputs that hold the Taproot Assets.
There are three outputs. Two outputs of 1000 satoshis each and the change output of LND’s internal wallet. The two 1000 satoshi inputs anchor the proofs of the sender and receiver. Even when the sender spends all of their assets, such an output is still created to carry proof of the transfer.
Once the transaction is confirmed on the Bitcoin Blockchain the sender will attempt to make the proofs available to the recipient via an end-to-end encrypted mailbox, similar to Lightning Node Connect (LNC).
By default, this mailbox is set to your default universe, but you can run your own mailbox through aperture and configure tapd to use it by specifying the --hashmailcourier.addr= flag at startup.
Please confirm destructive action.
Asset ID: b9ae86f52dcbdee7ea78e86b26320819c44c2f4f8a91b9c055ca0af4c4d1b22b
Current available balance: 100000
Amount to burn: 50
Are you sure you want to irreversibly burn (destroy, remove from circulation)
the specified amount of assets?
Please answer 'yes' or 'no' and press enter: yes
