From 07b9d14a72c679faa3200e7c1f09374bedacd06b Mon Sep 17 00:00:00 2001 From: "Jonathan \"Duke\" Leto" Date: Mon, 26 Feb 2018 00:06:40 -0800 Subject: [PATCH] Add Payment Disclosure documentation that was missed from upstream --- doc/payment-disclosure.md | 110 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 doc/payment-disclosure.md diff --git a/doc/payment-disclosure.md b/doc/payment-disclosure.md new file mode 100644 index 000000000..53b148dfe --- /dev/null +++ b/doc/payment-disclosure.md @@ -0,0 +1,110 @@ +# 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.