RPC API Specification

Version: 2.0.1 =======

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, lowersnakecase for message fields, and SCREAMINGSNAKECASE 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`
• `LoaderService`
• `WalletService`

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

LoaderService

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

Methods:

• `WalletExists`
• `CreateWallet`
• `OpenWallet`
• `CloseWallet`
• `StartConsensusRPC`

Shared messages:

• `BlockDetails`
• `TransactionDetails`

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.

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.

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 LoaderService and/or using a secret to authenticate the operation.

StartConsensusRPC

The StartConsensusRPC method is used to provide clients the ability to dynamically start the pod RPC client. This RPC client is used for wallet syncing and publishing transactions to the Bitcoin network.

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 pod RPC port of the active Bitcoin 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 LoaderService 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.

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`
• `GetTransactions`
• `ChangePassphrase`
• `RenameAccount`
• `NextAccount`
• `NextAddress`
• `ImportPrivateKey`
• `FundTransaction`
• `SignTransaction`
• `PublishTransaction`
• `TransactionNotifications`
• `SpentnessNotifications`
• `AccountNotifications`

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.

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.

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.

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

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

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: There should be a way to specify a starting block or time to begin the rescan at. Additionally, since the client is expected to be able to do asynchronous RPC, it may be useful for the response to block on the rescan finishing before returning.

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.

Response: NextAddressResponse

• string address: The payment address string.

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 key WIF string is not a valid WIF encoding.

• Aborted: The wallet database is closed.

• InvalidArgument: The private passphrase is incorrect.

• NotFound: The account does not exist.

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.

• 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

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.

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.

PublishTransaction

The PublishTransaction method publishes a signed, serialized transaction to the Bitcoin 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

Expected errors:

• InvalidArgument: The serialized transaction can not be decoded or is missing

input scripts.

• Aborted: The wallet database is closed.

Stability: Unstable

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.

SpentnessNotifications

The SpentnessNotifications method returns a stream of notifications regarding the spending of unspent outputs and/or the discovery of new unspent outputs for an account.

Request: SpentnessNotificationsRequest

• uint32 account: The account to create notifications for.

• bool no_notify_unspent: If true, do not send any notifications for

newly-discovered unspent outputs controlled by the account.

• bool no_notify_spent: If true, do not send any notifications for newly-spent

transactions controlled by the account.

Response: stream SpentnessNotificationsResponse

• bytes transaction_hash: The hash of the serialized transaction containing

the output being reported.

• uint32 output_index: The output index of the output being reported.

• Spender spender: If null, the output is a newly-discovered unspent output.

If not null, the message records the transaction input that spends the previously-unspent output.

Nested message: Spender

- bytes transaction_hash: The hash of the serialized transaction that spends the reported output.

- uint32 input_index: The index of the input that spends the reported output.

Expected errors:

• InvalidArgument: The no_notify_unspent and no_notify_spent request

fields are both true.

• Aborted: The wallet database is closed.

Stability: Unstable

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.

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

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.