DecodeAssetPayReq

DecodeAssetPayReq is similar to lnd's lnrpc.DecodePayReq, but it accepts an asset ID or group key and returns the invoice amount expressed in asset units along side the normal information.

Source: tapchannelrpc/tapchannel.proto

gRPC

rpc DecodeAssetPayReq (AssetPayReq) returns (AssetPayReqResponse);

REST

HTTP Method	Path
POST	/v1/taproot-assets/channels/invoice/decode

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('tapchannelrpc/tapchannel.proto', loaderOptions);
const tapchannelrpc = grpc.loadPackageDefinition(packageDefinition).tapchannelrpc;
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 tapchannelrpc.TaprootAssetChannels(GRPC_HOST, creds);
let request = {
  asset_id: <bytes>,
  pay_req_string: <string>,
  group_key: <bytes>,
};
client.decodeAssetPayReq(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "asset_amount": <uint64>,
//    "decimal_display": <DecimalDisplay>,
//    "asset_group": <AssetGroup>,
//    "genesis_info": <GenesisInfo>,
//    "pay_req": <PayReq>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the tapchannelrpc/tapchannel.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import tapchannel_pb2 as tapchannelrpc, tapchannel_pb2_grpc as tapchannelstub

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 = tapchannelstub.TaprootAssetChannelsStub(channel)
request = tapchannelrpc.AssetPayReq(
  asset_id=<bytes>,
  pay_req_string=<string>,
  group_key=<bytes>,
)
response = stub.DecodeAssetPayReq(request)
print(response)
# {
#    "asset_amount": <uint64>,
#    "decimal_display": <DecimalDisplay>,
#    "asset_group": <AssetGroup>,
#    "genesis_info": <GenesisInfo>,
#    "pay_req": <PayReq>,
# }

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 requestBody = {
  asset_id: <string>, // <bytes> (base64 encoded)
  pay_req_string: <string>, // <string> 
  group_key: <string>, // <bytes> (base64 encoded)
};
let options = {
  url: `https://${REST_HOST}/v1/taproot-assets/channels/invoice/decode`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "asset_amount": <string>, // <uint64> 
//    "decimal_display": <object>, // <DecimalDisplay> 
//    "asset_group": <object>, // <AssetGroup> 
//    "genesis_info": <object>, // <GenesisInfo> 
//    "pay_req": <object>, // <PayReq> 
//  }

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/channels/invoice/decode'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'asset_id': base64.b64encode(<bytes>),
  'pay_req_string': <string>,
  'group_key': base64.b64encode(<bytes>),
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "asset_amount": <uint64>,
#    "decimal_display": <DecimalDisplay>,
#    "asset_group": <AssetGroup>,
#    "genesis_info": <GenesisInfo>,
#    "pay_req": <PayReq>,
# }

Shell

$ litcli ln decodeassetinvoice --help

NAME:
   litcli ln decodeassetinvoice - Decodes an LN invoice and displays the invoice's amount in asset units specified by an asset ID or group key.

USAGE:
   litcli ln decodeassetinvoice [command options] --pay_req=X [--asset_id=X | --group_key=X]

CATEGORY:
   Payments

DESCRIPTION:
   
  This command can be used to display the information encoded in an
  invoice.
  Given a chosen asset_id or group_key, the invoice's amount expressed in
  units of the asset will be displayed.
  
  Other information such as the decimal display of an asset, and the asset
  group information (if applicable) are also shown.
  

OPTIONS:
   --pay_req value    a zpay32 encoded payment request to fulfill
   --asset_id value   the asset ID of the asset to use when sending payments with assets; cannot be used at the same time as --group_key
   --group_key value  the group key of the asset to use when sending payments with assets; cannot be used at the same time as --asset_id
   

Messages

tapchannelrpc.AssetPayReq

Source: tapchannelrpc/tapchannel.proto

Field	gRPC Type	REST Type	REST Placement
asset_id The asset ID that will be used to resolve the invoice's satoshi amount. Mutually exclusive to group_key.	bytes	string	body
pay_req_string The normal LN invoice that whose amount will be mapped to units of the asset ID.	string	string	body
group_key The group key that will be used to resolve the invoice's satoshi amount. Mutually exclusive to asset_id.	bytes	string	body

tapchannelrpc.AssetPayReqResponse

Source: tapchannelrpc/tapchannel.proto

Field	gRPC Type	REST Type
asset_amount The invoice amount, expressed in asset units.	uint64	string
decimal_display The decimal display corresponding to the asset_id.	DecimalDisplay	object
asset_group The group the asset ID belong to, if applicable.	AssetGroup	object
genesis_info Genesis information for the asset ID which includes the meta hash, and asset ID. This is only set if the payment request was decoded with an asset ID and not with a group key (since a group can contain assets from different minting events or genesis infos).	GenesisInfo	object
pay_req The normal decoded payment request.	PayReq	object

Nested Messages

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

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