AddAssetBuyOrder

AddAssetBuyOrder is used to add a buy order for a specific asset. If a buy order already exists for the asset, it will be updated.

A buy order instructs the RFQ (Request For Quote) system to request a quote from a peer for the acquisition of an asset.

The normal use of a buy order is as follows:

1. Alice, operating a wallet node, wants to receive a Tap asset as payment by issuing a Lightning invoice.
2. Alice has an asset channel established with Bob's edge node.
3. Before issuing the invoice, Alice needs to agree on an exchange rate with Bob, who will facilitate the asset transfer.
4. To obtain the best exchange rate, Alice creates a buy order specifying the desired asset.
5. Alice's RFQ subsystem processes the buy order and sends buy requests to relevant peers to find the best rate. In this example, Bob is the only available peer.
6. Once Bob provides a satisfactory quote, Alice accepts it.
7. Alice issues the Lightning invoice, which Charlie will pay.
8. Instead of paying Alice directly, Charlie pays Bob.
9. Bob then forwards the agreed amount of the Tap asset to Alice over their asset channel.

Source: rfqrpc/rfq.proto

gRPC

rpc AddAssetBuyOrder (AddAssetBuyOrderRequest) returns (AddAssetBuyOrderResponse);

REST

HTTP Method	Path
POST	/v1/taproot-assets/rfq/buyorder/asset-id/{asset_specifier.asset_id_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('rfqrpc/rfq.proto', loaderOptions);
const rfqrpc = grpc.loadPackageDefinition(packageDefinition).rfqrpc;
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 rfqrpc.Rfq(GRPC_HOST, creds);
let request = {
  asset_specifier: <AssetSpecifier>,
  asset_max_amt: <uint64>,
  expiry: <uint64>,
  peer_pub_key: <bytes>,
  timeout_seconds: <uint32>,
  skip_asset_channel_check: <bool>,
};
client.addAssetBuyOrder(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "accepted_quote": <PeerAcceptedBuyQuote>,
//    "invalid_quote": <InvalidQuoteResponse>,
//    "rejected_quote": <RejectedQuoteResponse>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the rfqrpc/rfq.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import rfq_pb2 as rfqrpc, rfq_pb2_grpc as rfqstub

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 = rfqstub.RfqStub(channel)
request = rfqrpc.AddAssetBuyOrderRequest(
  asset_specifier=<AssetSpecifier>,
  asset_max_amt=<uint64>,
  expiry=<uint64>,
  peer_pub_key=<bytes>,
  timeout_seconds=<uint32>,
  skip_asset_channel_check=<bool>,
)
response = stub.AddAssetBuyOrder(request)
print(response)
# {
#    "accepted_quote": <PeerAcceptedBuyQuote>,
#    "invalid_quote": <InvalidQuoteResponse>,
#    "rejected_quote": <RejectedQuoteResponse>,
# }

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_specifier: <object>, // <AssetSpecifier> 
  asset_max_amt: <string>, // <uint64> 
  expiry: <string>, // <uint64> 
  peer_pub_key: <string>, // <bytes> (base64 encoded)
  timeout_seconds: <integer>, // <uint32> 
  skip_asset_channel_check: <boolean>, // <bool> 
};
let options = {
  url: `https://${REST_HOST}/v1/taproot-assets/rfq/buyorder/asset-id/{asset_specifier.asset_id_str}`,
  // 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:
//  {
//    "accepted_quote": <object>, // <PeerAcceptedBuyQuote> 
//    "invalid_quote": <object>, // <InvalidQuoteResponse> 
//    "rejected_quote": <object>, // <RejectedQuoteResponse> 
//  }

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/rfq/buyorder/asset-id/{asset_specifier.asset_id_str}'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'asset_specifier': <AssetSpecifier>,
  'asset_max_amt': <uint64>,
  'expiry': <uint64>,
  'peer_pub_key': base64.b64encode(<bytes>),
  'timeout_seconds': <uint32>,
  'skip_asset_channel_check': <bool>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "accepted_quote": <PeerAcceptedBuyQuote>,
#    "invalid_quote": <InvalidQuoteResponse>,
#    "rejected_quote": <RejectedQuoteResponse>,
# }

Shell

# There is no CLI command for this RPC

Messages

rfqrpc.AddAssetBuyOrderRequest

Source: rfqrpc/rfq.proto

Field	gRPC Type	REST Type	REST Placement
asset_specifier asset_specifier is the subject asset. Nested REST Parameters asset_specifier: object in body asset_specifier.asset_id_str: string in path	AssetSpecifier	object	mixed
asset_max_amt The maximum amount of the asset that the provider must be willing to offer.	uint64	string	body
expiry The unix timestamp in seconds after which the order is no longer valid.	uint64	string	body
peer_pub_key peer_pub_key is an optional field for specifying the public key of the intended recipient peer for the order.	bytes	string	body
timeout_seconds timeout_seconds is the number of seconds to wait for the peer to respond with an accepted quote (or a rejection).	uint32	integer	body
skip_asset_channel_check If set, the check if a channel with the given asset exists with the peer will be skipped. An active channel with the peer is still required for the RFQ negotiation to work. This flag shouldn't be set outside of test scenarios.	bool	boolean	body

rfqrpc.AddAssetBuyOrderResponse

Source: rfqrpc/rfq.proto

Field	gRPC Type	REST Type
accepted_quote accepted_quote holds the quote received from the peer as a response to our quote request.	PeerAcceptedBuyQuote	object
invalid_quote invalid_quote is returned if the quote response received from the peer was invalid or insufficient.	InvalidQuoteResponse	object
rejected_quote rejected_quote is returned if the quote request was rejected by the peer.	RejectedQuoteResponse	object

Nested Messages

rfqrpc.AssetSpecifier

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

rfqrpc.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	string
scale The scale is the component that determines how many decimal places the coefficient should be divided by to obtain the fractional value.	uint32	integer

rfqrpc.InvalidQuoteResponse

Field	gRPC Type	REST Type
status status is the status of the quote response.	QuoteRespStatus	string
peer peer is the quote counterparty peer.	string	string
id id is the unique identifier of the quote request.	bytes	string

rfqrpc.PeerAcceptedBuyQuote

Field	gRPC Type	REST Type
peer Quote counterparty peer.	string	string
id The unique identifier of the quote request.	bytes	string
scid The short channel ID of the channel over which the payment for the quote should be made.	uint64	string
asset_max_amount The maximum exchange amount denoted in the subject asset. This includes the user-configured maximum routing fees, so the actual payment amount will be less than this. This just defines the maximum volume that the edge node has accepted to divest with the given rate.	uint64	string
ask_asset_rate ask_asset_rate is the asset to BTC conversion rate represented as a fixed-point number.	FixedPoint	object
expiry The unix timestamp in seconds after which the quote is no longer valid.	uint64	string
min_transportable_units The smallest amount of asset units that can be transported within a single HTLC over the Lightning Network with the given rate. This is the asset unit equivalent of 354 satoshis, which is the minimum amount for an HTLC to be above the dust limit.	uint64	string

rfqrpc.RejectedQuoteResponse

Field	gRPC Type	REST Type
peer peer is the quote counterparty peer.	string	string
id id is the unique identifier of the quote request.	bytes	string
error_message error_message is a human-readable error message.	string	string
error_code error_code is a machine-readable error code.	uint32	integer

Enums

rfqrpc.QuoteRespStatus

Name	Number
INVALID_ASSET_RATES INVALID_ASSET_RATES indicates that at least one asset rate in the quote response is invalid.	0
INVALID_EXPIRY INVALID_EXPIRY indicates that the expiry in the quote response is invalid.	1
PRICE_ORACLE_QUERY_ERR PRICE_ORACLE_QUERY_ERR indicates that an error occurred when querying the price oracle whilst evaluating the quote response.	2