LBRYCommunity/lbcwallet
1
0
Fork 0
Code Issues 5 Pull requests Projects Releases 14 Packages Wiki Activity
lbcwallet/rpc/documentation/api.md
Roy Lee 202374ebd8 [lbry] fork from btcsuite to lbryio 
1. btcd -> lbcd
2. btcwallet -> lbcallet
3. btcutil -> lbcutil
2022-05-24 10:31:06 -07:00

999 lines
32 KiB
Markdown
Raw Blame History

# RPC API Specification
Version: 2.0.1
=======
**Note:** This document assumes the reader is familiar with gRPC concepts.
Refer to the [gRPC Concepts documentation](http://www.grpc.io/docs/guides/concepts.html)
for any unfamiliar terms.
**Note:** The naming style used for autogenerated identifiers may differ
depending on the language being used. This document follows the naming style
used by Google in their Protocol Buffers and gRPC documentation as well as this
project's `.proto` files. That is, CamelCase is used for services, methods, and
messages, lower_snake_case for message fields, and SCREAMING_SNAKE_CASE for
enums.
**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](http://semver.org/).
Only optional proto3 message fields are used (the `required` keyword is never
used in the `.proto` file). If a message field must be set to something other
than the default value, or any other values are invalid, the error must occur in
the application's message handling. This prevents accidentally introducing
parsing errors if a previously optional field is missing or a new required field
is added.
Functionality is grouped into gRPC services. Depending on what functions are
currently callable, different services will be running. As an example, the
server may be running without a loaded wallet, in which case the Wallet service
is not running and the Loader service must be used to create a new or load an
existing wallet.
- [`VersionService`](#versionservice)
- [`LoaderService`](#loaderservice)
- [`WalletService`](#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`](#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`](#walletexists)
- [`CreateWallet`](#createwallet)
- [`OpenWallet`](#openwallet)
- [`CloseWallet`](#closewallet)
- [`StartConsensusRpc`](#startconsensusrpc)
**Shared messages:**
- [`BlockDetails`](#blockdetails)
- [`TransactionDetails`](#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 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 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:
- [RPC API Specification](#rpc-api-specification)
- [Version: 2.0.1](#version-201)
- [`VersionService`](#versionservice)
- [Methods](#methods)
- [`Version`](#version)
- [`LoaderService`](#loaderservice)
- [Methods](#methods-1)
- [`WalletExists`](#walletexists)
- [`CreateWallet`](#createwallet)
- [`OpenWallet`](#openwallet)
- [`CloseWallet`](#closewallet)
- [`StartConsensusRpc`](#startconsensusrpc)
- [`WalletService`](#walletservice)
- [`Ping`](#ping)
- [`Network`](#network)
- [`AccountNumber`](#accountnumber)
- [`Accounts`](#accounts)
- [`Balance`](#balance)
- [`GetTransactions`](#gettransactions)
- [`ChangePassphrase`](#changepassphrase)
- [`RenameAccount`](#renameaccount)
- [`NextAccount`](#nextaccount)
- [`NextAddress`](#nextaddress)
- [`ImportPrivateKey`](#importprivatekey)
- [`FundTransaction`](#fundtransaction)
- [`SignTransaction`](#signtransaction)
- [`PublishTransaction`](#publishtransaction)
- [`TransactionNotifications`](#transactionnotifications)
- [`SpentnessNotifications`](#spentnessnotifications)
- [`AccountNotifications`](#accountnotifications)
- [Shared messages](#shared-messages)
- [`BlockDetails`](#blockdetails)
- [`TransactionDetails`](#transactiondetails)
#### `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](#blockdetails).
- `repeated TransactionDetails unmined_transactions`: All unmined transactions.
The ordering is unspecified.
The `TransactionDetails` message is used by other methods and is documented
[here](#transactiondetails).
**Expected errors:**
- `InvalidArgument`: A non-default block hash field did not have the correct length.
- `Aborted`: The wallet database is closed.
- `NotFound`: A block, specified by its height or hash, is unknown to the
wallet.
**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](#blockdetails).
- `repeated bytes detached_blocks`: The hashes of every block that was
reorganized out of the main chain. These are sorted by heights in decreasing
order (newest blocks first).
- `repeated TransactionDetails unmined_transactions`: All newly added unmined
transactions. When relevant transactions are reorganized out and not included
in (or double-spent by) the new chain, they are included here.
The `TransactionDetails` message is used by other methods and is documented
[here](#transactiondetails).
- `repeated bytes unmined_transaction_hashes`: The hashes of every
currently-unmined transaction. This differs from the `unmined_transactions`
field by including every unmined transaction, rather than those newly added to
the unmined set.
**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](#transactiondetails).
**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.
Reference in a new issue View git blame Copy permalink