Protocol spec

[xaur]

I encountered a few references to the "original vspd spec" (latest in decred/dcrwallet#2213) and thought maybe it should live in this repo, similar to the one in dcrdex repo?

It looks like a good amount of VSP behavior is already captured in api.md and two-way-accountability.md so maybe there is nothing else to do. But just in case, it might be worth checking if anything can be pulled from decred/dcrstakepool#574 - the only document I remember being referred to as "spec". There may be more notes/docs elsewhere ofc.

[jholdstock]

I think you're correct in saying "there is nothing else to do", those two docs capture everything afaict.

[xaur]

To check if anything is missing I read api.md, two-way-accountability.md, and then decred/dcrstakepool#574 looking for things not mentioned in the first two.

First of all I appreciate the new docs. They are easy to read, explain what's going on pretty well and I can imagine writing a custom client with them, so they work as a "spec" for me.

Overall all important stuff is covered. I noted a few points not (explicitly) mentioned in the new docs, listed below.

1. Motivation and improvements over dcrstakepool

solve the privacy issues associated with VSP accounts, while simultaneously removing the VSP fees from tickets themselves, making it possible for both solo and VSP stakers to purchase mixed tickets in the same anonymity set.

Not critical for using the docs and the API but could help for general understanding what was driving the design (ability to mix in the same anon set, redeem scripts, maybe other).

2. Key derivation stuff.

For this design, a new purpose key should be used, since these keys are used differently from normal wallet accounts, and handling should be logically and hierarchically separated. A new purpose key of 565350 is chosen (565350 is the UTF-8 encoding of "VSP", as hex).

This and any other references of accoutns, branches, "purpose key" etc. I'm not sure if this is used in the current implementation or if it belongs to vspd docs, i.e. something vspd is concerned about vs being dcrwallet internals.

3. The bit about constructing signatures

This requires signing a message (which should be constructed in a way that prevents the signature from being used for unintended purposes) with the commitment address' key.

Same as (2), not sure vspd is concerned about this or if it should be in the docs.

4. Timestamped receipts

A timestamped receipt is returned by the server that commits to the ticket and the voting preferences. [or to any other data received from the client]

Looks like "timestamped receipt" is is implemented by VSP-Client-Signature HTTP client request header, VSP-Server-Signature server response header, and the timestamp field in requests and responses (timestamp is signed along the other fields). So this is done and covered by the docs.

5. Storing audit trail

I guess the original idea was for client and server to store all comms between each other locally (for a reasonable duration, e.g. until the ticket is voted?), and optionally anchoring to a blockchain or a transparent log system. In case this is not implemented it could be mentioned as a possible future upgrade.

[jholdstock]

1. Announcement blog post covers most of that stuff. Perhaps this repo could link to that somewhere.
2. Thats an internal wallet detail, it doesn't concern vspd at all. In fact, it is so detached from the implementation of vspd that I don't even know if it was implemented in wallet.
3. Covered in the accountability doc. I've been meaning to add an example to that doc so I've created docs: add a request/response/signature example to accountability doc #380.
4. Yep
5. vspd keeps a permanent log of its comms. We don't want to discard the data after a ticket has voted, thats arguably when it becomes most important because it provides evidence that the vote preferences requested by the user match those which were recorded onchain. It isn't that much data to keep around and we can always purge later if it becomes problematic.

[xaur]

Great, with #380 branched off we can close this with #381. Thank you!