docs: Review and polish existing docs. (#390)
Also includes a couple of updates to comments in webapi code.
This commit is contained in:
Jamie Holdstock
GitHub
parent
43a1b9fbdc
commit
f46ffcb60d
@ -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.
|
||||
|
||||
@ -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.
|
||||
|
||||
15
docs/api.md
15
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`
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
}
|
||||
|
||||
@ -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)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user