RPC API Specification

Version: 7.2.x

Note: This document assumes the reader is familiar with gRPC concepts. Refer to the gRPC Concepts documentation 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.

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
WalletLoaderService
WalletService
SeedService
TicketBuyerService
TicketBuyerV2Service
AgendaService
VotingService
MessageVerificationService
DecodeMessageService

`VersionService`

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

Methods:

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
CreateWallet
CreateWatchingOnlyWallet
OpenWallet
CloseWallet
RescanPoint
SpvSync
RpcSync

Shared messages:

BlockDetails
TransactionDetails
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
Network
AccountNumber
Accounts
Balance
BlockInfo
GetTransaction
GetTransactions
GetTicket
GetTickets
ChangePassphrase
RenameAccount
Rescan
NextAccount
NextAddress
ImportPrivateKey
ImportScript
FundTransaction
UnspentOutputs
ConstructTransaction
SignTransaction
SignTransactions
CreateSignature
PublishTransaction
PublishUnminedTransactions
TicketPrice
StakeInfo
PurchaseTickets
RevokeTickets
LoadActiveDataFilters
SignMessage
SignMessages
ValidateAddress
TransactionNotifications
AccountNotifications
ConfirmationNotifications
CommittedTickets
BestBlock
SweepAccount

`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.
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.
repeated TransactionDetails unmined_transactions: All unmined transactions. The ordering is unspecified.

The TransactionDetails message is used by other methods and is documented here.

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 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.
- 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.
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: The private passphrase is incorrect.
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.

`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

`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) behaviour 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.

Response: PurchaseTicketsResponse

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

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.

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

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.
bool approves_parent: Whether this block stake validates its parent block.

`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).

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

`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
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
StopAutoBuyer
TicketBuyerConfig
SetAccount
SetBalanceToMaintain
SetMaxFee
SetMaxPriceRelative
SetMaxPriceAbsolute
SetVotingAddress
SetPoolAddress
SetPoolFees
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

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.

`AgendaService`

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

Methods:

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

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.

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

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

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.

Expected errors:

InvalidArgument: The serialized transaction could not be decoded.

Files

api.md

Latest commit

History

api.md

File metadata and controls

RPC API Specification

VersionService

Methods

Version

WalletLoaderService

Methods

WalletExists

CreateWallet

CreateWatchingOnlyWallet

OpenWallet

CloseWallet

RescanPoint

SpvSync

RpcSync

WalletService

Ping

Network

CoinType

AccountNumber

Accounts

Balance

BlockInfo

GetAccountExtendedPubKey

GetAccountExtendedPrivKey

GetTransaction

GetTransactions

GetTicket

GetTickets

ChangePassphrase

RenameAccount

Rescan

NextAccount

NextAddress

ImportPrivateKey

ImportScript

FundTransaction

UnspentOutputs

ConstructTransaction

SignTransaction

SignTransactions

CreateSignature

PublishTransaction

PublishUnminedTransactions

TicketPrice

StakeInfo

PurchaseTickets

RevokeTickets

LoadActiveDataFilters

SignMessage

SignMessages

ValidateAddress

CommittedTickets

BestBlock

SweepAccount

TransactionNotifications

AccountNotifications

ConfirmationNotifications

Shared messages

BlockDetails

TransactionDetails

DecodedTransaction

SyncNotificationType

FetchHeadersNotification

FetchMissingCFiltersNotification

RescanProgressNotification

PeerNotification

SeedService

Methods

GenerateRandomSeed

DecodeSeed

TicketBuyerService

Methods

StartAutoBuyer

StopAutoBuyer

`VersionService`

`Version`

`WalletLoaderService`

`WalletExists`

`CreateWallet`

`CreateWatchingOnlyWallet`

`OpenWallet`

`CloseWallet`

`RescanPoint`

`SpvSync`

`RpcSync`

`WalletService`

`Ping`

`Network`

`CoinType`

`AccountNumber`

`Accounts`

`Balance`

`BlockInfo`

`GetAccountExtendedPubKey`

`GetAccountExtendedPrivKey`

`GetTransaction`

`GetTransactions`

`GetTicket`

`GetTickets`

`ChangePassphrase`

`RenameAccount`

`Rescan`

`NextAccount`

`NextAddress`

`ImportPrivateKey`

`ImportScript`

`FundTransaction`

`UnspentOutputs`

`ConstructTransaction`

`SignTransaction`

`SignTransactions`

`CreateSignature`

`PublishTransaction`

`PublishUnminedTransactions`

`TicketPrice`

`StakeInfo`

`PurchaseTickets`

`RevokeTickets`

`LoadActiveDataFilters`

`SignMessage`

`SignMessages`

`ValidateAddress`

`CommittedTickets`

`BestBlock`

`SweepAccount`

`TransactionNotifications`

`AccountNotifications`

`ConfirmationNotifications`

`BlockDetails`

`TransactionDetails`

`DecodedTransaction`

`SyncNotificationType`

`FetchHeadersNotification`

`FetchMissingCFiltersNotification`

`RescanProgressNotification`

`PeerNotification`

`SeedService`

`GenerateRandomSeed`

`DecodeSeed`

`TicketBuyerService`

`StartAutoBuyer`

`StopAutoBuyer`

`TicketBuyerConfig`

`SetAccount`

`SetBalanceToMaintain`

`SetMaxFee`

`SetMaxPriceRelative`

`SetMaxPriceAbsolute`

`SetVotingAddress`

`SetPoolAddress`

`SetPoolFees`

`SetMaxPerBlock`

`TicketBuyerV2Service`

`RunTicketBuyer`