|
| 1 | +# vspd 1.1.0 |
| 2 | + |
| 3 | +This release of vspd introduces several new features, as well as some important |
| 4 | +performance improvements and bug fixes. Some of the key highlights are: |
| 5 | + |
| 6 | +- Enabling users to set voting preferences for Treasury spend votes. |
| 7 | +- Supporting tickets purchased with Trezor hardware wallets. |
| 8 | +- Improvements to the web interface such as exposing more stats on the homepage, |
| 9 | + and a tabbed navigation system for the admin screen. |
| 10 | +- Dramatically improving performance of the vspd database when it contains a |
| 11 | + large number of tickets. |
| 12 | +- Several changes to the HTTP API. |
| 13 | +- Several new config file settings. |
| 14 | + |
| 15 | +Details of all notable changes and new features are provided in a section below. |
| 16 | + |
| 17 | +vspd v1.1.0 contains all development work completed since |
| 18 | +[v1.0.0](https://github.com/decred/vspd/releases/tag/release-v1.0.0) (January 2021). |
| 19 | +Since then, 82 commits have been produced and merged by 5 contributors. All |
| 20 | +commits included in this release can be viewed on GitHub |
| 21 | +[here](https://github.com/decred/vspd/compare/release-v1.0.0...release-v1.1.0). |
| 22 | + |
| 23 | +## Downgrade Warning |
| 24 | + |
| 25 | +This release contains a backwards incompatible database upgrade. |
| 26 | +The new database format is not compatible with previous versions of the vspd |
| 27 | +software, and there is no code to downgrade the database back to the previous |
| 28 | +version. |
| 29 | + |
| 30 | +Making a copy of the database backup before running the upgrade is suggested |
| 31 | +in order to enable rolling back to a previous version of the software if required. |
| 32 | + |
| 33 | +## Dependencies |
| 34 | + |
| 35 | +vspd 1.1.0 must be built with go 1.16 or later, and requires: |
| 36 | + |
| 37 | +- dcrd 1.7.1 |
| 38 | +- dcrwallet 1.7.1 |
| 39 | + |
| 40 | +When deploying vspd to production, always use release versions of all binaries. |
| 41 | +Neither vspd nor its dependencies should be built from master when handling |
| 42 | +mainnet tickets. |
| 43 | + |
| 44 | +## Recommended Upgrade Path |
| 45 | + |
| 46 | +The upgrade path below includes vspd downtime, during which clients will not be |
| 47 | +able to register new tickets, check their ticket status, or update their voting |
| 48 | +preferences. Voting on tickets already registered with the VSP will not be |
| 49 | +interrupted. You may wish to put up a temporary maintenance webpage or announce |
| 50 | +downtime in public channels. |
| 51 | + |
| 52 | +1. Build vspd from the 1.1.0 release tag. Build dcrwallet and dcrd from their |
| 53 | + 1.7.1 release tags. |
| 54 | +1. Stop vspd. |
| 55 | +1. Stop the instance of dcrd running on the vspd server. |
| 56 | +1. **Make a backup of the vspd database file in case rollback is required.** |
| 57 | +1. Install new dcrd binary on the vspd server, start it and it will begin |
| 58 | + database upgrades. You can proceed with the following steps while the |
| 59 | + upgrades run. |
| 60 | +1. Upgrade voting wallets one at a time so at least two wallets remain online |
| 61 | + for voting. On each server: |
| 62 | + 1. Stop dcrwallet. |
| 63 | + 1. Stop dcrd. |
| 64 | + 1. Install new dcrd binary and start. |
| 65 | + 1. Wait for dcrd database upgrades to complete. |
| 66 | + 1. Check dcrd log file for warnings or errors. |
| 67 | + 1. Install new dcrwallet binary and start. |
| 68 | + 1. Wait for dcrwallet database upgrades to complete. |
| 69 | + 1. Check dcrwallet log file for warnings or errors. |
| 70 | +1. Make any required changes to `vspd.conf`. New config items are detailed below. |
| 71 | +1. Wait for dcrd on the vspd server to complete its database upgrade. |
| 72 | +1. Check dcrd log file for warnings or errors. |
| 73 | +1. Install new vspd binary and start it. |
| 74 | +1. Check vspd log file for warnings or errors. |
| 75 | +1. Log in to the admin webpage and check the VSP Status tab for any issues. |
| 76 | + |
| 77 | +## Notable Changes |
| 78 | + |
| 79 | +### Treasury Spend Voting |
| 80 | + |
| 81 | +This release adds the ability for users to set their voting preferences for |
| 82 | +transactions spending from the Decred Treasury. |
| 83 | + |
| 84 | +Users can either set their voting preference for a single TSpend hash (a.k.a. |
| 85 | +TSpend policy), or they can chose to set a preference for all TSpends signed by |
| 86 | +a specific Treasury key (a.k.a. Treasury policy). |
| 87 | +This corresponds directly to the API exposed by dcrwallet. |
| 88 | + |
| 89 | +Voting policies can be set when a ticket is initially registered with vspd using |
| 90 | +the `/payfee` endpoint, and they may subsequently be updated with the |
| 91 | +`/setvotechoices` endpoint. |
| 92 | + |
| 93 | +TSpend and Treasury policies will be returned from the `/ticketstatus` endpoint, |
| 94 | +as well as being shown in ticket lookup section of the admin screen. |
| 95 | +Any requests which set or update TSpend or Treasury policies will be recorded in |
| 96 | +the same manner that requests updating consensus vote choices are currently |
| 97 | +recorded. |
| 98 | + |
| 99 | +### Trezor Support |
| 100 | + |
| 101 | +Requests sent to vspd must be signed in order to prove ticket ownership. |
| 102 | +Previously this signing would only be allowed with the commitment address of a |
| 103 | +ticket, but in order to enable support for tickets purchased with a Trezor |
| 104 | +hardware wallet, clients may now add alternate signing addresses to their |
| 105 | +tickets. |
| 106 | + |
| 107 | +A single alternate signing address can be added to each ticket by using a new |
| 108 | +API call `/setaltsignaddr`. The initial call to this endpoint must still be |
| 109 | +signed with the tickets commitment address, but any subsequent calls may be |
| 110 | +signed with either the commitment address or the address provided in the |
| 111 | +`/setaltsignaddr` call. |
| 112 | + |
| 113 | +All requests and responses from this endpoint are added to the database using |
| 114 | +existing mechanisms, to ensure |
| 115 | +[two-way accountability](https://github.com/decred/vspd/blob/master/docs/two-way-accountability.md) |
| 116 | +is maintained. |
| 117 | + |
| 118 | +If a ticket has an alternate signing address it will be shown in ticket lookup |
| 119 | +section of the admin screen, and it will be returned by the `/ticketstatus` API |
| 120 | +call. |
| 121 | + |
| 122 | +### Admin screen improvements |
| 123 | + |
| 124 | +- The features of the admin screen are now separated into a tabbed interface. |
| 125 | + The tabs are: |
| 126 | + - VSP Status |
| 127 | + - Ticket Search |
| 128 | + - Database |
| 129 | + - Logout |
| 130 | +- Show status of the vspd server's local dcrd instance (previously only voting |
| 131 | + wallet status was shown). |
| 132 | +- Wallet status table redesigned to match Decred look and feel. |
| 133 | +- Database file size is now shown. |
| 134 | +- Ticket information: |
| 135 | + - Table split into "Ticket", "Fee" and "Vote Choice" sections. |
| 136 | + - Raw JSON is now formatted for improved readability. |
| 137 | + - Ticket fees are displayed in DCR rather than atoms. |
| 138 | + - Block explorer links added for hashes, blocks heights and addresses. |
| 139 | + - Ticket purchase height is displayed. |
| 140 | + - Date/times are now properly formatted instead of displaying raw Unix timestamps. |
| 141 | + |
| 142 | +### General UI improvements |
| 143 | + |
| 144 | +- Homepage now displays a message when the VSP is closed. This is configurable, |
| 145 | + although a sensible default is also provided. |
| 146 | +- Large numbers are now comma separated. |
| 147 | +- Network proportion added to displayed stats. |
| 148 | +- Display number of a revoked tickets as proportion of all tickets. |
| 149 | +- Include timezone in timestamps. |
| 150 | +- Add cache-busting to all web resources to ensure web clients will always |
| 151 | + download new versions when resources change. |
| 152 | +- Cleared up terminology around "**Consensus** vote choices", so as to |
| 153 | + distinguish from newly added "**Treasury** vote choices". |
| 154 | + |
| 155 | +### Database Performance |
| 156 | + |
| 157 | +In order to preemptively deal with scaling issues seen on vspd databases |
| 158 | +containing very large numbers of tickets, a number of changes have been made to |
| 159 | +the database code and the database storage format. |
| 160 | + |
| 161 | +- Each ticket is now stored in its own database bucket. Previously tickets were |
| 162 | + stored in a single bucket as JSON encoded strings. |
| 163 | +- Previously when searching through all tickets in the database with a filter, |
| 164 | + every ticket would be fully deserialized. Now only tickets which match the |
| 165 | + filter are deserialized. |
| 166 | +- The fee payment raw transaction hex is now only stored in the database for as |
| 167 | + long as it is required. Once the transaction is confirmed on-chain, the hex is |
| 168 | + deleted from the database. |
| 169 | + |
| 170 | +As a result of these changes: |
| 171 | + |
| 172 | +- Database file size is reduced by ~30%. A database with 200,000 tickets can now |
| 173 | + be expected to use roughly 900 MB of disk space, and 400,000 tickets around |
| 174 | + 1,700 MB. |
| 175 | +- Count, search and insert times now scale linearly with number of tickets |
| 176 | + stored (previously scaled exponentially). |
| 177 | +- Given a database containing 200,000 tickets: |
| 178 | + - Count time reduced by ~90% |
| 179 | + - Insert/search time reduced by ~65% |
| 180 | + |
| 181 | +### API changes |
| 182 | + |
| 183 | +- New endpoint `/setaltsignaddr` allows clients to add an alternate signing |
| 184 | + address to their tickets. |
| 185 | +- Optional parameters added to `/payfee` and `/setvotechoices` for setting |
| 186 | + TSpend and Treasury voting preferences. |
| 187 | +- Network proportion, closed message and best block height added to `/vspinfo`. |
| 188 | +- Alternate signing address and Treasury/TSpend policies are returned by |
| 189 | + `/ticketstatus` response. |
| 190 | +- Status of the vspd server's local dcrd instance is now included in the |
| 191 | + `/admin/status` response. |
| 192 | + |
| 193 | +### Config Changes |
| 194 | + |
| 195 | +- Behaviour of the internal log rotator can now be customized using new |
| 196 | + `maxlogsize` and `logstokeep` options. These values were previously hard-coded |
| 197 | + which limited the amount of log history which would be retained. |
| 198 | +- A new option `vspclosedmsg` can be used to display a short message on the |
| 199 | + webpage when `vspclosed` is set to true. The message will also be returned by |
| 200 | + the `/vspinfo` API endpoint. |
| 201 | + |
| 202 | +### Bug Fixes |
| 203 | + |
| 204 | +- Terminate process on `SIGHUP` signal, not just `SIGTERM` or `SIGINT` |
| 205 | + ([#293](https://github.com/decred/vspd/pull/293)). |
| 206 | +- Log client IPs from `X-Forwarded-For` or `X-Real-Ip` HTTP headers |
| 207 | + ([#308](https://github.com/decred/vspd/pull/308)). |
| 208 | +- Ensure purchase height is always set for every ticket |
| 209 | + ([#277](https://github.com/decred/vspd/pull/277)). |
| 210 | +- Wait for any running notification handlers to finish before closing RPC/DB |
| 211 | + connections ([#271](https://github.com/decred/vspd/pull/271)). |
| 212 | +- Removed two data races in the API data caching code |
| 213 | + ([#273](https://github.com/decred/vspd/pull/273)). |
| 214 | +- Ensure panics generated by web requests are logged to file and not only |
| 215 | + stdout. This includes logging a stack trace, and the full body and headers of |
| 216 | + the HTTP request which caused the panic |
| 217 | + ([#255](https://github.com/decred/vspd/pull/255)). |
| 218 | +- Return an error response to clients if generating a fee address fails |
| 219 | + ([#240](https://github.com/decred/vspd/pull/240)). |
| 220 | +- Avoid a potential divide by zero |
| 221 | + ([#282](https://github.com/decred/vspd/pull/282)). |
| 222 | +- Ensure tickets which are revoked outside of the vspd deployment (eg. by a |
| 223 | + users ticketbuyer wallet) are identified as revoked by vspd. |
| 224 | + ([#301](https://github.com/decred/vspd/pull/301)). |
| 225 | +- Add new vote choices to old ones, rather than destructively overwriting the |
| 226 | + old choices ([#323](https://github.com/decred/vspd/pull/323)). |
0 commit comments