decred.org/dcrwallet/v3@v3.1.0/rpc/documentation/api.md

# RPC API Specification

Version: 7.13.x

**Note:** This document assumes the reader is familiar with gRPC concepts.
Refer to the [gRPC Concepts documentation](https://www.grpc.io/docs/guides/concepts.html)
for any unfamiliar terms.

**Note:** The naming style used for autogenerated identifiers may differ
depending on the language being used.  This document follows the naming style
used by Google in their Protocol Buffers and gRPC documentation as well as this
project's `.proto` files.  That is, CamelCase is used for services, methods, and
messages, lower_snake_case for message fields, and SCREAMING_SNAKE_CASE for
enums.

This document is the authoritative source on the RPC API's definitions and
semantics.  Any divergence from this document is an implementation error.  API
fixes and additions require a version increase according to the rules of
[Semantic Versioning 2.0.0](https://semver.org/).

Only optional proto3 message fields are used (the `required` keyword is never
used in the `.proto` file).  If a message field must be set to something other
than the default value, or any other values are invalid, the error must occur in
the application's message handling.  This prevents accidentally introducing
parsing errors if a previously optional field is missing or a new required field
is added.

Functionality is grouped into gRPC services.  Depending on what functions are
currently callable, different services will be running.  As an example, the
server may be running without a loaded wallet, in which case the Wallet service
is not running and the Loader service must be used to create a new or load an
existing wallet.

- [`VersionService`](#versionservice)
- [`WalletLoaderService`](#walletloaderservice)
- [`WalletService`](#walletservice)
- [`SeedService`](#seedservice)
- [`TicketBuyerService`](#ticketbuyerservice)
- [`TicketBuyerV2Service`](#ticketbuyerv2service)
- [`AgendaService`](#agendaservice)
- [`VotingService`](#votingservice)
- [`MessageVerificationService`](#messageverificationservice)
- [`DecodeMessageService`](#decodemessageservice)
- [`NetworkService`](#networkservice)

## `VersionService`

The `VersionService` service provides the caller with versioning information
regarding the RPC server.  It has no dependencies and is always running.

**Methods:**

- [`Version`](#version)

### Methods

#### `Version`

The `Version` method returns the RPC server version.  Versioning follows the
rules of Semantic Versioning (SemVer) 2.0.0.

**Request:** `VersionRequest`

**Response:** `VersionResponse`

- `string version_string`: The version encoded as a string.

- `uint32 major`: The SemVer major version number.

- `uint32 minor`: The SemVer minor version number.

- `uint32 patch`: The SemVer patch version number.

- `string prerelease`: The SemVer pre-release version identifier, if any.

- `string build_metadata`: Extra SemVer build metadata, if any.

**Expected errors:** None

**Stability:** Stable: This service will never introduce a breaking change even
  in future major versions of the API.  It is suitable and recommended to use as
  a runtime compatibility check.

## `WalletLoaderService`

The `WalletLoaderService` service provides the caller with functions related to
the management of the wallet and its connection to the Decred network.  It has
no dependencies and is always running.

**Methods:**

- [`WalletExists`](#walletexists)
- [`CreateWallet`](#createwallet)
- [`CreateWatchingOnlyWallet`](#createwatchingonlywallet)
- [`OpenWallet`](#openwallet)
- [`CloseWallet`](#closewallet)
- [`RescanPoint`](#rescanpoint)
- [`SpvSync`](#spvsync)
- [`RpcSync`](#rpcsync)

**Shared messages:**

- [`BlockDetails`](#blockdetails)
- [`DetachedBlockDetails`](#detachedblockdetails)
- [`TransactionDetails`](#transactiondetails)
- [`DecodedTransaction`](#decodedtransaction)

### Methods

#### `WalletExists`

The `WalletExists` method returns whether a file at the wallet database's file
path exists.  Clients that must load wallets with this service are expected to
call this RPC to query whether `OpenWallet` should be used to open an existing
wallet, or `CreateWallet` to create a new wallet.

**Request:** `WalletExistsRequest`

**Response:** `WalletExistsResponse`

- `bool exists`: Whether the wallet file exists.

**Expected errors:** None

___

#### `CreateWallet`

The `CreateWallet` method is used to create a wallet that is protected by two
levels of encryption: the public passphrase (for data that is made public on the
blockchain) and the private passphrase (for private keys).  Since the seed is
not saved in the wallet database and clients should make their users backup the
seed, it needs to be passed as part of the request.

After creating a wallet, the `WalletService` service begins running.

Since API version 3.0.0, creating the wallet no longer automatically
synchronizes the wallet to the consensus server if it was previously loaded.

**Request:** `CreateWalletRequest`

- `bytes public_passphrase`: The passphrase used for the outer wallet
  encryption.  This passphrase protects data that is made public on the
  blockchain.  If this passphrase has zero length, an insecure default is used
  instead.

- `bytes private_passphrase`: The passphrase used for the inner wallet
  encryption.  This is the passphrase used for data that must always remain
  private, such as private keys.  The length of this field must not be zero.

- `bytes seed`: The BIP0032 seed used to derive all wallet keys.  The length of
  this field must be between 16 and 64 bytes, inclusive.

**Response:** `CreateWalletReponse`

**Expected errors:**

- `FailedPrecondition`: The wallet is currently open.

- `AlreadyExists`: A file already exists at the wallet database file path.

- `InvalidArgument`: A private passphrase was not included in the request, or
  the seed is of incorrect length.

___

#### `CreateWatchingOnlyWallet`

The `CreateWatchingOnlyWallet` method is used to create a watching only wallet.
After creating a wallet, the `WalletService` service begins running.

**Request:** `CreateWatchingOnlyWalletRequest`

- `string extended_public_key`: The extended public key of the wallet.

- `bytes public_passphrase`: The passphrase used for the outer wallet
  encryption.  This passphrase protects data that is made public on the
  blockchain.  If this passphrase has zero length, an insecure default is used
  instead.

**Response:** `CreateWatchingOnlyWalletReponse`

**Expected errors:**

- `FailedPrecondition`: The wallet is currently open.

- `AlreadyExists`: A file already exists at the wallet database file path.

___

#### `OpenWallet`

The `OpenWallet` method is used to open an existing wallet database.  If the
wallet is protected by a public passphrase, it can not be successfully opened if
the public passphrase parameter is missing or incorrect.

After opening a wallet, the `WalletService` service begins running.

Since API version 3.0.0, creating the wallet no longer automatically
synchronizes the wallet to the consensus server if it was previously loaded.

**Request:** `OpenWalletRequest`

- `bytes public_passphrase`: The passphrase used for the outer wallet
  encryption.  This passphrase protects data that is made public on the
  blockchain.  If this passphrase has zero length, an insecure default is used
  instead.

**Response:** `OpenWalletResponse`

**Expected errors:**

- `FailedPrecondition`: The wallet is currently open.

- `NotFound`: The wallet database file does not exist.

- `InvalidArgument`: The public encryption passphrase was missing or incorrect.

___

#### `CloseWallet`

The `CloseWallet` method is used to cleanly stop all wallet operations on a
loaded wallet and close the database.  After closing, the `WalletService`
service will remain running but any operations that require the database will be
unusable.

**Request:** `CloseWalletRequest`

**Response:** `CloseWalletResponse`

**Expected errors:**

- `FailedPrecondition`: The wallet is not currently open.

___

#### `RescanPoint`

The `RescanPoint` returns the block hash at which a rescan should begin
(inclusive), or null when no rescan is necessary.  A non-null rescan point
indicates that blocks currently in the main chain must be checked for address
usage and relevant transactions.

**Request:** `RescanPointRequest`

**Response:** `RescanPointResponse`

- `bytes rescan_point`: The current hash of the rescan point.

**Expected Errors:**

- `FailedPrecondition`: The wallet or consensus RPC server has not been opened.

___

#### `SpvSync`

The `SpvSync` method begins the spv syncing process.  It will
stream back progress to provide feedback on the current state of the wallet
loading/bringup.  This is a long lived RPC and only end when canceled
or upon received an error.

**Request:** `SpvSyncRequest`

- `bool discover_accounts`:  Whether or not the wallet should attempt to
  discover accounts during discovery.  This requires the private passphrase to
  be set as well and will error otherwise.

- `bytes private_passphrase`: The current private passphrase for the wallet.
  This is only required if discover_accounts is set to true and will error
  otherwise.

- `repeated string spv_connect`: When given a list of addresses, the wallet in
  spv mode will no longer attempt to use DNS address discovery to seek out other
  persistent peers and instead use the ones specified here as persistent peers.

**Response:** `stream SpvSyncResponse`

- `bool synced`: This streamed update response denotes whether the wallet is
  synced or not.

- `SyncNotificationType notification_type`: This denotes what type of
  notification has been sent by the wallet.

- `FetchHeadersNotification fetch_headers`: This contains all the information
  for a fetch headers notification response.  In any other case it will be 
  set to nil.

- `FetchMissingCFiltersNotification fetch_missing_cfilters`: This contains all
  the information for a fetch missing cfilters notification response.  In any
  other case it will be set to nil.

- `RescanProgressNotifiction rescan_progress`: This contains all the information
  for a rescan progress notification.  In any other case it will be set to nil.

- `PeerNotification peer_information`: This contains information about the
  current state of the wallet's peers.

**Expected Errors:**

- `FailedPrecondition`: The wallet or consensus RPC server has not been opened.
  The private passphrase does not successfully unlock the wallet.  The string
  provided to spv_connect is not a valid address or port.

- `InvalidArgument`: The private passphrase is incorrect.

___

#### `RpcSync`

The `RpcSync` method begins the syncing process via rpc connection to a daemon. 
It will stream back progress to provide feedback on the current state of the
wallet loading/bringup.  This is a long lived RPC and only end when canceled
or upon received an error.

**Request:** `RpcSyncRequest`

- `string network_address`: The host/IP and optional port of the RPC server to
  connect to.  IP addresses may be IPv4 or IPv6.  If the port is missing, a
  default port is chosen corresponding to the default dcrd RPC port of the
  active Decred network.

- `string username`: The RPC username required to authenticate to the RPC
  server.

- `bytes password`: The RPC password required to authenticate to the RPC server.

- `bytes certificate`: The consensus RPC server's TLS certificate.  If this
  field has zero length and the network address describes a loopback connection
  (`localhost`, `127.0.0.1`, or `::1`) TLS will be disabled.

- `bool discover_accounts`:  Whether or not the wallet should attempt to
  discover accounts during discovery.  This requires the private passphrase to
  be set as well and will error otherwise.

- `bytes private_passphrase`: The current private passphrase for the wallet.
  This is only required if discover_accounts is set to true and will error
  otherwise.

- `repeated string spv_connect`: When given a list of addresses, the wallet in
  spv mode will no longer attempt to use DNS address discovery to seek out other
  persistent peers and instead use the ones specified here as persistent peers.

**Response:** `stream RpcSyncResponse`

- `bool synced`: This streamed update response denotes whether the wallet is
  synced or not.

- `SyncNotificationType notification_type`: This denotes what type of
  notification has been sent by the wallet.

- `FetchHeadersNotification fetch_headers`: This contains all the information
  for a fetch headers notification response.  In any other case it will be 
  set to nil.

- `FetchMissingCFiltersNotification fetch_missing_cfilters`: This contains all
  the information for a fetch missing cfilters notification response.  In any
  other case it will be set to nil.

- `RescanProgressNotifiction rescan_progress`: This contains all the information
  for a rescan progress notification.  In any other case it will be set to nil.

- `SyncingStatus syncing_status`: Various properties to describe the current
  state of syncing the wallet is currently performing.  Once synced, this will
  be set to nil.

**Expected Errors:**

- `InvalidArgument`: The network address is ill-formatted or does not contain a
  valid IP address.
  
- `InvalidArgument`: The private passphrase is not supplied, but discoveraccounts
  is requested. 

- `InvalidArgument`: The username, password, or certificate are invalid.  This
  condition may not be return `Unauthenticated` as that refers to the client not
  having the credentials to call this method.

- `Unavailable`: The consensus RPC server is unreachable.

- `FailedPrecondition`: A consensus RPC client is already active.

- `FailedPrecondition`: The wallet or consensus RPC server has not been opened.

- `FailedPrecondition`: The private passphrase does not successfully unlock the
  wallet.

## `WalletService`

The WalletService service provides RPCs for the wallet itself.  The service
depends on a loaded wallet and does not run when the wallet has not been created
or opened yet.

The service provides the following methods:

- [`Ping`](#ping)
- [`Network`](#network)
- [`AccountNumber`](#accountnumber)
- [`Accounts`](#accounts)
- [`Balance`](#balance)
- [`BlockInfo`](#blockinfo)
- [`GetTransaction`](#gettransaction)
- [`GetTransactions`](#gettransactions)
- [`GetTicket`](#getticket)
- [`GetTickets`](#gettickets)
- [`ChangePassphrase`](#changepassphrase)
- [`RenameAccount`](#renameaccount)
- [`Rescan`](#rescan)
- [`NextAccount`](#nextaccount)
- [`NextAddress`](#nextaddress)
- [`ImportPrivateKey`](#importprivatekey)
- [`ImportScript`](#importscript)
- [`ImportVotingAccountFromSeed`](#importvotingaccountfromseed)
- [`FundTransaction`](#fundtransaction)
- [`UnspentOutputs`](#unspentoutputs)
- [`ConstructTransaction`](#constructtransaction)
- [`SignTransaction`](#signtransaction)
- [`SignTransactions`](#signtransactions)
- [`CreateSignature`](#createsignature)
- [`PublishTransaction`](#publishtransaction)
- [`PublishUnminedTransactions`](#publishunminedtransactions)
- [`TicketPrice`](#ticketprice)
- [`StakeInfo`](#stakeinfo)
- [`PurchaseTickets`](#purchasetickets)
- [`RevokeTickets`](#revoketickets)
- [`LoadActiveDataFilters`](#loadactivedatafilters)
- [`SignMessage`](#signmessage)
- [`SignMessages`](#signmessages)
- [`ValidateAddress`](#validateaddress)
- [`AbandonTransaction`](#abandontransaction)
- [`TransactionNotifications`](#transactionnotifications)
- [`AccountNotifications`](#accountnotifications)
- [`ConfirmationNotifications`](#confirmationnotifications)
- [`CommittedTickets`](#committedtickets)
- [`BestBlock`](#bestblock)
- [`SweepAccount`](#sweepaccount)
- [`SignHashes`](#signhashes)
- [`GetCFilters`](#GetCFilters)
- [`UnlockWallet`](#UnlockWallet)
- [`LockWallet`](#LockWallet)
- [`UnlockAccount`](#UnlockAccount)
- [`LockAccount`](#LockAccount)
- [`GetTrackedVSPTickets`](#GetTrackedVSPTickets)
- [`Address`](#Address)
- [`DumpPrivateKey`](#DumpPrivateKey)

#### `Ping`

The `Ping` method checks whether the service is active.

**Request:** `PingRequest`

**Response:** `PingResponse`

**Expected errors:** None

___

#### `Network`

The `Network` method returns the network identifier constant describing the
server's active network.

**Request:** `NetworkRequest`

**Response:** `NetworkResponse`

- `uint32 active_network`: The network identifier.

**Expected errors:** None

___

#### `CoinType`

The `CoinType` method returns the coin type identifier constant describing the
wallet's coin type.

**Request:** `CoinTypeRequest`

**Response:** `CoinTypeResponse`

- `uint32 coin_type`: The wallet's coin type identifier.

**Expected errors:**

- `WatchingOnly`: Watching-only wallet, coin type keys are not saved.

___

#### `AccountNumber`

The `AccountNumber` method looks up a BIP0044 account number by an account's
unique name.

**Request:** `AccountNumberRequest`

- `string account_name`: The name of the account being queried.

**Response:** `AccountNumberResponse`

- `uint32 account_number`: The BIP0044 account number.

**Expected errors:**

- `Aborted`: The wallet database is closed.

- `NotFound`: No accounts exist by the name in the request.

___

#### `Accounts`

The `Accounts` method returns the current properties of all accounts managed in
the wallet.

**Request:** `AccountsRequest`

**Response:** `AccountsResponse`

- `repeated Account accounts`: Account properties grouped into `Account` nested
  message types, one per account, ordered by increasing account numbers.

  **Nested message:** `Account`

  - `uint32 account_number`: The BIP0044 account number.

  - `string account_name`: The name of the account.

  - `int64 total_balance`: The total (zero-conf and immature) balance, counted
    in Atoms.

  - `uint32 external_key_count`: The number of derived keys in the external
     key chain.

  - `uint32 internal_key_count`: The number of derived keys in the internal
     key chain.

  - `uint32 imported_key_count`: The number of imported keys.

- `bytes current_block_hash`: The hash of the block wallet is considered to
  be synced with.

- `int32 current_block_height`: The height of the block wallet is considered
  to be synced with.

**Expected errors:**

- `Aborted`: The wallet database is closed.

___

#### `Balance`

The `Balance` method queries the wallet for an account's balance.  Balances are
returned as combination of total, spendable (by consensus and request policy),
and unspendable immature coinbase balances.

**Request:** `BalanceRequest`

- `uint32 account_number`: The account number to query.

- `int32 required_confirmations`: The number of confirmations required before an
  unspent transaction output's value is included in the spendable balance.  This
  may not be negative.

**Response:** `BalanceResponse`

- `int64 total`: The total (zero-conf and immature) balance, counted in
  Atoms.

- `int64 spendable`: The spendable balance, given some number of required
  confirmations, counted in Atoms.  This equals the total balance when the
  required number of confirmations is zero and there are no immature coinbase
  outputs.

- `int64 immature_reward`: The total value of all immature coinbase outputs,
  counted in Atoms.

- `int64 immature_stake_generation`: The total value of all immature stakebase outputs,
  or any revocations, counted in Atoms.

- `int64 locked_by_tickets`: The total value of all tickets that are currently locked,
  and awaiting vote.

- `int64 voting_authority`: The total value of all tickets that the account has voting
  authority over.  

- `int64 unconfirmed`: The total value of all unconfirmed transactions with
   with reference to the minimum number of confirmations for a transaction
   (minconf). If minconf is 0 unconfirmed will be 0, otherwise unconfirmed
   will be the total balance of transactions that do fulfill the requested
   minconf.  

**Expected errors:**

- `InvalidArgument`: The required number of confirmations is negative.

- `Aborted`: The wallet database is closed.

- `NotFound`: The account does not exist.

___

#### `BlockInfo`

The `BlockInfo` method queries for info pertaining to blocks that are recorded
by the wallet.  Blocks are queried using either the block hash or height as an
identifier.  Any block currently or previously in the main chain can be queried,
but not all sidechain blocks may be known by the wallet.

**Request:** `BlockInfoRequest`

- `bytes block_hash`: The hash of the block being queried, or null to lookup
  blocks by their height.

- `int32 block_height`: The height of the block being queried.  Height lookup
  only returns results of blocks in the main chain.

**Response:** `BlockInfoResponse`

- `bytes block_hash`: The hash of the queried block.

- `int32 block_height`: The height of the queried block.  This is the height
  recorded in the block header and will be the height in the sidechain for any
  reorged blocks.

- `int32 confirmations`: The number of block confirmations of all transactions
  in the block.  If the block is not currently in the main chain, this field is
  set to zero.

- `int64 timestamp`: The unix timestamp of the block.

- `bytes block_header`: The serialized block header.

- `bool stake_invalidated`: Whether the queried block is in the main chain and
  the next main chain block has stake invalidated the queried block.

- `bool approves_parent`: Whether this block stake validates its parent block.

**Expected errors:**

- `InvalidArgument`: The block hash and height were each set to non-default
  values.

- `Aborted`: The wallet database is closed.

- `NotFound`: The block is not recorded by the wallet in the current main chain
  or any old sidechain.

___

#### `GetAccountExtendedPubKey`

The `GetAccountExtendedPubKey` method queries the wallet for an account pubkey.

**Request:** `GetAccountExtendedPubKeyRequest`

- `uint32 account_number`: The number of the account to retrieve the pubkey.

**Response:** `GetAccountExtendedPubKeyResponse`

- `string acc_extended_pub_key`: The account's extended key.

**Expected errors:**

- `NotFound`: The account does not exist.

___

#### `GetAccountExtendedPrivKey`

The `GetAccountExtendedPrivKey` method queries the wallet for an account privkey.

**Request:** `GetAccountExtendedPrivKeyRequest`

- `uint32 account_number`: The number of the account to retrieve the privkey.

- `bytes passphrase`: The passphrase to unlock the wallet and retrieve the
account private key.

**Response:** `GetAccountExtendedPrivKeyResponse`

- `string acc_extended_priv_key`: The account's extended private key.

**Expected errors:**

- `NotFound`: The account does not exist.

- `InvalidArgument`: The private passphrase is incorrect.
___

#### `GetTransaction`

The `GetTransaction` method queries the wallet for a relevant transaction by its
hash.

**Request:** `GetTransactionRequest`

- `bytes transaction_hash`: The hash of the transaction being queried.

**Response:** ` GetTransactionResponse`

- `TransactionDetails transaction`: Wallet details regarding the transaction.

  The `TransactionDetails` message is used by other methods and is documented
  [here](#transactiondetails).

- `int32 confirmations`: The number of block confirmations of the transaction in
  the main chain.  If the transaction was mined in a stake-invalidated block and
  pushed back to mempool to be mined again, or was mined again after being stake
  invalidated, the latest number of confirmations is used (not the confirmations
  of an invalidated block).

- `bytes block_hash`: The block hash the transaction is most recently mined in,
  or null if unmined.

**Expected errors:**

- `InvalidArgument`: The transaction hash is of incorrect length.

- `Aborted`: The wallet database is closed.

- `NotFound`: The transaction is not recorded by the wallet.

___

#### `GetTransactions`

The `GetTransactions` method queries the wallet for relevant transactions.  The
query set may be specified using a block range, inclusive, with the heights or
hashes of the minimum and maximum block.  Transaction results are grouped
by the block they are mined in, or grouped together with other unmined
transactions.

To avoid exceeding the maximum message size with the return result, a stream is
used to break up the response into several messages.  A single message will have
results of a single block and no unmined transactions, or only unmined
transactions (and no mined transactions).

**Request:** `GetTransactionsRequest`

- `bytes starting_block_hash`: The block hash of the block to begin including
  transactions from.  If this field is set to the default, the
  `starting_block_height` field is used instead.  If changed, the byte array
  must have length 32 and `starting_block_height` must be zero.

- `sint32 starting_block_height`: The block height to begin including
  transactions from.  If this field is non-zero, `starting_block_hash` must be
  set to its default value to avoid ambiguity.  If positive, the field is
  interpreted as a block height.  If negative, the height is subtracted from the
  block wallet considers itself in sync with.

- `bytes ending_block_hash`: The block hash of the last block to include
  transactions from.  If this default is set to the default, the
  `ending_block_height` field is used instead.  If changed, the byte array must
  have length 32 and `ending_block_height` must be zero.

- `int32 ending_block_height`: The block height of the last block to include
  transactions from.  If non-zero, the `ending_block_hash` field must be set to
  its default value to avoid ambiguity.  If both this field and
  `ending_block_hash` are set to their default values, no upper block limit is
  used and transactions through the best block and all unmined transactions are
  included.

- `int32 target_transaction_count`: Try to return at most this amount of
  transactions. Both mined and unmined transactions count towards this limit.
  Note that as transactions are returned on a per-block basis, **more** than
  this amount of transactions may be returned in total, to prevent transactions
  from not being seen. The caller is responsible for further clipping of the
  dataset if it has a hard requirement on the number of total transactions it
  manages.

**Response:** `stream GetTransactionsResponse`

- `BlockDetails mined_transactions`: All mined transactions, organized
  by blocks in the order they appear in the blockchain.

  The `BlockDetails` message is used by other methods and is documented
  [here](#blockdetails).

- `repeated TransactionDetails unmined_transactions`: All unmined transactions.
  The ordering is unspecified.

  The `TransactionDetails` message is used by other methods and is documented
  [here](#transactiondetails).

**Expected errors:**

- `InvalidArgument`: A non-default block hash field did not have the correct length.

- `Aborted`: The wallet database is closed.

- `NotFound`: A block, specified by its height or hash, is unknown to the
  wallet.

___

#### `GetTicket`

The `GetTicket` method queries the wallet for the provided ticket.

**Request:** `GetTicketRequest`

- `bytes ticket_hash`: The hash of the ticket being queried.

**Response:** `GetTicketsResponse`

Refer to [GetTickets](#gettickets) response documentation.

**Expected errors:**

- `InvalidArgument`: The ticket hash field did not have the correct length.

- `NotFound`: The specified transaction is not known by the wallet. 
___

#### `GetTickets`

The `GetTickets` method queries the wallet for relevant tickets.  The
query set may be specified using a block range, inclusive, with the heights or
hashes of the minimum and maximum block.

To avoid exceeding the maximum message size with the return result, a stream is
used to break up the response into several messages.  A single message will have
results of a single ticket.

**Request:** `GetTicketsRequest`

- `bytes starting_block_hash`: The block hash of the block to begin including
  tickets from.  If this field is set to the default, the
  `starting_block_height` field is used instead.  If changed, the byte array
  must have length 32 and `starting_block_height` must be zero.

- `sint32 starting_block_height`: The block height to begin including
  tickets from.  If this field is non-zero, `starting_block_hash` must be
  set to its default value to avoid ambiguity.  If positive, the field is
  interpreted as a block height.  If negative, the height is subtracted from the
  block wallet considers itself in sync with.

- `bytes ending_block_hash`: The block hash of the last block to include
  tickets from.  If this default is set to the default, the
  `ending_block_height` field is used instead.  If changed, the byte array must
  have length 32 and `ending_block_height` must be zero.

- `int32 ending_block_height`: The block height of the last block to include
  tickets from.  If non-zero, the `ending_block_hash` field must be set to
  its default value to avoid ambiguity.  If both this field and
  `ending_block_hash` are set to their default values, no upper block limit is
  used and transactions through the best block and all unmined transactions are
  included.

- `int32 target_ticket_count`: Try to return at most this amount of tickets.
  Both mined and unmined tickets count towards this limit. Note that the number
  of tickets returned may be higher or lower than this specified target and
  callers are responsible for further clipping of the dataset if required.

**Response:** `stream GetTicketsResponse`

- `TicketDetails tickets`: A given ticket's details.

  **Nested Message** `TicketDetails`

  - `TransactionDetails ticket`: The transaction details of a given ticket.

  - `TransactionDetails spender`: The transaction details of the ticket's
    spender if applicable (otherwise empty).

    The `TransactionDetails` message is used by other methods and is documented
    [here](#transactiondetails).

  - `TicketStatus ticket_status`: The observed status of the given ticket.

    **Nested enum:** `TicketStatus`

    - `UNKNOWN`: A ticket whose status was unable to be determined.

    - `UNMINED`: A ticket that has yet to be mined into a block.

    - `IMMATURE`: A ticket that has not yet matured enough to be live.

    - `LIVE`: A currently live ticket that is waiting to be voted.

    - `VOTED`: A ticket that has been voted.

    - `EXPIRED`: A ticket that is expired but not yet revoked.

    - `MISSED`: A ticket that was missed but not yet revoked.

    - `REVOKED`: A ticket that has been revoked.

- `BlockDetails block`: The block the ticket was mined. It is null if the
   ticket hasn't been mined yet.

  **Nested Message** `BlockDetails`

  - `bytes hash`: The binary hash of the block.

  - `int32 height`: The block height.

  - `int64 timestamp`: The timestamp the block was mined.


**Expected errors:**

- `InvalidArgument`: A non-default block hash field did not have the correct length.

- `InvalidArgument`: A negative target value was provided.

- `Aborted`: The wallet database is closed.

- `NotFound`: A block, specified by its height or hash, is unknown to the
  wallet.

___

#### `ChangePassphrase`

The `ChangePassphrase` method requests a change to either the public (outer) or
private (inner) encryption passphrases.

**Request:** `ChangePassphraseRequest`

- `Key key`: The key being changed.

  **Nested enum:** `Key`

  - `PRIVATE`: The request specifies to change the private (inner) encryption
    passphrase.

  - `PUBLIC`: The request specifies to change the public (outer) encryption
    passphrase.

- `bytes old_passphrase`: The current passphrase for the encryption key.  This
  is the value being modified.  If the public passphrase is being modified and
  this value is the default value, an insecure default is used instead.

- `bytes new_passphrase`: The replacement passphrase.  This field may only have
  zero length if the public passphrase is being changed, in which case an
  insecure default will be used instead.

**Response:** `ChangePassphraseResponse`

**Expected errors:**

- `InvalidArgument`: A zero length passphrase was specified when changing the
  private passphrase, or the old passphrase was incorrect.

- `Aborted`: The wallet database is closed.

___

#### `RenameAccount`

The `RenameAccount` method requests a change to an account's name property.

**Request:** `RenameAccountRequest`

- `uint32 account_number`: The number of the account being modified.

- `string new_name`: The new name for the account.

**Response:** `RenameAccountResponse`

**Expected errors:**

- `Aborted`: The wallet database is closed.

- `InvalidArgument`: The new account name is a reserved name.

- `NotFound`: The account does not exist.

- `AlreadyExists`: An account by the same name already exists.

___

#### `Rescan`

The `Rescan` method begins a rescan for all relevant transactions involving all
active addresses and watched outpoints.  Rescans can be time consuming depending
on the amount of data that must be checked, and the size of the blockchain.  If
transactions being scanned for are known to only exist after some height, the
request can specify which block height to begin scanning from.  This RPC returns
a stream of block heights the rescan has completed through.

**Request:** `RescanRequest`

- `int32 begin_height`: The block height to begin the rescan at (inclusive).

**Response:** `stream RescanResponse`

- `int32 rescanned_through`: The block height the rescan has completed through
  (inclusive).

**Expected errors:**

- `FailedPrecondition`: There is no consensus server associated with the wallet.

- `InvalidArgument`: The begin height is negative.

- `NotFound`: There is no known block in the main chain at the begin height.

___

#### `NextAccount`

The `NextAccount` method generates the next BIP0044 account for the wallet.

**Request:** `NextAccountRequest`

- `bytes passphrase`: The private passphrase required to derive the next
  account's key.

- `string account_name`: The name to give the new account.

**Response:** `NextAccountResponse`

- `uint32 account_number`: The number of the newly-created account.

**Expected errors:**

- `Aborted`: The wallet database is closed.

- `InvalidArgument`: The private passphrase is incorrect.

- `InvalidArgument`: The new account name is a reserved name.

- `AlreadyExists`: An account by the same name already exists.

___

#### `NextAddress`

The `NextAddress` method generates the next deterministic address for the
wallet.

**Request:** `NextAddressRequest`

- `uint32 account`: The number of the account to derive the next address for.

- `Kind kind`: The type of address to generate.

  **Nested enum:** `Kind`

  - `BIP0044_EXTERNAL`: The request specifies to generate the next address for
    the account's BIP0044 external key chain.

  - `BIP0044_INTERNAL`: The request specifies to generate the next address for
    the account's BIP0044 internal key chain.

- `GapPolicy gap_policy`: The policy to use when the BIP0044 unused address gap
  limit would be violated.

  **Nested enum:** `GapPolicy`

  - `GAP_POLICY_UNSPECIFIED`: Do not specify any policy in particular.  This
    will default to using the erroring policy unless otherwise changed in the
    wallet's settings.

  - `GAP_POLICY_ERROR`: Override any other specified gap policy in the wallet
    settings.  If the gap limit would be violated, return an error.

  - `GAP_POLICY_IGNORE`: Override any other specified gap policy in the wallet
    settings.  Ignore any gap limit violations and return the next child address
    anyways.

  - `GAP_POLICY_WRAP`: Override any other specified gap policy in the wallet
    settings.  If the gap limit would be violated, wrap around to the child
    index after the last used address.

**Response:** `NextAddressResponse`

- `string address`: The payment address string.

- `string public_key`: The public key encoded as a string in the Decred encoding
  format.

**Expected errors:**

- `Aborted`: The wallet database is closed.

- `NotFound`: The account does not exist.

___

#### `ImportPrivateKey`

The `ImportPrivateKey` method imports a private key in Wallet Import Format
(WIF) encoding to a wallet account.  A rescan may optionally be started to
search for transactions involving the private key's associated payment address.

**Request:** `ImportPrivateKeyRequest`

- `bytes passphrase`: The wallet's private passphrase.

- `uint32 account`: The account number to associate the imported key with.

- `string private_key_wif`: The private key, encoded using WIF.

- `bool rescan`: Whether or not to perform a blockchain rescan for the imported
  key.

**Response:** `ImportPrivateKeyResponse`

**Expected errors:**

- `InvalidArgument`: The private passphrase is incorrect.

- `InvalidArgument`: The private key WIF string is not a valid WIF encoding.

- `InvalidArgument`: A rescan height was specified, but the rescan option was
  not set.

- `InvalidArgument`: A negative rescan height was passed.

- `Aborted`: The wallet database is closed.

- `NotFound`: The account does not exist.

___

#### `ImportScript`

The `ImportScript` method imports a script into the wallet.  A rescan may
optionally be started to search for transactions involving the script, either
as an output or in a P2SH input.

**Request:** `ImportScriptRequest`

- `bytes passphrase`: The wallet's private passphrase.  This parameter is
  deprecated and ignored.

- `bytes script`: The raw script.

- `bool rescan`: Whether or not to perform a blockchain rescan for the imported
  script.

- `int32 scan_from`: The block height to begin a rescan from.

- `bool require_redeemable`: The script must be a multisig script where all of
  the keys necessary to redeem the script are available to the wallet.

**Response:** `ImportScriptResponse`

- `string p2sh_address`: The pay-to-script-hash address for the imported script.

- `bool redeemable`: Whether the imported script is a multisig script and all
  of the keys necessary to redeem the script are available to the wallet.

**Expected errors:**

- `InvalidArgument`: A rescan height was specified, but the rescan option was
  not set.

- `InvalidArgument`: A negative rescan height was passed.

- `Aborted`: The wallet database is closed.

- `NotFound`: The account does not exist.

- `FailedPrecondition`: A multisig script was required to be redeemable by the
  wallet but is not without additional secrets.

___

#### `ImportVotingAccountFromSeed`
The `ImportVotingAccountFromSeed` method imports bytes that become the master
seed for a hierarchical deterministic private key that is imported into the
wallet with the supplied name and locked with the supplied password. Addresses
derived from this account MUST NOT be sent any funds. They are solely for the
use of creating stake submission scripts. A rescan may optionally be started to
search for tickets using submission scripts derived from this account.

**Request:** `ImportVotingAccountFromSeedRequest`

- `bytes seed`: The bytes to be used in the master seed.

- `bytes passphrase`: The wallet's private passphrase.

- `string name`: A name to use for the account. Must be unique.

- `bool rescan`: Whether or not to perform a blockchain rescan for the imported
  key.

- `int32 scan_from`: The block height to begin a rescan from. Default will scan from 0.

- `bool discover_usage`: Whether or not to perform discover usage.

- `int32 discover_from`: The block height to begin discovering usage from. Default is 0.

- `int32 discover_gap_limit`: The gap limit used when discovering usage. Dafaults to wallet config defaults.

**Response:** `ImportPrivateKeyResponse`

- `uint32 account`: The account number of the account.

**Expected errors:**

- `InvalidArgument`: Passphrase not supplied.

- `InvalidArgument`: The seed supplied is invalid.

- `InvalidArgument`: Duplicate name.

- `InvalidArgument`: A rescan height was specified, but the rescan option was
  not set.

- `InvalidArgument`: A negative rescan or discover height or gap limit was passed.

- `InvalidArgument`: A discover height or gap limit was specified, but the
  discover usage option was not set.
___

#### `FundTransaction`

The `FundTransaction` method queries the wallet for unspent transaction outputs
controlled by some account.  Results may be refined by setting a target output
amount and limiting the required confirmations.  The selection algorithm is
unspecified.

Output results are always created even if a minimum target output amount could
not be reached.  This allows this method to behave similar to the `Balance`
method while also including the outputs that make up that balance.

Change outputs can optionally be returned by this method as well.  This can
provide the caller with everything necessary to construct an unsigned
transaction paying to already known addresses or scripts.

**Request:** `FundTransactionRequest`

- `uint32 account`: Account number containing the keys controlling the output
  set to query.

- `int64 target_amount`: If positive, the service may limit output results to
  those that sum to at least this amount (counted in Atoms).  If zero, all
  outputs not excluded by other arguments are returned.  This may not be
  negative.

- `int32 required_confirmations`: The minimum number of block confirmations
  needed to consider including an output in the return set.  This may not be
  negative.

- `bool include_immature_coinbases`: If true, immature coinbase outputs will
  also be included.

- `bool include_change_script`: If true, a change script is included in the
  response object.

**Response:** `FundTransactionResponse`

- `repeated PreviousOutput selected_outputs`: The output set returned as a list
  of `PreviousOutput` nested message objects.

  **Nested message:** `PreviousOutput`

  - `bytes transaction_hash`: The hash of the transaction this output originates
    from.

  - `uint32 output_index`: The output index of the transaction this output
    originates from.

  - `int64 amount`: The output value (counted in Atoms) of the unspent
    transaction output.

  - `bytes pk_script`: The output script of the unspent transaction output.

  - `int64 receive_time`: The earliest Unix time the wallet became aware of the
    transaction containing this output.

  - `bool from_coinbase`: Whether the output is a coinbase output.

  - `int32 tree`: The tree the output belongs to.  This can take on the values
    `-1` (invalid), `0` (regular), and `1` (stake).

- `int64 total_amount`: The sum of all returned output amounts.  This may be
  less than a positive target amount if there were not enough eligible outputs
  available.

- `bytes change_pk_script`: A transaction output script used to pay the
  remaining amount to a newly-generated change address for the account.  This is
  null if `include_change_script` was false or the target amount was not
  exceeded.

**Expected errors:**

- `InvalidArgument`: The target amount is negative.

- `InvalidArgument`: The required confirmations is negative.

- `Aborted`: The wallet database is closed.

- `NotFound`: The account does not exist.

___

#### `UnspentOutputs`

The `UnspentOutputs` method queries the wallet for unspent transaction outputs
controlled by some account.  Results may be refined by setting a target output
amount and limiting the required confirmations.  The selection algorithm is
unspecified.

Output results are always created even if a minimum target output amount could
not be reached.  This allows this method to behave similar to the `Balance`
method while also including the outputs that make up that balance.

**Request:** `UnspentOutputsRequest`

- `uint32 account`: Account number containing the keys controlling the output
  set to query.

- `int64 target_amount`: If positive, the service may limit output results to
  those that sum to at least this amount (counted in Atoms).  This may not be
  negative.

- `int32 required_confirmations`: The minimum number of block confirmations
  needed to consider including an output in the return set.  This may not be
  negative.

- `bool include_immature_coinbases`: If true, immature coinbase outputs will
  also be included.

**Response:** `stream UnspentOutputResponse`

- `bytes transaction_hash`: The hash of the transaction this output originates
  from.

- `uint32 output_index`: The output index of the transaction this output
  originates from.

- `int64 amount`: The output value (counted in atoms) of the unspent
  transaction output.

- `bytes pk_script`: The output script of the unspent transaction output.

- `int64 receive_time`: The earliest Unix time the wallet became aware of the
  transaction containing this output.

- `bool from_coinbase`: Whether the output is a coinbase output.

- `int32 tree`: The tree the output belongs to.  This can take on the values
  `-1` (invalid), `0` (regular), and `1` (stake).

- `int64 amount_sum`: The rolling sum of all streamed output amounts including
  the current response. This may be less than a positive target amount if
  there were not enough eligible outputs available.

**Expected errors:**

- `InvalidArgument`: The target amount is negative.

- `InvalidArgument`: The required confirmations is negative.

- `Aborted`: The wallet database is closed.

- `NotFound`: The account does not exist.

___

#### `ConstructTransaction`

The `ConstructTransaction` method constructs an unsigned transaction based on
the request parameters, referencing unspent outputs from a wallet account.  If a
change output is added, it is inserted at a random output position.

**Request:** `ConstructTransactionRequest`

- `uint32 source_account`: The account to select outputs from.

- `int32 required_confirmations`: The number of block confirmations required
  before an output is considered spendable.

- `int32 fee_per_kb`: The transaction relay fee per kB.  If zero, the default
  mempool policy relay fee is used.

- `OutputSelectionAlgorithm output_selection_algorithm`: The algorithm used when
  selecting transaction outputs.

  **Nested enum:** `OutputSelectionAlgorithm`

  - `UNSPECIFIED`: An unspecified selection algorithm is used.  At time of
    writing the wallet only has one selection algorithm but it is not
    optimized for any particular use case.  This will never use the `ALL`
    algorithm, but as other algorithms are introduced, it may become an alias
    for one of them.

  - `ALL`: All spendable outputs from the account are used as inputs

- `repeated Output non_change_outputs`: Non-change outputs to include in the
  transaction.  Outputs are not guaranteed to appear in the same order as they
  are in this repeated field.

  **Nested message:** `Output`

  - `OutputDestination destination`: The output destination (address, script,
    etc.).

  - `int64 amount`: The value created by the output.

  **Nested message**: `OutputDestination`

  - `string address`: Address string to use as the output destination.  If null
    or the empty string, this is skipped and the next destination kind is
    checked.

  - `bytes script`: The script bytes to use in the output script.  Only checked
    if none of the previous destination kinds were set.

  - `uint32 script_version`: When the output destination is a script, this
    specifies the script version to use in the output.

- `OutputDestination change_destination`: Optional destination to use for any
  transaction change.  If null and a change output is needed, an internal change
  address is created for the wallet.

**Response:** `ConstructTransactionResponse`

- `bytes unsigned_transaction`: The raw serialized transaction.

- `int64 total_previous_output_amount`: The total previous output amount
  consumed by the transaction's inputs.

- `int64 total_output_amount`: The total output value produced by the
  transaction's outputs.

- `uint32 estimated_signed_size`: An estimated size of the transaction once the
  transaction is signed.

- `int32 change_index`: The index of the change output or -1 if no change
  output was created.

**Expected errors:**

- `InvalidArgument`: An output destination address could not be decoded.

- `InvalidArgument`: No output destinations (change or non-change) were provided.

- `NotFound`: The account does not exist.

- `ResourceExhausted`: There was not enough available input value to construct
  the transaction.

___

#### `SignTransaction`

The `SignTransaction` method adds transaction input signatures to a serialized
transaction using a wallet private keys.

**Request:** `SignTransactionRequest`

- `bytes passphrase`: The wallet's private passphrase.

- `bytes serialized_transaction`: The transaction to add input signatures to.

- `repeated AdditionalScript additional_scripts`: Additional output scripts of
  previous outputs spent by the transaction that the wallet may not be aware of.
  Offline signing may require previous outputs to be provided to the wallet.

  **Nested message:** `AdditionalScript`

  - `bytes transaction_hash`: The transaction hash of the previous output.

  - `uint32 output_index`: The output index of the previous output.

  - `int32 tree`: The transaction tree the previous transaction belongs to.

  - `bytes pk_script`: The output script of the previous output.

**Response:** `SignTransactionResponse`

- `bytes transaction`: The serialized transaction with added input scripts.

- `repeated uint32 unsigned_input_indexes`: The indexes of every input that an
  input script could not be created for.

**Expected errors:**

- `Aborted`: The wallet database is closed.

- `InvalidArgument`: The private passphrase is incorrect.

- `InvalidArgument`: The serialized transaction can not be decoded.

___

#### `SignTransactions`

The `SignTransactions` method adds transaction input signatures to a set of
serialized transactions using a wallet private keys.

**Request:** `SignTransactionsRequest`

- `bytes passphrase`: The wallet's private passphrase.

- `repeated UnsignedTransaction unsigned_transaction`: - The unsigned transactions set.

  **Nested message:** `UnsignedTransaction`

  - `bytes serialized_transaction`: The transaction to add input signatures to.

- `repeated AdditionalScript additional_scripts`: Additional output scripts of
  previous outputs spent by the transaction that the wallet may not be aware of.
  Offline signing may require previous outputs to be provided to the wallet.

  **Nested message:** `AdditionalScript`

  - `bytes transaction_hash`: The transaction hash of the previous output.

  - `uint32 output_index`: The output index of the previous output.

  - `int32 tree`: The transaction tree the previous transaction belongs to.

  - `bytes pk_script`: The output script of the previous output.

**Response:** `SignTransactionsResponse`

- `repeated SignedTransaction transactions`: The signed transaction set.

  **Nested message:** `SignedTransaction`

  - `bytes transaction`: The serialized transaction with added input scripts.

**Expected errors:**

- `Aborted`: The wallet database is closed.

- `InvalidArgument`: A serialized transaction can not be decoded.

- `InvalidArgument`: The private passphrase is incorrect.

___

#### `CreateSignature`

The `CreateSignature` method creates a raw signature created by the private key
of a wallet address for transaction input script.  The serialized compressed
public key of the address is also returned.  The raw signature and public key
are useful when creating custom input scripts.

**Request:** `CreateSignatureRequest`

- `bytes passphrase`: The wallet's private passphrase.

- `string address`: The address of the private key to use to create the
  signature.

- `bytes serialized_transaction`: The transaction to add input signatures to.

- `uint32 input_index`: The index of the transaction input to sign.

- `SigHashType hash_type`: The signature hash flags to use.

  **Nested enum:** `SigHashType`

  - `SIGHASH_OLD`
  - `SIGHASH_ALL`
  - `SIGHASH_NONE`
  - `SIGHASH_SINGLE`
  - `SIGHASH_ALLVALUE`
  - `SIGHASH_ANYONECANPAY`

- `bytes previous_pk_script`: The previous output script or P2SH redeem script.

**Response:** `CreateSignatureResponse`

- `bytes signature`: The raw signature.

- `bytes public_key`: The serialized compressed pubkey of the address.

**Expected errors:**

- `InvalidArgument`: The private passphrase is incorrect.

- `InvalidArgument`: The address can not be decoded.

- `NotFound`: The address is unknown by the wallet.

- `InvalidArgument`: The serialized transaction can not be decoded.

- `InvalidArgument`: The input index does not exist in the transaction.

___

#### `PublishTransaction`

The `PublishTransaction` method publishes a signed, serialized transaction to
the Decred network.  If the transaction spends any of the wallet's unspent
outputs or creates a new output controlled by the wallet, it is saved by the
wallet and republished later if it or a double spend are not mined.

**Request:** `PublishTransactionRequest`

- `bytes signed_transaction`: The signed transaction to publish.

**Response:** `PublishTransactionResponse`

- `bytes transaction_hash`: The hash of the published transaction.

**Expected errors:**

- `InvalidArgument`: The serialized transaction can not be decoded or is missing
  input scripts.

- `Aborted`: The wallet database is closed.

___

#### `PublishUnminedTransactions`

The `PublishTransactions` method re-broadcasts all unmined transactions
to the consensus RPC server so it can be propagated to other nodes
and eventually mined.

**Request:** `PublishUnminedTransactionsRequest`

**Response:** `PublishUnminedTransactionsResponse`

**Expected errors:**: None

___

#### `TicketPrice`

The `TicketPrice` method returns the price of a ticket for the next block, also
known as the stake difficulty. May be incorrect if the daemon is currently
syncing.

**Request:** `TicketPriceRequest`

**Response:** `TicketPriceResponse`

- `int64 ticket_price`: The stake difficulty for the next block.

- `int32 height`: The block height for this query.

**Expected errors:** None

___

#### `SignHashes`

The `SignHashes` method creates signatures of multiple hash values using the
provided private keys and addresses.

**Request:** `SignHashesRequest`

- `bytes passphrase`: The wallet's private passphrase.

- `string address`: The address of the private key to use to create the
  signature.

- `repeated bytes hashes`: Hash values to sign.

**Response:** `SignHashesResponse`

- `bytes public_key`: The serialized compressed pubkey of the address.

- `repeated bytes signature`: Raw signatures. The index of each signature
   corresponds to the index of an incoming hash.

**Expected errors:**

- `InvalidArgument`: The private passphrase is incorrect.

**Stability:** Unstable: this method may require API changes to support
signature algorithms other than secp256k1.

___

#### `StakeInfo`

The `StakeInfo` method returns various statistics about the wallet in relation
to tickets owned fully or completely by the wallet, such as number of tickets
owned and votes cast.

**Request:** `StakeInfoRequest`

**Response:** `StakeInfoResponse`

- `uint32 pool_size`: The current size of the ticket pool.

- `uint32 all_mempool_tix`: The number of tickets in the mempool.

- `uint32 own_mempool_tix`: The number of tickets in the mempool owned by this
  wallet.

- `uint32 immature`: The number of tickets in the blockchain that are not yet
  mature (can't yet be used to vote on blocks).

- `uint32 live`: The number of active tickets owned by the user.

- `uint32 voted`: The number of successful votes cast by the user.

- `uint32 missed`: The number of votes that were missed by the user.

- `uint32 revoked`: The number of revocations for missed votes cast by the user.

- `uint32 expired`: The number of expired tickets owned by the user.

- `int64 total_subsidy`: The total subsidy received by the user for proof-of-stake voting.

- `uint32 unspent`: The number of unspent tickets. This could include live, missed or expired tickets.

**Expected errors:** None

___

#### `PurchaseTickets`

The `PurchaseTickets` method is used to purchase tickets. It can use a specified
address for voting rights, and can additionally be used in conjunction with a
stake pool. An expiration value can be set for the tickets. Expired tickets are
pruned from the wallet and funds and then restored to the user. The following
fields can be left unset, and unset (empty or zero) behavior is given below:
ticker_address, pool_address, expiry, tx_fee, ticket_fee.

**Request:** `PurchaseTicketsRequest`

- `bytes passphrase`: The wallet's private passphrase.

- `uint32 account`: The account to use to purchase the tickets.

- `int64 spend_limit`: The maximum amount to pay for a single ticket. If the
  current stake difficulty is above this amount, the wallet will return an error.

- `uint32 required_confirmations`: The number of required confirmations for
  funds used to purchase a ticket. If set to zero, it will use unconfirmed and
  confirmed outputs to purchase tickets.

- `string ticket_address`: The address to give voting rights to. If it is set
  to an empty string, an internal address will be used from the wallet.

- `uint32 num_tickets`: The number of tickets to purchase. It must be set and
  at least 1.

- `string pool_address`: The address of the stake pool used. Pool mode will
  be disabled if an empty string is passed.

- `double pool_fees`: The stake pool fees amount. This must be set to a positive
  value in the allowed range of 0.01 to 100.00 to be valid. It must be set when
  the pool_address is also set.

- `uint32 expiry`: The height at which the tickets expire and can no longer enter
  the blockchain. It defaults to 0 (no expiry).

- `int64 tx_fee`: Fees per kB to use for the transaction generating outputs to use
  for buying tickets. If 0 is passed, the global value for a transaction fee
  will be used.

- `int64 ticket_fee`: Fees per kB to use for all purchased tickets. If 0 is
  passed, the global value for a ticket fee will be used.  This option is
  deprecated and ignored; use `tx_fee` instead.

- `bool dont_sign_tx`: If the tickets tx should be signed or not.

- `string cspp_server`: The cspp server to use.

- `uint32 mixed_account`: The mixed account.

- `uint32 mixed_account_branch`: The mixed account branch.

- `uint32 mixed_split_account`: The mixed split account.

- `uint32 change_account`: The change account.

- `string vsp_host`: The vsp host.

- `string vsp_pubkey`: The vsp pubkey.

- `bool use_voting_account`: Whether to force use of the voting account to
  derive submission scripts.

- `uint32 voting_account`: The account to derive submission scripts from.

**Response:** `PurchaseTicketsResponse`

- `repeated bytes ticket_hashes`: The transaction hashes of the generated tickets.

- `repeated bytes unsigned_tickets`: The unsigned tickets bytes when dont_sign_tx is true.

- `repeated bytes split_tx`: The split tx bytes when dont_sign_tx is true.

___

**Expected errors:**

- `InvalidArgument`: The private passphrase is incorrect.

- `InvalidArgument`: The spent limit was negative.

- `InvalidArgument`: An invalid number of tickets was specified.

- `InvalidArgument`: An invalid ticket address was specified.

- `InvalidArgument`: An invalid pool address was specified.

- `InvalidArgument`: Pool address was specified, but pool fees were not.

- `InvalidArgument`: Pool address was not specified, but pool fees were.

- `InvalidArgument`: And invalid pool fees amount was given, either too large or
  small.

- `InvalidArgument`: A negative fees per kB was set.

- `FailedPrecondition`: The wallet balance was not enough to buy tickets.

___

#### `RevokeTickets`

The `RevokeTickets` method creates revocations for any missed or expired tickets
that have not yet been revoked.

**Request:** `RevokeTicketsRequest`

- `bytes passphrase`: The wallet's private passphrase.

**Response:** `RevokeTicketsResponse`

**Expected errors:**

- `InvalidArgument`: The private passphrase is incorrect.

___

#### `LoadActiveDataFilters`

The `LoadActiveDataFilters` method loads a transaction filter with the
associated consensus RPC server for all active addresses and watched outpoints.

**Request:** `LoadActiveDataFiltersRequest`

**Response:** `LoadActiveDataFiltersResponse`

**Expected errors:**

- `FailedPrecondition`: There is no consensus server associated with the wallet.

___

#### `SignMessage`

The `SignMessage` method creates a signature of a message using the private key
of an address.

**Request:** `SignMessageRequest`

- `string address`: The associated address of the private key to use to sign the
  message.  Must be P2PKH or P2PK.

- `string message`: The message to sign.

- `bytes passphrase`: The wallet's private passphrase.

**Response:** `SignMessageResponse`

- `bytes signature`: The signature of the message.

**Expected errors:**

- `InvalidArgument`: The address cannot be decoded, is for the wrong network, or
  is not P2PKH or P2PK.

- `InvalidArgument`: The private passphrase is incorrect.

___

#### `SignMessages`

The `SignMessages` method creates a signature of multiple messages using the
provided private keys and addresses.

**Request:** `SignMessagesRequest`

- `bytes passphrase`: The wallet's private passphrase.

- `repeated Message messages`: Message that needs to be signed.

  **Nested message:** `Message`

  - `string address`: The associated address of the private key to use to sign
    the message.  Must be P2PKH or P2PK.

  - `string message`: The message to sign.

**Response:** `SignMessageResponse`

- `repeated SignReply replies`: Replies of all signing operations. Caller
   must check the error field. The index of reply is identical to the incoming
   messages.

  **Nested message:** `SignReply`

  - `bytes signature`: The signature of the message.

  - `string error`: Human readable error if the signature command failed.
    "" indicates success.

**Expected errors:**

- `InvalidArgument`: The private passphrase is incorrect.

___

#### `ValidateAddress`

The `ValidateAddress` method verifies if an address is valid.

**Request:** `ValidateAddressRequest`

- `string address`: The address to be validated.

**Response:** `ValidateAddressResponse`

- `bool is_valid`: True if valid, false if not.

- `bool is_mine`: True if the address is an address of the querying wallet, false if not.

- `uint32 account_number`:  The account number of the wallet. For watch-only
  wallets this will always be 0.

- `string pub_key_addr`: The public key address.

- `bytes pub_key`: The serialized public key.

- `bool is_script`: True if the address pays to a script.

- `repeated string pk_script_addrs`: the address(es) being paid to by the redeem script.

- `ScriptType script_type`: The script type.

- `bytes pay_to_addr_script`: The redeem script.

- `uint32 sigs_required`: The number of signatures required.

- `bool is_internal`: True if the address is from the internal branch of the hd
  wallet.

- `index`: The child index for addresses derived from hd public keys. It will be
  0 for other types of addresses.

___

#### `CommittedTickets`

The `CommittedTickets` method returns the matching ticket purchase hashes and
addresses for which the largest commitment is controlled by this wallet.

**Request:** `CommittedTicketsRequest`

- `repeated bytes tickets`: The hashes of tickets that are being verified.

**Response:** `CommittedTicketsResponse`

- `repeated TicketAddresses ticketAddresses`: The hashes and addresses that are
  controlled by this wallet.

  **Nested message:** `TicketAddresses`

  - `bytes Ticket`: Hash of the ticket.

  - `string address`: Address of the largest commitment.
___

#### `BestBlock`

The `BestBlock` method returns the block height and height of the best block on
the main chain.

**Request:** `BestBlockRequest`

**Response:** `BestBlockResponse`

- `bytes hash`: The hash of the best block.

- `uint32 height`: The height of the best block.

___

#### `SweepAccount`

The `SweepAccount` method Moves as much value as possible in a transaction from
an account per the request parameters.

**Request:** `SweepAccountRequest`
- `string source_account`:  The account to be swept.

- `string destination_address`: The destination address to pay to.

- `uint32 required_confirmations`: The minimum utxo confirmation requirement.

- `double fee_per_kb`: The minimum relay fee policy (optional).

**Response:** `SweepAccountResponse`
- `bytes unsigned_transaction`: The unsigned transaction bytes.

- `int64 total_previous_output_amount`: The total transaction input amount.

- `int64 total_output_amount`: The total transaction output amount.

- `uint32 estimated_signed_size`: The estimated size of the transaction when signed.

___

#### `AbandonTransaction`

The `AbandonTransaction` method removes a pending mempool transaction from the
wallet.  Mined transactions may not be abandoned.

**Request:** `AbandonTransactionRequest`
- `bytes transaction_hash`: Hash of the transaction to remove

**Response:** `AbandonTransactionResponse`

**Expected errors:**

- `Aborted`: The wallet database is closed.

- `NotFound`: The transaction does not exist.

___

#### `TransactionNotifications`

The `TransactionNotifications` method returns a stream of notifications
regarding changes to the blockchain and transactions relevant to the wallet.

**Request:** `TransactionNotificationsRequest`

**Response:** `stream TransactionNotificationsResponse`

- `repeated BlockDetails attached_blocks`: A list of blocks attached to the main
  chain, sorted by increasing height.  All newly mined transactions are included
  in these messages, in the message corresponding to the block that contains
  them.  If this field has zero length, the notification is due to an unmined
  transaction being added to the wallet.

  The `BlockDetails` message is used by other methods and is documented
  [here](#blockdetails).

- `repeated bytes detached_blocks`: The hashes of every block that was
  reorganized out of the main chain.  These are sorted by heights in decreasing
  order (newest blocks first).

- `repeated TransactionDetails unmined_transactions`: All newly added unmined
  transactions.  When relevant transactions are reorganized out and not included
  in (or double-spent by) the new chain, they are included here.

  The `TransactionDetails` message is used by other methods and is documented
  [here](#transactiondetails).

- `repeated bytes unmined_transaction_hashes`: The hashes of every
  currently-unmined transaction.  This differs from the `unmined_transactions`
  field by including every unmined transaction, rather than those newly added to
  the unmined set.

- `repeated detached_block_headers`: Details of every block that was reorganized
  out of the main chain. These are in the same order as `detached_blocks`.

  The `DetachedBlockDetails` message is documented [here](#detachedblockdetails).

**Expected errors:**

- `Aborted`: The wallet database is closed.

___

#### `AccountNotifications`

The `AccountNotifications` method returns a stream of notifications for account
property changes, such as name and key counts.

**Request:** `AccountNotificationsRequest`

**Response:** `stream AccountNotificationsResponse`

- `uint32 account_number`: The BIP0044 account being reported.

- `string account_name`: The current account name.

- `uint32 external_key_count`: The current number of BIP0032 external keys
  derived for the account.

- `uint32 internal_key_count`: The current number of BIP0032 internal keys
  derived for the account.

- `uint32 imported_key_count`: The current number of private keys imported into
  the account.

**Expected errors:**

- `Aborted`: The wallet database is closed.

___

#### `ConfirmationNotifications`

The `ConfirmationNotifications` method allows notifications of transaction
confirmations.  Transaction hashes to watch are streamed as requests and a
stream of responses is returned which include the number of confirmations of
each watched transaction.  A response is immediately streamed that includes the
current number of confirmations for all newly-watched transactions.  Further
responses will continue to describe the number of confirmations of each
transaction until the confirmation upper limit is met or the transaction is
removed from the wallet (e.g. due to a double spend).

**Request:** `stream ConfirmationNotificationsRequest`

- `repeated bytes tx_hashes`: Hashes of transactions to begin watching.

- `int32 stop_after`: The upper limit on how many confirmations is needed before
  the transaction becomes unwatched.

**Response:** `stream ConfirmationNotificationsResponse`

- `repeated TransactionConfirmations confirmations`: Hashes of watched
  transactions and their current number of confirmations.

  **Nested message:** `TransactionConfirmations`

  - `bytes tx_hash`: The hash of a watched transaction.

  - `int32 confirmations`: The current number of confirmations of the
    transaction.  If the transaction is unknown to the wallet or was removed due
    to a double spend, this value is set to `-1`.

  - `bytes block_hash`: The hash of the block the transaction is mined in, or
    null if unmined.

  - `int32 block_height`: The height of the block the transaction is mined in,
    or `-1` if unmined.

**Expected errors:**

- `InvalidArgument`: A transaction hash did not have the correct length.

- `InvalidArgument`: A negative `stop_after` was specified.

- `Aborted`: The wallet database is closed.

___

### Shared messages

The following messages are used by multiple methods.  To avoid unnecessary
duplication, they are documented once here.

#### `BlockDetails`

The `BlockDetails` message is included in responses to report a block and the
wallet's relevant transactions contained therein.

- `bytes hash`: The hash of the block being reported.

- `int32 height`: The height of the block being reported.

- `int64 timestamp`: The Unix time included in the block header.

- `repeated TransactionDetails transactions`: All transactions relevant to the
  wallet that are mined in this block.  Transactions are sorted by their block
  index in increasing order.

  The `TransactionDetails` message is used by other methods and is documented
  [here](#transactiondetails).

- `bool approves_parent`: Whether this block stake validates its parent block.

- `bytes prev_block`: The hash of the parent (previous) block of the block being
  reported.


___


#### `DetachedBlockDetails`

The `DetachedBlockDetails` message is included in responses to report a block
detached from the wallet's main chain.

- `bytes hash`: The hash of the block being reported.

- `int32 height`: The height of the block being reported.

- `int64 timestamp`: The Unix time included in the block header.

- `bytes prev_block`: The hash of the parent (previous) block of the block being
  reported.

___


#### `TransactionDetails`

The `TransactionDetails` message is included in responses to report transactions
relevant to the wallet.  The message includes details such as which previous
wallet inputs are spent by this transaction, whether each output is controlled
by the wallet or not, the total fee (if calculable), and the earlist time the
transaction was seen.

- `bytes hash`: The hash of the serialized transaction.

- `bytes transaction`: The serialized transaction.

- `repeated Input debits`: Properties for every previously-unspent wallet output
  spent by this transaction.

  **Nested message:** `Input`

  - `uint32 index`: The transaction input index of the input being reported.

  - `uint32 previous_account`: The account that controlled the now-spent output.

  - `int64 previous_amount`: The previous output value.

- `repeated Output credits`: Properties for every output controlled by the wallet.

  **Nested message:** `Output`

  - `uint32 index`: The transaction output index of the output being reported.

  - `uint32 account`: The account number of the controlled output.

  - `bool internal`: Whether the output pays to an address derived from the
    account's internal key series.  This often means the output is a change
    output.

  - `int64 amount`: The amount for this output.

  - `string address`: The address that the output paid to, if the output script
    can be parsed to a known address type. Otherwise this will be null or the
    empty string.

  - `bytes output_script`: The output script.

- `int64 fee`: The transaction fee, if calculable.  The fee is only calculable
  when every previous output spent by this transaction is also recorded by
  wallet.  Otherwise, this field is zero.

- `int64 timestamp`: The Unix time of the earliest time this transaction was
  seen.

- `TransactionType transaction_type`: The observed type of transaction.

  **Nested enum:** `TransactionType`

  - `REGULAR`: All normal regular tx tree transactions.

  - `TICKET_PURCHASE`: A transaction that purchases a ticket to be consumed later
    by a vote transaction upon random selection, or a recovation if the ticket
    is expired or missed.

  - `VOTE`: A transaction that uses a ticket purchase transaction as an input
    and includes a stake base reward as one of the outputs.

  - `REVOCATION`: A transaction that will free a previously locked utxos in
    a ticket purchase due to expiry or the ticket being missed.  Just as stakebase
    rewards must reach maturity to be used, outputs from an revocation also must
    mature that same amount.

  - `COINBASE`: A coinbase transaction in the regular tx tree.

___

#### `DecodedTransaction`

The `DecodedTransaction` message is included in responses that provide full
transaction details. This message includes inputs and outputs not belonging to
the wallet (in contrast with [`TransactionDetails`](#transactiondetails)).

- `bytes transaction_hash`: The hash of the transaction.

- `int32 version`: The version of the transaction.

- `uint32 lock_time`: The lock time field of the transaction.

- `uint32 expiry`: The expiry field of the transaction.

- `TransactionDetails.TransactionType transaction_type`: The type of the
transaction. Note the available types are defined in the
[`TransactionDetails`](#transactiondetails) message.

- `repeated Input inputs`: Information available on the inputs of the
transaction.

  **Nested message:** `Input`

  - `bytes previous_transaction_hash`: The hash of the transaction from where
  this input is being spent.

  - `uint32 previous_transaction_index`: The index of the output, on the
  previous transaction, from where this input is being spent.

  - `TreeType tree`: The type of blockchain tree this input belongs to.

    **Nested Enum** `TreeType`

    - `REGULAR`: An input belonging to the regular chain of transactions.

    - `UNKNOWN`: An input on an unknown chain.

    - `STAKE`: An input belonging to the stake chain of transactions.


  - `uint32 sequence`: The sequence number of this input.

  - `int64 amount_in`: The amount (in atoms) of the input.

  - `uint32 block_height`: The block height field of witness inputs.

  - `uint32 block_index`: The block index field of witness inputs.

  - `bytes signature_script`: The serialized signature script of witness inputs.

  - `string signature_script_asm`: The disassembled version of the signature
  script of witness inputs.

- `repeated Output outputs`: Information available on the outputs of the
transaction.

  **Nested Message** `Output`

  - `int64 value`: The amount (in atoms) of the output.

  - `uint32 index`: The index of the output in the transaction.

  - `int32 version`: The version field of the output.

  - `bytes script`: The serialized output script.

  - `string script_asm`: The disassembled output script.

  - `int32 required_signatures`: The number of required signatures for the
  output.

  - `ScriptClass script_class`: The type of the output script.

    **Nested Enum** `ScriptClass`
    - `NON_STANDARD`: A non-standard (or unidentifiable) output script.

    - `PUB_KEY`: A Pay to PubKey script.

    - `PUB_KEY_HASH`: A Pay to PubKey Hash script.

    - `SCRIPT_HASH`: A Pay to Script Hash script.

    - `MULTI_SIG`:  A Multi Signature script.

    - `NULL_DATA`: An empty data script.

    - `STAKE_SUBMISSION`: A Stake Submission script.

    - `STAKE_GEN`: A Stake Generation script.

    - `STAKE_REVOCATION`: A Stake Revocation script.

    - `STAKE_SUB_CHANGE`: Change for a Stake Submission transaction.

    - `PUB_KEY_ALT`: Alternative Pay to PubKey script.

    - `PUB_KEY_HASH_ALT`: Alternative Pay to PubKey Hash script.

    - `TGEN`: A treasury generation script.

    - `TADD`: A treasury add script.

  - `repeated string addresses`: Addresses found when decoding the output
  script.

  - `int64 commitment_amount`: Amount committed to a ticket on an SStx
  transaction.

___

#### `SyncNotificationType`

The `SyncNotificationType` enum contains all the various different types of
notifications that can occur during the syncing process.  When any notification
is sent there will be a type included.

- `SYNCED`: When the wallet is synced to its connected peers.

- `UNSYNCED`: When the wallet is unsynced to its connected peers.

- `PEER_CONNECTED`: When a peer connects to the wallet.  This is only available
  while using SPV.

- `PEER_DISCONNECTED`: When a peer disconnects from the wallet.  This is only
  available while using SPV.

- `FETCHED_MISSING_CFILTERS_STARTED`: Notifies when the wallet attempts to find
  any missing committed filters.

- `FETCHED_MISSING_CFILTERS_PROGRESS`: When any missing committed filters are
  found and the progress is notified.

- `FETCHED_MISSING_CFILTERS_FINISHED`: Notifies when the wallet is finished
  fetching any missing committed filters.

- `FETCHED_HEADERS_STARTED`: Notifies when the wallet attempts to fetch headers
  from connected peers. 

- `FETCHED_HEADERS_PROGRESS`: When new headers are received by the wallet, any
  progress is notified.

- `FETCHED_HEADERS_FINISHED`: Notifies when the wallet has completed fetching
  headers.

- `DISCOVER_ADDRESSES_STARTED`: Notifies when the wallet has begun the discover
  addresses process.

- `DISCOVER_ADDRESSES_FINISHED`: Notifies when the wallet has finished the
  discover addesses process.

- `RESCAN_STARTED`: When the rescan process has begun (if at all).

- `RESCAN_PROGRESS`: When the rescan process has any progress to update.

- `RESCAN_FINISHED`: When the rescan procress has finished.

___

#### `FetchHeadersNotification`

The `FetchHeadersNotification` message is used during the syncing process for
any fetch headers notification updates.  It contains the count of the fetched
headers and the time of the last header fetched.

- `int32 fetched_headers_count`: The number of headers recently fetched.

- `int64 last_header_time`: The time (in nanoseconds) of the last header that
  was fetched.

___

#### `FetchMissingCFiltersNotification`

The `FetchMissingCFiltersNotification` message is used during the syncing
process for any fetch missing committed filters notification updates.
It may contain the starting and ending height of the filters that were found.

- `int32 fetched_cfilters_start_height`: The height of the first missing
  committed filter that was found.
- `int32 fetched_cfilters_end_height`: The height of the last missing committed
  filter that was found.

___

#### `RescanProgressNotification`

The `RescanProgressNotification` message is used during the syncing process
for any rescan progress notification updates.  It will contain the height
of the block that the rescan process has gotten through.

- `int32 rescanned_through`:  The block height that rescan has progressed
  through.

___

#### `PeerNotification`

The `PeerNotification` message is used during the syncing process for any peer
information updates.  This includes peer count and possibly the address of
the peer that caused a notification to be sent.

- `int32 peer_count`:  The number of peers currently connected.

- `string address`:  The address of the peer that caused the notification.

___

#### `GetCFilters`

The `GetCFilters` method allows callers to fetch the V2 committed filters from
the wallet database. Callers can query these filters to search for the presence
(as spends or new outputs) of arbitrary scripts in blocks.

Only blocks from the current mainchain (from the wallet's point of view) can be
queried. The available filters have already been verified against the header
following DCP0005 activation and are therefore safe for use.


**Request:** `GetCFiltersRequest`

- `bytes starting_block_hash`: The block hash of the block to begin including
  cfilters from.  If this field is set to the default, the
  `starting_block_height` field is used instead.  If changed, the byte array
  must have length 32 and `starting_block_height` must be zero.

- `sint32 starting_block_height`: The block height to begin including
  cfilters from.  If this field is non-zero, `starting_block_hash` must be
  set to its default value to avoid ambiguity.  If positive, the field is
  interpreted as a block height.  If negative, the height is subtracted from the
  block wallet considers itself in sync with.

- `bytes ending_block_hash`: The block hash of the last block to return
  cfilters from.  If this default is set to the default, the
  `ending_block_height` field is used instead.  If changed, the byte array must
  have length 32 and `ending_block_height` must be zero.

- `int32 ending_block_height`: The block height of the last block to return
  cfilters from.  If non-zero, the `ending_block_hash` field must be set to
  its default value to avoid ambiguity.  If both this field and
  `ending_block_hash` are set to their default values, no upper block limit is
  used and cfilters through the best block are returned.


**Response:** `stream GetCFiltersResponse`

Each returned element of the stream corresponds to a single cfilter. The
returned fields for each element are:

- `bytes key`: A byte array with the key that must be used to query the filter.
  This byte array will be of length 16.

- `bytes filter`: The serialized, version 2 committed filter.

- `bytes block_hash`: The block hash of the corresponding block.

**Expected errors:**

- `InvalidArgument`: When both `starting_block_hash` and `starting_block_height`
  are specified.

- `InvalidArgument`: When both `ending_block_hash` and `ending_block_height` are
  specified.

___

#### `UnlockWallet`

The `UnlockWallet` method allows the wallet to be persistently unlocked, until
`LockWallet` is used, or an incorrect passphrase is provided later.

**Request:** `UnlockWalletRequest`

- `bytes passphrase`: The passphrase to unlock the wallet.

**Response:** `UnlockWalletResponse`

**Expected errors:**

- `InvalidArgument`: The private passphrase is incorrect.

___

#### `LockWallet`

The `LockWallet` request locks the wallet, preventing use of any keys protected
by the private passphrase.  This does not affect accounts which are encrypted
with a separate passphrase.

**Request:** `LockWalletRequest`

**Response:** `LockWalletResponse`

**Expected errors:** None

___

#### `UnlockAccount`

The `UnlockAccount` method unlocks keys for a separately encrypted account with
its own passphrase.  Keys remain available until `LockAccount` is used, or an
incorrect passphrase is provided later by this method.

**Request:** `UnlockAccountRequest`

- `bytes passphrase`: The passphrase to unlock an account.

- `uint32 account_number`: The account to unlock.

**Response:** `UnlockAccountResponse`

**Expected errors:**

- `FailedPrecondition`: The account is not encrypted with an individual
  passphrase.

- `InvalidArgument`: The private passphrase is incorrect.

___

#### `LockAccount`

The `LockAccount` request locks an account, preventing use of any keys protected
by the private passphrase.  This does not affect any other accounts.

**Request:** `LockAccountRequest`

- `uint32 account_number`: The account to lock.

**Response:** `LockAccountResponse`

**Expected errors:** 

- `FailedPrecondition`: The account is not encrypted with an individual
  passphrase.


#### `GetTrackedVSPTickets`

The `GetTrackedVSPTickets` request returns the list of tickets currently tracked
by the VSP client inside dcrwallet. This only applies to tickets purchased
following the new vspd mode.

**Request** `GetTrackedVSPTicketsRequest`

**Response** `GetTrackedVSPTicketsResponse`


- `VSP vsps`: The list of tickets, grouped by VSP.

  Nested message `VSP`:

  - `string host`: URL of the VSP

  - `repeated Ticket tickets`: List of tickets tracked for this VSP.

  Nested message `Ticket`:

  - `bytes ticket hash`: The transaction hash of the corresponding ticket.

  - `string voting_address`: The voting address of the ticket.

  - `string commitment_address`: The commitment address of the ticket.

  - `uint32 state`: The internal state the VSP client believes the ticket to be.

  - `int64 fee`: The amount (in atoms) paid as VSP fee in the fee transaction.

  - `bytes fee_hash`: The hash of the fee transaction that pays to the VSP.

___

#### `Address`

The `Address` method queries the wallet for an address and public key from a
certain account, branch, and index.

**Request:** `AddressRequest`

- `uint32 account`: The account number.

- `Kind kind`: The branch.

  **Nested enum:** `Kind`

  - `BIP0044_EXTERNAL`: The request specifies to use the account's BIP0044
    external key chain.

  - `BIP0044_INTERNAL`: The request specifies to use the account's BIP0044
    internal key chain.

- `uint32 index`: The address index.

**Response:** `AddressResponse`

- `string address`: The address's p2pkh.

- `string pulic_key`: The address's pkh if available.

**Expected errors:**

- `InvalidArgument`: Kind is not 0 or 1.

- `NotFound`: Unknown account.

- `Unknown`: Index is out of range.

___

#### `DumpPrivateKey`

The `DumpPrivateKey` method returns the private key for an address. The wallet
or account must be unlocked.

**Request:** `DumpPrivateKeyRequest`

- `string address`: The address to retrieve the private key for.

**Response:** `DumpPrivateKeyResponse`

- `string private_key_wif`: The address's private key in wif format.

**Expected errors:**

- `InvalidArgument`: Unable to decode address.

- `NotFound`: Address not found.

- `FailedPrecondition`: Account locked.

- `InvalidArgument`: Watching only wallet.

## `SeedService`

The `SeedService` service provides RPC clients with the ability to generate
secure random seeds encoded in both binary and human-readable formats, and
decode any human-readable input back to binary.  It has no dependencies and is
always running.

**Methods:**

- [`GenerateRandomSeed`](#generaterandomseed)
- [`DecodeSeed`](#decodeseed)

### Methods

#### `GenerateRandomSeed`

The `GenerateRandomSeed` generates a secure random seed, returning it as binary,
hexadecimal, and in a mnemonic word list format.

**Request:** `GenerateRandomSeedRequest`

- `uint32 seed_length`: The length of the seed to create.  If zero, the
  recommended seed length is used instead.

**Response:** `GenerateRandomSeedResponse`

- `bytes seed_bytes`: The generated seed in a binary format.

- `string seed_hex`: The generated seed encoded as a hexadecimal string.

- `string seed_mnemonic`: The generated seed encoded as a mnemonic word list.

**Expected errors:**

- `InvalidArgument`: The non-zero seed length is invalid.

___

#### `DecodeSeed`

The `DecodeSeed` decodes a human-readable form of the seed back into binary.  
The user input can be either a hexadecimal string or a mnemonic word list.

**Request:** `DecodeSeedRequest`

- `string user_input`: The user input to decode.

**Response:** `DecodeSeedResponse`

- `bytes decoded_seed`: The seed resulting from the decoded user input.

**Expected errors:**

- `InvalidArgument`: The input is invalid.

## `TicketBuyerService`

The `TicketBuyerService` service provides RPC clients with the ability to
launch the automatic ticket buyer with given initial configuration parameters,
and to stop it.  It is always running but depends on the wallet to be loaded.

**Methods:**

- [`StartAutoBuyer`](#startautobuyer)
- [`StopAutoBuyer`](#stopautobuyer)
- [`TicketBuyerConfig`](#ticketbuyerconfig)
- [`SetAccount`](#setaccount)
- [`SetBalanceToMaintain`](#setbalancectomaintain)
- [`SetMaxFee`](#setmaxfee)
- [`SetMaxPriceRelative`](#setmaxpricerelative)
- [`SetMaxPriceAbsolute`](#setmaxpriceabsolute)
- [`SetVotingAddress`](#setvotingaddress)
- [`SetPoolAddress`](#setpooladdress)
- [`SetPoolFees`](#setpoolfees)
- [`SetMaxPerBlock`](#setmaxperblock)

### Methods

#### `StartAutoBuyer`

The `StartAutoBuyer` method starts an automatic ticket buyer with the given
parameters.  Ticket purchase requires the wallet to be unlocked thus the
private passphrase must be passed as a parameter when performing this action.

**Request:** `StartAutoBuyerRequest`

- `bytes passphrase`: The private passphrase to unlock the wallet.

- `uint32 account`: The account number to use for purchasing tickets.

- `int64 balance_to_maintain`: The minimum amount of funds to never dip below when purchasing tickets.

- `int64 max_fee_per_kb`: The maximum ticket fee amount per KB.

- `double max_price_relative`: The scaling factor for setting the maximum ticket price, multiplied by the average price.

- `int64 max_price_absolute`: The maximum absolute ticket price.

- `string voting_address`: The address to delegate voting rights to.

- `string pool_address`: The stake pool address where ticket fees will go to.

- `double pool_fees`: The absolute per ticket fee mandated by the stake pool as a percent.

- `int64 max_per_block`: The maximum tickets per block. Negative number indicates one ticket every n blocks.

**Response:** `StartAutoBuyerResponse`

**Expected errors:**

- `InvalidArgument`: The private passphrase is incorrect.

- `NotFound`: The account does not exist.

- `InvalidArgument`: An invalid balance to maintain was specified.

- `InvalidArgument`: An invalid maximum ticket fee amount per KB was specified.

- `InvalidArgument`: An invalid maximum ticket price was specified.

- `InvalidArgument`: An invalid voting address was specified.

- `InvalidArgument`: An invalid pool address was specified.

- `InvalidArgument`: Pool address was specified, but pool fees were not.

- `InvalidArgument`: Pool address was not specified, but pool fees were.

- `InvalidArgument`: And invalid pool fees amount was given, either too large or too small.

- `FailedPrecondition`: Wallet has not been loaded.

- `FailedPrecondition`: Chain client is not available.

- `FailedPrecondition`: Ticket buyer is already started.

___

#### `StopAutoBuyer`

The `StopAutoBuyer` method stops the automatic ticket buyer.

**Request:** `StopAutoBuyerRequest`

**Response:** `StopAutoBuyerResponse`

**Expected errors:**

- `FailedPrecondition`: Ticket buyer is not running.

___

#### `TicketBuyerConfig`

The `TicketBuyerConfig` method returns the current configuration of the
automatic ticket buyer.

**Request:** `TicketBuyerConfigRequest`

**Response:** `TicketBuyerConfigResponse`

- `uint32 account`: The account number to use for purchasing tickets.

- `string avg_price_mode` : The mode to use for calculating the average price.

- `int64 avg_priceVWAP_delta`: The number of blocks from the current block to use to calculate the VWAP.

- `int64 balance_to_maintain`: The minimum amount of funds to never dip below when purchasing tickets.

- `int64 blocks_to_avg`: The number of blocks to average for fees calculation.

- `bool dont_wait_for_tickets`: If true, wait until the last round of tickets have entered the blockchain, before attempting more purchases.

- `int64 expiry_delta`: The number of blocks in the future before the ticket expires.

- `string fee_source`: The fee source to use for ticket fee per KB (median or mean).

- `double fee_target_scaling`: The scaling factor for setting the ticket fee, multiplies by the average fee.

- `int64 min_fee`: The minimum ticket fee amount per KB

- `int64 max_fee`: The maximum ticket fee amount per KB.

- `int64 max_per_block`: The maximum tickets per block. Negative number indicates one ticket every n blocks.

- `int64 max_price_absolute`: The maximum absolute ticket price.

- `double max_price_relative`: The scaling factor for setting the maximum ticket price, multiplied by the average price.

- `int64 max_in_mempool`: The maximum number of own tickets in mempool before attempting more purchases.

- `string pool_address`: The stake pool address where ticket fees will go to.

- `double pool_fees`: The absolute per ticket fee mandated by the stake pool as a percent.

- `bool spread_ticket_purchases`: If true, spread ticket purchases evenly throughout the window.

- `string voting_address`: The address to delegate voting rights to.

- `int64 tx_fee`: The transaction fee amount per KB.


**Expected errors:**

- `FailedPrecondition`: Ticket buyer is not running.

- `FailedPrecondition`: Wallet has not been loaded.

___

#### `SetAccount`

The `SetAccount` configures the account to use for the automatic ticket buyer.

**Request:** `SetAccountRequest`

- `uint32 account`: The account number to use for purchasing tickets.

**Response:** `SetAccountResponse`

**Expected errors:**

- `FailedPrecondition`: Ticket buyer is not running.

- `FailedPrecondition`: Wallet has not been loaded.

- `NotFound`: The account does not exist.

___

#### `SetBalanceToMaintain`

The `SetBalanceToMaintain` configures the balance to maintain for the automatic
ticket buyer.

**Request:** `SetBalanceToMaintainRequest`

- `int64 balance_to_maintain`: The minimum amount of funds to never dip below when purchasing tickets.

**Response:** `SetBalanceToMaintainResponse`

**Expected errors:**

- `FailedPrecondition`: Ticket buyer is not running.

- `InvalidArgument`: An invalid balance to maintain was specified.

___

#### `SetMaxFee`

The `SetMaxFee` configures the maximum ticket fee per KB for the automatic
ticket buyer.

**Request:** `SetMaxFeeRequest`

- `int64 max_fee_per_kb`: The maximum ticket fee amount per KB.

**Response:** `SetMaxFeeResponse`

**Expected errors:**

- `FailedPrecondition`: Ticket buyer is not running.

- `InvalidArgument`: An invalid maximum ticket fee amount per KB was specified.

___

#### `SetMaxPriceRelative`

The `SetMaxPriceRelative` configures the maximum relative ticket price for the
automatic ticket buyer.

**Request:** `SetMaxPriceRelativeRequest`

- `double max_price_relative`: The scaling factor for setting the maximum ticket price, multiplied by the average price.

**Response:** `SetMaxPriceRelativeResponse`

**Expected errors:**

- `FailedPrecondition`: Ticket buyer is not running.

- `InvalidArgument`: An invalid maximum ticket price was specified.

___

#### `SetMaxPriceAbsolute`

The `SetMaxPriceAbsolute` configures the maximum absolute ticket price for the
automatic ticket buyer.

**Request:** `SetMaxPriceAbsoluteRequest`

- `int64 max_price_absolute`: The maximum absolute ticket price.

**Response:** `SetMaxPriceAbsoluteResponse`

**Expected errors:**

- `FailedPrecondition`: Ticket buyer is not running.

- `InvalidArgument`: An invalid maximum ticket price was specified.

___

#### `SetVotingAddress`

The `SetVotingAddress` configures the ticket address for the automatic ticket
buyer.

**Request:** `SetVotingAddressRequest`

- `string ticket_address`: The address to delegate voting rights to.

**Response:** `SetVotingAddressResponse`

**Expected errors:**

- `FailedPrecondition`: Voting buyer is not running.

- `FailedPrecondition`: Wallet has not been loaded.

- `InvalidArgument`: An invalid voting address was specified.

___

#### `SetPoolAddress`

The `SetPoolAddress` configures the pool address for the automatic ticket buyer.

**Request:** `SetPoolAddressRequest`

- `string pool_address`: The stake pool address where ticket fees will go to.

**Response:** `SetPoolAddressResponse`

**Expected errors:**

- `FailedPrecondition`: Ticket buyer is not running.

- `FailedPrecondition`: Wallet has not been loaded.

- `InvalidArgument`: Pool address was specified, but pool fees were not.

- `InvalidArgument`: Pool address was not specified, but pool fees were.

- `InvalidArgument`: An invalid pool address was specified.

___

#### `SetPoolFees`

The `SetPoolFees` configures the pool fees for the automatic ticket buyer.

**Request:** `SetPoolFeesRequest`

- `double pool_fees`: The absolute per ticket fee mandated by the stake pool as a percent.

**Response:** `SetPoolFeesResponse`

**Expected errors:**

- `FailedPrecondition`: Ticket buyer is not running.

- `InvalidArgument`: Pool address was specified, but pool fees were not.

- `InvalidArgument`: Pool address was not specified, but pool fees were.

- `InvalidArgument`: And invalid pool fees amount was given, either too large or too small.

___

#### `SetMaxPerBlock`

The `SetMaxPerBlock` configures the maximum tickets per block for the automatic
ticket buyer.

**Request:** `SetMaxPerBlockRequest`

- `int64 max_per_block`: The maximum tickets per block. Negative number indicates one ticket every n blocks.

**Response:** `SetMaxPerBlockResponse`

**Expected errors:**

- `FailedPrecondition`: Ticket buyer is not running.

## `TicketBuyerV2Service`

The `TicketBuyerV2Service` service provides RPC clients with the ability to
launch the V2 ticket buyer.  

**Methods:**

- [`RunTicketBuyer`](#runautobuyer)

### Methods

#### `RunTicketBuyer`

The `RunTicketBuyer` starts a new V2 ticket buyer for the specified account.
The users may specify a balance to maintain as well as various settings for purchasing tickets for stakepools.

**Request:** `RunTicketBuyerRequest`

- `bytes passphrase`: The private passphrase to unlock the wallet.

- `uint32 account`: The account number from which to purchase the tickets.

- `uint32 voting_account`: The account that will be used for the voting address (if no voting address is specified.) 

- `int64 balance_to_maintain`: When set, the account will purchase as many tickets as possible without going under this amount.

- `string voting_address`: The address to give the tickets purchased voting rights.

- `string pool_address`: The address that will be used in any stakepool fee commitment utxos.

- `double pool_fees`: The percentage used to calculate the proper fee in the stakepool fee commitment utxos.

**Response:** `stream RunTicketBuyerResponse`

**Expected errors:**

- `FailedPrecondition`: Wallet has not been loaded.

- `InvalidArgument`: An invalid voting address was used.

- `InvalidArgument`: An invalid pool address was used.

- `InvalidArgument`: A negative balance to maintain given.

## `AccountMixerService`

The `AccountMixerService` service provides RPC clients with the ability to
launch the V2 ticket buyer.  

**Methods:**

- [`RunAccountMixer`](#runautobuyer)

### Methods

#### `RunAccountMixer`

The `RunAccountMixer` starts a new account mixer for the specified account (and branch).

**Request:** `RunAccountMixerRequest`

- `bytes passphrase`: The private passphrase to unlock the wallet.

- `uint32 mixed_account`: The account number to which the mixing funds should end up.

- `uint32 mixed_account_branch`: The branch number to which the mixing funds should end up.

- `uint32 change_account`: The account that will be used for any unmixed change that is waiting to be mixed.

- `string cspp_server`: The CSPP mixing server URL and port.

**Response:** `stream RunAccountMixerResponse`

**Expected errors:**

- `FailedPrecondition`: Wallet has not been loaded.

## `AgendaService`

The `AgendaService` service provides RPC clients with the ability to query the
agendas of the latest supported stake version.

**Methods:**

- [`Agendas`](#agendas)

### Methods

#### `Agendas`

The `Agendas` method queries for defined agendas in the latest stake version
supported by this software.

**Request:** `AgendasRequest`

**Response:** `AgendasResponse`

- `uint32 version`: The latest stake version supported by the software and the
  version of the included agendas.

- `repeated Agenda agendas`: All agendas defined by the latest supported stake
  version.

  **Nested message:** `Agenda`

  - `string id`: The ID for this agenda.

  - `string description`: A description of what the agenda is voting about.

  - `uint32 mask`: The bitmask of bits allocated to defining votes for this
    agenda.  At the moment this is limited to 16 bits in the software, but
    protobuf v3 requires this field to be at least 32 bits wide.

  - `repeated Choice choices`: All possible vote choices for the agenda.

  - `int64 start_time`: The Unix time that the agenda voting begins.

  - `int64 expire_time`: The Unix time that the agenda voting expires.

  **Nested message:** `Choice`

  - `string id`: The ID for this agenda vote choice.

  - `string description`: A description of what this agenda vote entails.

  - `uint32 bits`: The bitmask of bits used to vote for this choice.  At the
    moment this is limited to 16 bits in the software, but protobuf v3 requires
    this field to be at least 32 bits wide.

  - `bool is_abstain`: Whether the choice describes to abstain from the vote.

  - `bool is_no`: Whether the choice describes to vote against all changes and
    keep the current consensus rules (if the vote is for a consensus change).

**ExpectedErrors:** None

## `VotingService`

The `VotingService` service provides RPC clients with the ability to query and
set the vote preferences of a voting wallet.

**Methods:**

- [`VoteChoices`](#votechoices)
- [`SetVoteChoices`](#setvotechoices)

### Methods

#### `VoteChoices`

The `VoteChoices` method queries for the current vote choices used to define
vote bits of the latest supported stake version agendas.

**Request:** `VoteChoicesRequest`

- `bytes ticket_hash`: The hash of the ticket to return vote choices for. If
  hash is not specified or the ticket has no choices set, the default vote
  choices are returned.

**Response:** `VoteChoicesResponse`

- `uint32 version`: The latest stake version supported by the software and the
  version of the included agendas.

- `repeated Choice choices`: The currently configured agenda vote choices,
  including abstaining votes.

  **Nested message:** `Choice`

  - `string agenda_id`: The ID for the agenda the choice concerns.

  - `string agenda_description`: A description of the agenda the choice
	  concerns.

  - `string choice_id`: The ID of the current choice for this agenda.

  - `string choice_description`: A description of the current choice for this
    agenda.

- `uint32 votebits`: The votebits of the currently-configured choices.

**ExpectedErrors:** None

___

#### `SetVoteChoices`

The `SetVoteChoices` method sets choices  for defined agendas in the latest stake version
supported by this software.

**Request:** `SetVoteChoicesRequest`

- `repeated Choice choices`: Choices for each agenda to modify.  If a choice is
  specified multiple times for an agenda, the last takes preference.

  **Nested message:** `Choice`

  - `string agenda_id`: The ID for the agenda to modify.

  - `string choice_id`: The ID for the choice to choose.

- `bytes ticket_hash`: The hash of the ticket to set choices for.

**Response:** `SetVoteChoicesResponse`

  - `uint32 votebits`: The votebits for the wallet after setting choices.

**ExpectedErrors:**

- `InvalidArgument`: An agenda ID or choice ID is not valid for the latest
  supported stake version.

## `MessageVerificationService`

The `MessageVerificationService` service provides the caller with the ability to
verify that a message was signed using the private key of a particular address.

**Methods:**

- [`VerifyMessage`](#verifymessage)

### Methods

#### `VerifyMessage`

The `VerifyMessage` method verifies that a signature is a valid signature of a
message and was created using the secp256k1 private key for an address.

**Request:** `VerifyMessageRequest`

- `string address`: The address to compare against a recovered public key from
  the signature.  Must be secp256k1 P2PK or P2PKH.

- `string message`: The message to verify.

- `bytes signature`: The signature of the message.

**Response:** `VerifyMessageResponse`

- `bool valid`: The signature is valid and was signed by the private key of the
  address.

**Expected errors:**

- `InvalidArgument`: The address cannot be decoded or is not secp256k1 P2PK or
  P2PKH.

## `DecodeMessageService`

The `DecodeMessageService` service provides the caller with the ability to
decode various messages and structures given their serialized (binary)
representation.

Unless otherwise noted, all serialized parameters on requests **MUST** belong
to the same network (mainnet/testnet) as the wallet, otherwise the returned
data may contain incorrect information.

**Methods:**

- [`DecodeRawTransaction`](#decoderawtransaction)

### Methods

#### `DecodeRawTransaction`

The `DecodeRawTransaction` method takes a serialized transaction and decodes as
much information as possible.

**Request:** `DecodeRawTransactionRequest`

- `bytes serialized_transaction`: The raw, serialized transaction.

**Response:** `DecodeRawTransactionResponse`

- `DecodedTransaction transaction`: The decoded transaction data.

The `DecodedTransaction` message is documented [here](#decodedtransaction).

**Expected errors:**

- `InvalidArgument`: The serialized transaction could not be decoded.

## NetworkService

The `NetworkService` service provides the caller with the ability to query and
perform actions in the P2P network related to blockchain data not necessarily
tracked by the wallet.

In order to use this service, the wallet must have already been loaded. Most
operations fail if the wallet is not connected to an underlying dcrd instance
(when running in regular RPC mode) or to remote peers (when running in SPV mode).

**Methods**

- [`GetRawBlock`](#GetRawBlock)

### Methods

#### `GetRawBlock`

The `GetRawBlock` method queries the network for a full blockchain block. The
returned block is **not** cached by the wallet, therefore callers are advised
to consider the bandwidth implications of requesting a large number of blocks.

**Request:** `GetRawBlockRequest`

- `bytes block_hash`: The hash of the desired block. If unspecified, the block
  is fetched by `block_height`.

- `sint32 block_height` The height of the (mainchain) block to fetch. The wallet
  must have seen this block height for the request to succeed.

**Response:** `GetRawBlockResponse`

- `bytes block`: The serialized raw block.

**Expected errors:**

- `Unavailable`: The wallet is not currently connected to the p2p network.