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>,
  commit_outpoint: <OutPoint>,
  spent_commit_outpoint: <OutPoint>,
  very_first: <bool>,
};
client.fetchSupplyCommit(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "chain_data": <SupplyCommitChainData>,
//    "tx_chain_fees_sats": <int64>,
//    "issuance_subtree_root": <SupplyCommitSubtreeRoot>,
//    "burn_subtree_root": <SupplyCommitSubtreeRoot>,
//    "ignore_subtree_root": <SupplyCommitSubtreeRoot>,
//    "issuance_leaves": <SupplyLeafEntry>,
//    "burn_leaves": <SupplyLeafEntry>,
//    "ignore_leaves": <SupplyLeafEntry>,
//    "total_outstanding_supply": <uint64>,
//    "spent_commitment_outpoint": <OutPoint>,
//  }

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>,
  commit_outpoint=<OutPoint>,
  spent_commit_outpoint=<OutPoint>,
  very_first=<bool>,
)
response = stub.FetchSupplyCommit(request)
print(response)
# {
#    "chain_data": <SupplyCommitChainData>,
#    "tx_chain_fees_sats": <int64>,
#    "issuance_subtree_root": <SupplyCommitSubtreeRoot>,
#    "burn_subtree_root": <SupplyCommitSubtreeRoot>,
#    "ignore_subtree_root": <SupplyCommitSubtreeRoot>,
#    "issuance_leaves": <SupplyLeafEntry>,
#    "burn_leaves": <SupplyLeafEntry>,
#    "ignore_leaves": <SupplyLeafEntry>,
#    "total_outstanding_supply": <uint64>,
#    "spent_commitment_outpoint": <OutPoint>,
# }

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:
//  {
//    "chain_data": <object>, // <SupplyCommitChainData> 
//    "tx_chain_fees_sats": <string>, // <int64> 
//    "issuance_subtree_root": <object>, // <SupplyCommitSubtreeRoot> 
//    "burn_subtree_root": <object>, // <SupplyCommitSubtreeRoot> 
//    "ignore_subtree_root": <object>, // <SupplyCommitSubtreeRoot> 
//    "issuance_leaves": <array>, // <SupplyLeafEntry> 
//    "burn_leaves": <array>, // <SupplyLeafEntry> 
//    "ignore_leaves": <array>, // <SupplyLeafEntry> 
//    "total_outstanding_supply": <string>, // <uint64> 
//    "spent_commitment_outpoint": <object>, // <OutPoint> 
//  }

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())
# {
#    "chain_data": <SupplyCommitChainData>,
#    "tx_chain_fees_sats": <int64>,
#    "issuance_subtree_root": <SupplyCommitSubtreeRoot>,
#    "burn_subtree_root": <SupplyCommitSubtreeRoot>,
#    "ignore_subtree_root": <SupplyCommitSubtreeRoot>,
#    "issuance_leaves": <SupplyLeafEntry>,
#    "burn_leaves": <SupplyLeafEntry>,
#    "ignore_leaves": <SupplyLeafEntry>,
#    "total_outstanding_supply": <uint64>,
#    "spent_commitment_outpoint": <OutPoint>,
# }

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
commit_outpoint Fetch the the supply commitment that created this new commitment output on chain. Nested REST Parameters commit_outpoint.txid: string in query commit_outpoint.output_index: integer in query	OutPoint	object	query
spent_commit_outpoint Fetch the supply commitment that spent the specified commitment output on chain to create a new supply commitment. This can be used to traverse the chain of supply commitments by watching the spend of the commitment output. Nested REST Parameters spent_commit_outpoint.txid: string in query spent_commit_outpoint.output_index: integer in query	OutPoint	object	query
very_first Fetch the very first supply commitment for the asset group. This returns the initial supply commitment that spent the pre-commitment output of the very first asset mint of a grouped asset (also known as the group anchor). This is useful as the starting point to fetch all supply commitments for a grouped asset one by one.	bool	boolean	query

universerpc.FetchSupplyCommitResponse

Source: universerpc/universe.proto

Field	gRPC Type	REST Type
chain_data The supply commitment chain data that contains both the commitment and chain proof information.	SupplyCommitChainData	object
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_leaves The issuance leaves that were added by this supply commitment. Does not include leaves that were already present in the issuance subtree before the block height at which this supply commitment was anchored.	SupplyLeafEntry[]	array
burn_leaves The burn leaves that were added by this supply commitment. Does not include leaves that were already present in the burn subtree before the block height at which this supply commitment was anchored.	SupplyLeafEntry[]	array
ignore_leaves The ignore leaves that were added by this supply commitment. Does not include leaves that were already present in the ignore subtree before the block height at which this supply commitment was anchored.	SupplyLeafEntry[]	array
total_outstanding_supply The total outstanding supply of the asset after applying all the supply changes (issuance, burn, ignore) included in this supply commitment.	uint64	string
spent_commitment_outpoint The outpoint of the previous commitment that this new commitment is spending. This must be set unless this is the very first supply commitment of a grouped asset.	OutPoint	object

Nested Messages

taprpc.OutPoint

Field	gRPC Type	REST Type
txid Raw bytes representing the transaction id.	bytes	string
output_index The index of the output on the transaction.	uint32	integer

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

universerpc.SupplyCommitChainData

Field	gRPC Type	REST Type
txn The raw transaction that created the root commitment.	bytes	string
tx_out_idx The index of the output in the transaction where the commitment resides.	uint32	integer
internal_key The internal key used to create the commitment output.	bytes	string
output_key The taproot output key used to create the commitment output.	bytes	string
supply_root_hash The root hash of the supply tree that contains the set of sub-commitments. The sum value of this tree is the outstanding supply value.	bytes	string
supply_root_sum The sum value of the supply root tree, representing the outstanding supply amount.	uint64	string
block_header The block header of the block that contains the supply commitment transaction.	bytes	string
block_hash The hash of the block that contains the commitment.	bytes	string
block_height The block height of the block that contains the supply commitment transaction.	uint32	integer
tx_block_merkle_proof The merkle proof that proves that the supply commitment transaction is included in the block.	bytes	string
tx_index The index of the supply commitment transaction in the block.	uint32	integer

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

universerpc.SupplyLeafEntry

Field	gRPC Type	REST Type
leaf_key The key that identifies the supply leaf in the supply commitment subtree.	SupplyLeafKey	object
leaf_node The merkle sum node representing the supply leaf in the supply commitment subtree.	MerkleSumNode	object
block_height The block height at which the supply leaf was created.	uint32	integer
raw_leaf The raw serialized bytes of the supply leaf.	bytes	string

universerpc.SupplyLeafKey

Field	gRPC Type	REST Type
outpoint The outpoint associated with the supply leaf.	Outpoint	object
script_key The script key of the supply leaf. This is the script key of the asset point.	bytes	string
asset_id The asset ID associated with the supply leaf. This is only set for ignore type supply leaves.	bytes	string