FetchSupplyCommit

FetchSupplyCommit fetches the on-chain supply commitment for a specific asset group.

Source: universerpc/universe.proto

gRPC

rpc FetchSupplyCommit (FetchSupplyCommitRequest) returns (FetchSupplyCommitResponse);

REST

HTTP Method	Path
GET	/v1/taproot-assets/universe/supply/{group_key_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 = {
  group_key_bytes: <bytes>,
  group_key_str: <string>,
  issuance_leaf_keys: <bytes>,
  burn_leaf_keys: <bytes>,
  ignore_leaf_keys: <bytes>,
};
client.fetchSupplyCommit(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "supply_commitment_root": <MerkleSumNode>,
//    "anchor_txid": <string>,
//    "anchor_tx_out_idx": <uint32>,
//    "anchor_tx_out_internal_key": <bytes>,
//    "block_height": <uint32>,
//    "block_hash": <bytes>,
//    "block_tx_index": <uint32>,
//    "tx_chain_fees_sats": <int64>,
//    "issuance_subtree_root": <SupplyCommitSubtreeRoot>,
//    "burn_subtree_root": <SupplyCommitSubtreeRoot>,
//    "ignore_subtree_root": <SupplyCommitSubtreeRoot>,
//    "issuance_leaf_inclusion_proofs": <bytes>,
//    "burn_leaf_inclusion_proofs": <bytes>,
//    "ignore_leaf_inclusion_proofs": <bytes>,
//  }

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.FetchSupplyCommitRequest(
  group_key_bytes=<bytes>,
  group_key_str=<string>,
  issuance_leaf_keys=<bytes>,
  burn_leaf_keys=<bytes>,
  ignore_leaf_keys=<bytes>,
)
response = stub.FetchSupplyCommit(request)
print(response)
# {
#    "supply_commitment_root": <MerkleSumNode>,
#    "anchor_txid": <string>,
#    "anchor_tx_out_idx": <uint32>,
#    "anchor_tx_out_internal_key": <bytes>,
#    "block_height": <uint32>,
#    "block_hash": <bytes>,
#    "block_tx_index": <uint32>,
#    "tx_chain_fees_sats": <int64>,
#    "issuance_subtree_root": <SupplyCommitSubtreeRoot>,
#    "burn_subtree_root": <SupplyCommitSubtreeRoot>,
#    "ignore_subtree_root": <SupplyCommitSubtreeRoot>,
#    "issuance_leaf_inclusion_proofs": <bytes>,
#    "burn_leaf_inclusion_proofs": <bytes>,
#    "ignore_leaf_inclusion_proofs": <bytes>,
# }

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/supply/{group_key_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:
//  {
//    "supply_commitment_root": <object>, // <MerkleSumNode> 
//    "anchor_txid": <string>, // <string> 
//    "anchor_tx_out_idx": <integer>, // <uint32> 
//    "anchor_tx_out_internal_key": <string>, // <bytes> 
//    "block_height": <integer>, // <uint32> 
//    "block_hash": <string>, // <bytes> 
//    "block_tx_index": <integer>, // <uint32> 
//    "tx_chain_fees_sats": <string>, // <int64> 
//    "issuance_subtree_root": <object>, // <SupplyCommitSubtreeRoot> 
//    "burn_subtree_root": <object>, // <SupplyCommitSubtreeRoot> 
//    "ignore_subtree_root": <object>, // <SupplyCommitSubtreeRoot> 
//    "issuance_leaf_inclusion_proofs": <array>, // <bytes> 
//    "burn_leaf_inclusion_proofs": <array>, // <bytes> 
//    "ignore_leaf_inclusion_proofs": <array>, // <bytes> 
//  }

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/supply/{group_key_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())
# {
#    "supply_commitment_root": <MerkleSumNode>,
#    "anchor_txid": <string>,
#    "anchor_tx_out_idx": <uint32>,
#    "anchor_tx_out_internal_key": <bytes>,
#    "block_height": <uint32>,
#    "block_hash": <bytes>,
#    "block_tx_index": <uint32>,
#    "tx_chain_fees_sats": <int64>,
#    "issuance_subtree_root": <SupplyCommitSubtreeRoot>,
#    "burn_subtree_root": <SupplyCommitSubtreeRoot>,
#    "ignore_subtree_root": <SupplyCommitSubtreeRoot>,
#    "issuance_leaf_inclusion_proofs": <bytes>,
#    "burn_leaf_inclusion_proofs": <bytes>,
#    "ignore_leaf_inclusion_proofs": <bytes>,
# }

Shell

# There is no CLI command for this RPC

Messages

universerpc.FetchSupplyCommitRequest

Source: universerpc/universe.proto

Field	gRPC Type	REST Type	REST Placement
group_key_bytes 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	path
issuance_leaf_keys Optional: A list of issuance leaf keys. For each key in this list, the endpoint will generate and return an inclusion proof.	bytes[]	array	query
burn_leaf_keys Optional: A list of burn leaf keys. For each key in this list, the endpoint will generate and return an inclusion proof.	bytes[]	array	query
ignore_leaf_keys Optional: A list of ignore leaf keys. For each key in this list, the endpoint will generate and return an inclusion proof.	bytes[]	array	query

universerpc.FetchSupplyCommitResponse

Source: universerpc/universe.proto

Field	gRPC Type	REST Type
supply_commitment_root The supply commitment merkle sum root node for the specified asset.	MerkleSumNode	object
anchor_txid The txid of the anchor transaction that commits to the supply commitment for the specified asset.	string	string
anchor_tx_out_idx The output index of the anchor transaction that commits to the supply commitment for the specified asset.	uint32	integer
anchor_tx_out_internal_key The transaction output taproot internal key of the anchor transaction that commits to the supply commitment for the specified asset.	bytes	string
block_height The height of the block at which the supply commitment was anchored.	uint32	integer
block_hash The hash of the block at which the supply commitment was anchored.	bytes	string
block_tx_index The index of the transaction in the block that commits to the supply commitment.	uint32	integer
tx_chain_fees_sats The total number of satoshis in on-chain fees paid by the supply commitment transaction.	int64	string
issuance_subtree_root The root of the issuance tree for the specified asset.	SupplyCommitSubtreeRoot	object
burn_subtree_root The root of the burn tree for the specified asset.	SupplyCommitSubtreeRoot	object
ignore_subtree_root The root of the ignore tree for the specified asset.	SupplyCommitSubtreeRoot	object
issuance_leaf_inclusion_proofs Inclusion proofs for each issuance leaf key provided in the request. Each entry corresponds to the key at the same index in `issuance_leaf_keys`.	bytes[]	array
burn_leaf_inclusion_proofs Inclusion proofs for each burn leaf key provided in the request. Each entry corresponds to the key at the same index in `burn_leaf_keys`.	bytes[]	array
ignore_leaf_inclusion_proofs Inclusion proofs for each ignored leaf key provided in the request. Each entry corresponds to the key at the same index in `ignore_leaf_keys`.	bytes[]	array

Nested Messages

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

Field	gRPC Type	REST Type
type The type of the supply commit subtree.	string	string
root_node The root node of the supply commit subtree.	MerkleSumNode	object
supply_tree_leaf_key The leaf key which locates the subtree leaf node in the supply commit tree.	bytes	string
supply_tree_inclusion_proof The inclusion proof for the supply commit subtree root node.	bytes	string