docs: Review and polish existing docs. (#390)

Also includes a couple of updates to comments in webapi code.

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.

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.

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`
 

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.

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
  }

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)