156 lines
3.6 KiB
Markdown
156 lines
3.6 KiB
Markdown
# API
|
|
|
|
## General notes
|
|
|
|
- Success responses use HTTP status 200 and a JSON encoded body.
|
|
|
|
- Error responses use either HTTP status 500 or 400, and a JSON encoded error
|
|
in the body. For example `{"error":"Description"}`.
|
|
|
|
- Requests which reference specific tickets need to be properly signed as
|
|
described in [two-way-accountability.md](./two-way-accountability.md).
|
|
|
|
- Implementation of request and response types can be found in
|
|
[webapi/types.go](./webapi/types.go).
|
|
|
|
## Expected usage
|
|
|
|
### Get VSP public key
|
|
|
|
Clients should first retrieve the VSP's public key so they can check the
|
|
signature on later API responses. A VSP should never change their public key so
|
|
it can be requested once and cached indefinitely.
|
|
|
|
- `GET /api/pubkey`
|
|
|
|
No request body.
|
|
|
|
Response:
|
|
|
|
```json
|
|
{
|
|
"timestamp":1590509065,
|
|
"pubkey":"bLNwVVcda3LqRLv+m0J5sjd60+twjO/fuhcx8RUErDQ="
|
|
}
|
|
```
|
|
|
|
### Register ticket
|
|
|
|
**Registering a ticket is a two step process. The VSP will not add a ticket to
|
|
its voting wallets unless both of these calls have succeeded.**
|
|
|
|
Request fee amount and address for a ticket. The fee amount is only valid until
|
|
the expiration time has passed.
|
|
|
|
- `POST /feeaddress`
|
|
|
|
Request:
|
|
|
|
```json
|
|
{
|
|
"timestamp":1590509066,
|
|
"tickethash":"484a68f7148e55d05f0b64a29fe7b148572cb5272d1ce2438cf15466d347f4f4"
|
|
}
|
|
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{
|
|
"timestamp":1590509066,
|
|
"feeaddress":"Tsfkn6k9AoYgVZRV6ZzcgmuVSgCdJQt9JY2",
|
|
"fee":0.001,
|
|
"expiration":1590563759,
|
|
"request": {"<Copy of request body>"}
|
|
}
|
|
```
|
|
|
|
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. The VSP will not broadcast the fee transaction
|
|
until the ticket purchase has 6 confirmations, and it will not add the ticket to
|
|
its voting wallets until the fee transaction has 6 confirmations.
|
|
|
|
- `POST /payfee`
|
|
|
|
Request:
|
|
|
|
```json
|
|
{
|
|
"timestamp":1590509066,
|
|
"tickethash":"484a68f7148e55d05f0b64a29fe7b148572cb5272d1ce2438cf15466d347f4f4",
|
|
"feetx":"010000000125...737b266ffb9a93",
|
|
"votingkey":"PtWUJWhSXsM9ztPkdtH8REe91z7uoidX8dsMChJUZ2spagm7YvrNm",
|
|
"votechoices":{"headercommitments":"yes"}
|
|
}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{
|
|
"timestamp":1590509066,
|
|
"request": {"<Copy of request body>"}
|
|
}
|
|
```
|
|
|
|
### Information requests
|
|
|
|
Clients can check the status of the server at any time.
|
|
|
|
// TODO
|
|
|
|
Clients can check the status of a ticket at any time after calling
|
|
`/feeaddress`.
|
|
|
|
- `GET /ticketstatus`
|
|
|
|
Request:
|
|
|
|
```json
|
|
{
|
|
"timestamp":1590509066,
|
|
"tickethash":"484a68f7148e55d05f0b64a29fe7b148572cb5272d1ce2438cf15466d347f4f4"
|
|
}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{
|
|
"timestamp":1590509066,
|
|
"status":"active",
|
|
"votechoices":{"headercommitments":"no"},
|
|
"request": {"<Copy of request body>"}
|
|
}
|
|
```
|
|
|
|
### Update vote choices
|
|
|
|
Clients can update the voting preferences of their ticket at any time after
|
|
after calling `/payfee`.
|
|
|
|
- `POST /setvotechoices`
|
|
|
|
Request:
|
|
|
|
```json
|
|
{
|
|
"timestamp":1590509066,
|
|
"tickethash":"484a68f7148e55d05f0b64a29fe7b148572cb5272d1ce2438cf15466d347f4f4",
|
|
"votechoices":{"headercommitments":"no"}
|
|
}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{
|
|
"timestamp":1590509066,
|
|
"votechoices":{"headercommitments":"no"},
|
|
"request": {"<Copy of request body>"}
|
|
}
|
|
```
|