From 86dd2da3eb15408405dde74dcd14d19727d6fcfd Mon Sep 17 00:00:00 2001 From: rbndg Date: Wed, 6 Jul 2022 18:10:23 +1000 Subject: [PATCH 1/3] Channel request spec --- channelrequest.md | 174 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 channelrequest.md diff --git a/channelrequest.md b/channelrequest.md new file mode 100644 index 0000000..85c3ebd --- /dev/null +++ b/channelrequest.md @@ -0,0 +1,174 @@ +# LSP channel request + + +## Version: 0.0.1 + +### /node/info + +#### GET +##### Summary + +Returns general service information about LSP + +##### Description + +Returns information about LSP Lightning node and services on offer. + +##### Responses + +| Code | Description | +| ---- | ----------- | +| 200 | Node and service info | + +### /channel/buy + +#### POST +##### Summary + +Request a channel to purchase. + +##### Description + +Request a channel to purchase. + +##### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ---- | +| Channel request | body | Channel to purchase. | Yes | object | + +##### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Channel quote | [ChannelQuote](#channelquote) | + +### /channel/manual_finalise + +#### POST +##### Summary + +Finalise a purchased channel + +##### Description + +Set the node that LSP will open a channel to after paying for your channel. + +##### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ---- | +| Channel request | body | Channel to purchase. | Yes | object | + +##### Responses + +| Code | Description | +| ---- | ----------- | +| 200 | Channel claimed | + +### /channel/order + +#### GET +##### Summary + +Get an order + +##### Description + +Get all information regarding a channel order + +##### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ---- | +| order_id | query | Order id. | Yes | string | + +##### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | Channel quote | [ChannelOrder](#channelorder) | + +### /lnurl/channel + +#### GET +##### Summary + +LN URL connect to node + +##### Description + +LNURL Channel + +##### Parameters + +| Name | Located in | Description | Required | Schema | +| ---- | ---------- | ----------- | -------- | ---- | +| order_id | query | Required for LNURL connect | Yes | string | +| k1 | query | Required for LNURL callback | Yes | string | +| remote_id | query | Required for LNURL callback. Remote node address of form node_key@ip_address:port_number | Yes | string | + +##### Responses + +| Code | Description | Schema | +| ---- | ----------- | ------ | +| 200 | LNURL connect | [LNURLConnect](#lnurlconnect) | + +### Models + +#### LNURLConnect + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| k1 | string | order id | Yes | +| tag | string | | Yes | +| callback | string | A second-level URL which would initiate an OpenChannel message from target LN node | Yes | +| uri | string | LSP node info | Yes | +| status | string | Response status
_Enum:_ `"OK"`, `"ERROR"` | Yes | +| reason | string | Error reason | Yes | + +#### ChannelQuote + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| order_id | string | | Yes | +| ln_invoice | string | | Yes | +| total_amount | integer | | Yes | +| btc_address | string | | Yes | +| lnurl_channel | string | | Yes | + +#### ChannelOrder + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| _id | string | Order id | Yes | +| local_balance | integer | | Yes | +| remote_balance | integer | | Yes | +| channel_expiry | integer | Channel expiry is in weeks. | Yes | +| channel_expiry_ts | integer | LSP has the righ to close the channel after this time | Yes | +| order_expiry | integer | order is valid until this time | Yes | +| total_amount | integer | total amount payable by customer | Yes | +| btc_address | string | Destination address for on chain payments | Yes | +| created_at | integer | Time that the order was created | Yes | +| amount_received | number | how much satoshi orders has recieved | Yes | +| remote_node | object | | Yes | +| channel_open_tx | object | | Yes | +| purchase_invoice | string | | Yes | +| lnurl | object | LNUrl channel object | Yes | +| state | [OrderStates](#orderstates) | | Yes | +| onchain_payments | [ object ] | | Yes | + +#### OrderStates + +Order state can be one of the following + +| Name | Type | Description | Required | +| ---- | ---- | ----------- | -------- | +| CREATED | number | Order has been created | Yes | +| PAID | number | Order has been paid | Yes | +| URI_SET | number | Order has been paid and node uri is set | Yes | +| OPENING | number | Lightning channel is opening | Yes | +| CLOSING | number | Lightning channel is closing | Yes | +| GIVE_UP | number | Gave up opening channel | Yes | +| CLOSED | number | Lightning channel has been closed | Yes | +| OPEN | number | Lightning channel is open | Yes | From af107a3849d13f1893d3d0b0c84d6fcbb1852828 Mon Sep 17 00:00:00 2001 From: rbndg Date: Wed, 17 Aug 2022 14:14:34 +1000 Subject: [PATCH 2/3] README update --- README.md | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index bd586e2..d92b828 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,29 @@ -# lsp +# Lightning Service Provider Spec API specifications for Lightning Service Providers The current scope is limited to channel sales and services specifically about your channel and the peer that provides it. Once the important aspects are covered, we may work on liquidity marketplace concepts, and other wallet or info services. + + +## Specs + +### **LSPS.1** [Channel Request](channel-request.md) +A unified channel request API standard for services to buy channels from LSP. This spec supports both just in time channel openings and pre paid channels + + + +## Services +List of Lightning Service Providers that currently or will support LSP specs in future. + +(If you would like to get added to this list, please open a PR and update the table below) + +| Name | Specs | Status | +| ---- | ----------- | ------ | +| Blocktank | LSPS1 | Soon | +| ZeroFeeRouting | ? | ? | +| SwissRouting | ? | ? | +| LNBIG | ? | ? | +| TBD | ? | ? | + + From f089b8755de23d11af22b4861d9a8af77ffde9f2 Mon Sep 17 00:00:00 2001 From: rbndg Date: Wed, 17 Aug 2022 14:15:08 +1000 Subject: [PATCH 3/3] Removed unused spec proposals --- channelrequest.md | 174 ------------------------------ open-channel-via-ln-payment.md | 186 --------------------------------- 2 files changed, 360 deletions(-) delete mode 100644 channelrequest.md delete mode 100644 open-channel-via-ln-payment.md diff --git a/channelrequest.md b/channelrequest.md deleted file mode 100644 index 85c3ebd..0000000 --- a/channelrequest.md +++ /dev/null @@ -1,174 +0,0 @@ -# LSP channel request - - -## Version: 0.0.1 - -### /node/info - -#### GET -##### Summary - -Returns general service information about LSP - -##### Description - -Returns information about LSP Lightning node and services on offer. - -##### Responses - -| Code | Description | -| ---- | ----------- | -| 200 | Node and service info | - -### /channel/buy - -#### POST -##### Summary - -Request a channel to purchase. - -##### Description - -Request a channel to purchase. - -##### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| Channel request | body | Channel to purchase. | Yes | object | - -##### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Channel quote | [ChannelQuote](#channelquote) | - -### /channel/manual_finalise - -#### POST -##### Summary - -Finalise a purchased channel - -##### Description - -Set the node that LSP will open a channel to after paying for your channel. - -##### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| Channel request | body | Channel to purchase. | Yes | object | - -##### Responses - -| Code | Description | -| ---- | ----------- | -| 200 | Channel claimed | - -### /channel/order - -#### GET -##### Summary - -Get an order - -##### Description - -Get all information regarding a channel order - -##### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| order_id | query | Order id. | Yes | string | - -##### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | Channel quote | [ChannelOrder](#channelorder) | - -### /lnurl/channel - -#### GET -##### Summary - -LN URL connect to node - -##### Description - -LNURL Channel - -##### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| order_id | query | Required for LNURL connect | Yes | string | -| k1 | query | Required for LNURL callback | Yes | string | -| remote_id | query | Required for LNURL callback. Remote node address of form node_key@ip_address:port_number | Yes | string | - -##### Responses - -| Code | Description | Schema | -| ---- | ----------- | ------ | -| 200 | LNURL connect | [LNURLConnect](#lnurlconnect) | - -### Models - -#### LNURLConnect - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| k1 | string | order id | Yes | -| tag | string | | Yes | -| callback | string | A second-level URL which would initiate an OpenChannel message from target LN node | Yes | -| uri | string | LSP node info | Yes | -| status | string | Response status
_Enum:_ `"OK"`, `"ERROR"` | Yes | -| reason | string | Error reason | Yes | - -#### ChannelQuote - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| order_id | string | | Yes | -| ln_invoice | string | | Yes | -| total_amount | integer | | Yes | -| btc_address | string | | Yes | -| lnurl_channel | string | | Yes | - -#### ChannelOrder - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| _id | string | Order id | Yes | -| local_balance | integer | | Yes | -| remote_balance | integer | | Yes | -| channel_expiry | integer | Channel expiry is in weeks. | Yes | -| channel_expiry_ts | integer | LSP has the righ to close the channel after this time | Yes | -| order_expiry | integer | order is valid until this time | Yes | -| total_amount | integer | total amount payable by customer | Yes | -| btc_address | string | Destination address for on chain payments | Yes | -| created_at | integer | Time that the order was created | Yes | -| amount_received | number | how much satoshi orders has recieved | Yes | -| remote_node | object | | Yes | -| channel_open_tx | object | | Yes | -| purchase_invoice | string | | Yes | -| lnurl | object | LNUrl channel object | Yes | -| state | [OrderStates](#orderstates) | | Yes | -| onchain_payments | [ object ] | | Yes | - -#### OrderStates - -Order state can be one of the following - -| Name | Type | Description | Required | -| ---- | ---- | ----------- | -------- | -| CREATED | number | Order has been created | Yes | -| PAID | number | Order has been paid | Yes | -| URI_SET | number | Order has been paid and node uri is set | Yes | -| OPENING | number | Lightning channel is opening | Yes | -| CLOSING | number | Lightning channel is closing | Yes | -| GIVE_UP | number | Gave up opening channel | Yes | -| CLOSED | number | Lightning channel has been closed | Yes | -| OPEN | number | Lightning channel is open | Yes | diff --git a/open-channel-via-ln-payment.md b/open-channel-via-ln-payment.md deleted file mode 100644 index 6e3b38f..0000000 --- a/open-channel-via-ln-payment.md +++ /dev/null @@ -1,186 +0,0 @@ -# Protocol Documentation - - -## Table of Contents - -- [lspd.proto](#lspd.proto) - - [ChannelInformationReply](#lspd.ChannelInformationReply) - - [ChannelInformationRequest](#lspd.ChannelInformationRequest) - - [OpenChannelReply](#lspd.OpenChannelReply) - - [OpenChannelRequest](#lspd.OpenChannelRequest) - - [PaymentInformation](#lspd.PaymentInformation) - - [RegisterPaymentReply](#lspd.RegisterPaymentReply) - - [RegisterPaymentRequest](#lspd.RegisterPaymentRequest) - - - - - [ChannelOpener](#lspd.ChannelOpener) - - -- [Scalar Value Types](#scalar-value-types) - - - - -

Top

- -## lspd.proto - - - - - -### ChannelInformationReply - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [string](#string) | | The name of of lsp | -| pubkey | [string](#string) | | The identity pubkey of the Lightning node | -| host | [string](#string) | | The network location of the lightning node, e.g. `12.34.56.78:9012` or / `localhost:10011` | -| channel_capacity | [int64](#int64) | | The channel capacity in satoshis | -| target_conf | [int32](#int32) | | The target number of blocks that the funding transaction should be / confirmed by. | -| base_fee_msat | [int64](#int64) | | The base fee charged regardless of the number of milli-satoshis sent. | -| fee_rate | [double](#double) | | The effective fee rate in milli-satoshis. The precision of this value goes / up to 6 decimal places, so 1e-6. | -| time_lock_delta | [uint32](#uint32) | | The required timelock delta for HTLCs forwarded over the channel. | -| min_htlc_msat | [int64](#int64) | | The minimum value in millisatoshi we will require for incoming HTLCs on / the channel. | -| channel_fee_permyriad | [int64](#int64) | | | -| lsp_pubkey | [bytes](#bytes) | | | - - - - - - - - -### ChannelInformationRequest - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| pubkey | [string](#string) | | The identity pubkey of the Lightning node | - - - - - - - - -### OpenChannelReply - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| tx_hash | [string](#string) | | The transaction hash | -| output_index | [uint32](#uint32) | | The output index | - - - - - - - - -### OpenChannelRequest - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| pubkey | [string](#string) | | The identity pubkey of the Lightning node | - - - - - - - - -### PaymentInformation - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| payment_hash | [bytes](#bytes) | | | -| payment_secret | [bytes](#bytes) | | | -| destination | [bytes](#bytes) | | | -| incoming_amount_msat | [int64](#int64) | | | -| outgoing_amount_msat | [int64](#int64) | | | - - - - - - - - -### RegisterPaymentReply - - - - - - - - - -### RegisterPaymentRequest - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| blob | [bytes](#bytes) | | | - - - - - - - - - - - - - - -### ChannelOpener - - -| Method Name | Request Type | Response Type | Description | -| ----------- | ------------ | ------------- | ------------| -| ChannelInformation | [ChannelInformationRequest](#lspd.ChannelInformationRequest) | [ChannelInformationReply](#lspd.ChannelInformationReply) | | -| OpenChannel | [OpenChannelRequest](#lspd.OpenChannelRequest) | [OpenChannelReply](#lspd.OpenChannelReply) | | -| RegisterPayment | [RegisterPaymentRequest](#lspd.RegisterPaymentRequest) | [RegisterPaymentReply](#lspd.RegisterPaymentReply) | | - - - - - -## Scalar Value Types - -| .proto Type | Notes | C++ Type | Java Type | Python Type | -| ----------- | ----- | -------- | --------- | ----------- | -| double | | double | double | float | -| float | | float | float | float | -| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | -| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | -| uint32 | Uses variable-length encoding. | uint32 | int | int/long | -| uint64 | Uses variable-length encoding. | uint64 | long | int/long | -| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | -| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | -| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | -| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | -| sfixed32 | Always four bytes. | int32 | int | int | -| sfixed64 | Always eight bytes. | int64 | long | int/long | -| bool | | bool | boolean | boolean | -| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | -| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | -