RFC: JSON Payment Token

[agates]

This is not a final draft and is merely a proposal. Discussion for improvements is encouraged.

Introduction

The use of digital information brings with it new context and characteristics of value transfer. Blockchain technology has, for example, provided means of provable accounting mechanisms for a distributed consensus to trust and verify transfers via cryptographic procedure. Much like traditional banking systems follow established governmental rules to determine what are considered valid transactions, cryptographic procedure and distributed consensus govern validity of transactions in the information age.

With traditional banking systems come established methods of recording and acknowledging valid transfers of value. Indeed, it is a common desire for one to be able to prove they have paid for something. Often, we refer to this representation as a receipt of acknowledgement of transfer. However, in the age of information, there does not yet exist a unified method of providing proof of payment. Merely showing someone, let alone a digital information processor, a transaction exists only validates the rules of cryptographic procedure and distributed consensus function correctly.

If there was a standardized method of being able to show proof of payment, we would be able to use it in protocols to at once provide programmatic access to services via payment without authentication and easily allow for multiple avenues of payment with the same interface. Such a representation may in the age of information be characterized as a nonfungible token.

Requirements

Requirements to fulfill via such a token are:

1. Provide means to determine the payment method
2. Provide non-sensitive transaction information
3. Provide sufficient information for a receiver to validate the transaction information
4. Provide means for the receiver to validate the information hasn't been tampered with
5. Provide means for the receiver to validate the information is supplied by the entity that made the payment
6. Ensure the token can be used separately from the payment method, where a given application has no knowledge of the payment method, let alone how to participate in transactions

Given #1, this standard should not be specific to any particular payment method, but any implementation should expect to be able to determine the supplied payment method.

Proposal

The precedent here has been long established by the use of JSON Web Tokens (JWTs), which fulfill much the same goals for authentication and authorization.

This proposal merely builds upon JWTs, removing claims of identity while replacing them with claims of transaction information. These will be referred to as JSON Payment Tokens (JPTs).

Likewise while JWTs provide means of decentralized proof of identity, JPTs can perform the function for decentralized proof of payment. Note that these goals are not necessarily mutually exclusive, but neither one implies the other.

Example for Lightning payments

Use of this method of proof of payment allows one to begin to move application data out of the lightning layer, and to tie together lightning payments with 3rd party applications while avoiding overhead of the payment layer itself -- a well-known issue with the use of "TLV" records in payment metadata.

The following is a work-in-progress example of how to satisfy the above requirements for lightning payments.

Header

Similar to a JWT header, a JPT header needs to identify itself so an application knows how to handle it. This is the typ property.

Likewise, alg, traditionally a means of telling the application how to handle the cryptographic signature of the token, is set to lightning-keysend here to tell the application that verification of the token needs to happen on a lightning node. It's possible alg shouldn't be utilized for this going forward, but was merely used as an example here.

{
    "alg": "lightning-keysend",
    "typ": "JPT"
}

Payload

The body attempts to utilize some of the standard claims from RFC 7519 - JSON Web Token (JWT). Specifically:

• aud - The intended audience of the token. In the case of lightning, this is the public key of the node that received the payment. This allows the application to know which lightning node to verify the token against.
• iss - The issuer of the token. In the case of lightning, this is the public key of the node that made the payment. This needs to be used to verify the signature of the token as well as ideally match a public key included in the payment's TLV record for verification. This works as a "self-signed" token because this merely prevents tampering while still allowing verification of payment information
• iat - This is a unix timestmap representing when the token was issued.

The remaining claims are new properties not defined in RFC 7519:

• resolve_time - This is the unix timestamp of when the payment was resolved. Ideally, this would be checked on the receiver end to ensure the time matches up. Currently unsure if this is the correct way to do it, and one may need to account for a small amount of time drift.
• amt_paid_msat - This is the actual amount of sats paid. This SHOULD match on the receiver end. Note that by the nature of this value not being hidden, this could allow one to display this amount publicly to others given validity of the token.
• payment_hash - This is the most important claim, as it's what allows the lightning node to look up and verify the payment.

{
    "aud": "032f4ffbbafffbe51726ad3c164a3d0d37ec27bc67b29a159b0f49ae8ac21b8508",
    "iss": "02b66d7caae1acb51a95e036fc12b1e6837d9143141fcff520876b04b9d82f36d1",
    "iat": "1647906111",
    "resolve_time": "1647891435",
    "amt_paid_msat": "100000",
    "payment_hash": "d87bdee6f9e4d3f00f09c9ad29d61d34405bb4cfe64fc0490b26e5105d7acea7"
}

Encoding

The above JSON objects then get encoded to base64 with whitespace removed:

Header:

eyJhbGciOiJsaWdodG5pbmcta2V5c2VuZCIsInR5cCI6IkpQVCJ9

Payload:

eyJhdWQiOiIwMzJmNGZmYmJhZmZmYmU1MTcyNmFkM2MxNjRhM2QwZDM3ZWMyN2JjNjdiMjlhMTU5YjBmNDlhZThhYzIxYjg1MDgiLCJpc3MiOiIwMmI2NmQ3Y2FhZTFhY2I1MWE5NWUwMzZmYzEyYjFlNjgzN2Q5MTQzMTQxZmNmZjUyMDg3NmIwNGI5ZDgyZjM2ZDEiLCJpYXQiOiIxNjQ3OTA2MTExIiwicmVzb2x2ZV90aW1lIjoiMTY0Nzg5MTQzNSIsImFtdF9wYWlkX21zYXQiOiIxMDAwMDAiLCJwYXltZW50X2hhc2giOiJkODdiZGVlNmY5ZTRkM2YwMGYwOWM5YWQyOWQ2MWQzNDQwNWJiNGNmZTY0ZmMwNDkwYjI2ZTUxMDVkN2FjZWE3In0

Signature:

The following is the signature of the header and the payload concatenated by a "." (period), signed by the lightning node with the public key listed in iss above:

d6o1uw865o1qpoubc5o1d9zmtooahoqkegokjogpoqt3zdquau6m1z1dyqcyypehz8i8k7bn5bfnm4sckrd7679nmqbmnk1559jx937r

Full JPT

All together, this results in full a JPT -- header.payload.signature

In lightning terms, the "message" to be verified is header.payload and the signature is just signature. If the receiver node doesn't know about the originating node of the payment, the public key needs to be explicitly provided for verification. This can be done on lnd via the VerifyMessage Unary RPC call.

Feel free to paste the string below into a JWT debugger such as jwt.io. It will display correctly, albeit complain about an invalid signature.

eyJhbGciOiJsaWdodG5pbmcta2V5c2VuZCIsInR5cCI6IkpQVCJ9.eyJhdWQiOiIwMzJmNGZmYmJhZmZmYmU1MTcyNmFkM2MxNjRhM2QwZDM3ZWMyN2JjNjdiMjlhMTU5YjBmNDlhZThhYzIxYjg1MDgiLCJpc3MiOiIwMmI2NmQ3Y2FhZTFhY2I1MWE5NWUwMzZmYzEyYjFlNjgzN2Q5MTQzMTQxZmNmZjUyMDg3NmIwNGI5ZDgyZjM2ZDEiLCJpYXQiOiIxNjQ3OTA2MTExIiwicmVzb2x2ZV90aW1lIjoiMTY0Nzg5MTQzNSIsImFtdF9wYWlkX21zYXQiOiIxMDAwMDAiLCJwYXltZW50X2hhc2giOiJkODdiZGVlNmY5ZTRkM2YwMGYwOWM5YWQyOWQ2MWQzNDQwNWJiNGNmZTY0ZmMwNDkwYjI2ZTUxMDVkN2FjZWE3In0.d6o1uw865o1qpoubc5o1d9zmtooahoqkegokjogpoqt3zdquau6m1z1dyqcyypehz8i8k7bn5bfnm4sckrd7679nmqbmnk1559jx937r

Conclusion

The JPT can be attached anywhere needed and is immutable by nature of cryptographic verification. Like JWTs, it can be included in an HTTP Authorization to allow access to resources -- say, a podcast episode that only gets unlocked after 100 sats. Claims can and should be expanded upon for token expiration time to prevent abuse along with systems of revocation as desired, and that is out of scope of the examples here.

Additionally, if one wanted to make this information publicly available, perhaps attached to a public comment via ActivityPub, one could add more claims for proof of identity to ensure use of the token is inherently tied to a specific user. This would allow one to publicly provide proof of payment, perhaps as a donation, in attachment to something like a message.

Lastly, the JPT is not intended to be exclusive to bitcoin lightning. The same interface could theoretically be used by other blockchains or existing payment providers, in lieu of a system of authentication. In combination with existing interfaces such as the standard HTTP Authorization mentioned above, this becomes a very powerful interface.

[agates]

Thinking about this, we could add receiver lightning addresses such as [email protected] to help clients know where to check to verify payments in lieu of actually knowing the receiving server.

We also don't necessarily need to generate JPTs for every receipt in a value split, maybe have a way of identifying which ones want to receive a comment.