diff --git a/README.md b/README.md index 11842e8..f1734cb 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 @@ -175,6 +175,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-0050.md b/lnpbp-0050.md new file mode 100644 index 0000000..f943d7e --- /dev/null +++ b/lnpbp-0050.md @@ -0,0 +1,244 @@ +``` +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 diff --git a/lnpbp-0051.md b/lnpbp-0051.md new file mode 100644 index 0000000..392d980 --- /dev/null +++ b/lnpbp-0051.md @@ -0,0 +1,190 @@ +``` +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 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 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 + +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