BurnAsset

BurnAsset burns the given number of units of a given asset by sending them to a provably un-spendable script key. Burning means irrevocably destroying a certain number of assets, reducing the total supply of the asset. Because burning is such a destructive and non-reversible operation, some specific values need to be set in the request to avoid accidental burns.

Source: taprootassets.proto

gRPC

rpc BurnAsset (BurnAssetRequest) returns (BurnAssetResponse);

REST

HTTP Method	Path
POST	/v1/taproot-assets/burn

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:10029'
const MACAROON_PATH = 'TAPROOT-ASSETS_DIR/regtest/taproot-assets.macaroon'
const TLS_PATH = 'TAPROOT-ASSETS_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('taprootassets.proto', loaderOptions);
const taprpc = grpc.loadPackageDefinition(packageDefinition).taprpc;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
const macaroon = fs.readFileSync(MACAROON_PATH).toString('hex');
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
  let metadata = new grpc.Metadata();
  metadata.add('macaroon', macaroon);
  callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let client = new taprpc.TaprootAssets(GRPC_HOST, creds);
let request = {
  asset_id: <bytes>,
  asset_id_str: <string>,
  amount_to_burn: <uint64>,
  confirmation_text: <string>,
};
client.burnAsset(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "burn_transfer": <AssetTransfer>,
//    "burn_proof": <DecodedProof>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the taprootassets.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import taprootassets_pb2 as taprpc, taprootassets_pb2_grpc as taprootassetsstub

GRPC_HOST = 'localhost:10029'
MACAROON_PATH = 'TAPROOT-ASSETS_DIR/regtest/taproot-assets.macaroon'
TLS_PATH = 'TAPROOT-ASSETS_DIR/tls.cert'

# create macaroon credentials
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
def metadata_callback(context, callback):
  callback([('macaroon', macaroon)], None)
auth_creds = grpc.metadata_call_credentials(metadata_callback)
# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# combine macaroon and SSL credentials
combined_creds = grpc.composite_channel_credentials(ssl_creds, auth_creds)
# make the request
channel = grpc.secure_channel(GRPC_HOST, combined_creds)
stub = taprootassetsstub.TaprootAssetsStub(channel)
request = taprpc.BurnAssetRequest(
  asset_id=<bytes>,
  asset_id_str=<string>,
  amount_to_burn=<uint64>,
  confirmation_text=<string>,
)
response = stub.BurnAsset(request)
print(response)
# {
#    "burn_transfer": <AssetTransfer>,
#    "burn_proof": <DecodedProof>,
# }

REST

Javascript

const fs = require('fs');
const request = require('request');

const REST_HOST = 'localhost:8089'
const MACAROON_PATH = 'TAPROOT-ASSETS_DIR/regtest/taproot-assets.macaroon'

let requestBody = {
  asset_id: <string>, // <bytes> (base64 encoded)
  asset_id_str: <string>, // <string> 
  amount_to_burn: <string>, // <uint64> 
  confirmation_text: <string>, // <string> 
};
let options = {
  url: `https://${REST_HOST}/v1/taproot-assets/burn`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "burn_transfer": <object>, // <AssetTransfer> 
//    "burn_proof": <object>, // <DecodedProof> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8089'
MACAROON_PATH = 'TAPROOT-ASSETS_DIR/regtest/taproot-assets.macaroon'
TLS_PATH = 'TAPROOT-ASSETS_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/taproot-assets/burn'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'asset_id': base64.b64encode(<bytes>),
  'asset_id_str': <string>,
  'amount_to_burn': <uint64>,
  'confirmation_text': <string>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "burn_transfer": <AssetTransfer>,
#    "burn_proof": <DecodedProof>,
# }

Shell

$ tapcli assets burn --help

NAME:
   tapcli assets burn - burn a number of asset units

USAGE:
   tapcli assets burn [command options] [arguments...]

DESCRIPTION:
   
  Burn (destroy, remove from circulation) a number of asset units in a
  provable way. The returned burn proof is cryptographic evidence that the
  assets can no longer be spent and that the supply has been reduced by
  the specified amount.

  To avoid a dangling BTC output, not all assets within a commitment can
  be burned completely, there always must be a change output (either with
  a change amount or another asset that resides in the same commitment).
  

OPTIONS:
   --asset_id value                        the asset ID to burn units from
   --amount value                          the amount of units to burn/destroy (default: 0)
   --override_confirmation_destroy_assets  if set, the confirmation prompt will be skipped and the assets are burned/destroyed immediately
   

Messages

taprpc.BurnAssetRequest

Source: taprootassets.proto

Field	gRPC Type	REST Type	REST Placement
asset_id The asset ID of the asset to burn units of.	bytes	string	body
asset_id_str The hex encoded asset ID of the asset to burn units of.	string	string	body
amount_to_burn	uint64	string	body
confirmation_text A safety check to ensure the user is aware of the destructive nature of the burn. This needs to be set to the value "assets will be destroyed" for the burn to succeed.	string	string	body

taprpc.BurnAssetResponse

Source: taprootassets.proto

Field	gRPC Type	REST Type
burn_transfer The asset transfer that contains the asset burn as an output.	AssetTransfer	object
burn_proof The burn transition proof for the asset burn output.	DecodedProof	object

Nested Messages

taprpc.AnchorInfo

Field	gRPC Type	REST Type
anchor_tx The transaction that anchors the Taproot Asset commitment where the asset resides.	bytes	string
anchor_block_hash The block hash the contains the anchor transaction above.	string	string
anchor_outpoint The outpoint (txid:vout) that stores the Taproot Asset commitment.	string	string
internal_key The raw internal key that was used to create the anchor Taproot output key.	bytes	string
merkle_root The Taproot merkle root hash of the anchor output the asset was committed to. If there is no Tapscript sibling, this is equal to the Taproot Asset root commitment hash.	bytes	string
tapscript_sibling The serialized preimage of a Tapscript sibling, if there was one. If this is empty, then the merkle_root hash is equal to the Taproot root hash of the anchor output.	bytes	string
block_height The height of the block which contains the anchor transaction.	uint32	integer

taprpc.Asset

Field	gRPC Type	REST Type
version The version of the Taproot Asset.	AssetVersion	string
asset_genesis The base genesis information of an asset. This information never changes.	GenesisInfo	object
amount The total amount of the asset stored in this Taproot Asset UTXO.	uint64	string
lock_time An optional locktime, as with Bitcoin transactions.	int32	integer
relative_lock_time An optional relative lock time, same as Bitcoin transactions.	int32	integer
script_version The version of the script, only version 0 is defined at present.	int32	integer
script_key The script key of the asset, which can be spent under Taproot semantics.	bytes	string
script_key_is_local Indicates whether the script key is known to the wallet of the lnd node connected to the Taproot Asset daemon.	bool	boolean
asset_group The information related to the key group of an asset (if it exists).	AssetGroup	object
chain_anchor Describes where in the chain the asset is currently anchored.	AnchorInfo	object
prev_witnesses	PrevWitness[]	array
is_spent Indicates whether the asset has been spent.	bool	boolean
lease_owner If the asset has been leased, this is the owner (application ID) of the lease.	bytes	string
lease_expiry If the asset has been leased, this is the expiry of the lease as a Unix timestamp in seconds.	int64	string
is_burn Indicates whether this transfer was an asset burn. If true, the number of assets in this output are destroyed and can no longer be spent.	bool	boolean

taprpc.AssetGroup

Field	gRPC Type	REST Type
raw_group_key The raw group key which is a normal public key.	bytes	string
tweaked_group_key The tweaked group key, which is derived based on the genesis point and also asset type.	bytes	string
asset_witness A witness that authorizes a specific asset to be part of the asset group specified by the above key.	bytes	string

taprpc.AssetMeta

Field	gRPC Type	REST Type
data The raw data of the asset meta data. Based on the type below, this may be structured data such as a text file or PDF. The size of the data is limited to 1MiB.	bytes	string
type The type of the asset meta data.	AssetMetaType	string
meta_hash The hash of the meta. This is the hash of the TLV serialization of the meta itself.	bytes	string

taprpc.AssetTransfer

Field	gRPC Type	REST Type
transfer_timestamp	int64	string
anchor_tx_hash The new transaction that commits to the set of Taproot Assets found at the above new anchor point.	bytes	string
anchor_tx_height_hint	uint32	integer
anchor_tx_chain_fees	int64	string
inputs Describes the set of spent assets.	TransferInput[]	array
outputs Describes the set of newly created asset outputs.	TransferOutput[]	array

taprpc.DecodedProof

Field	gRPC Type	REST Type
proof_at_depth The index depth of the decoded proof, with 0 being the latest proof.	uint32	integer
number_of_proofs The total number of proofs contained in the decoded proof file (this will always be 1 if a single mint/transition proof was given as the raw_proof instead of a file).	uint32	integer
asset The asset referenced in the proof.	Asset	object
meta_reveal The reveal meta data associated with the proof, if available.	AssetMeta	object
tx_merkle_proof The merkle proof for AnchorTx used to prove its inclusion within BlockHeader.	bytes	string
inclusion_proof The TaprootProof proving the new inclusion of the resulting asset within AnchorTx.	bytes	string
exclusion_proofs The set of TaprootProofs proving the exclusion of the resulting asset from all other Taproot outputs within AnchorTx.	bytes[]	array
split_root_proof An optional TaprootProof needed if this asset is the result of a split. SplitRootProof proves inclusion of the root asset of the split.	bytes	string
num_additional_inputs The number of additional nested full proofs for any inputs found within the resulting asset.	uint32	integer
challenge_witness ChallengeWitness is an optional virtual transaction witness that serves as an ownership proof for the asset. If this is non-nil, then it is a valid transfer witness for a 1-input, 1-output virtual transaction that spends the asset in this proof and sends it to the NUMS key, to prove that the creator of the proof is able to produce a valid signature to spend the asset.	bytes[]	array
is_burn Indicates whether the state transition this proof represents is a burn, meaning that the assets were provably destroyed and can no longer be spent.	bool	boolean
genesis_reveal GenesisReveal is an optional field that is the Genesis information for the asset. This is required for minting proofs.	GenesisReveal	object
group_key_reveal GroupKeyReveal is an optional field that includes the information needed to derive the tweaked group key.	GroupKeyReveal	object

taprpc.GenesisInfo

Field	gRPC Type	REST Type
genesis_point The first outpoint of the transaction that created the asset (txid:vout).	string	string
name The name of the asset.	string	string
meta_hash The hash of the meta data for this genesis asset.	bytes	string
asset_id The asset ID that uniquely identifies the asset.	bytes	string
asset_type The type of the asset.	AssetType	string
output_index The index of the output that carries the unique Taproot Asset commitment in the genesis transaction.	uint32	integer

taprpc.GenesisReveal

Field	gRPC Type	REST Type
genesis_base_reveal The base genesis information in the genesis reveal.	GenesisInfo	object

taprpc.GroupKeyReveal

Field	gRPC Type	REST Type
raw_group_key The raw group key which is a normal public key.	bytes	string
tapscript_root The tapscript root included in the tweaked group key, which may be empty.	bytes	string

taprpc.PrevInputAsset

Field	gRPC Type	REST Type
anchor_point	string	string
asset_id	bytes	string
script_key	bytes	string
amount	uint64	string

taprpc.PrevWitness

Field	gRPC Type	REST Type
prev_id	PrevInputAsset	object
tx_witness	bytes[]	array
split_commitment	SplitCommitment	object

taprpc.SplitCommitment

Field	gRPC Type	REST Type
root_asset	Asset	object

taprpc.TransferInput

Field	gRPC Type	REST Type
anchor_point The old/current location of the Taproot Asset commitment that was spent as an input.	string	string
asset_id The ID of the asset that was spent.	bytes	string
script_key The script key of the asset that was spent.	bytes	string
amount The amount of the asset that was spent.	uint64	string

taprpc.TransferOutput

Field	gRPC Type	REST Type
anchor	TransferOutputAnchor	object
script_key	bytes	string
script_key_is_local	bool	boolean
amount	uint64	string
new_proof_blob The new individual transition proof (not a full proof file) that proves the inclusion of the new asset within the new AnchorTx.	bytes	string
split_commit_root_hash	bytes	string
output_type	OutputType	string
asset_version	AssetVersion	string

taprpc.TransferOutputAnchor

Field	gRPC Type	REST Type
outpoint The new location of the Taproot Asset commitment that was created on chain.	string	string
value	int64	string
internal_key	bytes	string
taproot_asset_root	bytes	string
merkle_root	bytes	string
tapscript_sibling	bytes	string
num_passive_assets	uint32	integer

Enums

taprpc.AssetMetaType

Name	Number
META_TYPE_OPAQUE Opaque is used for asset meta blobs that have no true structure and instead should be interpreted as opaque blobs.	0
META_TYPE_JSON JSON is used for asset meta blobs that are to be interpreted as valid JSON strings.	1

taprpc.AssetType

Name	Number
NORMAL Indicates that an asset is capable of being split/merged, with each of the units being fungible, even across a key asset ID boundary (assuming the key group is the same).	0
COLLECTIBLE Indicates that an asset is a collectible, meaning that each of the other items under the same key group are not fully fungible with each other. Collectibles also cannot be split or merged.	1

taprpc.AssetVersion

Name	Number
ASSET_VERSION_V0 ASSET_VERSION_V0 is the default asset version. This version will include the witness vector in the leaf for a tap commitment.	0
ASSET_VERSION_V1 ASSET_VERSION_V1 is the asset version that leaves out the witness vector from the MS-SMT leaf encoding.	1

taprpc.OutputType

Name	Number
OUTPUT_TYPE_SIMPLE OUTPUT_TYPE_SIMPLE is a plain full-value or split output that is not a split root and does not carry passive assets. In case of a split, the asset of this output has a split commitment.	0
OUTPUT_TYPE_SPLIT_ROOT OUTPUT_TYPE_SPLIT_ROOT is a split root output that carries the change from a split or a tombstone from a non-interactive full value send output. In either case, the asset of this output has a tx witness.	1