astra-lightning 1.1.2 → 1.1.4

package/grpc/protos/rfqrpc/rfq.proto

@@ -131,8 +131,7 @@ message AddAssetBuyOrderRequest {
     // The unix timestamp in seconds after which the order is no longer valid.
     uint64 expiry = 3;
 
-    // peer_pub_key is an optional field for specifying the public key of the
-    // intended recipient peer for the order.
+    // The public key of the intended recipient peer for the order.
     bytes peer_pub_key = 4;
 
     // timeout_seconds is the number of seconds to wait for the peer to respond
@@ -144,6 +143,16 @@ message AddAssetBuyOrderRequest {
     // the RFQ negotiation to work. This flag shouldn't be set outside of test
     // scenarios.
     bool skip_asset_channel_check = 6;
+
+    // An optional text field that can be used to provide additional metadata
+    // about the buy order 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.
+    string price_oracle_metadata = 7;
 }
 
 message AddAssetBuyOrderResponse {
@@ -173,8 +182,7 @@ message AddAssetSellOrderRequest {
     // The unix timestamp in seconds after which the order is no longer valid.
     uint64 expiry = 3;
 
-    // peer_pub_key is an optional field for specifying the public key of the
-    // intended recipient peer for the order.
+    // The public key of the intended recipient peer for the order.
     bytes peer_pub_key = 4;
 
     // timeout_seconds is the number of seconds to wait for the peer to respond
@@ -186,6 +194,16 @@ message AddAssetSellOrderRequest {
     // the RFQ negotiation to work. This flag shouldn't be set outside of test
     // scenarios.
     bool skip_asset_channel_check = 6;
+
+    // An optional text field that can be used to provide additional metadata
+    // about the sell order 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.
+    string price_oracle_metadata = 7;
 }
 
 message AddAssetSellOrderResponse {
@@ -229,6 +247,16 @@ message AddAssetBuyOfferResponse {
 message QueryPeerAcceptedQuotesRequest {
 }
 
+message AssetSpec {
+    // The 32-byte asset ID specified as raw bytes.
+    bytes id = 1;
+
+    // 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 group_pub_key = 2;
+}
+
 message PeerAcceptedBuyQuote {
     // Quote counterparty peer.
     string peer = 1;
@@ -258,6 +286,16 @@ message PeerAcceptedBuyQuote {
     // asset unit equivalent of 354 satoshis, which is the minimum amount for an
     // HTLC to be above the dust limit.
     uint64 min_transportable_units = 7;
+
+    // An optional user-provided text field used to provide additional metadata
+    // about the buy order 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.
+    string price_oracle_metadata = 8;
+
+    // The subject asset specifier.
+    AssetSpec asset_spec = 9;
 }
 
 message PeerAcceptedSellQuote {
@@ -287,6 +325,16 @@ message PeerAcceptedSellQuote {
     // amount for a non-dust HTLC) plus the equivalent of one asset unit in
     // milli-satoshis.
     uint64 min_transportable_msat = 7;
+
+    // An optional user-provided text field used to provide additional metadata
+    // about the sell order 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.
+    string price_oracle_metadata = 8;
+
+    // The subject asset specifier.
+    AssetSpec asset_spec = 9;
 }
 
 // QuoteRespStatus is an enum that represents the status of a quote response.
@@ -385,4 +433,4 @@ message RfqEvent {
         // RFQ service.
         AcceptHtlcEvent accept_htlc = 3;
     }
-}
+}

package/grpc/protos/router.proto

@@ -227,10 +227,11 @@ message SendPaymentRequest {
     string payment_request = 5;
 
     /*
-    An upper limit on the amount of time we should spend when attempting to
-    fulfill the payment. This is expressed in seconds. If we cannot make a
-    successful payment within this time frame, an error will be returned.
-    This field must be non-zero.
+    An optional limit, expressed in seconds, on the time to wait before
+    attempting the first HTLC. Once HTLCs are in flight, the payment will
+    not be aborted until the HTLCs are either settled or failed. If the field
+    is not set or is explicitly set to zero, the default value of 60 seconds
+    will be applied.
     */
     int32 timeout_seconds = 6;
 
@@ -1063,6 +1064,10 @@ message ForwardHtlcInterceptResponse {
     // Any custom records that should be set on the p2p wire message message of
     // the resumed HTLC. This field is ignored if the action is not
     // RESUME_MODIFIED.
+    //
+    // This map will merge with the existing set of custom records (if any),
+    // replacing any conflicting types. Note that there currently is no support
+    // for deleting existing custom records (they can only be replaced).
     map<uint64, bytes> out_wire_custom_records = 8;
 }
 

package/grpc/protos/routerrpc/router.proto

@@ -195,6 +195,13 @@ service Router {
     */
     rpc XDeleteLocalChanAliases (DeleteAliasesRequest)
         returns (DeleteAliasesResponse);
+
+    /*
+    XFindBaseLocalChanAlias is an experimental API that looks up the base scid
+    for a local chan alias that was registered during the current runtime.
+    */
+    rpc XFindBaseLocalChanAlias (FindBaseAliasRequest)
+        returns (FindBaseAliasResponse);
 }
 
 message SendPaymentRequest {
@@ -227,10 +234,11 @@ message SendPaymentRequest {
     string payment_request = 5;
 
     /*
-    An upper limit on the amount of time we should spend when attempting to
-    fulfill the payment. This is expressed in seconds. If we cannot make a
-    successful payment within this time frame, an error will be returned.
-    This field must be non-zero.
+    An optional limit, expressed in seconds, on the time to wait before
+    attempting the first HTLC. Once HTLCs are in flight, the payment will
+    not be aborted until the HTLCs are either settled or failed. If the field
+    is not set or is explicitly set to zero, the default value of 60 seconds
+    will be applied.
     */
     int32 timeout_seconds = 6;
 
@@ -1063,6 +1071,10 @@ message ForwardHtlcInterceptResponse {
     // Any custom records that should be set on the p2p wire message message of
     // the resumed HTLC. This field is ignored if the action is not
     // RESUME_MODIFIED.
+    //
+    // This map will merge with the existing set of custom records (if any),
+    // replacing any conflicting types. Note that there currently is no support
+    // for deleting existing custom records (they can only be replaced).
     map<uint64, bytes> out_wire_custom_records = 8;
 }
 
@@ -1111,4 +1123,14 @@ message DeleteAliasesRequest {
 
 message DeleteAliasesResponse {
     repeated lnrpc.AliasMap alias_maps = 1;
+}
+
+message FindBaseAliasRequest {
+    // The alias we want to look up the base scid for.
+    uint64 alias = 1;
+}
+
+message FindBaseAliasResponse {
+    // The base scid that resulted from the base scid look up.
+    uint64 base = 1;
 }

package/grpc/protos/{tapchannelrpc.proto → tapchannel.proto}

@@ -10,13 +10,14 @@ import "routerrpc/router.proto";
 import "taprootassets.proto";
 
 service TaprootAssetChannels {
-    /*
+    /* litcli: `ln fundchannel`
     FundChannel initiates the channel funding negotiation with a peer for the
     creation of a channel that contains a specified amount of a given asset.
     */
     rpc FundChannel (FundChannelRequest) returns (FundChannelResponse);
 
     /*
+    Deprecated.
     EncodeCustomRecords allows RPC users to encode Taproot Asset channel related
     data into the TLV format that is used in the custom records of the lnd
     payment or other channel related RPCs. This RPC is completely stateless and
@@ -24,9 +25,11 @@ service TaprootAssetChannels {
     validation.
     */
     rpc EncodeCustomRecords (EncodeCustomRecordsRequest)
-        returns (EncodeCustomRecordsResponse);
+        returns (EncodeCustomRecordsResponse) {
+        option deprecated = true;
+    };
 
-    /*
+    /* litcli: `ln sendpayment`
     SendPayment is a wrapper around lnd's routerrpc.SendPaymentV2 RPC method
     with asset specific parameters. It allows RPC users to send asset keysend
     payments (direct payments) or payments to an invoice with a specified asset
@@ -34,17 +37,19 @@ service TaprootAssetChannels {
     */
     rpc SendPayment (SendPaymentRequest) returns (stream SendPaymentResponse);
 
-    /*
+    /* litcli: `ln addinvoice`
     AddInvoice is a wrapper around lnd's lnrpc.AddInvoice method with asset
     specific parameters. It allows RPC users to create invoices that correspond
-    to the specified asset amount.
+    to the specified asset amount. If a peer pubkey is specified, then only that
+    peer will be used for RFQ negotiations. If none is specified then RFQ quotes
+    for all peers with suitable asset channels will be created.
     */
     rpc AddInvoice (AddInvoiceRequest) returns (AddInvoiceResponse);
 
-    /*
+    /* litcli: `ln decodeassetinvoice`
     DecodeAssetPayReq is similar to lnd's lnrpc.DecodePayReq, but it accepts an
-    asset ID and returns the invoice amount expressed in asset units along side
-    the normal information.
+    asset ID or group key and returns the invoice amount expressed in asset
+    units along side the normal information.
     */
     rpc DecodeAssetPayReq (AssetPayReq) returns (AssetPayReqResponse);
 }
@@ -70,6 +75,11 @@ message FundChannelRequest {
     // is equivalent to a donation to the remote party, unless they reimburse
     // the funds in another way (outside the protocol).
     int64 push_sat = 5;
+
+    // The group key to use for the channel. This can be used instead of the
+    // asset_id to allow assets from a fungible group to be used for the channel
+    // funding instead of just assets from a single minting tranche (asset_id).
+    bytes group_key = 6;
 }
 
 message FundChannelResponse {
@@ -93,6 +103,7 @@ message RouterSendPaymentData {
 
 message EncodeCustomRecordsRequest {
     oneof input {
+        // The custom records to encode for a payment request.
         RouterSendPaymentData router_send_payment = 1;
     }
 }
@@ -106,7 +117,7 @@ message SendPaymentRequest {
     // The asset ID to use for the payment. This must be set for both invoice
     // and keysend payments, unless RFQ negotiation was already done beforehand
     // and payment_request.first_hop_custom_records already contains valid RFQ
-    // data.
+    // data. Mutually exclusive to group_key.
     bytes asset_id = 1;
 
     // The asset amount to send in a keysend payment. This amount is ignored for
@@ -117,8 +128,8 @@ message SendPaymentRequest {
     uint64 asset_amount = 2;
 
     // The node identity public key of the peer to ask for a quote for sending
-    // out the assets and converting them to satoshis. This must be specified if
-    // there are multiple channels with the given asset ID.
+    // out the assets and converting them to satoshis. If set, only a quote with
+    // this peer may be negotiated to carry out the payment.
     bytes peer_pubkey = 3;
 
     // The full lnd payment request to send. All fields behave the same way as
@@ -142,6 +153,27 @@ message SendPaymentRequest {
     // are sent out to the network than the invoice amount plus routing fees
     // require to be paid.
     bool allow_overpay = 6;
+
+    // The group key which dictates which assets may be used for this payment.
+    // Mutually exclusive to asset_id.
+    bytes group_key = 7;
+
+    // An optional text field that can be used to provide additional metadata
+    // about the payment 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.
+    string price_oracle_metadata = 8;
+}
+
+message AcceptedSellQuotes {
+    // If swapping of assets is necessary to carry out the payment, a number of
+    // RFQ quotes may be negotiated for that purpose. The following field
+    // contains all the sell orders that were negotiated with our peers.
+    repeated rfqrpc.PeerAcceptedSellQuote accepted_sell_orders = 1;
 }
 
 message SendPaymentResponse {
@@ -150,44 +182,75 @@ message SendPaymentResponse {
         // sell order is negotiated with the channel peer. The result will be
         // the first message in the response stream. If no swap is needed, the
         // payment results will be streamed directly.
+        // Deprecated. This will now only contain the first quote that was
+        // negotiated. Since the introduction of multi-rfq we now negotiate
+        // multiple quotes in the context of a payment. Use the new field named
+        // "accepted_sell_orders" to retrieve all of them.
         rfqrpc.PeerAcceptedSellQuote accepted_sell_order = 1;
 
-        // The payment result of a single payment attempt. Multiple attempts may
-        // be returned per payment request until either the payment succeeds or
-        // the payment times out.
+        // If swapping of assets is necessary to carry out the payment, a number
+        // of RFQ quotes may be negotiated for that purpose. The following field
+        // contains all the sell orders that were negotiated with our peers.
+        AcceptedSellQuotes accepted_sell_orders = 3;
+
+        // The payment result of a single payment attempt. Multiple attempts
+        // may be returned per payment request until either the payment
+        // succeeds or the payment times out.
         lnrpc.Payment payment_result = 2;
     }
 }
 
 message HodlInvoice {
+    // The payment hash of the HODL invoice to be created.
     bytes payment_hash = 1;
 }
 
 message AddInvoiceRequest {
-    // The asset ID to use for the invoice.
+    // The asset ID to use for the invoice. Mutually exclusive to group_key.
     bytes asset_id = 1;
 
     // The asset amount to receive.
     uint64 asset_amount = 2;
 
     // The node identity public key of the peer to ask for a quote for receiving
-    // assets and converting them from satoshis. This must be specified if
-    // there are multiple channels with the given asset ID.
+    // assets and converting them from satoshis. When specified only quotes with
+    // this peer will be negotiated.
     bytes peer_pubkey = 3;
 
-    // The full lnd invoice request to send. All fields (except for the value
-    // and the route hints) behave the same way as they do for lnd's
-    // lnrpc.AddInvoice RPC method (see the API docs at
+    // The full lnd invoice request to send. All fields behave the same way as
+    // they do for lnd's lnrpc.AddInvoice RPC method (see the API docs at
     // https://lightning.engineering/api-docs/api/lnd/lightning/add-invoice
-    // for more details). The value/value_msat fields will be overwritten by the
-    // satoshi (or milli-satoshi) equivalent of the asset amount, after
-    // negotiating a quote with a peer that supports the given asset ID.
+    // for more details).
+    //
+    // Only one of the asset_amount/value/value_msat may be set to dictate the
+    // value of the invoice. When using asset_amount, the value/value_msat
+    // fields will be overwritten by the satoshi (or milli-satoshi) equivalent
+    // of the asset amount, after negotiating a quote with a peer that supports
+    // the given asset ID.
+    //
+    // If the value/value_msat are used, we still receive assets, but they will
+    // exactly evaluate to the defined amount in sats/msats.
     lnrpc.Invoice invoice_request = 4;
 
     // If set, then this will make the invoice created a hodl invoice, which
     // won't be settled automatically. Instead, users will need to use the
     // invoicesrpc.SettleInvoice call to manually settle the invoice.
     HodlInvoice hodl_invoice = 5;
+
+    // The group key which dictates which assets may be accepted for this
+    // invoice. If set, any asset that belongs to this group may be accepted to
+    // settle this invoice. Mutually exclusive to asset_id.
+    bytes group_key = 6;
+
+    // An optional text field that can be used to provide additional metadata
+    // about the invoice 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.
+    string price_oracle_metadata = 7;
 }
 
 message AddInvoiceResponse {
@@ -200,11 +263,26 @@ message AddInvoiceResponse {
 
 message AssetPayReq {
     // The asset ID that will be used to resolve the invoice's satoshi amount.
+    // Mutually exclusive to group_key.
     bytes asset_id = 1;
 
     // The normal LN invoice that whose amount will be mapped to units of the
     // asset ID.
     string pay_req_string = 2;
+
+    // The group key that will be used to resolve the invoice's satoshi amount.
+    // Mutually exclusive to asset_id.
+    bytes group_key = 3;
+
+    // An optional text field that can be used to provide additional metadata
+    // about the invoice 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.
+    string price_oracle_metadata = 4;
 }
 
 message AssetPayReqResponse {
@@ -218,9 +296,11 @@ message AssetPayReqResponse {
     taprpc.AssetGroup asset_group = 3;
 
     // Genesis information for the asset ID which includes the meta hash, and
-    // asset ID.
+    // 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).
     taprpc.GenesisInfo genesis_info = 4;
 
     // The normal decoded payment request.
     lnrpc.PayReq pay_req = 5;
-}
+}

package/grpc/protos/tapcommon.proto

@@ -0,0 +1,36 @@
+syntax = "proto3";
+
+package taprpc;
+
+option go_package = "github.com/lightninglabs/taproot-assets/taprpc";
+
+// Represents a Bitcoin transaction outpoint.
+message OutPoint {
+    /*
+    Raw bytes representing the transaction id.
+    */
+    bytes txid = 1;
+
+    /*
+    The index of the output on the transaction.
+    */
+    uint32 output_index = 2;
+}
+
+// A transaction outpoint annotated with TAP-level asset metadata. It uniquely
+// identifies an asset anchored at a specific outpoint.
+message AssetOutPoint {
+    // The outpoint of the asset anchor, represented as a string in the
+    // format "<txid>:<vout>". The <txid> is the transaction ID of the UTXO,
+    // hex-encoded and byte-reversed (i.e., the internal little-endian
+    // 32-byte value is reversed to big-endian hex format) to match standard
+    // Bitcoin RPC and UI conventions.
+    string anchor_out_point = 1;
+
+    // The asset ID of the asset anchored at the outpoint.
+    bytes asset_id = 2;
+
+    // The script key of the asset. This is the taproot output key that the
+    // asset is locked to.
+    bytes script_key = 3;
+}