hush/doc/payment-disclosure.md

Payment Disclosure (Experimental Feature)

Summary

Use RPC calls z_getpaymentdisclosure and z_validatepaymentdisclosure to reveal details of a shielded payment.

Who should read this document

Frequent users of shielded transactions, payment processors, exchanges, block explorers

Experimental Feature

This is an experimental feature. Enable it by launching hushd with flags:

hushd -experimentalfeatures -paymentdisclosure -debug=paymentdisclosure -txindex=1

These flags can also be set as options in hush.conf.

All nodes that generate or validate payment disclosures must run with txindex=1 enabled.

Background

Payment Disclosure is an implementation of the work-in-progress Payment Disclosure upstream ZIP [1].

The ZIP describes a method of proving that a payment was sent to a shielded address. In the typical case, this means enabling a sender to present a proof that they transferred funds to a recipient's shielded address.

[1] https://github.com/hush/zips/pull/119

Example Use Case

Alice the customer sends 10 ZEC to Bob the merchant at the shielded address shown on their website. However, Bob is not sure if he received the funds.

Alice's node is running with payment disclosure enabled, so Alice generates a payment disclosure and provides it to Bob, who verifies the payment was made.

If Bob is a bad merchant, Alice can present the payment disclosure to a third party to validate that payment was indeed made.

Solution

A payment disclosure can be generated for any output of a JoinSplit using the RPC call:

z_getpaymentdisclosure txid js_index output_index (message)

An optional message can be supplied. This could be used for a refund address or some other reference, as currently it is not common practice to (ahead of time) include a refund address in the memo field when making a payment.

To validate a payment disclosure, the following RPC call can be used:

z_validatepaymentdisclosure hexdata

Example

Generate a payment disclosure for the first joinsplit, second output (index starts from zero):

hush-cli z_getpaymentdisclosure 79189528d611e811a1c7bb0358dd31343033d14b4c1e998d7c4799c40f8b652b 0 1 "Hello"

This returns a payment disclosure in the form of a hex string:

706462ff000a3722aafa8190cdf9710bfad6da2af6d3a74262c1fc96ad47df814b0cd5641c2b658b0fc499477c8d991e4c4bd133303431dd5803bbc7a111e811d6289518790000000000000000017e861adb829d8cb1cbcf6330b8c2e25fb0d08041a67a857815a136f0227f8a5342bce5b3c0d894e2983000eb594702d3c1580817d0374e15078528e56bb6f80c0548656c6c6f59a7085395c9e706d82afe3157c54ad4ae5bf144fcc774a8d9c921c58471402019c156ec5641e2173c4fb6467df5f28530dc4636fa71f4d0e48fc5c560fac500

To validate the payment disclosure:

hush-cli z_validatepaymentdisclosure HEXDATA

This returns data related to the payment and the payment disclosure:

{
  "txid": "79189528d611e811a1c7bb0358dd31343033d14b4c1e998d7c4799c40f8b652b",
  "jsIndex": 0,
  "outputIndex": 1,
  "version": 0,
  "onetimePrivKey": "1c64d50c4b81df47ad96fcc16242a7d3f62adad6fa0b71f9cd9081faaa22370a",
  "message": "Hello",
  "joinSplitPubKey": "d1c465d16166b602992479acfac18e87dc18065f6cefde6a002e70bc371b9faf",
  "signatureVerified": true,
  "paymentAddress": "ztaZJXy8iX8nrk2ytXKDBoTWqPkhQcj6E2ifARnD3wfkFwsxXs5SoX7NGmrjkzSiSKn8VtLHTJae48vX5NakvmDhtGNY5eb",
  "memo": "f600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "value": 12.49900000,
  "commitmentMatch": true,
  "valid": true
}

The signatureVerified field confirms that the payment disclosure was generated and signed with the joinSplitPrivKey, which should only be known by the node generating and sending the transaction 7918...652b in question.

Where is the data stored?

For all nodes, payment disclosure does not touch wallet.dat in any way.

For nodes that only validate payment disclosures, no data is stored locally.

For nodes that generate payment disclosures, a LevelDB database is created in the node's datadir. For most users, this would be in the folder:

$HOME/.hush/paymentdisclosure

If you decide you don't want to use payment disclosure, it is safe to shut down your node and delete the database folder.

Security Properties

Please consult the work-in-progress ZIP for details about the protocol, security properties and caveats.

Reminder

Feedback is most welcome!

This is an experimental feature so there are no guarantees that the protocol, database format, RPC interface etc. will remain the same in the future.

Notes

Currently there is no user friendly way to help senders identify which joinsplit output index maps to a given payment they made. It is possible to construct this from debug.log. Ideas and feedback are most welcome on how to improve the user experience.