From 98396dd6cd359827ce91dbdfd25bc7a92887c93b Mon Sep 17 00:00:00 2001 From: Dr Maxim Orlovsky Date: Mon, 1 Nov 2021 15:11:43 +0100 Subject: [PATCH 1/4] Bifrost base spec --- lnpbp-0050.md | 152 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 lnpbp-0050.md diff --git a/lnpbp-0050.md b/lnpbp-0050.md new file mode 100644 index 0000000..7f76d61 --- /dev/null +++ b/lnpbp-0050.md @@ -0,0 +1,152 @@ +``` +LNPBP: 0050 +Layer: OSI Application (i7) +Vertical: Lightning network protocol +Title: Bifrost: generalized Lightning network protocol core +Author: Dr Maxim Orlovsky +Comments-URI: https://github.com/LNP-BP/lnpbps/pulls/<____> +Status: Draft +Type: Standards Track +Created: 2021-11-01 +Finalized: not yet +License: CC0-1.0 +``` + +## Abstract + + +## Background + + +## Motivation + +Extending existing lightning network messaging system, defined as part of multiple BOLTs, is hard. The first problem is the necessity to introduce changes to multiple independent standards for each atomic feature; making review and acceptance process very time-consuming. Next, it is hard to implement these features one by one, since they are defined in different places. Finally, there is no place to put feature-specific test vectors in the existing BOLT structure. + +The second problem is separation of new and not yet well tested/experimental functionality from the well-tested existing lightning network core. The separation of experimental protocols and existing tested core functionality is good from the security point of view. + +The third reason is the fact that Lightning network was designed as a payment network and for payment purposes. At the same time, it is possible to create much more advanced forms of non-payment state channels basing on bitcoin transactions (useful for storage and different forms of financial smart contracts), or use lightning network for non-payment data communication (like messaging or DEX). These extensions when put into existing LN spec framework, not suited for such extensibility, will require constant introduction of multiple hacks or complete refactoring of the BOLT specifications. + +Finally, some of lightning network design decisions were proven to be non-efficient in context of more broad applications, for instance use of BigInt encoding is not advised for client-side-validated data […]. It will be impossible to fix such issues without introducing new network communication protocol. + +Bifrost is a proposed new set of standards, defined as a part of LNPBP standards suite, that includes extensible core networking protocol (LNPBP-50, this specification), and specific extensions for different forms of state channel management and network data communications. Current standard is built on top of other LNPBP standards (like strict encoding), BIPs (partially signed bitcoin transactions), parts of BOLT standards (Noise_XK protocol), extracted as a separate LNPBP standards, and puts them into a single well-abstracted protocol suite. + + +## Design + +Design goals: +1. Extensibility, including + - support for non-payment / custom lightning channels + - support for non-payment network messaging & communications + - support for arbitrary extension of channel transaction structure (combining different types of channels) + - support for custom / new route discovery mechanisms +2. Maximal use of existing LNPBP standards, in particular + - LNPBP-7 strict encoding […] + - LNPBP-9 client-side-validation […] + - LNPBP-15 Noise_XK handshake & network encryption (BOLT-8 extract) […] + - LNPBP-18 Native message framing (BOLT-8 extract) […] + - LNPBP-16 handshake over WebSockets […] +3. Privacy: improved re-use of onion messaging from Lightning network + + +## Specification + +Bifrost operates using TCP connection, on top of LNPBP-15 (session & encryption layer) and LNPBP-18 (message framing layer) as application protocol. Default port for Bifrost connection is 9913 (see [rationale](#use-of-dedicated-port)). + +All message fields are encoded with LNPBP-7 strict encoding instead of other types of encoding used in BOLTs / legacy Lightning network. + +### Announcing Bifrost connectivity + +Support for Bifrost protocol can be announced as a part of local features flag ([see why not global](#using-local-features)) in legacy lightning network `init` message, inside `node_announcement`, `channel_announcement` and `channel_update` messages (`INC` context in terms of BOLT-9). Bifrost feature flags should not be used with BOLT-11 invoices; instead, all Bifrost channels MUST use LNPBP-38 invoicing. + +Since BOLT-9 provides no ability to add arbitrary feature flags from outside of the BOLT-defined protocol scope, this feature will be a non-standard. We reserve flag number 255/256 for it (see [rationale](#feature-bit-selection)). + + +### Bifrost URLs + +Bifrost URLs are designed to be compliant with RFC 3986 [1] and consists of `bifrost` as *scheme name*, *authority* in form of node public key, combined with optional network address details, channel id as a *path* and feature parameters and route suggestion as *query*, where both *path* and *query* parts are optional (emphasized words stand for RFC 3986-defined terms): + +`://[/][?]` => +`bifrost://[/][? | ]` + +Host part MUST always include node public key, optionally followed by either IPv4, IPv6 or ONION v3 Tor address. IPv4 and IPv6 addresses may include optional port number, which becomes mandatory if a non-standard Bifrost port is used. The address, if present, MUST be separated from the public key by `+` symbol (see [rationale](#why-URL-uses-plus-instead-of-at-symbol)). + +`bifrost://[+ [:] | ]/[][? | ]` + +Example: + +- Node with a known IPv4 address operating non-standard port: `bifrost://02b39e7040cd9233e1cf86823ea321c1c799534c622c9e8b563a689409962657c7+124.155.54.210:9935` + +- Node with Onion v3 address and path suggestion: `bifrost://02b39e7040cd9233e1cf86823ea321c1c799534c622c9e8b563a689409962657c7+worldehc62cgugrgj7oc76tcna45fme47oqjrei4d4aa7xorw7fyvcyd/?` + + +### Bifrost initiation from legacy Lightning messaging + +Two nodes connected via Lightning network may send each other specific message indicating intent to open Bifrost connection. The message uses onion routing, enabling NAT bypassing, such that a party without NAT may “hole punch” NAT of another party by asking to establish Bifrost connection to its explicit IP address. + +### Establishing connection + + + + +## Compatibility + +### Channels + +Bifrost may be used to operate channels created using legacy Lightning network protocols – until there are changes into the channel structure which make them incompatible with existing BOLT specifications. Also, channels created with Bifrost can be accessed via legacy lightning network until they become incompatible (in their structure) with BOLT specifications. + +Thus, to prevent undefined behavior, it is advised that nodes will maintain each channel either under legacy LN or under Bifrost using the following rules: + +1. If the channel was created in legacy LN it can be moved into Bifrost once and only once – and a dedicated gossip `channel_update` message must be published to the legacy LN with Bifrost even flag set. +2. If the channel was created in Bifrost network, it MAY be announced in the legacy LN only with odd (required) Bifrost flag set. +3. Bifrost channels can’t be operated using legacy LN messaging; a node receiving message referencing to a Bifrost server over the legacy LN MUST respond with `error` message. +4. Legacy LN channels MUST not be operated from Bifrost network before their movement according to the pt. 1. A node receiving Bifrost message for legacy LN channel MUST respond with `error` message. + +In order to enable fallback for Bifrost-managed channels in case of bugs discovered in Bifrost, the following rules SHOULD be supported by Lightning node implementations, but SHOULD not be used until a fallback scenario: + +5. Bifrost channels which maintain BOLT compatibility can be moved back into legacy Lightning network by properly announcing removal of the channel in Bifrost network – and publishing `channel_announcement` (for previously non-announced channels) or `channel_update` gossip messages with all Bifrost feature flags removed + +### Invoices + +All bifrost-operated channels MUST use LNPBP-38 invoices. BOLT-11 invoices MUST NOT be created for any channel which was moved into Bifrost network. + + +## Rationale + +### Use of dedicated port + +Bifrost requires use of a non-LN port to enable simultaneous and independent operations of lightning nodes using both legacy LN messages and Bifrost messages. + +### Why URL uses plus instead of at symbol + +While at* symbol (`@`) is broadly used in legacy Lightning node addresses (`@[:]` form), it can’t be used as a proper part of Bifrost URL since in RFC 3986 it is reserved as a separator for optional username prefix before mandatory host name part – while pubkey is not optional in Bifrost and host is optional. Thus, we replace `@` usage with `+`, since `+` is allowed in RFC 3986 as a separator in host name part of authority field and it semantically defines “additional information”, which is a network address of the node for a given public key. + +### Using local features + +Bifrost support is specified in the local features field of the `init` message since it is against BOLT-9 to use feature bits greater than 13 in the global features field. + +### Feature bit selection + +Bits 255/256 are the largest bit numbers which may be stored by a 32-byte value. It is still far enough from the current used feature bits in BOLT-9 (26/27), allowing another 5 to 10 years without the risk of the conflict (until Bifrost will be recognized) and at the same time does not over-enlarges the size of the feature flag field in `init` and other messages. + + +## Reference implementation + +The current Bifrost reference implementation is provided by [`LNP Core Library`](https://github.com/LNP-BP/lnp-core) and [`LNP Node`](https://github.com/LNP-BP/lnp-node) + +## Acknowledgements + +The authors are thankful to Giacomo Zucco, Christian Decker and Martin Habovštiak for multiple discussions and ideas which led to the creation and shaping of this specification. + + +## References + +1. RFC 3986. Uniform Resource Identifier (URI): Generic Syntax. https://www.rfc-editor.org/rfc/rfc3986#section-3.1 + +## Copyright + +This document is licensed under the Creative Commons CC0 1.0 Universal license. + + +## Test vectors + +TBD \ No newline at end of file From 08def9a1b043ba350d19a68de69472f17e03e947 Mon Sep 17 00:00:00 2001 From: Dr Maxim Orlovsky Date: Thu, 4 Nov 2021 15:54:11 +0100 Subject: [PATCH 2/4] Reformating Bifrost proposal --- lnpbp-0050.md | 162 +++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 127 insertions(+), 35 deletions(-) diff --git a/lnpbp-0050.md b/lnpbp-0050.md index 7f76d61..f943d7e 100644 --- a/lnpbp-0050.md +++ b/lnpbp-0050.md @@ -20,15 +20,41 @@ License: CC0-1.0 ## Motivation -Extending existing lightning network messaging system, defined as part of multiple BOLTs, is hard. The first problem is the necessity to introduce changes to multiple independent standards for each atomic feature; making review and acceptance process very time-consuming. Next, it is hard to implement these features one by one, since they are defined in different places. Finally, there is no place to put feature-specific test vectors in the existing BOLT structure. - -The second problem is separation of new and not yet well tested/experimental functionality from the well-tested existing lightning network core. The separation of experimental protocols and existing tested core functionality is good from the security point of view. - -The third reason is the fact that Lightning network was designed as a payment network and for payment purposes. At the same time, it is possible to create much more advanced forms of non-payment state channels basing on bitcoin transactions (useful for storage and different forms of financial smart contracts), or use lightning network for non-payment data communication (like messaging or DEX). These extensions when put into existing LN spec framework, not suited for such extensibility, will require constant introduction of multiple hacks or complete refactoring of the BOLT specifications. - -Finally, some of lightning network design decisions were proven to be non-efficient in context of more broad applications, for instance use of BigInt encoding is not advised for client-side-validated data […]. It will be impossible to fix such issues without introducing new network communication protocol. - -Bifrost is a proposed new set of standards, defined as a part of LNPBP standards suite, that includes extensible core networking protocol (LNPBP-50, this specification), and specific extensions for different forms of state channel management and network data communications. Current standard is built on top of other LNPBP standards (like strict encoding), BIPs (partially signed bitcoin transactions), parts of BOLT standards (Noise_XK protocol), extracted as a separate LNPBP standards, and puts them into a single well-abstracted protocol suite. +Extending existing lightning network messaging system, defined as part of +multiple BOLTs, is hard. The first problem is the necessity to introduce changes +to multiple independent standards for each atomic feature; making review and +acceptance process very time-consuming. Next, it is hard to implement these +features one by one, since they are defined in different places. Finally, there +is no place to put feature-specific test vectors in the existing BOLT structure. + +The second problem is separation of new and not yet well tested/experimental +functionality from the well-tested existing lightning network core. The +separation of experimental protocols and existing tested core functionality is +good from the security point of view. + +The third reason is the fact that Lightning network was designed as a payment +network and for payment purposes. At the same time, it is possible to create +much more advanced forms of non-payment state channels basing on bitcoin +transactions (useful for storage and different forms of financial smart +contracts), or use lightning network for non-payment data communication (like +messaging or DEX). These extensions when put into existing LN spec framework, +not suited for such extensibility, will require constant introduction of +multiple hacks or complete refactoring of the BOLT specifications. + +Finally, some of lightning network design decisions were proven to be +non-efficient in context of more broad applications, for instance use of BigInt +encoding is not advised for client-side-validated data […]. It will be +impossible to fix such issues without introducing new network communication +protocol. + +Bifrost is a proposed new set of standards, defined as a part of LNPBP standards +suite, that includes extensible core networking protocol (LNPBP-50, this +specification), and specific extensions for different forms of state channel +management and network data communications. Current standard is built on top of +other LNPBP standards (like strict encoding), BIPs (partially signed bitcoin +transactions), parts of BOLT standards (Noise_XK protocol), extracted as a +separate LNPBP standards, and puts them into a single well-abstracted protocol +suite. ## Design @@ -37,7 +63,8 @@ Design goals: 1. Extensibility, including - support for non-payment / custom lightning channels - support for non-payment network messaging & communications - - support for arbitrary extension of channel transaction structure (combining different types of channels) + - support for arbitrary extension of channel transaction structure + (combining different types of channels) - support for custom / new route discovery mechanisms 2. Maximal use of existing LNPBP standards, in particular - LNPBP-7 strict encoding […] @@ -50,38 +77,62 @@ Design goals: ## Specification -Bifrost operates using TCP connection, on top of LNPBP-15 (session & encryption layer) and LNPBP-18 (message framing layer) as application protocol. Default port for Bifrost connection is 9913 (see [rationale](#use-of-dedicated-port)). +Bifrost operates using TCP connection, on top of LNPBP-15 (session & encryption +layer) and LNPBP-18 (message framing layer) as application protocol. Default +port for Bifrost connection is 9913 (see [rationale](#use-of-dedicated-port)). -All message fields are encoded with LNPBP-7 strict encoding instead of other types of encoding used in BOLTs / legacy Lightning network. +All message fields are encoded with LNPBP-7 strict encoding instead of other +types of encoding used in BOLTs / legacy Lightning network. ### Announcing Bifrost connectivity -Support for Bifrost protocol can be announced as a part of local features flag ([see why not global](#using-local-features)) in legacy lightning network `init` message, inside `node_announcement`, `channel_announcement` and `channel_update` messages (`INC` context in terms of BOLT-9). Bifrost feature flags should not be used with BOLT-11 invoices; instead, all Bifrost channels MUST use LNPBP-38 invoicing. +Support for Bifrost protocol can be announced as a part of local features flag +([see why not global](#using-local-features)) in legacy lightning network `init` +message, inside `node_announcement`, `channel_announcement` and `channel_update` +messages (`INC` context in terms of BOLT-9). Bifrost feature flags should not be +used with BOLT-11 invoices; instead, all Bifrost channels MUST use LNPBP-38 +invoicing. -Since BOLT-9 provides no ability to add arbitrary feature flags from outside of the BOLT-defined protocol scope, this feature will be a non-standard. We reserve flag number 255/256 for it (see [rationale](#feature-bit-selection)). +Since BOLT-9 provides no ability to add arbitrary feature flags from outside of +the BOLT-defined protocol scope, this feature will be a non-standard. We reserve +flag number 255/256 for it (see [rationale](#feature-bit-selection)). ### Bifrost URLs -Bifrost URLs are designed to be compliant with RFC 3986 [1] and consists of `bifrost` as *scheme name*, *authority* in form of node public key, combined with optional network address details, channel id as a *path* and feature parameters and route suggestion as *query*, where both *path* and *query* parts are optional (emphasized words stand for RFC 3986-defined terms): +Bifrost URLs are designed to be compliant with RFC 3986 [1] and consists of +`bifrost` as *scheme name*, *authority* in form of node public key, combined +with optional network address details, channel id as a *path* and feature +parameters and route suggestion as *query*, where both *path* and *query* parts +are optional (emphasized words stand for RFC 3986-defined terms): `://[/][?]` => `bifrost://[/][? | ]` -Host part MUST always include node public key, optionally followed by either IPv4, IPv6 or ONION v3 Tor address. IPv4 and IPv6 addresses may include optional port number, which becomes mandatory if a non-standard Bifrost port is used. The address, if present, MUST be separated from the public key by `+` symbol (see [rationale](#why-URL-uses-plus-instead-of-at-symbol)). +Host part MUST always include node public key, optionally followed by either +IPv4, IPv6 or ONION v3 Tor address. IPv4 and IPv6 addresses may include optional +port number, which becomes mandatory if a non-standard Bifrost port is used. The +address, if present, MUST be separated from the public key by `+` symbol (see +[rationale](#why-URL-uses-plus-instead-of-at-symbol)). `bifrost://[+ [:] | ]/[][? | ]` Example: -- Node with a known IPv4 address operating non-standard port: `bifrost://02b39e7040cd9233e1cf86823ea321c1c799534c622c9e8b563a689409962657c7+124.155.54.210:9935` +- Node with a known IPv4 address operating non-standard port: + `bifrost://02b39e7040cd9233e1cf86823ea321c1c799534c622c9e8b563a689409962657c7+124.155.54.210:9935` -- Node with Onion v3 address and path suggestion: `bifrost://02b39e7040cd9233e1cf86823ea321c1c799534c622c9e8b563a689409962657c7+worldehc62cgugrgj7oc76tcna45fme47oqjrei4d4aa7xorw7fyvcyd/?` +- Node with Onion v3 address and path suggestion: + `bifrost://02b39e7040cd9233e1cf86823ea321c1c799534c622c9e8b563a689409962657c7+worldehc62cgugrgj7oc76tcna45fme47oqjrei4d4aa7xorw7fyvcyd/?` ### Bifrost initiation from legacy Lightning messaging -Two nodes connected via Lightning network may send each other specific message indicating intent to open Bifrost connection. The message uses onion routing, enabling NAT bypassing, such that a party without NAT may “hole punch” NAT of another party by asking to establish Bifrost connection to its explicit IP address. +Two nodes connected via Lightning network may send each other specific message +indicating intent to open Bifrost connection. The message uses onion routing, +enabling NAT bypassing, such that a party without NAT may “hole punch” NAT of +another party by asking to establish Bifrost connection to its explicit IP +address. ### Establishing connection @@ -92,50 +143,91 @@ Two nodes connected via Lightning network may send each other specific message i ### Channels -Bifrost may be used to operate channels created using legacy Lightning network protocols – until there are changes into the channel structure which make them incompatible with existing BOLT specifications. Also, channels created with Bifrost can be accessed via legacy lightning network until they become incompatible (in their structure) with BOLT specifications. +Bifrost may be used to operate channels created using legacy Lightning network +protocols – until there are changes into the channel structure which make them +incompatible with existing BOLT specifications. Also, channels created with +Bifrost can be accessed via legacy lightning network until they become +incompatible (in their structure) with BOLT specifications. + +Thus, to prevent undefined behavior, it is advised that nodes will maintain each +channel either under legacy LN or under Bifrost using the following rules: + +1. If the channel was created in legacy LN it can be moved into Bifrost once and + only once – and a dedicated gossip `channel_update` message must be published + to the legacy LN with Bifrost even flag set. + +2. If the channel was created in Bifrost network, it MAY be announced in the + legacy LN only with odd (required) Bifrost flag set. -Thus, to prevent undefined behavior, it is advised that nodes will maintain each channel either under legacy LN or under Bifrost using the following rules: +3. Bifrost channels can’t be operated using legacy LN messaging; a node + receiving message referencing to a Bifrost server over the legacy LN MUST + respond with `error` message. -1. If the channel was created in legacy LN it can be moved into Bifrost once and only once – and a dedicated gossip `channel_update` message must be published to the legacy LN with Bifrost even flag set. -2. If the channel was created in Bifrost network, it MAY be announced in the legacy LN only with odd (required) Bifrost flag set. -3. Bifrost channels can’t be operated using legacy LN messaging; a node receiving message referencing to a Bifrost server over the legacy LN MUST respond with `error` message. -4. Legacy LN channels MUST not be operated from Bifrost network before their movement according to the pt. 1. A node receiving Bifrost message for legacy LN channel MUST respond with `error` message. +4. Legacy LN channels MUST not be operated from Bifrost network before their + movement according to the pt. 1. A node receiving Bifrost message for legacy + LN channel MUST respond with `error` message. -In order to enable fallback for Bifrost-managed channels in case of bugs discovered in Bifrost, the following rules SHOULD be supported by Lightning node implementations, but SHOULD not be used until a fallback scenario: + In order to enable fallback for Bifrost-managed channels in case of bugs + discovered in Bifrost, the following rules SHOULD be supported by Lightning + node implementations, but SHOULD not be used until a fallback scenario: -5. Bifrost channels which maintain BOLT compatibility can be moved back into legacy Lightning network by properly announcing removal of the channel in Bifrost network – and publishing `channel_announcement` (for previously non-announced channels) or `channel_update` gossip messages with all Bifrost feature flags removed +5. Bifrost channels which maintain BOLT compatibility can be moved back into + legacy Lightning network by properly announcing removal of the channel in + Bifrost network – and publishing `channel_announcement` (for previously + non-announced channels) or `channel_update` gossip messages with all Bifrost + feature flags removed ### Invoices -All bifrost-operated channels MUST use LNPBP-38 invoices. BOLT-11 invoices MUST NOT be created for any channel which was moved into Bifrost network. +All bifrost-operated channels MUST use LNPBP-38 invoices. BOLT-11 invoices MUST +NOT be created for any channel which was moved into Bifrost network. ## Rationale ### Use of dedicated port -Bifrost requires use of a non-LN port to enable simultaneous and independent operations of lightning nodes using both legacy LN messages and Bifrost messages. +Bifrost requires use of a non-LN port to enable simultaneous and independent +operations of lightning nodes using both legacy LN messages and Bifrost +messages. ### Why URL uses plus instead of at symbol -While at* symbol (`@`) is broadly used in legacy Lightning node addresses (`@[:]` form), it can’t be used as a proper part of Bifrost URL since in RFC 3986 it is reserved as a separator for optional username prefix before mandatory host name part – while pubkey is not optional in Bifrost and host is optional. Thus, we replace `@` usage with `+`, since `+` is allowed in RFC 3986 as a separator in host name part of authority field and it semantically defines “additional information”, which is a network address of the node for a given public key. +While at* symbol (`@`) is broadly used in legacy Lightning node addresses +(`@[:]` form), it can’t be used as a proper part of Bifrost +URL since in RFC 3986 it is reserved as a separator for optional username prefix +before mandatory host name part – while pubkey is not optional in Bifrost and +host is optional. Thus, we replace `@` usage with `+`, since `+` is allowed in +RFC 3986 as a separator in host name part of authority field and it semantically +defines “additional information”, which is a network address of the node for a +given public key. ### Using local features -Bifrost support is specified in the local features field of the `init` message since it is against BOLT-9 to use feature bits greater than 13 in the global features field. +Bifrost support is specified in the local features field of the `init` message +since it is against BOLT-9 to use feature bits greater than 13 in the global +features field. ### Feature bit selection -Bits 255/256 are the largest bit numbers which may be stored by a 32-byte value. It is still far enough from the current used feature bits in BOLT-9 (26/27), allowing another 5 to 10 years without the risk of the conflict (until Bifrost will be recognized) and at the same time does not over-enlarges the size of the feature flag field in `init` and other messages. +Bits 255/256 are the largest bit numbers which may be stored by a 32-byte value. +It is still far enough from the current used feature bits in BOLT-9 (26/27), +allowing another 5 to 10 years without the risk of the conflict (until Bifrost +will be recognized) and at the same time does not over-enlarges the size of the +feature flag field in `init` and other messages. ## Reference implementation -The current Bifrost reference implementation is provided by [`LNP Core Library`](https://github.com/LNP-BP/lnp-core) and [`LNP Node`](https://github.com/LNP-BP/lnp-node) +The current Bifrost reference implementation is provided by [`LNP Core +Library`](https://github.com/LNP-BP/lnp-core) and [`LNP +Node`](https://github.com/LNP-BP/lnp-node) ## Acknowledgements -The authors are thankful to Giacomo Zucco, Christian Decker and Martin Habovštiak for multiple discussions and ideas which led to the creation and shaping of this specification. +The authors are thankful to Giacomo Zucco, Christian Decker and Martin +Habovštiak for multiple discussions and ideas which led to the creation and +shaping of this specification. ## References @@ -149,4 +241,4 @@ This document is licensed under the Creative Commons CC0 1.0 Universal license. ## Test vectors -TBD \ No newline at end of file +TBD From f93a5d7ce38d68901d4874d153b6594c0dfaedde Mon Sep 17 00:00:00 2001 From: Dr Maxim Orlovsky Date: Thu, 4 Nov 2021 15:59:30 +0100 Subject: [PATCH 3/4] Bifrost: channel negotiation basics --- README.md | 9 +-- lnpbp-0051.md | 186 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 191 insertions(+), 4 deletions(-) create mode 100644 lnpbp-0051.md diff --git a/README.md b/README.md index f5a4526..0a101fb 100644 --- a/README.md +++ b/README.md @@ -74,8 +74,8 @@ No | Layer | Vertical | Title | Authors 47 | OSI Application (i7) | Lightning network protocol | Multipeer lightning channels | Maxim Orlovsky | Standard | Planned 48 | OSI Application (i7) | Lightning network protocol | Bilateral channel funding | Maxim Orlovsky | Standard | Draft 49 | OSI Application (i7) | Lightning network protocol | Synchronized multi-hop state updates via delegation in Lightning network | Maxim Orlovsky, Christian Decker | Standard | Planned -[50]| OSI Application (i7) | Lightning network protocol | Bifrost: generalized Lightning network protocol core | Maxim Orlovsky | Standard | Planned - 51 | OSI Application (i7) | Lightning network protocol | Channel transaction structure negotiation using PSBTs (generalized LN) | Maxim Orlovsky, Christian Decker | Standard | Planned +[50]| OSI Application (i7) | Lightning network protocol | Bifrost: generalized Lightning network protocol core | Maxim Orlovsky | Standard | Draft +[51]| OSI Application (i7) | Lightning network protocol | Bifrost: channel management protocol | Maxim Orlovsky | Standard | Draft 52-56| Reserved | | For the future use by lightning network protocol extensions 57 | OSI Application (i7) | Lightning network protocol | Decentralized naming & name resolution system | Maxim Orlovsky | Standard | Planned [58]| Client-validated data (3) | Cryptographic primitives | Apophis: distributed elliptic curve-based key creation with shared secrets | Maxim Orlovsky | Standard | Draft @@ -106,7 +106,7 @@ No | Layer | Vertical | Title | Authors 3. Generalized lightning network standartisation and related [eltoo] and [PTLC] proposals 4. Micropayments: - - [LSAT Authentication and Payments for the Lightning-Native Web][LSAT] + - [LSAT Authentication and Payments for the Lightning-Native Web][LSAT] by Olaoluwa Osuntokun @@ -121,7 +121,7 @@ No | Title | Description 5 | Application | Specific high-level applications build of underlying layers | Assets, audit, storage, computing, messaging, decentralized exchanges and marketplaces Additionally to these layers there is a set of network protocol layers organized -according to [ISO OSI model][ISO-OSI], with numbers prefixed using `i` symbol +according to [ISO OSI model][ISO-OSI], with numbers prefixed using `i` symbol ("complex dimension"). ## Verticals for LNP/BP proposals: @@ -173,6 +173,7 @@ Game theory | Game-theoretical setups for trustless protocols [44]: https://github.com/LNP-BP/descriptor-wallet/blob/master/src/descriptor/script.rs [46]: https://github.com/LNP-BP/LNPBPs/pull/98 [50]: https://github.com/LNP-BP/LNPBPs/pull/97 +[51]: https://github.com/LNP-BP/LNPBPs/pull/97 [58]: https://github.com/pandoracore/typhon-spec [59]: https://github.com/pandoracore/typhon-spec [60]: https://github.com/pandoracore/ibiss-spec diff --git a/lnpbp-0051.md b/lnpbp-0051.md new file mode 100644 index 0000000..e3deadd --- /dev/null +++ b/lnpbp-0051.md @@ -0,0 +1,186 @@ +``` +LNPBP: 0051 +Layer: OSI Application (i7) +Vertical: Lightning network protocol +Title: CBifrost: channel management protocol +Author: Dr Maxim Orlovsky +Comments-URI: https://github.com/LNP-BP/lnpbps/pulls/97 +Status: Draft +Type: Standards Track +Created: 2021-11-01 +Finalized: not yet +License: CC0-1.0 +``` + +## Abstract + +## Background + +## Motivation + +## Design + +## Specification + +### Bifrost transaction requirements + +Bifrost requires all off-chain transactions always have v2 and use v1 witness +P2TR outputs (or later witness versions). Transaction inputs, aside from funding +transaction, also must be v1 witness inputs spending P2TR outputs (or above). + +For funding onchain transactions and funding outputs of channel level 1 this +requirement is released to witness v0 or above. The reason for lower requirement +is the interoperability with the legacy lightning network, allowing migration of +existing channels opened in legacy network to Bifrost. + + +### Channel coordination + +For channel operations we assume that any channel may be a multi-peer channel. +Thus, for channel updates it is required that all parties cooperate and sign the +latest version of updated channel transactions. This is achieved by introducing +concept of *channel coordinator*. Channel coordinator is the lightning node that +has originally proposed channel. It is responsible for orchestrating message +flow between all nodes which are the parts of the channel and keeping them +up-to-date. Also, the channel coordinator is the only party required to have +direct connections with other channel participants – and each of channel +participants is required to be connected at least to the channel coordinator. + +If a multiple nested channels are present, for all higher-level channels channel +coordinator MUST be the same as channel coordinator for the base (level 1) +channel; the list of participants for the nested channels MUST be a subset of +the participants of the topmost level 1 channel. + + +#### Channel workflows + +There are following workflows affecting channel status / existence. Each of +these workflows represent a set of P2P messages exchanged by channel peers. + +- Channel creation +- Moving channel from legacy to Bifrost LN +- Removing channel from Bifrost to legacy LN +- Changing channel status (pausing etc) +- Upgrading channel to support more protocols +- Downgrading channel by removing specific protocol +- Cooperatively closing channel + +Workflow can be initiated only by a *channel coordinator*, and specific P2P +messages inside the workflow can be sent either from the *channel coordinator* +to a peer – or, in response, from a peer to the *channel coordinator*. + +Normal channel operations are covered by application-specific business logic and +messages and are not part of any listed channel workflow. Unlike workflows, they +may be initiated by any of the channel peers sending message to the channel +coordinator, however whenever they involve other peers or external channels, +after being initiated they must be coordinated by the channel coordinator. + +## Channel creation workflow + +Considering generic case of multi-peer channel setup channel creation workflow +is organized with the following algorithm: + +1. First, all parties agree on the structure of the *funding transaction* + and overall transaction graph within the channel – simultaneously signing + *refund transaction* (which, upon channel creation, will become first + version of the channel *commitment transaction*). This is done using + `ProposeChannel` requests sent by the *channel coordinator* to each of + the peers, replying with either `AcceptChannel` (containing updated + transaction graph with signed refund transaction) or `Error`. + peers must wait for `CHANNEL_CREATION_TIMEOUT` period and discard all + provisional channel data from their memory. + +2. Once the refund transaction is fully signed – implying that the + transaction graph if agreed between participants – channel coordinator + starts next phase, where the funding transaction gets fully signed. + Coordinator sends `FinalizeChannel` message to each of the peers and + collects signatures, publishing the final transaction either to bitcoin + blockchain (for level 1 channels) or updating the state of the top-level + channel (for nested channels above level 1). Peers track upper level + channel or blockchain to detect funding transaction, and upon transaction + mining starts operate channel in active mode, not requiring any other + messages from the channel coordinator (NB: this differs from the legacy + LN channel creation workflow). + +3. Replacing funding by fee (RBF): channel coordinator SHOULD initiate RBF + subworkflow for level 1 channels if the funding transaction was not mined + after reasonable amount of time, which should be less than + `ChannelParams::funding_timeout`. With RGB subworkflow coordinator + updates funding transaction – and propagates it with `FinalizeChannel` + request, collecting new signatures (peers MUST reset their funding + timeout counters). + +4. Cancelling channel creation: if any of the peer nodes replied with + `Error` on any of the channel construction requests within the channel + creation workflow – or if the coordinator detected incorrect reply, + channel coordinator MUST abandon channel creation – and MUST forward + `Error` message to all other peers. A peer posting `Error` MUST + provide a valid error code and a message explaining the cause of the + error. The coordinator SHOULD also send `Error` message to peers if + any of the stages of transaction construction workflow has stuck + without a reply from a peer for over `ChannelParams::peer_timeout` + time. + +5. Timeouts: the coordinator SHOULD send `Error` message to peers if any + of the peers at any stage of transaction construction workflow has stuck + without a reply for over `ChannelParams::peer_timeout` time. + The peers should abandon channel and clear all information about it from + the memory regardless whether they have received `Error` message from + the coordinator after `ChannelParams::peer_timeout`` * 2` time before + `ChannelFinalized` – and if they has not received new + `FinalizeChannel` request from the coordinator after + `ChannelParams::funding_timeout` time (see pt 3 for RBF subworkflow). + +``` +Channel coordinator Peer 1 Peer 2 + | | | +(enters ChannelProposed state) | | + | | | + | --(1)- ProposeChannel ------> | | + | | | + | --(1)------------ ProposeChannel --------------> | + | | | + | (enter ChannelProposed state) + | | | + | <-(2)------------- AcceptChannel --------------- | + | | | + | <-(2)-- AcceptChannel ------- | | + | | | + (enters ChannelAccepted state) (enter ChannelAccepted state) + | | | + | --(3)- FinalizeChannel -----> | | + | | | + | --(3)------------ FinalizeChannel -------------> | + | | | + | <-(4)-- FinalizeChannel ----- | | + | | | + | <-(4)------------- FinalizeChannel ------------- | + | | | + (enters ChannelFinalized state) (enter ChannelFinalized state) + | | | +(await funding transaction mining or entering the valid super-channel state) + | | | + (enters ChannelActive state) (enter ChannelActive state) + | | | +``` + +During channel construction workflow channels are identified by +`ChannelId`, which is constructed as a tagged SHA-256 hash +(using `bifrost:channel-proposal` as tag) of the strict-serialized +`ChannelParams` data and coordinator node public key. + +## Compatibility + +## Rationale + +## Reference implementation + +## Acknowledgements + +## References + +## Copyright + +This document is licensed under the Creative Commons CC0 1.0 Universal license. + +## Test vectors From 4558109acbd422e38aa6d54655614abb0fb7c7ac Mon Sep 17 00:00:00 2001 From: Dr Maxim Orlovsky Date: Sat, 13 Nov 2021 16:18:13 +0100 Subject: [PATCH 4/4] Bifrost: more details no tx requirements --- lnpbp-0051.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/lnpbp-0051.md b/lnpbp-0051.md index e3deadd..392d980 100644 --- a/lnpbp-0051.md +++ b/lnpbp-0051.md @@ -24,15 +24,19 @@ License: CC0-1.0 ### Bifrost transaction requirements -Bifrost requires all off-chain transactions always have v2 and use v1 witness -P2TR outputs (or later witness versions). Transaction inputs, aside from funding -transaction, also must be v1 witness inputs spending P2TR outputs (or above). +Bifrost requires all off-chain transactions always be of version 2. Transaction +outputs which are internal to the channel (i.e. spend by other offchain +transactions participating in channel) MUST use v1 witness P2TR outputs (or +later witness versions). The scripts in taproot key path spends MUST be +miniscript-compatible. -For funding onchain transactions and funding outputs of channel level 1 this +For on-chain funding transactions and funding outputs of channel level 1 this requirement is released to witness v0 or above. The reason for lower requirement is the interoperability with the legacy lightning network, allowing migration of existing channels opened in legacy network to Bifrost. +There is no specific requirements for outputs which are not internal for the +channel. ### Channel coordination