AssetLeaves

AssetLeaves queries for the set of asset leaves (the values in the Universe MS-SMT tree) for a given asset_id or group_key. These represents either asset issuance events (they have a genesis witness) or asset transfers that took place on chain. The leaves contain a normal Taproot Asset proof, as well as details for the asset.

Source: universerpc/universe.proto

gRPC

rpc AssetLeaves (ID) returns (AssetLeafResponse);

REST

HTTP Method	Path
GET	/v1/taproot-assets/universe/leaves/asset-id/{asset_id_str}

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('universerpc/universe.proto', loaderOptions);
const universerpc = grpc.loadPackageDefinition(packageDefinition).universerpc;
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 universerpc.Universe(GRPC_HOST, creds);
let request = {
  asset_id: <bytes>,
  asset_id_str: <string>,
  group_key: <bytes>,
  group_key_str: <string>,
  proof_type: <ProofType>,
};
client.assetLeaves(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "leaves": <AssetLeaf>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the universerpc/universe.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import universe_pb2 as universerpc, universe_pb2_grpc as universestub

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 = universestub.UniverseStub(channel)
request = universerpc.ID(
  asset_id=<bytes>,
  asset_id_str=<string>,
  group_key=<bytes>,
  group_key_str=<string>,
  proof_type=<ProofType>,
)
response = stub.AssetLeaves(request)
print(response)
# {
#    "leaves": <AssetLeaf>,
# }

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 options = {
  url: `https://${REST_HOST}/v1/taproot-assets/universe/leaves/asset-id/{asset_id_str}`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
}
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "leaves": <array>, // <AssetLeaf> 
//  }

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/universe/leaves/asset-id/{asset_id_str}'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
r = requests.get(url, headers=headers, verify=TLS_PATH)
print(r.json())
# {
#    "leaves": <AssetLeaf>,
# }

Shell

$ tapcli universe leaves --help

NAME:
   tapcli universe leaves - return the known set of leaves in a Universe

USAGE:
   tapcli universe leaves [command options] [arguments...]

DESCRIPTION:
   
  Query for the set of known leaves for a given asset universe. A leaf in a
  universe is an entry that denotes either a new issuance event (asset
  minting) or an asset transfer. A leaf includes the asset under action, a
  state transition proof for that asset.

OPTIONS:
   --asset_id value    the asset ID of the universe to query for
   --group_key value   the group key of the universe to query for
   --proof_type value  the type of proof to show the leaves for, either 'issuance' or 'transfer' (default: "issuance")
   

Messages

universerpc.ID

Source: universerpc/universe.proto

Field	gRPC Type	REST Type	REST Placement
asset_id The 32-byte asset ID specified as raw bytes (gRPC only).	bytes	string	query
asset_id_str The 32-byte asset ID encoded as a hex string (use this for REST).	string	string	path
group_key The 32-byte asset group key specified as raw bytes (gRPC only).	bytes	string	query
group_key_str The 32-byte asset group key encoded as hex string (use this for REST).	string	string	query
proof_type Nested REST Parameters proof_type: string in query	ProofType	string	query

universerpc.AssetLeafResponse

Source: universerpc/universe.proto

Field	gRPC Type	REST Type
leaves The set of asset leaves for the given asset ID or group key.	AssetLeaf[]	array

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
script_key_declared_known Indicates whether this script key has either been derived by the local wallet or was explicitly declared to be known by using the DeclareScriptKey RPC. Knowing the key conceptually means the key belongs to the local wallet or is at least known by a software that operates on the local wallet. The flag is never serialized in proofs, so this is never explicitly set for keys foreign to the local wallet. Therefore, if this method returns true for a script key, it means the asset with the script key will be shown in the wallet balance.	bool	boolean
script_key_has_script_path Indicates whether the script key is known to have a Tapscript spend path, meaning that the Taproot merkle root tweak is not empty. This will only ever be true if either script_key_is_local or script_key_internals_known is true as well, since the presence of a Tapscript spend path cannot be determined for script keys that aren't known to the wallet of the local tapd node.	bool	boolean
decimal_display This field defines a decimal display value that may be present. If this field is null, it means the presence of a decimal display field is unknown in the current context.	DecimalDisplay	object

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
tapscript_root The root hash of a tapscript tree, which enables future issuance authorized with a script witness.	bytes	string

taprpc.DecimalDisplay

Field	gRPC Type	REST Type
decimal_display Decimal display dictates the number of decimal places to shift the amount to the left converting from Taproot Asset integer representation to a UX-recognizable fractional quantity. For example, if the decimal_display value is 2 and there's 100 of those assets, then a wallet would display the amount as "1.00". This field is intended as information for wallets that display balances and has no impact on the behavior of the daemon or any other part of the protocol. This value is encoded in the MetaData field as a JSON field, therefore it is only compatible with assets that have a JSON MetaData field.	uint32	integer

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.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

universerpc.AssetLeaf

Field	gRPC Type	REST Type
asset The asset included in the leaf.	Asset	object
proof The asset issuance or transfer proof, which proves that the asset specified above was issued or transferred properly. This is always just an individual mint/transfer proof and never a proof file.	bytes	string

Enums

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

universerpc.ProofType

Name	Number
PROOF_TYPE_UNSPECIFIED	0
PROOF_TYPE_ISSUANCE	1
PROOF_TYPE_TRANSFER	2