LNPBP-37: Invoices (rejected)
Vertical: Smart contracts
Title: Invoicing formats for RGB-20 fungible assets schema
Authors: Alekos Filini <[email protected]>
Type: Standards Track
Note: This standard has been superseded by LNPBP-38 Universal LNP/BP invoices due to incompatibility with Lightning, Coinjoin, and consignment metadata.
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.
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 describes a way to create a "payment URI" given a Bitcoin address and some extra customizable parameters like an amount, while BOLT-11 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.
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.
Given a Bitcoin address and an
asset-identifier, the payment invoice is generated by following the procedure describted by BIP-21, with the following changes:
- 1.The URI prefix MUST be unique and represent the asset protocol, like
asset-identifierMUST be present, and it should be encoded as a Base58 string without checksum.
Optionally, like in any normal BIP-21 URIs, an
amountfield can be added. If present, the
amountMUST 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-endpointthat 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.
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:
- 1.Encode the
txidin the network binary format (reverse of the hex string usually displayed) in a temporary buffer.
- 2.Append the
voutencoded 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, using the human-redable part of the network where the UTXO is defined and a witness version of
- 1.Generate the LNPBP-0005 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, using the human-redable part of the network where the UTXO is defined and a witness version of
Assets-aware Lightning network invoices should be generated like any normal BOLT-11 invoice, with the following changes:
- 1.The human readable part MUST be
ln + <unique prefix>.
- 2.An extra tagged field with type
aMUST be present, and MUST be set to the binary representation of the
- 3.Optional fallback addresses (
ffields) 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
ffield is present, serialized in a string as described in the "On-Chain Address" part of this standard. Multiple
efields MAY be specified in an implied preferred order.
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.
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:
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.
- Dr Maxim Orlovsky and Giacomo Zucco for the extensive conversation that led to this proposal.
- 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
This document is licensed under the Creative Commons CC0 1.0 Universal license.