ForwardingHistory

ForwardingHistory is used to query for completed asset forwarding events. These are historical records of HTLCs that were settled successfully.

Source: rfqrpc/rfq.proto

gRPC

rpc ForwardingHistory (ForwardingHistoryRequest) returns (ForwardingHistoryResponse);

REST

HTTP Method	Path
GET	/v1/taproot-assets/rfq/forwardinghistory

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 = {
  min_timestamp: <uint64>,
  max_timestamp: <uint64>,
  peer: <bytes>,
  asset_specifier: <AssetSpecifier>,
  limit: <int32>,
  offset: <int32>,
};
client.forwardingHistory(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "forwards": <ForwardingEvent>,
//    "total_count": <int64>,
//  }

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.ForwardingHistoryRequest(
  min_timestamp=<uint64>,
  max_timestamp=<uint64>,
  peer=<bytes>,
  asset_specifier=<AssetSpecifier>,
  limit=<int32>,
  offset=<int32>,
)
response = stub.ForwardingHistory(request)
print(response)
# {
#    "forwards": <ForwardingEvent>,
#    "total_count": <int64>,
# }

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/rfq/forwardinghistory`,
  // 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:
//  {
//    "forwards": <array>, // <ForwardingEvent> 
//    "total_count": <string>, // <int64> 
//  }

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/forwardinghistory'
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())
# {
#    "forwards": <ForwardingEvent>,
#    "total_count": <int64>,
# }

Shell

$ tapcli rfq forwardinghistory --help

NAME:
   tapcli rfq forwardinghistory - query historical asset forwarding events

USAGE:
   tapcli rfq forwardinghistory [command options] [arguments...]

DESCRIPTION:
   
  Query historical records of asset forwarding events executed by the RFQ
  system. This provides accounting and record-keeping for edge nodes that
  perform asset swaps. Events are recorded when opened and updated when
  they settle or fail.


OPTIONS:
   --min_timestamp value  minimum Unix timestamp in seconds; only events opened at or after this time are returned (default: 0)
   --max_timestamp value  maximum Unix timestamp in seconds; only events opened at or before this time are returned (default: 0)
   --peer value           filter by peer public key
   --asset_id value       filter by asset ID
   --group_key value      filter by asset group key
   --limit value          maximum number of records to return (default: 100)
   --offset value         number of records to skip (default: 0)
   

Messages

rfqrpc.ForwardingHistoryRequest

Source: rfqrpc/rfq.proto

Field	gRPC Type	REST Type	REST Placement
min_timestamp min_timestamp is the minimum Unix timestamp in seconds. Only forwarding events that settled at or after this time are returned. If not set, there is no lower bound.	uint64	string	query
max_timestamp max_timestamp is the maximum Unix timestamp in seconds. Only forwarding events that settled at or before this time are returned. If not set, there is no upper bound.	uint64	string	query
peer peer is the optional counterparty peer's public key. If set, only forwarding events involving this peer are returned.	bytes	string	query
asset_specifier asset_specifier optionally filters forwarding events by asset ID or group key. Nested REST Parameters asset_specifier.asset_id: string in query asset_specifier.asset_id_str: string in query asset_specifier.group_key: string in query asset_specifier.group_key_str: string in query	AssetSpecifier	object	query
limit limit is the maximum number of records to return.	int32	integer	query
offset offset is the number of records to skip for pagination.	int32	integer	query

rfqrpc.ForwardingHistoryResponse

Source: rfqrpc/rfq.proto

Field	gRPC Type	REST Type
forwards forwards is the list of completed asset forwarding events matching the query.	ForwardingEvent[]	array
total_count total_count is the total number of forwards matching the filter (before pagination is applied). This can be used for pagination.	int64	string

Nested Messages

rfqrpc.AssetSpec

Field	gRPC Type	REST Type
id The 32-byte asset ID specified as raw bytes.	bytes	string
group_pub_key The 32-byte asset group public key, serialized in BIP340 format. BIP340 defines a canonical encoding for Schnorr public keys. This field is serialized using schnorr.SerializePubKey.	bytes	string

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

Field	gRPC Type	REST Type
rfq_id rfq_id is the unique identifier of the RFQ session that governed this forward.	bytes	string
chan_id_in chan_id_in is the short channel ID of the incoming channel.	uint64	string
chan_id_out chan_id_out is the short channel ID of the outgoing channel.	uint64	string
htlc_id htlc_id is the HTLC ID on the incoming channel.	uint64	string
opened_at opened_at is the Unix timestamp in seconds when the forward was initiated.	uint64	string
settled_at settled_at is the Unix timestamp in seconds when the forward settled. A value of 0 means the forward has not settled yet.	uint64	string
failed_at failed_at is the Unix timestamp in seconds when the forward failed. A value of 0 means the forward has not failed.	uint64	string
asset_amt asset_amt is the asset amount that was swapped.	uint64	string
amt_in_msat amt_in_msat is the actual amount received on the incoming channel in millisatoshis.	uint64	string
amt_out_msat amt_out_msat is the actual amount sent on the outgoing channel in millisatoshis.	uint64	string
policy_type policy_type indicates whether this was a sale or purchase of assets from the edge node's perspective.	RfqPolicyType	string
peer peer is the counterparty peer's public key as a hex string.	string	string
asset_spec asset_specifier identifies the asset that was swapped.	AssetSpec	object
rate rate is the exchange rate that was used for this swap.	FixedPoint	object

Enums

rfqrpc.RfqPolicyType

Name	Number
RFQ_POLICY_TYPE_SALE RFQ_POLICY_TYPE_SALE indicates that the RFQ session was a sale.	0
RFQ_POLICY_TYPE_PURCHASE RFQ_POLICY_TYPE_PURCHASE indicates that the RFQ session was a purchase.	1