161 lines
3.8 KiB
Markdown
161 lines
3.8 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 info
|
|
|
|
Clients should retrieve the VSP's public key so they can check the signature on
|
|
future API responses. A VSP should never change their public key so it can be
|
|
requested once and cached indefinitely. `vspclosed` indicates that the VSP is
|
|
not currently accepting new tickets. Calling `/feeaddress` when a VSP is closed
|
|
will result in an error.
|
|
|
|
- `GET /api/vspinfo`
|
|
|
|
No request body.
|
|
|
|
Response:
|
|
|
|
```json
|
|
{
|
|
"timestamp":1590599436,
|
|
"pubkey":"SjAmrAqH7LScCUwM1qo5O6Cu7aKhrM1ORszgZwD7HmU=",
|
|
"feepercentage":0.05,
|
|
"vspclosed":false,
|
|
"network":"testnet3"
|
|
}
|
|
```
|
|
|
|
### 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. For this reason, it is important that the client ensures the
|
|
output being spent in the transaction is not spent elsewhere.
|
|
|
|
The VSP 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>"}
|
|
}
|
|
```
|
|
|
|
### Ticket Status
|
|
|
|
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,
|
|
"request": {"<Copy of request body>"}
|
|
}
|
|
```
|