AssetRoots

AssetRoots queries for the known Universe roots associated with each known asset. These roots represent the supply/audit state for each known asset.

Source: universerpc/universe.proto

gRPC

rpc AssetRoots (AssetRootRequest) returns (AssetRootResponse);

REST

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

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 = {
  with_amounts_by_id: <bool>,
  offset: <int32>,
  limit: <int32>,
  direction: <SortDirection>,
};
client.assetRoots(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "universe_roots": <UniverseRootsEntry>,
//  }

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.AssetRootRequest(
  with_amounts_by_id=<bool>,
  offset=<int32>,
  limit=<int32>,
  direction=<SortDirection>,
)
response = stub.AssetRoots(request)
print(response)
# {
#    "universe_roots": <UniverseRootsEntry>,
# }

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/roots`,
  // 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:
//  {
//    "universe_roots": <object>, // <UniverseRootsEntry> 
//  }

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/roots'
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())
# {
#    "universe_roots": <UniverseRootsEntry>,
# }

Shell

$ tapcli universe roots --help

NAME:
   tapcli universe roots - list the known asset universe roots

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

DESCRIPTION:
   Query for the set of known asset universe roots

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 roots for, either 'issuance' or 'transfer' (default: "issuance")
   --skip_amounts_by_id  skip showing the amounts by ID for grouped assets to optimize response size and speed
   

Messages

universerpc.AssetRootRequest

Source: universerpc/universe.proto

Field	gRPC Type	REST Type	REST Placement
with_amounts_by_id If true, then the response will include the amounts for each asset ID of grouped assets.	bool	boolean	query
offset The offset for the page.	int32	integer	query
limit The length limit for the page.	int32	integer	query
direction The direction of the page. Nested REST Parameters direction: string in query	SortDirection	object	query

universerpc.AssetRootResponse

Source: universerpc/universe.proto

Field	gRPC Type	REST Type
universe_roots A map of the set of known universe roots for each asset. The key in the map is the 32-byte asset_id or group key hash.	UniverseRootsEntry[]	object

Nested Messages

universerpc.AssetRootResponse.UniverseRootsEntry

Field	gRPC Type	REST Type
key	string	unknown
value	UniverseRoot	unknown

universerpc.ID

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

universerpc.MerkleSumNode

Field	gRPC Type	REST Type
root_hash The MS-SMT root hash for the branch node.	bytes	string
root_sum The root sum of the branch node. This is hashed to create the root_hash along with the left and right siblings. This value represents the total known supply of the asset.	int64	string

universerpc.UniverseRoot

Field	gRPC Type	REST Type
id	ID	object
mssmt_root The merkle sum sparse merkle tree root associated with the above universe ID.	MerkleSumNode	object
asset_name The name of the asset.	string	string
amounts_by_asset_id A map of hex encoded asset IDs to the number of units minted for that asset. This only contains more than one entry for grouped assets and in that case represents the whole list of assets currently known to exist within the group. For single (non-grouped) assets, this is equal to the asset ID above and the sum in the mssmt_root. A hex encoded string is used as the map key because gRPC does not support using raw bytes for a map key.	AmountsByAssetIdEntry[]	object

universerpc.UniverseRoot.AmountsByAssetIdEntry

Field	gRPC Type	REST Type
key	string	unknown
value	uint64	unknown

Enums

universerpc.ProofType

Name	Number
PROOF_TYPE_UNSPECIFIED	0
PROOF_TYPE_ISSUANCE	1
PROOF_TYPE_TRANSFER	2

universerpc.SortDirection

Name	Number
SORT_DIRECTION_ASC	0
SORT_DIRECTION_DESC	1