[draft] Describe the invoicing protocol

draft-lnpbp-invoices.md

@@ -0,0 +1,148 @@
+```
+LNPBP: XXXX
+Layer: Application (5)
+Field: Invoicing
+Title: Assets-aware Bitcoin addresses and Lightning invoices
+Authors: Alekos Filini <alekos.filini@gmail.com>
+Comments-URI: https://github.com/LNP-BP/lnpbps/issues/XXX
+Status: Draft
+Type: Standards Track
+Created: 2020-04-02
+License: CC0-1.0
+```
+
+## Abstract
+
+This work proposes a way to levearge existing standards on Bitcoin and the Lightning Netowrk to embed
+extra details related to assets and other protocol-specific informations into payment URIs and Lightning invoices.
+
+
+## Background
+
+Bitcoin addresses by themselves sometimes are not enough to convey all the necessary informations about a payment. A
+merchant might want to get paid a specific amount, or in the case of Lightning they might want to ask the payer to
+use a specific route over the nodes graph. For this reason, standards have been developed to encode these extra
+details in a way that could be easily encoded as a text string or in a QR code.
+
+Specifically, BIP-21[1] describes a way to create a "payment URI" given a Bitcoin address and some extra customizable
+parameters like an amount, while BOLT-11[3] describes a way to encode a large number of fields into single, relatively
+long, strings of text, normally called "invoices".
+
+This standard builds on top of them to extend their capabilities to multiasset protocols.
+
+
+## Motivation
+
+Multiasset protocols generally needs to embed more informations into a payment URI or invoice, compared to Bitcoin: above
+everything some kind of asset identifier, which is implicit in Bitcoin invoices because it's the only asset that is
+natively part of the network.
+
+Other more complex protocols like RGB also need extra parameters to help payer and payee connect to each other and
+exchange the client-validated part of the data.
+
+## Specification
+
+### "On-Chain" Addresses
+
+Given a Bitcoin address and an `asset-identifier`, the payment invoice is generated by following the procedure
+describted by BIP-21[1], with the following changes:
+
+1. The URI prefix MUST be unique and represent the asset protocol, like `rgb`.
+2. The `asset-identifier` MUST be present, and it should be encoded as a Base58[5] string **without** checksum.
+
+Optionally, like in any normal BIP-21 URIs, an `amount` field can be added. If present, the `amount` MUST be encoded
+as a floating-point number with the precision factor already applied, if the assets protocol supports it.
+
+Any other protocol-specific field can be added as described in BIP-21, with or without the `req-` prefix depending on
+whether or not the field should be considered "required".
+
+Specifically, the RGB protocol defines an extra field `req-endpoint` that indicates where the sender is supposed to
+upload the client validated history of the tokens. It should be equal to a V2 or V3 Tor onion endpoint, optionally
+followed by an explicit port if the listening server is running on a non-standard port.
+
+#### UTXO-based addresses
+
+Assets protocols that support a "send-to-existing-utxo" feature, can replace the Bitcoin address with a representation
+of said UTXO. For this purpose, this standard also defines a new type of address encoded in two possible ways:
+
+##### Extended Variant
+
+1. Encode the `txid` in the network binary format (reverse of the hex string usually displayed) in a temporary buffer.
+2. Append the `vout` encoded as a 32 bit long unsigned big endian integer.
+3. Encode the 36-byte long buffer as a Bech32 address, as specified in BIP-173[2], using the human-redable part of
+   the network where the UTXO is defined and a witness version of `0`.
+
+##### Short Variant
+
+1. Generate the LNPBP-0005[4] identifier for the UTXO and represent it as a 64 bit long unsigned big endian.
+   integer in a temporary buffer.
+2. Encode the 8-byte long buffer as a Bech32 address, as specified in BIP-173[2], using the human-redable part of
+   the network where the UTXO is defined and a witness version of `0`.
+
+### Lightning Invoices
+
+Assets-aware Lightning network invoices should be generated like any normal BOLT-11[3] invoice, with the following
+changes:
+
+1. The human readable part MUST be `ln + <unique prefix>`.
+2. An extra tagged field with type `a` MUST be present, and MUST be set to the binary representation of the
+   `asset-identifier`
+3. Optional fallback addresses (`f` fields) MAY be present and they MAY contain UTXO-based addresses, if the assets
+   protocol supports them. Any other field that would normally be required by the specific asset protocol in its
+   "On-Chain Addresses" MUST also be added with a unique field type defined by the protocol.
+
+Specifically, the RGB protocol requires an extra field tagged with `e` (endpoint) if at least one `f` field is present,
+serialized in a string as described in the "On-Chain Address" part of this standard. Multiple `e` fields MAY be
+specified in an implied preferred order.
+
+
+## Compatibility
+
+This protocol is somewhat a generalization of the Bitcoin and Lightning counterparty, and while it tries to be very
+similar both implementation-wise and end-result-wise (to look more familiar to people already using the existing
+protocols), some changes make it incompatible with existing standards. This acts as an extra precautios to avoid loss
+of funds from people that might mistake a Bitcoin URI with an asset-enabled one.
+
+
+## Rationale
+
+### UTXO-based addresses
+
+UTXO-based addresses are encoded exactly like standard Bech32 addresses with witness version of 0 (more commonly known
+as P2WPKH and P2WSH), however this proposal doesn't conflict in any way with them because, because neither of them has
+the same lenght as one of the existing type of addresses. From BIP-173[2]:
+
+> Decoders SHOULD enforce known-length restrictions on witness programs. For example, BIP141 specifies If the version
+> byte is 0, but the witness program is neither 20 nor 32 bytes, the script must fail.
+
+Introducing this new types of addresses of length 36 and 8 is in fact safer than bumping the version number and
+potentially have a conflict with a future upgrade of Bitcoin.
+
+## Reference implementation
+
+
+## Acknowledgements
+
+* Dr Maxim Orlovsky and Giacomo Zucco for the extensive conversation that led to this proposal.
+
+
+## References
+
+1. Nils Schneider, Matt Corallo. BIP-21: URI Scheme. <https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki>
+2. Pieter Wuille, Greg Maxwell. BIP-173: Base32 address format for native v0-16 witness outputs.
+   <https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki>
+3. BOLT#11: Invoice Protocol for Lightning Payments
+   <https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md>
+4. Dr Christian Decker, Dr Maxim Orlovsky. LNPBP-5: Universal short Bitcoin identifiers for blocks, transactions
+   and transaction inputs & outputs. <https://github.com/LNP-BP/lnpbps/blob/master/lnpbp-0005.md>
+5. Base58 Encoding Format. <https://en.bitcoin.it/wiki/Base58Check_encoding>
+
+
+## Copyright
+
+This document is licensed under the Creative Commons CC0 1.0 Universal license.
+
+
+## Test vectors
+
+TBD