QueryAssetStats

tapcli universe stats assets QueryAssetStats returns a set of statistics for a given set of assets. Stats can be queried for all assets, or based on the: asset ID, name, or asset type. Pagination is supported via the offset and limit params. Results can also be sorted based on any of the main query params.

Source: universerpc/universe.proto

gRPC

rpc QueryAssetStats (AssetStatsQuery) returns (UniverseAssetStats);

REST

HTTP Method	Path
GET	/v1/taproot-assets/universe/stats/assets

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_name_filter: <string>,
  asset_id_filter: <bytes>,
  asset_type_filter: <AssetTypeFilter>,
  sort_by: <AssetQuerySort>,
  offset: <int32>,
  limit: <int32>,
  direction: <SortDirection>,
};
client.queryAssetStats(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "asset_stats": <AssetStatsSnapshot>,
//  }

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.AssetStatsQuery(
  asset_name_filter=<string>,
  asset_id_filter=<bytes>,
  asset_type_filter=<AssetTypeFilter>,
  sort_by=<AssetQuerySort>,
  offset=<int32>,
  limit=<int32>,
  direction=<SortDirection>,
)
response = stub.QueryAssetStats(request)
print(response)
# {
#    "asset_stats": <AssetStatsSnapshot>,
# }

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/stats/assets`,
  // 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:
//  {
//    "asset_stats": <array>, // <AssetStatsSnapshot> 
//  }

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/stats/assets'
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())
# {
#    "asset_stats": <AssetStatsSnapshot>,
# }

Shell

# There is no CLI command for this RPC

Messages

universerpc.AssetStatsQuery

Source: universerpc/universe.proto

Field	gRPC Type	REST Type	REST Placement
asset_name_filter	string	string	query
asset_id_filter	bytes	string	query
asset_type_filter Nested REST Parameters asset_type_filter: string in query	AssetTypeFilter	object	query
sort_by Nested REST Parameters sort_by: string in query	AssetQuerySort	object	query
offset	int32	integer	query
limit	int32	integer	query
direction Nested REST Parameters direction: string in query	SortDirection	object	query

universerpc.UniverseAssetStats

Source: universerpc/universe.proto

Field	gRPC Type	REST Type
asset_stats	AssetStatsSnapshot[]	array

Nested Messages

universerpc.AssetStatsAsset

Field	gRPC Type	REST Type
asset_id	bytes	string
genesis_point	string	string
total_supply	int64	string
asset_name	string	string
asset_type	AssetType	string
genesis_height	int32	integer
genesis_timestamp	int64	string
anchor_point	string	string

universerpc.AssetStatsSnapshot

Field	gRPC Type	REST Type
group_key The group key of the asset group. If this is empty, then the asset is not part of a group.	bytes	string
group_supply The total supply of the asset group. If the asset is not part of an asset group then this is always zero.	int64	string
group_anchor The group anchor that was used to group assets together into an asset group. This is only set if the asset is part of an asset group.	AssetStatsAsset	object
asset If the asset is not part of an asset group, then this is the asset the stats below refer to.	AssetStatsAsset	object
total_syncs The total number of syncs either for the asset group or the single asset if it is not part of a group.	int64	string
total_proofs The total number of proofs either for the asset group or the single asset if it is not part of a group.	int64	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

universerpc.AssetQuerySort

Name	Number
SORT_BY_NONE	0
SORT_BY_ASSET_NAME	1
SORT_BY_ASSET_ID	2
SORT_BY_ASSET_TYPE	3
SORT_BY_TOTAL_SYNCS	4
SORT_BY_TOTAL_PROOFS	5
SORT_BY_GENESIS_HEIGHT	6
SORT_BY_TOTAL_SUPPLY	7

universerpc.AssetTypeFilter

Name	Number
FILTER_ASSET_NONE	0
FILTER_ASSET_NORMAL	1
FILTER_ASSET_COLLECTIBLE	2

universerpc.SortDirection

Name	Number
SORT_DIRECTION_ASC	0
SORT_DIRECTION_DESC	1