AssetLeafKeys

AssetLeafKeys queries for the set of Universe keys associated with a given asset_id or group_key. Each key takes the form: (outpoint, script_key), where outpoint is an outpoint in the Bitcoin blockchain that anchors a valid Taproot Asset commitment, and script_key is the script_key of the asset within the Taproot Asset commitment for the given asset_id or group_key.

Source: universerpc/universe.proto

gRPC

rpc AssetLeafKeys (AssetLeafKeysRequest) returns (AssetLeafKeyResponse);

REST

HTTP Method	Path
GET	/v1/taproot-assets/universe/keys/asset-id/{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 = {
  id: <ID>,
  offset: <int32>,
  limit: <int32>,
  direction: <SortDirection>,
};
client.assetLeafKeys(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "asset_keys": <AssetKey>,
//  }

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.AssetLeafKeysRequest(
  id=<ID>,
  offset=<int32>,
  limit=<int32>,
  direction=<SortDirection>,
)
response = stub.AssetLeafKeys(request)
print(response)
# {
#    "asset_keys": <AssetKey>,
# }

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/keys/asset-id/{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:
//  {
//    "asset_keys": <array>, // <AssetKey> 
//  }

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/keys/asset-id/{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())
# {
#    "asset_keys": <AssetKey>,
# }

Shell

$ tapcli universe keys --help

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

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

DESCRIPTION:
   
  Query for the set of known keys for a given asset universe. Keys take the
  form: (outpoint, script_key), where outpoint is the outpoint that anchors
  and asset, and script_key is the key for that asset within an asset_id
  tree.
  

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 keys for, either 'issuance' or 'transfer' (default: "issuance")
   

Messages

universerpc.AssetLeafKeysRequest

Source: universerpc/universe.proto

Field	gRPC Type	REST Type	REST Placement
id The ID of the asset to query for. Nested REST Parameters id.group_key: string in query id.group_key_str: string in query id.proof_type: string in query id.asset_id_str: string in path id.asset_id: string in query	ID	object	mixed
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.AssetLeafKeyResponse

Source: universerpc/universe.proto

Field	gRPC Type	REST Type
asset_keys The set of asset leaf keys for the given asset ID or group key.	AssetKey[]	array

Nested Messages

universerpc.AssetKey

Field	gRPC Type	REST Type
op_str	string	string
op	Outpoint	object
script_key_bytes	bytes	string
script_key_str	string	string

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

Field	gRPC Type	REST Type
hash_str The output as a hex encoded (and reversed!) string.	string	string
index The index of the output.	int32	integer

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