LNPBP-37: Invoices (rejected)

LNPBP: 0037
Vertical: Smart contracts
Title: Invoicing formats for RGB-20 fungible assets schema
Authors: Alekos Filini <alekos.filini@gmail.com>
Comments-URI: hhttps://github.com/LNP-BP/LNPBPs/pull/23
Status: Rejected
Type: Standards Track
Created: 2020-04-02
License: CC0-1.0

Note: This standard has been superseded by LNPBP-38 Universal LNP/BP invoices due to incompatibility with Lightning, Coinjoin, and consignment metadata.

Abstract

This work proposes a way to levearge existing standards on Bitcoin and the Lightning Network 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 precaution 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 length 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

PreviousLNPBP-31: Standard contractum libNextLNPBP-46: LN derivations

Last updated