Skip to content

Bolt 11: add a payment secret to invoice #671

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
t-bast wants to merge 2 commits into from
Closed

Bolt 11: add a payment secret to invoice #671

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f53a7ce
Bolt 11: add a payment secret to invoice
t-bast Sep 13, 2019
b9d6770
fixup! Bolt 11: add a payment secret to invoice
t-bast Sep 16, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 16 additions & 6 deletions 04-onion-routing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -235,10 +235,13 @@ parameters may lead to extraneous routing failure.

### `tlv_payload` payload format

This is a more flexible format, which avoids the redundant `short_channel_id` field for the final node.
This is a more flexible format, which avoids the redundant `short_channel_id` field for the final node.

1. tlvs: `tlv_payload`
2. types:
1. type: 1 (`payment_secret`)
2. data:
* [`16*byte`:`payment_secret`]
1. type: 2 (`amt_to_forward`)
2. data:
* [`tu64`:`amt_to_forward`]
Expand All @@ -253,6 +256,8 @@ This is a more flexible format, which avoids the redundant `short_channel_id` fi

The writer:
- MUST include `amt_to_forward` and `outgoing_cltv_value` for every node.
- MUST include `payment_secret` for the final node if provided by the recipient.
- MUST NOT include `payment_secret` for non-final nodes.
- MUST include `short_channel_id` for every non-final node.
- MUST NOT include `short_channel_id` for the final node.

Expand Down Expand Up @@ -282,7 +287,7 @@ sent across.

Nodes implementing non-strict forwarding are able to make real-time assessments
of channel bandwidths with a particular peer, and use the channel that is
locally-optimal.
locally-optimal.

For example, if the channel specified by `short_channel_id` connecting A and B
does not have enough bandwidth at forwarding time, then A is able use a
Expand Down Expand Up @@ -313,6 +318,8 @@ using an alternate channel.
When building the route, the origin node MUST use a payload for
the final node with the following values:

* `payment_secret`: set to the payment secret specified by the recipient (e.g.
`payment_secret` from a [BOLT #11](11-payment-encoding.md) payment invoice)
* `outgoing_cltv_value`: set to the final expiry specified by the recipient (e.g.
`min_final_cltv_expiry` from a [BOLT #11](11-payment-encoding.md) payment invoice)
* `amt_to_forward`: set to the final amount specified by the recipient (e.g. `amount`
Expand Down Expand Up @@ -577,7 +584,6 @@ The processing node:
- MUST drop the packet.
- MUST signal a route failure.


# Filler Generation

Upon receiving a packet, the processing node extracts the information destined
Expand Down Expand Up @@ -827,9 +833,10 @@ handling by the processing node.
* [`u64`:`htlc_msat`]
* [`u32`:`height`]

The `payment_hash` is unknown to the final node, the amount for that
`payment_hash` is incorrect or the CLTV expiry of the htlc is too close to the
current block height for safe handling.
The `payment_hash` is unknown to the final node, the `payment_secret` doesn't
match the `payment_hash`, the amount for that `payment_hash` is incorrect or
Copy link
Copy Markdown
Collaborator

@niftynei niftynei Oct 28, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is kind of confusing: "the payment_secret doesn't match the payment_hash"

I think what you really mean to convey is that the payment_secret corresponds with the expected secret for that payment_hash.

'match' implies equivalence, which isn't the exact case here.

Copy link
Copy Markdown
Collaborator Author

@t-bast t-bast Nov 8, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

True, the wording isn't great. This PR is now included in the MPP once so I'll be closing it anyway ;)

the CLTV expiry of the htlc is too close to the current block height for safe
handling.

The `htlc_msat` parameter is superfluous, but left in for backwards
compatibility. The value of `htlc_msat` always matches the amount specified in
Expand Down Expand Up @@ -952,6 +959,9 @@ An _intermediate hop_ MUST NOT, but the _final node_:
- if the payment hash has already been paid:
- MAY treat the payment hash as unknown.
- MAY succeed in accepting the HTLC.
- if the `payment_secret` doesn't match the expected value for that `payment_hash`:
- MUST fail the HTLC.
- MUST return an `incorrect_or_unknown_payment_details` error.
- if the amount paid is less than the amount expected:
- MUST fail the HTLC.
- MUST return an `incorrect_or_unknown_payment_details` error.
Expand Down
27 changes: 21 additions & 6 deletions 11-payment-encoding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,9 +128,10 @@ Each Tagged Field is of the form:

Currently defined tagged fields are:

* `p` (1): `data_length` 52. 256-bit SHA256 payment_hash. Preimage of this provides proof of payment.
* `d` (13): `data_length` variable. Short description of purpose of payment (UTF-8), e.g. '1 cup of coffee' or 'ナンセンス 1杯'
* `n` (19): `data_length` 53. 33-byte public key of the payee node
* `p` (1): `data_length` 52. 256-bit SHA256 payment_hash. Preimage of the payment_hash provides proof of payment.
* `s` (16): `data_length` 26. 128-bit payment_secret. This secret prevents forwarding nodes from probing the payment recipient.
* `d` (13): `data_length` variable. Short description of purpose of payment (UTF-8), e.g. '1 cup of coffee' or 'ナンセンス 1杯'.
* `n` (19): `data_length` 53. 33-byte public key of the payee node.
* `h` (23): `data_length` 52. 256-bit description of purpose of payment (SHA256). This is used to commit to an associated description that is over 639 bytes, but the transport mechanism for the description in that case is transport specific and not defined here.
* `x` (6): `data_length` variable. `expiry` time in seconds (big-endian). Default is 3600 (1 hour) if not specified.
* `c` (24): `data_length` variable. `min_final_cltv_expiry` to use for the last HTLC in the route. Default is 9 if not specified.
Expand All @@ -148,7 +149,7 @@ Currently defined tagged fields are:
### Requirements

A writer:
- MUST include exactly one `p` field.
- MUST include exactly one `p` and `s` fields.
- MUST set `payment_hash` to the SHA2 256-bit hash of the `payment_preimage`
that will be given in return for payment.
- MUST include either exactly one `d` or exactly one `h` field.
Expand Down Expand Up @@ -191,8 +192,8 @@ A writer:
- MUST specify the most-preferred field first, followed by less-preferred fields, in order.

A reader:
- MUST skip over unknown fields, OR an `f` field with unknown `version`, OR `p`, `h`, or
`n` fields that do NOT have `data_length`s of 52, 52, or 53, respectively.
- MUST skip over unknown fields, OR an `f` field with unknown `version`, OR `p`, `s`, `h`, or
`n` fields that do NOT have `data_length`s of 52, 26, 52, or 53, respectively.
- if the `9` field contains unknown _odd_ bits that are non-zero:
- MUST ignore the bit.
- if the `9` field contains unknown _even_ bits that are non-zero:
Expand All @@ -215,6 +216,10 @@ specs could add a new variant of different length: in which case,
writers could support both old and new variants, and old readers would
ignore the variant not the correct length.

The `s` field prevents forwarding nodes from probing to test if a node is the
recipient of the payment. The length of the `s` field could change in the
future so readers ignore it if it's not 128 bits.

The `d` field allows inline descriptions, but may be insufficient for
complex orders. Thus, the `h` field allows a summary: though the method
by which the description is served is as-yet unspecified and will
Expand Down Expand Up @@ -278,6 +283,16 @@ The field is big-endian. The least-significant bit is numbered 0,
which is _even_, and the next most significant bit is numbered 1,
which is _odd_.

The following feature bits are currently assigned by this specification:

| Bits | Name | Description |
|------|-------------------------|-------------------------------------------------------|
| 0/1 | `option_payment_secret` | Requires or supports the `payment_secret` field (`s`) |

The payee should set the _even_ `payment_secret` bit to prevent probing attacks
by the next-to-last node. If the payee wants to allow legacy payers, he may set
the _odd_ `payment_secret` bit instead. In that case probing attacks are possible.

# Payer / Payee Interactions

These are generally defined by the rest of the Lightning BOLT series,
Expand Down