lbcwallet/rpc/documentation/api.md

# RPC API Specification

Version: 1.0.0

**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 btcd 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 btcd 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`](#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)

#### `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 outputs`: Properties for every transaction output.  Every
  transaction output has a corresponding properties message in this repeated
  field.

  **Nested message:** `Output`

  - `bool mine`: Whether the output is controlled by the wallet.

  - `uint32 account`: The account number of the controlled output.  This field
    is only relevant if `mine` is true.

  - `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.  This field is only relevant if `mine` is true.

  - `repeated string addresses`: The payment address string(s) this output pays
    to.  This is only relevant if `mine` is false.

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