[Lightning-dev] Error Codes for LN

Carla Kirk-Cohen kirkcohenc at gmail.com
Fri Feb 12 07:34:04 UTC 2021

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


* 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:


   type: 17 (`error`)






   tlv_stream: `invalid_sig_tlvs`


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


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


* Incorrect gossip short channel ID [12]













-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.linuxfoundation.org/pipermail/lightning-dev/attachments/20210212/0fc08d61/attachment-0001.html>

More information about the Lightning-dev mailing list