QueryAssetRates

QueryAssetRates retrieves the exchange rate between a tap asset and BTC for a specified transaction type, subject asset, and payment asset. The asset rate represents the number of tap asset units per BTC.

Source: priceoraclerpc/price_oracle.proto

gRPC

rpc QueryAssetRates (QueryAssetRatesRequest) returns (QueryAssetRatesResponse);

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 = 'TAPD_DIR/data/regtest/admin.macaroon'
const TLS_PATH = 'TAPD_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('priceoraclerpc/price_oracle.proto', loaderOptions);
const priceoraclerpc = grpc.loadPackageDefinition(packageDefinition).priceoraclerpc;
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 priceoraclerpc.PriceOracle(GRPC_HOST, creds);
let request = {
  transaction_type: <TransactionType>,
  subject_asset: <AssetSpecifier>,
  subject_asset_max_amount: <uint64>,
  payment_asset: <AssetSpecifier>,
  payment_asset_max_amount: <uint64>,
  asset_rates_hint: <AssetRates>,
  intent: <Intent>,
  counterparty_id: <bytes>,
  metadata: <string>,
  node_id: <bytes>,
};
client.queryAssetRates(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "ok": <QueryAssetRatesOkResponse>,
//    "error": <QueryAssetRatesErrResponse>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the priceoraclerpc/price_oracle.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import price_oracle_pb2 as priceoraclerpc, price_oracle_pb2_grpc as price_oraclestub

GRPC_HOST = 'localhost:10029'
MACAROON_PATH = 'TAPD_DIR/data/regtest/admin.macaroon'
TLS_PATH = 'TAPD_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 = price_oraclestub.PriceOracleStub(channel)
request = priceoraclerpc.QueryAssetRatesRequest(
  transaction_type=<TransactionType>,
  subject_asset=<AssetSpecifier>,
  subject_asset_max_amount=<uint64>,
  payment_asset=<AssetSpecifier>,
  payment_asset_max_amount=<uint64>,
  asset_rates_hint=<AssetRates>,
  intent=<Intent>,
  counterparty_id=<bytes>,
  metadata=<string>,
  node_id=<bytes>,
)
response = stub.QueryAssetRates(request)
print(response)
# {
#    "ok": <QueryAssetRatesOkResponse>,
#    "error": <QueryAssetRatesErrResponse>,
# }

grpcurl

# grpcurl docs: https://github.com/fullstorydev/grpcurl
# Proto source: https://github.com/lightninglabs/taproot-assets
GRPC_HOST=localhost:10029
TAPD_DIR=~/.tapd
TAPD_SOURCE=path/to/taproot-assets
NETWORK=mainnet
MACAROON_PATH="$TAPD_DIR/data/$NETWORK/admin.macaroon"
TLS_PATH="$TAPD_DIR/tls.cert"

grpcurl \
    -import-path $TAPD_SOURCE/taprpc/ \
    -proto priceoraclerpc/price_oracle.proto \
    -cacert $TLS_PATH \
    -H "macaroon: $(xxd -ps -u -c 1000 $MACAROON_PATH)" \
    -d '{ "transaction_type": <TransactionType>, "subject_asset": <AssetSpecifier>, "subject_asset_max_amount": <uint64>, "payment_asset": <AssetSpecifier>, "payment_asset_max_amount": <uint64>, "asset_rates_hint": <AssetRates>, "intent": <Intent>, "counterparty_id": <bytes>, "metadata": <string>, "node_id": <bytes> }' \
    $GRPC_HOST \
    priceoraclerpc.PriceOracle/QueryAssetRates

Messages

priceoraclerpc.QueryAssetRatesRequest

Source: priceoraclerpc/price_oracle.proto

Field	gRPC Type	REST Type	REST Placement
transaction_type transaction_type indicates whether the transaction is a purchase or a sale.	TransactionType	unknown	unknown
subject_asset subject_asset is the asset to be priced for purchase or sale.	AssetSpecifier	unknown	unknown
subject_asset_max_amount subject_asset_max_amount is the maximum amount of the subject asset that could be involved in the transaction.	uint64	unknown	unknown
payment_asset payment_asset is the asset used for purchasing or receiving from a sale. NOTE: An asset ID of all zeros indicates that the payment asset is BTC. In this case, the asset rate will be given as milli-satoshi per asset unit	AssetSpecifier	unknown	unknown
payment_asset_max_amount payment_asset_max_amount is the maximum amount of the payment asset that could be involved in the transaction. This field is optional. If set to zero, it is considered unset.	uint64	unknown	unknown
asset_rates_hint asset_rates_hint is an optional suggestion of asset rates for the transaction, intended to provide guidance on expected pricing.	AssetRates	unknown	unknown
intent intent informs the price oracle about the stage of the payment flow that lead to the price rate query. This is used to provide context for the asset rates being requested, allowing the price oracle to tailor the response based on the specific use case, such as paying an invoice or receiving a payment and the different stages involved in those. This field will only be set by tapd v0.7.0 and later.	Intent	unknown	unknown
counterparty_id counterparty_id is the 33-byte public key of the peer that is on the opposite side of the transaction. This field will only be set by tapd v0.7.0 and later and only if the user initiating the transaction (sending a payment or creating an invoice) opted in to sharing their peer ID with the price oracle.	bytes	unknown	unknown
metadata metadata is an optional text field that can be used to provide additional metadata about the transaction to the price oracle. This can include information about the wallet end user that initiated the transaction, or any authentication information that the price oracle can use to give out a more accurate (or discount) asset rate. Though not verified or enforced by tapd, the suggested format for this field is a JSON string. This field is optional and can be left empty if no metadata is available. The maximum length of this field is 32'768 bytes. This field will only be set by tapd v0.7.0 and later.	string	unknown	unknown
node_id node_id is the 33-byte public key of the local node making the request to the price oracle. This identifies the tapd node that is querying rates, as opposed to the counterparty_id field which identifies the peer on the other side of the transaction. This field is set by default and can be disabled via the --experimental.rfq.priceoracledisablenodeid configuration option.	bytes	unknown	unknown

priceoraclerpc.QueryAssetRatesResponse

Source: priceoraclerpc/price_oracle.proto

Field	gRPC Type	REST Type
ok ok is the successful response to the query.	QueryAssetRatesOkResponse	unknown
error error is the error response to the query.	QueryAssetRatesErrResponse	unknown

Nested Messages

priceoraclerpc.AssetRates

Field	gRPC Type	REST Type
subjectAssetRate subjectAssetRate is the number of subject asset units per BTC represented as a fixed-point number. This field is also commonly referred to as the subject asset to BTC (conversion) rate. When the subject asset is BTC, this field should be set to 100 billion, as one BTC is equivalent to 100 billion msats.	FixedPoint	unknown
paymentAssetRate paymentAssetRate is the number of payment asset units per BTC represented as a fixed-point number. This field is also commonly referred to as the payment asset to BTC (conversion) rate. When the payment asset is BTC, this field should be set to 100 billion, as one BTC is equivalent to 100 billion msats.	FixedPoint	unknown
expiry_timestamp expiry_timestamp is the Unix timestamp in seconds after which the asset rates are no longer valid.	uint64	unknown

priceoraclerpc.AssetSpecifier

Field	gRPC Type	REST Type
asset_id The 32-byte asset ID specified as raw bytes (gRPC only).	bytes	unknown
asset_id_str The 32-byte asset ID encoded as a hex string (use this for REST).	string	unknown
group_key The 32-byte asset group key specified as raw bytes (gRPC only).	bytes	unknown
group_key_str The 32-byte asset group key encoded as hex string (use this for REST).	string	unknown

priceoraclerpc.FixedPoint

Field	gRPC Type	REST Type
coefficient The coefficient is the fractional value scaled-up as an integer. This integer is represented as a string as it may be too large to fit in a uint64.	string	unknown
scale The scale is the component that determines how many decimal places the coefficient should be divided by to obtain the fractional value.	uint32	unknown

priceoraclerpc.QueryAssetRatesErrResponse

Field	gRPC Type	REST Type
message error is the error message.	string	unknown
code code is the error code.	ErrorCode	unknown

priceoraclerpc.QueryAssetRatesOkResponse

Field	gRPC Type	REST Type
asset_rates asset_rates is the asset exchange rates for the transaction.	AssetRates	unknown

Enums

priceoraclerpc.ErrorCode

Name	Number
UNSPECIFIED_ORACLE_ERROR_CODE UNSPECIFIED_ORACLE_ERROR_CODE indicates an unspecified error.	0
UNSUPPORTED_ASSET_ORACLE_ERROR_CODE UNSUPPORTED_ASSET_ORACLE_ERROR_CODE indicates the asset is not supported.	1

priceoraclerpc.Intent

Name	Number
INTENT_UNSPECIFIED INTENT_UNSPECIFIED is used to indicate that the intent of the price rate query is not specified. This is the fallback default value and should not be used in production code. It is primarily used for backward compatibility with older versions of the protocol that did not include intent information.	0
INTENT_PAY_INVOICE_HINT INTENT_PAY_INVOICE_HINT is used to indicate that the user is requesting a price rate hint for paying an invoice. This is typically used by the payer of an invoice to provide a suggestion of the expected asset rate to the RFQ peer (edge node) that will determine the actual rate for the payment.	1
INTENT_PAY_INVOICE INTENT_PAY_INVOICE is used to indicate that a peer wants to pay an invoice with assets. This is typically used by the edge node that facilitates the swap from assets to BTC for the payer of an invoice. This intent is used to provide the actual asset rate for the payment, which may differ from the hint provided by the payer.	2
INTENT_PAY_INVOICE_QUALIFY INTENT_PAY_INVOICE_QUALIFY is used to indicate that the payer of an invoice has received an asset rate from their RFQ peer (edge node) and is qualifying the rate for the payment. This is typically used by the payer of an invoice to ensure that the asset rate provided by their peer (edge node) is acceptable before proceeding with the payment.	3
INTENT_RECV_PAYMENT_HINT INTENT_RECV_PAYMENT_HINT is used to indicate that the user is requesting a price rate hint for receiving a payment through an invoice. This is typically used by the creator of an invoice to provide a suggestion of the expected asset rate to the RFQ peer (edge node) that will determine the actual rate used for creating an invoice.	4
INTENT_RECV_PAYMENT INTENT_RECV_PAYMENT is used to indicate that a peer wants to create an invoice to receive a payment with assets. This is typically used by the edge node that facilitates the swap from BTC to assets for the receiver of a payment. This intent is used to provide the actual asset rate for the invoice creation, which may differ from the hint provided by the receiver.	5
INTENT_RECV_PAYMENT_QUALIFY INTENT_RECV_PAYMENT_QUALIFY is used to indicate that the creator of an invoice received an asset rate from their RFQ peer (edge node) and is qualifying the rate for the creation of the invoice. This is typically used by the creator of an invoice to ensure that the asset rate provided by their peer (edge node) is acceptable before proceeding with creating the invoice.	6

priceoraclerpc.TransactionType

Name	Number
PURCHASE PURCHASE indicates a purchase transaction.	0
SALE SALE indicates a sale transaction.	1