lnlink-server 1.0.0

package/dist/proto/stateservice.proto

@@ -0,0 +1,73 @@
+syntax = "proto3";
+
+package lnrpc;
+
+option go_package = "github.com/lightningnetwork/lnd/lnrpc";
+
+/*
+ * Comments in this file will be directly parsed into the API
+ * Documentation as descriptions of the associated method, message, or field.
+ * These descriptions should go right above the definition of the object, and
+ * can be in either block or // comment format.
+ *
+ * An RPC method can be matched to an lncli command by placing a line in the
+ * beginning of the description in exactly the following format:
+ * lncli: `methodname`
+ *
+ * Failure to specify the exact name of the command will cause documentation
+ * generation to fail.
+ *
+ * More information on how exactly the gRPC documentation is generated from
+ * this proto file can be found here:
+ * https://github.com/lightninglabs/lightning-api
+ */
+
+// State service is a always running service that exposes the current state of
+// the wallet and RPC server.
+service State {
+    // SubscribeState subscribes to the state of the wallet. The current wallet
+    // state will always be delivered immediately.
+    rpc SubscribeState (SubscribeStateRequest)
+        returns (stream SubscribeStateResponse);
+
+    // GetState returns the current wallet state without streaming further
+    // changes.
+    rpc GetState (GetStateRequest) returns (GetStateResponse);
+}
+
+enum WalletState {
+    // NON_EXISTING means that the wallet has not yet been initialized.
+    NON_EXISTING = 0;
+
+    // LOCKED means that the wallet is locked and requires a password to unlock.
+    LOCKED = 1;
+
+    // UNLOCKED means that the wallet was unlocked successfully, but RPC server
+    // isn't ready.
+    UNLOCKED = 2;
+
+    // RPC_ACTIVE means that the lnd server is active but not fully ready for
+    // calls.
+    RPC_ACTIVE = 3;
+
+    // SERVER_ACTIVE means that the lnd server is ready to accept calls.
+    SERVER_ACTIVE = 4;
+
+    // WAITING_TO_START means that node is waiting to become the leader in a
+    // cluster and is not started yet.
+    WAITING_TO_START = 255;
+}
+
+message SubscribeStateRequest {
+}
+
+message SubscribeStateResponse {
+    WalletState state = 1;
+}
+
+message GetStateRequest {
+}
+
+message GetStateResponse {
+    WalletState state = 1;
+}

package/dist/proto/swapserverrpc/common.proto

@@ -0,0 +1,37 @@
+syntax = "proto3";
+
+// We can't change this to swapserverrpc, it would be a breaking change because
+// the package name is also contained in the HTTP URIs and old clients would
+// call the wrong endpoints. Luckily with the go_package option we can have
+// different golang and RPC package names to fix protobuf namespace conflicts.
+package looprpc;
+
+option go_package = "github.com/lightninglabs/loop/swapserverrpc";
+
+message HopHint {
+    // The public key of the node at the start of the channel.
+    string node_id = 1;
+
+    // The unique identifier of the channel.
+    uint64 chan_id = 2;
+
+    // The base fee of the channel denominated in millisatoshis.
+    uint32 fee_base_msat = 3;
+
+    /*
+    The fee rate of the channel for sending one satoshi across it denominated in
+    millionths of a satoshi.
+    */
+    uint32 fee_proportional_millionths = 4;
+
+    // The time-lock delta of the channel.
+    uint32 cltv_expiry_delta = 5;
+}
+
+message RouteHint {
+    /*
+    A list of hop hints that when chained together can assist in reaching a
+    specific destination.
+    */
+    repeated HopHint hop_hints = 1;
+}

package/dist/proto/tapchannel.proto

@@ -0,0 +1,306 @@
+syntax = "proto3";
+
+package tapchannelrpc;
+
+option go_package = "github.com/lightninglabs/taproot-assets/taprpc/tapchannelrpc";
+
+import "rfqrpc/rfq.proto";
+import "lightning.proto";
+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
+    does not perform any checks on the data provided, other than pure format
+    validation.
+    */
+    rpc EncodeCustomRecords (EncodeCustomRecordsRequest)
+        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
+    amount.
+    */
+    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. 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 or group key and returns the invoice amount expressed in asset
+    units along side the normal information.
+    */
+    rpc DecodeAssetPayReq (AssetPayReq) returns (AssetPayReqResponse);
+}
+
+message FundChannelRequest {
+    // The asset amount to fund the channel with. The BTC amount is fixed and
+    // cannot be customized (for now).
+    uint64 asset_amount = 1;
+
+    // The asset ID to use for the channel funding.
+    bytes asset_id = 2;
+
+    // The public key of the peer to open the channel with. Must already be
+    // connected to this peer.
+    bytes peer_pubkey = 3;
+
+    // The channel funding fee rate in sat/vByte.
+    uint32 fee_rate_sat_per_vbyte = 4;
+
+    // The number of satoshis to give the remote side as part of the initial
+    // commitment state. This is equivalent to first opening a channel and then
+    // sending the remote party funds, but all done in one step. Therefore, this
+    // 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 {
+    // The channel funding transaction ID.
+    string txid = 1;
+
+    // The index of the channel funding output in the funding transaction.
+    int32 output_index = 2;
+}
+
+message RouterSendPaymentData {
+    // The string encoded asset ID to amount mapping. Instructs the router to
+    // use these assets in the given amounts for the payment. Can be empty for
+    // a payment of an invoice, if the RFQ ID is set instead.
+    map<string, uint64> asset_amounts = 1;
+
+    // The RFQ ID to use for the payment. Can be empty for a direct keysend
+    // payment that doesn't involve any conversion (and thus no RFQ).
+    bytes rfq_id = 2;
+}
+
+message EncodeCustomRecordsRequest {
+    oneof input {
+        // The custom records to encode for a payment request.
+        RouterSendPaymentData router_send_payment = 1;
+    }
+}
+
+message EncodeCustomRecordsResponse {
+    // The encoded custom records in TLV format.
+    map<uint64, bytes> custom_records = 1;
+}
+
+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. Mutually exclusive to group_key.
+    bytes asset_id = 1;
+
+    // The asset amount to send in a keysend payment. This amount is ignored for
+    // invoice payments as the asset amount is negotiated through RFQ with the
+    // peer, depending on the invoice amount. This can also be left unset if RFQ
+    // negotiation was already done beforehand and
+    // payment_request.first_hop_custom_records already contains valid RFQ data.
+    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. 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
+    // they do for lnd's routerrpc.SendPaymentV2 RPC method (see the API docs
+    // at https://lightning.engineering/api-docs/api/lnd/router/send-payment-v2
+    // for more details).
+    // To send a keysend payment, the payment_request.dest_custom_records must
+    // contain a valid keysend record (key 5482373484 and a 32-byte preimage
+    // that corresponds to the payment hash).
+    routerrpc.SendPaymentRequest payment_request = 4;
+
+    // The rfq id to use for this payment. If the user sets this value then the
+    // payment will immediately be dispatched, skipping the rfq negotiation
+    // phase, and using the following rfq id instead.
+    bytes rfq_id = 5;
+
+    // If a small invoice should be paid that is below the amount that always
+    // needs to be sent out to carry a single asset unit, then by default the
+    // payment is rejected. If this flag is set, then the payment will be
+    // allowed to proceed, even if it is uneconomical, meaning that more sats
+    // 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 {
+    oneof result {
+        // In case channel assets need to be swapped to another asset, an asset
+        // 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;
+
+        // 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. 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. When specified only quotes with
+    // this peer will be negotiated.
+    bytes peer_pubkey = 3;
+
+    // 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).
+    //
+    // 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 {
+    // The quote for the purchase of assets that was accepted by the peer.
+    rfqrpc.PeerAcceptedBuyQuote accepted_buy_quote = 1;
+
+    // The result of the invoice creation.
+    lnrpc.AddInvoiceResponse invoice_result = 2;
+}
+
+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 {
+    // The invoice amount, expressed in asset units.
+    uint64 asset_amount = 1;
+
+    // The decimal display corresponding to the asset_id.
+    taprpc.DecimalDisplay decimal_display = 2;
+
+    // The group the asset ID belong to, if applicable.
+    taprpc.AssetGroup asset_group = 3;
+
+    // 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).
+    taprpc.GenesisInfo genesis_info = 4;
+
+    // The normal decoded payment request.
+    lnrpc.PayReq pay_req = 5;
+}

package/dist/proto/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;
+}