From 6414147e6137b4fd8c2e67e2a726c8a12021d647 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Severin=20Alexander=20B=C3=BChler?= <8782386+SeverinAlexB@users.noreply.github.com> Date: Thu, 27 Jul 2023 12:54:53 +0300 Subject: [PATCH] Main Readme Update (#43) * updated main readme * grammer fix * Removed deprecated LSPS1 * Update README.md Co-authored-by: Elias Rohrer * Added draft status --------- Co-authored-by: Elias Rohrer --- OpenAPI/LSPS1.json | 259 --------------------------------------------- OpenAPI/LSPS1.yaml | 181 ------------------------------- README.md | 32 +++--- channel-request.md | 100 ----------------- 4 files changed, 17 insertions(+), 555 deletions(-) delete mode 100644 OpenAPI/LSPS1.json delete mode 100644 OpenAPI/LSPS1.yaml delete mode 100644 channel-request.md diff --git a/OpenAPI/LSPS1.json b/OpenAPI/LSPS1.json deleted file mode 100644 index bd00fe8..0000000 --- a/OpenAPI/LSPS1.json +++ /dev/null @@ -1,259 +0,0 @@ -{ - "swagger": "2.0", - "info": { - "description": "API documentation for channel opening request from a Lightning Network Service Provider (LSP)", - "version": "0.0.0", - "title": "LSP Spec 1" - }, - "tags": [ - { - "name": "Channel Request" - } - ], - "schemes": [ - "https" - ], - "x-readme": { - "explorer-enabled": true, - "samples-enabled": true, - "samples-languages": [ - "curl" - ] - }, - "paths": { - "/lsp/channel": { - "post": { - "tags": [ - "Channel Request" - ], - "summary": "Request a new channel opening from LSP", - "description": "This endpoint accepts arguments for a channel with a specific size and duration and returns an order information", - "operationId": "new-channel-request", - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "parameters": [ - { - "in": "body", - "name": "Channel request", - "description": "Requested channel parameters.", - "schema": { - "$ref": "#/definitions/ChannelOrderRequest" - } - } - ], - "responses": { - "200": { - "description": "Information for channel order", - "schema": { - "$ref": "#/definitions/ChannelOrderResponse" - } - } - } - }, - "get": { - "tags": [ - "Channel Request" - ], - "summary": "Get information about a channel order.", - "description": "Get information about a channel order", - "operationId": "get-channel-order", - "produces": [ - "application/json" - ], - "parameters": [ - { - "in": "query", - "name": "order id", - "description": "Order id of the channel", - "type": "string" - } - ], - "responses": { - "200": { - "description": "Channel information", - "schema": { - "$ref": "#/definitions/ChannelInformation" - } - } - } - } - } - }, - "definitions": { - "ChannelOrderRequest": { - "type": "object", - "required": [ - "node_connection_info" - ], - "properties": { - "node_connection_info": { - "type": "string", - "description": "pubkey@host:port" - }, - "remote_balance": { - "type": "integer", - "description": "Inbound liquidity amount in satoshis" - }, - "local_balance": { - "type": "integer", - "description": "Outbound liquidity amount in satoshis" - }, - "on_chain_fee_rate": { - "type": "number", - "description": "On-chain fee rate of the channel opening transaction in satoshis per vbyte" - }, - "channel_expiry": { - "type": "integer", - "description": "Channel expiration in weeks. " - } - } - }, - "ChannelOrderResponse": { - "type": "object", - "properties": { - "order_id": { - "type": "string", - "description": "An lsp generated order id used to look-up the status of this request" - }, - "order_total": { - "type": "integer", - "description": "The total fee plus the local_balance requested" - }, - "fee_total": { - "type": "integer", - "description": "The total fee the LSP will charge to open this channel" - }, - "fee_per_payment": { - "type": "integer", - "description": "For intercepted payment of fee, fee taken from each payment until fee is paid" - }, - "scid": { - "type": "string", - "description": "The scid user puts in the route hint of invoice to identify order" - }, - "ln_invoice": { - "type": "string", - "description": "A lightning bolt11 invoice to pay the fee for this channel open" - }, - "btc_address": { - "type": "string", - "description": "An on-chain bitcoin address to pay the fee for this channel open" - }, - "lnurl_channel": { - "type": "string", - "description": "LNURL channel request uri" - } - } - }, - "ChannelInformation": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "An lsp generated order id used to look-up the status of this request" - }, - "created_at": { - "description": "Number of seconds since epoch when this order was created", - "type": "number" - }, - "local_balance": { - "description": "Local balance in sats requested by client", - "type": "number" - }, - "remote_balance": { - "description": "Remote balance in sats requested by client", - "type": "number" - }, - "channel_expiry": { - "description": "Channel expiry in weeks requested by client", - "type": "number" - }, - "channel_expiry_ts": { - "description": "Number of seconds since epoch when the channel can be closed", - "type": "number" - }, - "order_expiry_ts": { - "description": "Number of seconds since epoch when this order can still be paid", - "type": "number" - }, - "order_total": { - "description": "The total fee plus the local_balance requested", - "type": "number" - }, - "fee_total": { - "description": "The total fee the lsp will charge to open this channel", - "type": "number" - }, - "fee_per_payment": { - "description": "For intercepted payment of fee, fee taken from each payment until fee is paid", - "type": "number" - }, - "scid": { - "description": "The scid user puts in the route hint of invoice to identify order", - "type": "string" - }, - "ln_invoice": { - "description": "A lightning bolt11 invoice to pay the fee for this channel open", - "type": "string" - }, - "btc_address": { - "description": "An on-chain bitcoin address to pay the fee for this channel open ", - "type": "string" - }, - "order_id": { - "description": "An lsp generated order id used to look-up the status of this request", - "type": "string" - }, - "lnurl_channel": { - "description": "A way to request the open via lnurl after the order is paid", - "type": "string" - }, - "amount_paid": { - "description": "Amount paid by client so far in sats", - "type": "number" - }, - "node_connection_info": { - "description": "The node_connection_info for the node to open the channel to", - "type": "string" - }, - "channel_open_tx": { - "description": "The txid of the channel funding tx once it is broadcast", - "type": "string" - }, - "state": { - "description": "The state of the order", - "type": "string" - }, - "onchain_payments": { - "description": "A list of payments received to btc_address on-chain |", - "type": "array", - "items": { - "type": "object", - "properties": { - "height": { - "type": "integer", - "description": "Transaction block height" - }, - "hash": { - "type": "string", - "description": "Transaction id" - }, - "amount": { - "type": "integer", - "description": "Transaction amount" - }, - "zero_conf": { - "type": "boolean", - "description": "If payment was accepted as zero confirmation" - } - } - } - } - } - } - } -} \ No newline at end of file diff --git a/OpenAPI/LSPS1.yaml b/OpenAPI/LSPS1.yaml deleted file mode 100644 index f16a1ff..0000000 --- a/OpenAPI/LSPS1.yaml +++ /dev/null @@ -1,181 +0,0 @@ -swagger: "2.0" -info: - description: "API documentation for channel opening request from a Lightning Network Service Provider (LSP)" - version: "0.0.0" - title: "LSP Spec 1" -tags: -- name: "Channel Request" -schemes: -- "https" -x-readme: - explorer-enabled: true - samples-enabled: true - samples-languages: - - curl -paths: - /lsp/channel: - post: - tags: - - "Channel Request" - summary: "Request a new channel opening from LSP" - description: "This endpoint accepts arguments for a channel with a specific size and duration and returns an order information" - operationId: "new-channel-request" - consumes: - - "application/json" - produces: - - "application/json" - parameters: - - in: body - name: Channel request - description: Requested channel parameters. - schema: - $ref: "#/definitions/ChannelOrderRequest" - responses: - "200": - description: "Information for channel order" - schema: - $ref: "#/definitions/ChannelOrderResponse" - get: - tags: - - "Channel Request" - summary: "Get information about a channel order." - description: "Get information about a channel order" - operationId: "get-channel-order" - produces: - - "application/json" - parameters: - - in: query - name: order id - description: Order id of the channel - type: string - responses: - "200": - description: "Channel information" - schema: - $ref: "#/definitions/ChannelInformation" -definitions: - ChannelOrderRequest: - type: "object" - required: - - node_connection_info - properties: - node_connection_info: - type: string - description: "pubkey@host:port" - remote_balance: - type: integer - description: "Inbound liquidity amount in satoshis" - local_balance: - type: integer - description: "Outbound liquidity amount in satoshis" - on_chain_fee_rate: - type: number - description: "On-chain fee rate of the channel opening transaction in satoshis per vbyte" - channel_expiry: - type: integer - description: "Channel expiration in weeks. " - ChannelOrderResponse: - type: "object" - properties: - order_id: - type: string - description: "An lsp generated order id used to look-up the status of this request" - order_total: - type: integer - description: "The total fee plus the local_balance requested" - fee_total: - type: integer - description: "The total fee the LSP will charge to open this channel" - fee_per_payment: - type: integer - description: "For intercepted payment of fee, fee taken from each payment until fee is paid" - scid: - type: string - description: "The scid user puts in the route hint of invoice to identify order" - ln_invoice: - type: string - description: "A lightning bolt11 invoice to pay the fee for this channel open" - btc_address: - type: string - description: "An on-chain bitcoin address to pay the fee for this channel open" - lnurl_channel: - type: "string" - description: "LNURL channel request uri" - ChannelInformation: - type: "object" - properties: - id: - type: string - description: "An lsp generated order id used to look-up the status of this request" - created_at: - description: "Number of seconds since epoch when this order was created" - type: "number" - local_balance: - description: "Local balance in sats requested by client" - type: "number" - remote_balance: - description: "Remote balance in sats requested by client" - type: "number" - channel_expiry: - description: "Channel expiry in weeks requested by client" - type: "number" - channel_expiry_ts: - description: "Number of seconds since epoch when the channel can be closed" - type: "number" - order_expiry_ts: - description: "Number of seconds since epoch when this order can still be paid" - type: "number" - order_total: - description: "The total fee plus the local_balance requested" - type: "number" - fee_total: - description: "The total fee the lsp will charge to open this channel" - type: "number" - fee_per_payment: - description: "For intercepted payment of fee, fee taken from each payment until fee is paid" - type: "number" - scid: - description: "The scid user puts in the route hint of invoice to identify order" - type: "string" - ln_invoice: - description: "A lightning bolt11 invoice to pay the fee for this channel open" - type: "string" - btc_address: - description: "An on-chain bitcoin address to pay the fee for this channel open " - type: "string" - order_id: - description: "An lsp generated order id used to look-up the status of this request" - type: "string" - lnurl_channel: - description: "A way to request the open via lnurl after the order is paid" - type: "string" - amount_paid: - description: "Amount paid by client so far in sats" - type: "number" - node_connection_info: - description: "The node_connection_info for the node to open the channel to" - type: "string" - channel_open_tx: - description: "The txid of the channel funding tx once it is broadcast" - type: "string" - state: - description: "The state of the order" - type: "string" - onchain_payments: - description: "A list of payments received to btc_address on-chain |" - type: "array" - items: - type: object - properties: - height: - type: integer - description: "Transaction block height" - hash: - type: string - description: "Transaction id" - amount: - type: integer - description: "Transaction amount" - zero_conf: - type: boolean - description: "If payment was accepted as zero confirmation" \ No newline at end of file diff --git a/README.md b/README.md index 43d4821..eda502e 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,23 @@ # Lightning Service Provider Spec -API specifications for Lightning Service Providers +API specifications for Lightning Service Providers (LSP) -The current scope is limited to channel sales and services specifically about your channel and the peer that provides it. +The goal of this repository is to provide a unified API specification for Lightning Service Providers (LSP) to create interoperability between different Lightning Network wallets/clients and LSPs. -Once the important aspects are covered, we may work on liquidity marketplace concepts, and other wallet or info services. +The group meets every second week on Wednesday 11am UTC. The meeting is open to everyone. Please join the [Telegram group][] for more information. +- [Telegram group][] +- [Meeting transcriptions](https://github.com/BitcoinAndLightningLayerSpecs/meetings) + +[Telegram group]: https://t.me/LSPstandards ## Status Specification All LSPS specifications include a "Status" field. "Status" can be one of the following: +* "Draft" - The specification is still under active development and + subject to change. Implementation is not recommended at this + time. * "For Implementation" - The specification has been widely reviewed by LSPS participants, is believed to have addressed all raised issues, and LSPS participants recommend this specification to be @@ -26,23 +33,18 @@ All LSPS specifications include a "Status" field. ### **LSPS0** [Transport Layer](LSPS0/README.md) Describes the basics of how clients and LSPs communicate to each other. -### **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 in alphabetic order 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 | -| Breez | [Breez](https://github.com/breez/lspd/blob/master/rpc/lspd.md) / LSPS1 | In production / Soon | -| LNBIG | ? | ? | -| SwissRouting | ? | ? | -| TBD | ? | ? | -| ZeroFeeRouting | ? | ? | +| Name | Specs | Status | +| ------------ | ----------- | ------ | +| Blocktank | - | - | +| Breez | - | - | +| c= | - | - | + + diff --git a/channel-request.md b/channel-request.md deleted file mode 100644 index 812d6ac..0000000 --- a/channel-request.md +++ /dev/null @@ -1,100 +0,0 @@ -# LSP channel request - - -## Version: 0.0.1 - -### /lsp/channel - -#### POST -##### Summary - -Request an inbound channel - -##### Description - -Request an inbound channel with a specific size and duration. - -##### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ------ | -| node_connection_info | body | pubkey or pubkey@host:port | Yes | string | -| remote_balance | body | Inbound liquidity amount in satoshis | No | integer | -| local_balance | body | Outbound liqudity amount in satoshis | No | integer | -| on_chain_fee_rate | body | On-chain fee rate of the channel opening transaction in satoshis per vbyte | No | number | -| channel_expiry | body | Channel expiration in weeks | No | integer | - - -##### Response - -| Name | Description | Schema | -| ---- | ----------- | ------ | -| order_total | The total fee plus the local_balance requested | number | -| fee_total | The total fee the lsp will charge to open this channel | number | -| fee_per_payment | For intercepted payment of fee, fee taken from each payment until fee is paid | number | -| temporary_scid | The scid user puts in the route hint of invoice to identify order | string | -| lsp_connection_info | pubkey or pubkey@host:port | string | -| ln_invoice | A lightning bolt11 invoice to pay the fee for this channel open | string | -| btc_address | An on-chain bitcoin address to pay the fee for this channel open | string | -| order_id | An lsp generated order id used to look-up the status of this request | string | -| lnurl_channel | A way to request the open via lnurl after the order is paid | string | - -### /lsp/channel - -#### GET -##### Summary - -Get information about a channel order - -##### Description - -Get information about a channel order - -##### Parameters - -| Name | Located in | Description | Required | Schema | -| ---- | ---------- | ----------- | -------- | ---- | -| id | query | order_id provided in response to channel request or scid | Yes | string | - -##### Response - -| Name | Description | Schema | -| ---- | ----------- | ------ | -| order_id | The order id | string | -| created_at | Number of seconds since epoch when this order was created | number | -| local_balance | Local balance in sats requested by client | number | -| remote_balance | Remote balance in sats requested by client | number | -| channel_expiry | Channel expiry in weeks requested by client | number | -| channel_expiry_ts | Number of seconds since epoch when the channel can be closed | number | -| order_expiry_ts | Number of seconds since epoch when this order can still be paid | number | -| order_total | The total fee plus the local_balance requested | number | -| fee_total | The total fee the lsp will charge to open this channel | number | -| fee_per_payment | For intercepted payment of fee, fee taken from each payment until fee is paid | number | -| temporary_scid | The scid user puts in the route hint of invoice to identify order | string | -| scid | The scid of the channel if already established | string | -| lsp_connection_info | pubkey or pubkey@host:port of the lsp node | string | -| ln_invoice | A lightning bolt11 invoice to pay the fee for this channel open | string | -| btc_address | An on-chain bitcoin address to pay the fee for this channel open | string | -| lnurl_channel | A way to request the open via lnurl after the order is paid | string | -| amount_paid | Amount paid by client so far in sats | number | -| node_connection_info | The node_connection_info for the node to open the channel to | string | -| channel_open_tx | The txid of the channel funding tx once it is broadcast | string | -| state | The state of the order | string | -| onchain_payments | A list of payments received to btc_address on-chain | object[] | - - -###### Order state enum - -| State | Description | -|---------------- |--------------------------------------------------------------------------------------- | -| CREATED | The order has been created but the user hasn't paid yet. | -| UNDER_FUNDED | Funding received but under paid. | -| PENDING | Order is paid but the channel has not been opened yet. | -| OPENING | The opening transaction has been broadcasted. 0conf might skip directly to OPENED. | -| OPENED | Channel is open and has the necessary block confirmations. | -| CLOSING | The closing transaction has been broadcasted. | -| CLOSED | Channel is closed and has the necessary block confirmations. | -| FAILED | Any error. For example, the LSP couldn't connect to the target node. | -| REFUNDED | Payment has been refunded. | -| OFFER_EXPIRED | Order has not been paid and offer has therefore expired. | -