From kirkcohenc at gmail.com Fri Feb 12 07:34:04 2021 From: kirkcohenc at gmail.com (Carla Kirk-Cohen) Date: Fri, 12 Feb 2021 09:34:04 +0200 Subject: [Lightning-dev] Error Codes for LN Message-ID: Hi all, I?d like to make a case for re-purposing the existing error message (17) in the spec to allow for more structured errors, and create a path for standardized, enriched errors going forward. As is: the error message contains an arbitrary string, and is used to communicate fatal errors to our peers. To (potentially) be: the error message contains an error code, and optional metadata which enriches the context of the error. There are a few benefits of upgrading these messages: * Better debugging information, and standardization across implementations * Clearer information for the end user * Reduced risk of leaking information in an arbitrary string * More fine-grained error handling based on error code Since we shouldn?t have non-ascii values in the error string itself, this can most easily be achieved by adding TLV fields after the data field. In terms of supporting nodes that have not upgraded, we could either include the error code in the data field to cover our bases, or introduce a feature bit so that we know whether to backfill the data field. This gives upgraded nodes an improved quality of life, while leaving older nodes unaffected. While we can?t enumerate every possible error, there are quite a few cases in the spec where we can introduce explicit error codes. For the sake of the skim-readers, I?ve left that list at the end of the email. Taking the example of our node receiving an invalid signature for a htlc, a new error would look like this: 1. type: 17 (`error`) 2. data [Channel_id:channel_id] [u16:len] [len*byte:data] 1. tlv_stream: `invalid_sig_tlvs` 2. Types i. type 0 (`error_code`) data: [u16: error_code] ii. type 1 (`htlc_id`) data: [u64: id] iii. type 2 (`state_number`) data: [u64: commitment_number] This new kind of error provides us with an error code that tells us exactly what has gone wrong, and metadata pointing to the htlc with an invalid sig. This information can be logged, or stored in a more permanent error store to help diagnose issues in the future. Right now, the spec is pretty strict on error handling [13], indicating that senders/recipients of errors `MUST` fail the channel referenced in the error. This isn?t very practical, and I believe that the majority of the impls don?t abide by this instruction. With the addition of error codes, we can pair each error code with a recommended action that is more appropriate for the error at hand - for example, still force closing if we get an invalid signature, but being more lenient if we get a low fee in update fee. While this may already be the case in practise, it?s messy for everybody to roll their own and then figure out what other impls are doing. With a standardized set of errors, and reasonable handling - rather than the current ?close-all-da-chans? prescription in the spec - we can clear up some of the ambiguity around errors, and a spec that?s reasonable for the end user to follow. Thanks for reading! - Carla Candidates for error codes: Signature problems: * Incorrect Signature [1] [3] [7] [12] *Non-standard signature [1] [3 [7] Funding Process: * Funding process timeout [2] * Fees greater than base fee [3] * Fees out of range [3] * Funding tx spent [11] * Funding params unacceptable (eg, channel too small) Channel State Machine: * HTLC timeout [4] * Zero htlc add [5] * Htlc add less than minimum [5] * Htlc add can?t afford at current fee rate [5] * Maximum htlc count exceeded [5] * Maximum htlc in flight exceeded [5] * cltv > 500000000 [5] * Sub-msat values [5] * Fulfill/fail htlc id not found [6] * Incorrect commitment number [10] * Incorrect preimage [6] * Incorrect per commit secret [8] Fee Updates * Update fee to low/high [9] * Unexpected update fee [9] * Cannot afford update fee [9] Connection Level * Disconnecting * Feature bit required Gossip * Incorrect gossip short channel ID [12] [1] https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#the-funding_created-message [2] https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#the-funding_locked-message [3] https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#closing-negotiation-closing_signed [4] https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#requirements-8 [5] https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#requirements-9 [6] https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#requirements-10 [7] https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#requirements-11 [8] https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#requirements-12 [9] https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#requirements-13 [10] https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#requirements-14 [11] https://github.com/lightningnetwork/lightning-rfc/blob/master/05-onchain.md#requirements [12] https://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md#requirements [13] https://github.com/lightningnetwork/lightning-rfc/blob/master/01-messaging.md#the-error-message -------------- next part -------------- An HTML attachment was scrubbed... URL: