Skip to content

Latest commit

 

History

History
257 lines (197 loc) · 7.43 KB

api.md

File metadata and controls

257 lines (197 loc) · 7.43 KB
Raw

API

General notes

  • Success responses use HTTP status 200 and a JSON encoded body.

  • Error responses use HTTP status 500 to indicate a server error or 4XX to indicate a client error, and will include a JSON body describing the error. For example:

    {"code":9, "message":"invalid vote choices"}

    A full list of error codes can be looked up in types/errors.go

  • 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 types/types.go.

  • The initial version of the vspd API is version 3. This is because the first version of the vspd API actually represents the third iteration of VSP APIs. The first and second iterations of VSP API were implemented by dcrstakepool.

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 or /payfee when a VSP is closed will result in an error.

  • GET /api/v3/vspinfo

    No request body.

    Response:

    {
    "apiversions":[3],
    "timestamp":1590599436,
    "pubkey":"SjAmrAqH7LScCUwM1qo5O6Cu7aKhrM1ORszgZwD7HmU=",
    "feepercentage":3.0,
    "vspclosed":false,
    "vspclosedmsg":"",
    "network":"testnet3",
    "vspdversion":"1.0.0-pre",
    "voting":10,
    "voted":25,
    "totalvotingwallets":3,
    "votingwalletsonline":3,
    "expired":2,
    "missed":1,
    "blockheight":623212,
    "estimatednetworkproportion":0.048478414
}

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.

Step Zero (optional)

Set an alternate signing address for a ticket. The ticket must be valid and will be transmitted to the network if not found. If set, for all future requests involving this ticket, the VSP will check that a signature is good for this address and fallback to the commitment address if not. The address must be valid for the network and a pay to secp256k1 ECDSA pubkey hash script. The address can only be set once. Further requests to set a new address will be rejected.

  • POST /api/v3/setaltsignaddr

    Request:

    {
    "timestamp":1590509066,
    "tickethash":"1b9f5dc3b4872c47f66b148b0633647458123d72a0f0623a90890cc51a668737",
    "tickethex":"0100000001a8...bfa6e4bf9c5ec1",
    "parenthex":"0100000022a7...580771a3064710",
    "altsignaddress":"Tsfkn6k9AoYgVZRV6ZzcgmuVSgCdJQt9JY2"
}

    Response:

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

Step One

Request fee amount and address for a ticket. The fee amount is only valid until the expiration time has passed. The fee amount is an absolute value denominated in DCR. Returns an error if the specified ticket is not currently in the mempool, immature or live.

This call will return an error if a fee transaction has already been provided for the specified ticket.

  • POST /api/v3/feeaddress

    Request:

    {
    "timestamp":1590509066,
    "tickethash":"1b9f5dc3b4872c47f66b148b0633647458123d72a0f0623a90890cc51a668737",
    "tickethex":"0100000001a8...bfa6e4bf9c5ec1",
    "parenthex":"0100000022a7...580771a3064710"
}

    Response:

    {
    "timestamp":1590509066,
    "feeaddress":"Tsfkn6k9AoYgVZRV6ZzcgmuVSgCdJQt9JY2",
    "feeamount":0.001,
    "expiration":1590563759,
    "request": {"<Copy of request body>"}
}

Step Two

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. Returns an error if the specified ticket is not currently in the mempool, immature or live.

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.

This call will return an error if a fee transaction has already been provided for the specified ticket.

  • POST /api/v3/payfee

    Request:

    {
"timestamp":1590509066,
"tickethash":"484a68f7148e55d05f0b64a29fe7b148572cb5272d1ce2438cf15466d347f4f4",
"feetx":"010000000125...737b266ffb9a93",
"votingkey":"PtWUJWhSXsM9ztPkdtH8REe91z7uoidX8dsMChJUZ2spagm7YvrNm",
"votechoices":{"headercommitments":"yes"},
"tspendpolicy":{"<tspend tx hash>":"yes"},
"treasurypolicy":{"<treasury spending key>":"no"}
}

    Response:

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

Ticket Status

Clients can check the status of a ticket at any time after calling /feeaddress.

  • ticketconfirmed is true when the ticket purchase has 6 confirmations.
  • feetxstatus can have the following values:
    • none - No fee transaction has been received yet.
    • received - Fee transaction has been received but not broadcast.
    • broadcast - Fee transaction has been broadcast but not confirmed.
    • confirmed - Fee transaction has been broadcast and confirmed.
    • error - Fee transaction could not be broadcast due to an error (eg. output in the tx was double spent).

If feetxstatus is error, the client needs to provide a new fee transaction using /payfee. The VSP will only add a ticket to the voting wallets once its feetxstatus is confirmed.

  • POST /api/v3/ticketstatus

    Request:

    {
    "tickethash":"484a68f7148e55d05f0b64a29fe7b148572cb5272d1ce2438cf15466d347f4f4"
}

    Response:

    {
  "timestamp":1590509066,
  "ticketconfirmed":true,
  "feetxstatus":"broadcast",
  "feetxhash":"e1c02b04b5bbdae66cf8e3c88366c4918d458a2d27a26144df37f54a2bc956ac",
  "altsignaddress":"Tsfkn6k9AoYgVZRV6ZzcgmuVSgCdJQt9JY2",
  "votechoices":{"headercommitments":"no"},
  "tspendpolicy":{"<tspend tx hash>":"yes"},
  "treasurypolicy":{"<treasury spending key>":"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. This call can be used to update consensus, treasury spend key, and tspend voting preferences. Returns an error if the specified ticket is not currently in the mempool, immature or live.

  • POST /api/v3/setvotechoices

    Request:

    {
  "timestamp":1590509066,
  "tickethash":"484a68f7148e55d05f0b64a29fe7b148572cb5272d1ce2438cf15466d347f4f4",
  "votechoices":{"headercommitments":"no"},
  "tspendpolicy":{"<tspend tx hash>":"yes"},
  "treasurypolicy":{"<treasury spending key>":"no"}
}

    Response:

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