Skip to content

Latest commit

 

History

History
2551 lines (1533 loc) · 78.4 KB

api.md

File metadata and controls

2551 lines (1533 loc) · 78.4 KB
Raw

RPC API Specification

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

Note: The entierty of the RPC API is currently considered unstable and may change anytime. Stability will be gradually added based on correctness, perceived usefulness and ease-of-use over alternatives, and user feedback.

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

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

Methods:

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

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:

Shared messages:

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

Stability: Unstable

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.

Stability: Unstable: There needs to be a way to recover all keys and transactions of a wallet being recovered by its seed. It is unclear whether it should be part of this method or a WalletService method.

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.

Stability: Unstable

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.

Stability: Unstable: It would be preferable to stop the WalletService after closing, but there does not appear to be any way to do so currently. It may also be a good idea to limit under what conditions a wallet can be closed, such as only closing wallets loaded by WalletLoaderService and/or using a secret to authenticate the operation.

StartConsensusRpc

The StartConsensusRpc method is used to provide clients the ability to dynamically start the dcrd RPC client. This RPC client is used for wallet syncing and publishing transactions to the Decred network.

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

Request: StartConsensusRpcRequest

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

Response: StartConsensusRpcResponse

Expected errors:

  • FailedPrecondition: A consensus RPC client is already active.

  • InvalidArgument: The network address is ill-formatted or does not contain a valid IP address.

  • NotFound: The consensus RPC server is unreachable. This condition may not return Unavailable as that refers to WalletLoaderService itself being unavailable.

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

Stability: Unstable: It is unknown if the consensus RPC client will remain used after the project gains SPV support.

DiscoverAddresses

The DiscoverAddresses method performs BIP0044 address discovery for the wallet with optional account discovery using the loaded consensus RPC server (required for querying for known used addresses). Account discovery requires the wallet to be unlocked in order to derive account hardened extended pubkeys, and thus the private passphrase must be passed as a parameter when performing this action. Account discovery is typically only required when reseeding a wallet.

Request: DiscoverAddressesRequest

  • bool discover_accounts: In addition to syncing addresses for already derived accounts, also look ahead for other used accounts.

  • bytes private_passphrase: The private passphrase to unlock the wallet when account discovery is enabled.

Response: DiscoverAddressesResponse

Expected Errors:

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

  • InvalidArgument: A zero length passphrase passphrase was specified when account discovery was enabled, or the passphrase was incorrect.

Stability: Unstable

SubscribeToBlockNotifications

The SubscribeToBlockNotifications method associates the wallet with the consensus RPC server, subscribes the wallet for attached block and chain switch notifications, and causes the wallet to process these notifications in the background.

Request: SubscribeToBlockNotificationsRequest

Response: SubscribeToBlockNotificationsResponse

Expected Errors:

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

Stability: Unstable

FetchHeaders

The FetchHeaders method fetches main chain block headers from the opened consensus server client. The response includes the hash and height of the first new block added to the main chain, if any. This is the block that a rescan should begin at.

Request: FetchHeadersRequest

Response: FetchHeadersResponse

  • uint32 fetched_headers_count: The number of new headers attached to the main chain.

  • bytes first_new_block_hash: The hash of the first new block added to the main chain. Only non-null when fetched_headers_count is not zero.

  • int32 first_new_block_height: The height of the first new block added to the main chain. Only non-zero when fetched_headers_count is not zero.

  • bytes main_chain_tip_block_hash: The hash of the main chain tip block after the fetched headers have been applied to the previous tip.

  • int32 main_chain_tip_block_height: The height of the main chain tip block after the fetched headers have been applied to the previous tip.

Expected errors:

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

Stability: Unstable

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

The Ping method checks whether the service is active.

Request: PingRequest

Response: PingResponse

Expected errors: None

Stability: Unstable: This may be moved to another service as it does not depend on the wallet.

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

Stability: Unstable: This may be moved to another service as it does not depend on the wallet.

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.

Stability: Unstable

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

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

Stability: Unstable

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

  • int64 spendable: The spendable balance, given some number of required confirmations, counted in Satoshis. 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 Satoshis.

  • int64 immature_stake_generation: The total value of all immature stakebase outputs, or any revocations, counted in Satoshis.

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

Stability: Unstable: It may prove useful to modify this RPC to query multiple accounts together.

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.

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.

Stability: Unstable

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.

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.

Stability: Unstable

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

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.

Stability: Unstable

  • There is currently no way to get only unmined transactions due to the way the block range is specified.

  • It would be useful to ignore the block range and return some minimum number of the most recent transaction, but it is unclear if that should be added to this method's request object, or to make a new method.

  • A specified ordering (such as dependency order) for all returned unmined transactions would be useful.

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.

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

      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.

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.

Stability: Unstable

  • There is currently no way to get only unmined transactions due to the way the block range is specified.

  • It would be useful to ignore the block range and return some minimum number of the most recent transaction, but it is unclear if that should be added to this method's request object, or to make a new method.

  • A specified ordering (such as dependency order) for all returned unmined transactions would be useful.

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.

Stability: Unstable

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.

Stability: Unstable

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.

Stability: Unstable

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.

Stability: Unstable

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.

Stability: Unstable

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.

Stability: Unstable

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.

Stability: Unstable

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

Stability: Unstable

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.

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.

Stability: Unstable

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 uint32 input_indexes: The input indexes that signature scripts must be created for. If there are no indexes, input scripts are created for every input that is missing an input script.

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

  • InvalidArgument: The serialized transaction can not be decoded.

  • Aborted: The wallet database is closed.

  • InvalidArgument: The private passphrase is incorrect.

Stability: Unstable: It is unclear if the request should include an account, and only secrets of that account are used when creating input scripts. It's also missing options similar to Core's signrawtransaction, such as the sighash flags and additional keys.

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.

Stability: Unstable

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

Stability: Unstable: The ticket price and height are pulled from separate daemon passthroughs and may race. Ideally these would be returned from stored values in the wallet when it updates from incoming stake ticket price notifications passed from the JSON RPC of dcrd. Right now, wallet block processing is very slow and it's difficult for these notifications to stay in sync. In the future, this API may be completely removed in favour of a passthrough for that set of notifications.

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

Expected errors: None

Stability: Unstable

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.

Stability: Unstable: there are a number of current bugs with ticket purchase and querying for stake difficulty. When the wallet has a more suitable means to track stake difficulty, and daemon is patched to better handle ticket purchases, these issues should disappear. They include the stake difficulty changing from the time it is queried, to the time the ticket is attempted to be purchased, to the time the ticket hits the daemon mempool and out of date stake difficulties queried from the daemon.

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.

Stability: Unstable

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.

Stability: Unstable: this method requires an associated consensus server RPC client and functionality might move for any future SPV support.

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.

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

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.

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

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.

Stability: Unstable: This method could use a better name.

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.

Stability: Unstable: This should probably share a message with the Accounts method.

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.

Stability: Unstable

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.

Stability: Unstable: This should probably include the block version.

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.

Stability: Unstable: Since the caller is expected to decode the serialized transaction, and would have access to every output script, the output properties could be changed to only include outputs controlled by the wallet.

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 commited to a ticket on an SStx transaction.

Stability: Unstable.

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:

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.

Stability: Unstable

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.

Stability: Unstable

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:

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.

Stability: Unstable

StopAutoBuyer

The StopAutoBuyer method stops the automatic ticket buyer.

Request: StopAutoBuyerRequest

Response: StopAutoBuyerResponse

Expected errors:

  • FailedPrecondition: Ticket buyer is not running.

Stability: Unstable

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.

Stability: Unstable

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.

Stability: Unstable

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.

Stability: Unstable

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.

Stability: Unstable

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.

Stability: Unstable

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.

Stability: Unstable

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.

Stability: Unstable

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.

Stability: Unstable

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.

Stability: Unstable

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.

Stability: Unstable

AgendaService

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

Methods:

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 concensus change).

ExpectedErrors: None

Stability: Unstable

VotingService

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

Methods:

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

Stability: Unstable

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.

Stability: Unstable

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:

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.

Stability: Unstable

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:

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.

Stability: Unstable