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. 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:

  {
  "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,
    "request": {"<Copy of request body>"}
  }