Auto merge of #2674 - str4d:2469-ci-workers-macos, r=str4d
[VerusCoin.git] / doc / payment-disclosure.md
1 # Payment Disclosure (Experimental Feature)
2
3 **Summary**
4
5 Use RPC calls `z_getpaymentdisclosure` and `z_validatepaymentdisclosure` to reveal details of a shielded payment.
6
7 **Who should read this document**
8
9 Frequent users of shielded transactions, payment processors, exchanges, block explorer
10
11 ### Experimental Feature
12
13 This is an experimental feature.  Enable it by launching `zcashd` with flags:
14
15     zcashd -experimentalfeatures -paymentdisclosure -debug=paymentdisclosure -txindex=1
16
17 These flags can also be set as options in `zcash.conf`.
18
19 All nodes that generate or validate payment disclosures must run with `txindex=1` enabled.
20
21 ### Background
22
23 Payment Disclosure is an implementation of the work-in-progress Payment Disclosure ZIP [1].
24
25 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. 
26
27 [1] https://github.com/zcash/zips/pull/119
28
29 ### Example Use Case
30
31 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.
32
33 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.
34
35 If Bob is a bad merchant, Alice can present the payment disclosure to a third party to validate that payment was indeed made.
36
37 ### Solution
38
39 A payment disclosure can be generated for any output of a JoinSplit using the RPC call:
40
41     z_getpaymentdisclosure txid js_index output_index (message)
42
43 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.
44
45 To validate a payment disclosure, the following RPC call can be used:
46
47     z_validatepaymentdisclosure hexdata
48
49 ### Example
50
51 Generate a payment disclosure for the first joinsplit, second output (index starts from zero):
52
53     zcash-cli z_getpaymentdisclosure 79189528d611e811a1c7bb0358dd31343033d14b4c1e998d7c4799c40f8b652b 0 1 "Hello"
54     
55 This returns a payment disclosure in the form of a hex string:
56
57     706462ff000a3722aafa8190cdf9710bfad6da2af6d3a74262c1fc96ad47df814b0cd5641c2b658b0fc499477c8d991e4c4bd133303431dd5803bbc7a111e811d6289518790000000000000000017e861adb829d8cb1cbcf6330b8c2e25fb0d08041a67a857815a136f0227f8a5342bce5b3c0d894e2983000eb594702d3c1580817d0374e15078528e56bb6f80c0548656c6c6f59a7085395c9e706d82afe3157c54ad4ae5bf144fcc774a8d9c921c58471402019c156ec5641e2173c4fb6467df5f28530dc4636fa71f4d0e48fc5c560fac500
58
59 To validate the payment disclosure:
60
61     zcash-cli z_validatepaymentdisclosure HEXDATA
62     
63 This returns data related to the payment and the payment disclosure:
64
65     {
66       "txid": "79189528d611e811a1c7bb0358dd31343033d14b4c1e998d7c4799c40f8b652b",
67       "jsIndex": 0,
68       "outputIndex": 1,
69       "version": 0,
70       "onetimePrivKey": "1c64d50c4b81df47ad96fcc16242a7d3f62adad6fa0b71f9cd9081faaa22370a",
71       "message": "Hello",
72       "joinSplitPubKey": "d1c465d16166b602992479acfac18e87dc18065f6cefde6a002e70bc371b9faf",
73       "signatureVerified": true,
74       "paymentAddress": "ztaZJXy8iX8nrk2ytXKDBoTWqPkhQcj6E2ifARnD3wfkFwsxXs5SoX7NGmrjkzSiSKn8VtLHTJae48vX5NakvmDhtGNY5eb",
75       "memo": "f600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
76       "value": 12.49900000,
77       "commitmentMatch": true,
78       "valid": true
79     }
80
81 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.
82
83 ### Where is the data stored?
84
85 For all nodes, payment disclosure does not touch `wallet.dat` in any way.
86
87 For nodes that only validate payment disclosures, no data is stored locally.
88
89 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:
90
91     $HOME/.zcash/paymentdisclosure
92     
93 If you decide you don't want to use payment disclosure, it is safe to shut down your node and delete the database folder.
94
95 ### Security Properties
96
97 Please consult the work-in-progress ZIP for details about the protocol, security properties and caveats.
98
99 ### Reminder
100
101 Feedback is most welcome!
102
103 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.
104
105 ### Notes
106
107 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.
This page took 0.028717 seconds and 4 git commands to generate.