From f46ffcb60ddbaf780ab3c682e8cda705a8c5acbc Mon Sep 17 00:00:00 2001 From: Jamie Holdstock Date: Tue, 13 Jun 2023 19:22:57 +0100 Subject: [PATCH] docs: Review and polish existing docs. (#390) Also includes a couple of updates to comments in webapi code. --- README.md | 8 ++++---- cmd/v3tool/README.md | 4 ++-- docs/api.md | 15 +++++++++------ docs/deployment.md | 28 +++++++++++++++------------- webapi/helpers.go | 6 ++++-- webapi/setvotechoices.go | 2 +- 6 files changed, 35 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 3443055f..6d1331a2 100644 --- a/README.md +++ b/README.md @@ -29,12 +29,12 @@ VSP will add the ticket to a pool of always-online voting wallets. detail on the API and its usage, read [api.md](./docs/api.md) - **Web front-end** - A minimal website (no JavaScript) providing public pool - stats. An admin page enables searching for tickets and downloading database - backups. + stats. A password protected admin page provides an overview of system status, + enables searching for tickets and downloading database backups. - **Two-way accountability** - All vspd requests and responses are signed by their sender, which enables both the client and the server to hold each other - accountable in the case of misbehaviour. For more detail, and examples, read + accountable in the case of misbehaviour. For more detail and examples, read [two-way-accountability.md](./docs/two-way-accountability.md). - **Dynamic fees** - Clients must request a new fee address and amount for every @@ -49,7 +49,7 @@ libraries: - [gin-gonic/gin](https://github.com/gin-gonic/gin) webserver. -- [etcd-io/bbolt](https://github.com/etcd-io/bbolt) k/v database. +- [etcd-io/bbolt](https://github.com/etcd-io/bbolt) key-value database. - [jrick/wsrpc](https://github.com/jrick/wsrpc) for RPC communication with dcrd and dcrwallet. diff --git a/cmd/v3tool/README.md b/cmd/v3tool/README.md index 51c62bc4..1a42d116 100644 --- a/cmd/v3tool/README.md +++ b/cmd/v3tool/README.md @@ -5,13 +5,13 @@ It is a developer tool, not suitable for end users or production use. ## Prerequisites -1. An instance of dcrwallet which owns at least one immature or live ticket. +1. An instance of dcrwallet which owns at least one mempool, immature or live ticket. 1. An instance of vspd to test. ## What v3tool does 1. Retrieve the pubkey from vspd. -1. Retrieve the list of owned immature/live tickets from dcrwallet. +1. Retrieve the list of owned mempool/immature/live tickets from dcrwallet. 1. For each ticket: 1. Use dcrwallet to find the tx hex, voting privkey and commitment address of the ticket. 1. Get a fee address and amount from vspd to register this ticket. diff --git a/docs/api.md b/docs/api.md index c075b01a..0d6416ae 100644 --- a/docs/api.md +++ b/docs/api.md @@ -9,7 +9,7 @@ For example: ```json - {"code": 9, "message":"invalid vote choices"} + {"code":9, "message":"invalid vote choices"} ``` A full list of error codes can be looked up in @@ -49,12 +49,12 @@ when a VSP is closed will result in an error. "pubkey":"SjAmrAqH7LScCUwM1qo5O6Cu7aKhrM1ORszgZwD7HmU=", "feepercentage":3.0, "vspclosed":false, - "vspclosedmsg": "", + "vspclosedmsg":"", "network":"testnet3", "vspdversion":"1.0.0-pre", "voting":10, "voted":25, - "totalvotingwallets": 3, + "totalvotingwallets":3, "votingwalletsonline":3, "revoked":3, "blockheight":623212, @@ -103,8 +103,9 @@ only be set once. Further requests to set a new address will be rejected. #### Step One Request fee amount and address for a ticket. The fee amount is only valid until -the expiration time has passed. The fee amount is an absolute value measured in -DCR. Returns an error if the specified ticket is not currently immature or live. +the expiration time has passed. The fee amount is an absolute value denominated +in DCR. Returns an error if the specified ticket is not currently in the +mempool, immature or live. This call will return an error if a fee transaction has already been provided for the specified ticket. @@ -141,7 +142,7 @@ Provide the voting key for the ticket, voting preference, and a signed transaction which pays the fee to the specified address. If the fee has expired, this call will return an error and the client will need to request a new fee by calling `/feeaddress` again. Returns an error if the specified ticket is not -currently immature or live. +currently in the mempool, immature or live. The VSP will not broadcast the fee transaction until the ticket purchase has 6 confirmations. For this reason, it is important that the client ensures the @@ -228,6 +229,8 @@ Clients can update the voting preferences of their ticket at any time after after calling `/payfee`. This call can be used to update consensus, treasury spend key, and tspend voting preferences. +Returns an error if the specified ticket is not currently in the +mempool, immature or live. - `POST /api/v3/setvotechoices` diff --git a/docs/deployment.md b/docs/deployment.md index 8f5c71f6..ee08a14e 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -57,8 +57,8 @@ A wallet should be created to collect VSP fees. Ideally this would be a cold wallet which is not used for any other purpose, and it should be completely separate from the vspd infrastructure. The dcrwallet `getmasterpubkey` RPC should be used to export an extended public (xpub) key from one of the wallet -accounts. This xpub key will be provided to vspd via config, and vspd will use -it to derive a new addresses for receiving fee payments. +accounts. This xpub key will be provided to vspd through a CLI flag, and it will +be used to derive addresses for receiving fee payments. ## Voting Servers @@ -67,14 +67,16 @@ servers hosting these wallets should ideally be in geographically separate locations. Each voting server should be running an instance of dcrd and dcrwallet. The -wallet on these servers should be completely empty and not used for any other -purpose. dcrwallet should be permanently unlocked and have voting enabled +wallet on these servers should be completely empty and not used for any purpose +other than voting tickets added by vspd. +dcrwallet should be permanently unlocked and have voting enabled (`--enablevoting`). dcrwallet is also required to have the manual tickets option (`--manualtickets`) enabled which disables dcrwallet adding tickets -arriving over the network. Without this option set, a user could reuse -voting addresses the VSP's voting wallets already have private keys for, -resulting in the VSP voting tickets without a fee paid. vspd on the -front-end server must be able to reach each instance of dcrwallet over RPC. +arriving over the network. +This prevents a user from reusing a voting address and the VSP voting multiple +tickets with only a single fee payment. +vspd on the front-end server must be able to reach each instance of dcrwallet +over RPC. ## Front-end Server @@ -188,11 +190,11 @@ the path `{homedir}/data/{network}/vspd.db`. vspd keeps a file lock on this file, so it cannot be opened by any other processes while vspd is running. To facilitate back-ups, vspd will periodically write a copy of the bbolt -database to the path `{homedir}/data/{network}/vspd.db-backup`. A copy of the -database file will also be written to this path when vspd shuts down. This file -should be backed up often and regularly (probably at least hourly). Backups -should be transferred off-site, ideally to a server which is not part of the -vspd deployment. +database to the path `{homedir}/data/{network}/vspd.db-backup`. +The backup file will also be written when vspd shuts down. +This file should be backed up often and regularly (probably at least hourly). +Backups should be transferred off-site, ideally to a server which is not part of +the vspd deployment. It is also possible to generate and download a database backup on demand from the admin page of the vspd web front-end. diff --git a/webapi/helpers.go b/webapi/helpers.go index 535d1c86..f947dfb5 100644 --- a/webapi/helpers.go +++ b/webapi/helpers.go @@ -170,7 +170,8 @@ func validateTicketHash(hash string) error { } // canTicketVote checks determines whether a ticket is able to vote at some -// point in the future by checking that it is currently either immature or live. +// point in the future by checking that it is currently either in the mempool, +// immature or live. func canTicketVote(rawTx *dcrdtypes.TxRawResult, dcrdClient Node, netParams *chaincfg.Params) (bool, error) { // Tickets which have more than (TicketMaturity+TicketExpiry+1) @@ -179,7 +180,8 @@ func canTicketVote(rawTx *dcrdtypes.TxRawResult, dcrdClient Node, netParams *cha return false, nil } - // If ticket is currently immature, it will be able to vote in future. + // If ticket is currently immature (or in the mempool), it will be able to + // vote in future. if rawTx.Confirmations <= int64(netParams.TicketMaturity) { return true, nil } diff --git a/webapi/setvotechoices.go b/webapi/setvotechoices.go index ec8cc26e..014ba991 100644 --- a/webapi/setvotechoices.go +++ b/webapi/setvotechoices.go @@ -46,7 +46,7 @@ func (s *Server) setVoteChoices(c *gin.Context) { return } - // Only allow vote choices to be updated for live/immature tickets. + // Only allow vote choices to be updated for mempool/immature/live tickets. if ticket.Outcome != "" { s.log.Warnf("%s: Ticket not eligible to vote (clientIP=%s, ticketHash=%s)", funcName, c.ClientIP(), ticket.Hash)