vspd/docs/api.md

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.

• Implementation of request and response types can be found in 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:

  {
      "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:

  {
      "timestamp":1590509066,
      "tickethash":"484a68f7148e55d05f0b64a29fe7b148572cb5272d1ce2438cf15466d347f4f4"
  }
  
  

  Response:

  {
      "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:

  {
  "timestamp":1590509066,
  "tickethash":"484a68f7148e55d05f0b64a29fe7b148572cb5272d1ce2438cf15466d347f4f4",
  "feetx":"010000000125...737b266ffb9a93",
  "votingkey":"PtWUJWhSXsM9ztPkdtH8REe91z7uoidX8dsMChJUZ2spagm7YvrNm",
  "votechoices":{"headercommitments":"yes"}
  }
  

  Response:

  {
  "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:

  {
      "timestamp":1590509066,
      "tickethash":"484a68f7148e55d05f0b64a29fe7b148572cb5272d1ce2438cf15466d347f4f4"
  }
  

  Response:

  {
      "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:

  {
    "timestamp":1590509066,
    "tickethash":"484a68f7148e55d05f0b64a29fe7b148572cb5272d1ce2438cf15466d347f4f4",
    "votechoices":{"headercommitments":"no"}
  }
  

  Response:

  {
    "timestamp":1590509066,
    "votechoices":{"headercommitments":"no"},
    "request": {"<Copy of request body>"}
  }