QueryProof

QueryProof attempts to query for an issuance or transfer proof for a given asset based on its UniverseKey. A UniverseKey is composed of the Universe ID (asset_id/group_key) and also a leaf key (outpoint || script_key). If found, then the issuance proof is returned that includes an inclusion proof to the known Universe root, as well as a Taproot Asset state transition or issuance proof for the said asset.

Source: universerpc/universe.proto

gRPC

rpc QueryProof (UniverseKey) returns (AssetProofResponse);

REST

HTTP Method	Path
GET	/v1/taproot-assets/universe/proofs/asset-id/{id.asset_id_str}/{leaf_key.op.hash_str}/{leaf_key.op.index}/{leaf_key.script_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 = {
  id: <ID>,
  leaf_key: <AssetKey>,
};
client.queryProof(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "req": <UniverseKey>,
//    "universe_root": <UniverseRoot>,
//    "universe_inclusion_proof": <bytes>,
//    "asset_leaf": <AssetLeaf>,
//    "multiverse_root": <MerkleSumNode>,
//    "multiverse_inclusion_proof": <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.UniverseKey(
  id=<ID>,
  leaf_key=<AssetKey>,
)
response = stub.QueryProof(request)
print(response)
# {
#    "req": <UniverseKey>,
#    "universe_root": <UniverseRoot>,
#    "universe_inclusion_proof": <bytes>,
#    "asset_leaf": <AssetLeaf>,
#    "multiverse_root": <MerkleSumNode>,
#    "multiverse_inclusion_proof": <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/proofs/asset-id/{id.asset_id_str}/{leaf_key.op.hash_str}/{leaf_key.op.index}/{leaf_key.script_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:
//  {
//    "req": <object>, // <UniverseKey> 
//    "universe_root": <object>, // <UniverseRoot> 
//    "universe_inclusion_proof": <string>, // <bytes> 
//    "asset_leaf": <object>, // <AssetLeaf> 
//    "multiverse_root": <object>, // <MerkleSumNode> 
//    "multiverse_inclusion_proof": <string>, // <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/proofs/asset-id/{id.asset_id_str}/{leaf_key.op.hash_str}/{leaf_key.op.index}/{leaf_key.script_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())
# {
#    "req": <UniverseKey>,
#    "universe_root": <UniverseRoot>,
#    "universe_inclusion_proof": <bytes>,
#    "asset_leaf": <AssetLeaf>,
#    "multiverse_root": <MerkleSumNode>,
#    "multiverse_inclusion_proof": <bytes>,
# }

Shell

$ tapcli universe proofs query --help

NAME:
   tapcli universe proofs query - query for a universe proof

USAGE:
   tapcli universe proofs query [command options] [arguments...]

DESCRIPTION:
   
  Attempt to query the target universe for a given proof based on a top
  level asset id or group key, and the leaf key of: outpoint || script key.
  

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
   --outpoint value    the target outpoint on chain to locate a tap proof within
   --script_key value  the script key (scoped to an assetID) to query a proof for
   --proof_type value  the type of proof to query for, either 'issuance' or 'transfer' (default: "issuance")
   

Messages

universerpc.UniverseKey

Source: universerpc/universe.proto

Field	gRPC Type	REST Type	REST Placement
id The ID of the asset to query for. Nested REST Parameters id.asset_id_str: string in path id.group_key: string in query id.group_key_str: string in query id.proof_type: string in query id.asset_id: string in query	ID	object	mixed
leaf_key The asset key to query for. Nested REST Parameters leaf_key.script_key_bytes: string in query leaf_key.script_key_str: string in path leaf_key.op_str: string in query leaf_key.op.hash_str: string in path leaf_key.op.index: integer in path	AssetKey	object	mixed

universerpc.AssetProofResponse

Source: universerpc/universe.proto

Field	gRPC Type	REST Type
req The original request for the issuance proof.	UniverseKey	object
universe_root The Universe root that includes this asset leaf.	UniverseRoot	object
universe_inclusion_proof An inclusion proof for the asset leaf included below. The value is that issuance proof itself, with a sum value of the amount of the asset.	bytes	string
asset_leaf The asset leaf itself, which includes the asset and the issuance proof.	AssetLeaf	object
multiverse_root MultiverseRoot is the root of the multiverse tree that includes this asset leaf.	MerkleSumNode	object
multiverse_inclusion_proof MultiverseInclusionProof is the inclusion proof for the asset leaf in the multiverse.	bytes	string

Nested Messages

taprpc.AnchorInfo

Field	gRPC Type	REST Type
anchor_tx The transaction that anchors the Taproot Asset commitment where the asset resides.	bytes	string
anchor_block_hash The block hash the contains the anchor transaction above.	string	string
anchor_outpoint The outpoint (txid:vout) that stores the Taproot Asset commitment.	string	string
internal_key The raw internal key that was used to create the anchor Taproot output key.	bytes	string
merkle_root The Taproot merkle root hash of the anchor output the asset was committed to. If there is no Tapscript sibling, this is equal to the Taproot Asset root commitment hash.	bytes	string
tapscript_sibling The serialized preimage of a Tapscript sibling, if there was one. If this is empty, then the merkle_root hash is equal to the Taproot root hash of the anchor output.	bytes	string
block_height The height of the block which contains the anchor transaction.	uint32	integer

taprpc.Asset

Field	gRPC Type	REST Type
version The version of the Taproot Asset.	AssetVersion	string
asset_genesis The base genesis information of an asset. This information never changes.	GenesisInfo	object
amount The total amount of the asset stored in this Taproot Asset UTXO.	uint64	string
lock_time An optional locktime, as with Bitcoin transactions.	int32	integer
relative_lock_time An optional relative lock time, same as Bitcoin transactions.	int32	integer
script_version The version of the script, only version 0 is defined at present.	int32	integer
script_key The script key of the asset, which can be spent under Taproot semantics.	bytes	string
script_key_is_local Indicates whether the script key is known to the wallet of the lnd node connected to the Taproot Asset daemon.	bool	boolean
asset_group The information related to the key group of an asset (if it exists).	AssetGroup	object
chain_anchor Describes where in the chain the asset is currently anchored.	AnchorInfo	object
prev_witnesses	PrevWitness[]	array
is_spent Indicates whether the asset has been spent.	bool	boolean
lease_owner If the asset has been leased, this is the owner (application ID) of the lease.	bytes	string
lease_expiry If the asset has been leased, this is the expiry of the lease as a Unix timestamp in seconds.	int64	string
is_burn Indicates whether this transfer was an asset burn. If true, the number of assets in this output are destroyed and can no longer be spent.	bool	boolean
script_key_declared_known Indicates whether this script key has either been derived by the local wallet or was explicitly declared to be known by using the DeclareScriptKey RPC. Knowing the key conceptually means the key belongs to the local wallet or is at least known by a software that operates on the local wallet. The flag is never serialized in proofs, so this is never explicitly set for keys foreign to the local wallet. Therefore, if this method returns true for a script key, it means the asset with the script key will be shown in the wallet balance.	bool	boolean
script_key_has_script_path Indicates whether the script key is known to have a Tapscript spend path, meaning that the Taproot merkle root tweak is not empty. This will only ever be true if either script_key_is_local or script_key_internals_known is true as well, since the presence of a Tapscript spend path cannot be determined for script keys that aren't known to the wallet of the local tapd node.	bool	boolean
decimal_display This field defines a decimal display value that may be present. If this field is null, it means the presence of a decimal display field is unknown in the current context.	DecimalDisplay	object

taprpc.AssetGroup

Field	gRPC Type	REST Type
raw_group_key The raw group key which is a normal public key.	bytes	string
tweaked_group_key The tweaked group key, which is derived based on the genesis point and also asset type.	bytes	string
asset_witness A witness that authorizes a specific asset to be part of the asset group specified by the above key.	bytes	string
tapscript_root The root hash of a tapscript tree, which enables future issuance authorized with a script witness.	bytes	string

taprpc.DecimalDisplay

Field	gRPC Type	REST Type
decimal_display Decimal display dictates the number of decimal places to shift the amount to the left converting from Taproot Asset integer representation to a UX-recognizable fractional quantity. For example, if the decimal_display value is 2 and there's 100 of those assets, then a wallet would display the amount as "1.00". This field is intended as information for wallets that display balances and has no impact on the behavior of the daemon or any other part of the protocol. This value is encoded in the MetaData field as a JSON field, therefore it is only compatible with assets that have a JSON MetaData field.	uint32	integer

taprpc.GenesisInfo

Field	gRPC Type	REST Type
genesis_point The first outpoint of the transaction that created the asset (txid:vout).	string	string
name The name of the asset.	string	string
meta_hash The hash of the meta data for this genesis asset.	bytes	string
asset_id The asset ID that uniquely identifies the asset.	bytes	string
asset_type The type of the asset.	AssetType	string
output_index The index of the output that carries the unique Taproot Asset commitment in the genesis transaction.	uint32	integer

taprpc.PrevInputAsset

Field	gRPC Type	REST Type
anchor_point	string	string
asset_id	bytes	string
script_key	bytes	string
amount	uint64	string

taprpc.PrevWitness

Field	gRPC Type	REST Type
prev_id	PrevInputAsset	object
tx_witness	bytes[]	array
split_commitment	SplitCommitment	object

taprpc.SplitCommitment

Field	gRPC Type	REST Type
root_asset	Asset	object

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

Field	gRPC Type	REST Type
asset The asset included in the leaf.	Asset	object
proof The asset issuance or transfer proof, which proves that the asset specified above was issued or transferred properly. This is always just an individual mint/transfer proof and never a proof file.	bytes	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 Nested REST Parameters proof_type: string in query	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.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.UniverseKey

Field	gRPC Type	REST Type
id The ID of the asset to query for. Nested REST Parameters id.asset_id_str: string in path id.group_key: string in query id.group_key_str: string in query id.proof_type: string in query id.asset_id: string in query	ID	object
leaf_key The asset key to query for. Nested REST Parameters leaf_key.script_key_bytes: string in query leaf_key.script_key_str: string in path leaf_key.op_str: string in query leaf_key.op.hash_str: string in path leaf_key.op.index: integer in path	AssetKey	object

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

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

taprpc.AssetVersion

Name	Number
ASSET_VERSION_V0 ASSET_VERSION_V0 is the default asset version. This version will include the witness vector in the leaf for a tap commitment.	0
ASSET_VERSION_V1 ASSET_VERSION_V1 is the asset version that leaves out the witness vector from the MS-SMT leaf encoding.	1

universerpc.ProofType

Name	Number
PROOF_TYPE_UNSPECIFIED	0
PROOF_TYPE_ISSUANCE	1
PROOF_TYPE_TRANSFER	2