Trait zebra_rpc::methods::Rpc

source · 
pub trait Rpc:
    Sized
    + Send
    + Sync
    + 'static {

Show 16 methods    // Required methods
    fn get_info(&self) -> Result<GetInfo>;
    fn get_blockchain_info(&self) -> BoxFuture<Result<GetBlockChainInfo>>;
    fn get_address_balance(
        &self,
        address_strings: AddressStrings,
    ) -> BoxFuture<Result<AddressBalance>>;
    fn send_raw_transaction(
        &self,
        raw_transaction_hex: String,
    ) -> BoxFuture<Result<SentTransactionHash>>;
    fn get_block(
        &self,
        hash_or_height: String,
        verbosity: Option<u8>,
    ) -> BoxFuture<Result<GetBlock>>;
    fn get_block_header(
        &self,
        hash_or_height: String,
        verbose: Option<bool>,
    ) -> BoxFuture<Result<GetBlockHeader>>;
    fn get_best_block_hash(&self) -> Result<GetBlockHash>;
    fn get_best_block_height_and_hash(&self) -> Result<GetBlockHeightAndHash>;
    fn get_raw_mempool(&self) -> BoxFuture<Result<Vec<String>>>;
    fn z_get_treestate(
        &self,
        hash_or_height: String,
    ) -> BoxFuture<Result<GetTreestate>>;
    fn z_get_subtrees_by_index(
        &self,
        pool: String,
        start_index: NoteCommitmentSubtreeIndex,
        limit: Option<NoteCommitmentSubtreeIndex>,
    ) -> BoxFuture<Result<GetSubtrees>>;
    fn get_raw_transaction(
        &self,
        txid_hex: String,
        verbose: Option<u8>,
    ) -> BoxFuture<Result<GetRawTransaction>>;
    fn get_address_tx_ids(
        &self,
        request: GetAddressTxIdsRequest,
    ) -> BoxFuture<Result<Vec<String>>>;
    fn get_address_utxos(
        &self,
        address_strings: AddressStrings,
    ) -> BoxFuture<Result<Vec<GetAddressUtxos>>>;
    fn stop(&self) -> Result<String>;

    // Provided method
    fn to_delegate<M: Metadata>(self) -> IoDelegate<Self, M> { ... }

}
Expand description

RPC method signatures.

Required Methods§

source

fn get_info(&self) -> Result<GetInfo>

Returns software information from the RPC server, as a GetInfo JSON struct.

zcashd reference: getinfo method: post tags: control

§Notes

The zcashd reference might not show some fields in Zebra’s GetInfo. Zebra uses the field names and formats from the zcashd code.

Some fields from the zcashd reference are missing from Zebra’s GetInfo. It only contains the fields required for lightwalletd support.

source

fn get_blockchain_info(&self) -> BoxFuture<Result<GetBlockChainInfo>>

Returns blockchain state information, as a GetBlockChainInfo JSON struct.

zcashd reference: getblockchaininfo method: post tags: blockchain

§Notes

Some fields from the zcashd reference are missing from Zebra’s GetBlockChainInfo. It only contains the fields required for lightwalletd support.

source

fn get_address_balance( &self, address_strings: AddressStrings, ) -> BoxFuture<Result<AddressBalance>>

Returns the total balance of a provided addresses in an AddressBalance instance.

zcashd reference: getaddressbalance method: post tags: address

§Parameters
  • address_strings: (object, example={“addresses”: [“tmYXBYJj1K7vhejSec5osXK2QsGa5MTisUQ”]}) A JSON map with a single entry
    • addresses: (array of strings) A list of base-58 encoded addresses.
§Notes

zcashd also accepts a single string parameter instead of an array of strings, but Zebra doesn’t because lightwalletd always calls this RPC with an array of addresses.

zcashd also returns the total amount of Zatoshis received by the addresses, but Zebra doesn’t because lightwalletd doesn’t use that information.

The RPC documentation says that the returned object has a string balance field, but zcashd actually returns an integer.

source

fn send_raw_transaction( &self, raw_transaction_hex: String, ) -> BoxFuture<Result<SentTransactionHash>>

Sends the raw bytes of a signed transaction to the local node’s mempool, if the transaction is valid. Returns the SentTransactionHash for the transaction, as a JSON string.

zcashd reference: sendrawtransaction method: post tags: transaction

§Parameters
  • raw_transaction_hex: (string, required, example=“signedhex”) The hex-encoded raw transaction bytes.
§Notes

zcashd accepts an optional allowhighfees parameter. Zebra doesn’t support this parameter, because lightwalletd doesn’t use it.

source

fn get_block( &self, hash_or_height: String, verbosity: Option<u8>, ) -> BoxFuture<Result<GetBlock>>

Returns the requested block by hash or height, as a GetBlock JSON string. If the block is not in Zebra’s state, returns error code -8.

zcashd reference: getblock method: post tags: blockchain

§Parameters
  • hash_or_height: (string, required, example=“1”) The hash or height for the block to be returned.
  • verbosity: (number, optional, default=1, example=1) 0 for hex encoded data, 1 for a json object, and 2 for json object with transaction data.
§Notes

With verbosity=1, lightwalletd only reads the tx field of the result, and other clients only read the hash and confirmations fields, so we only return a few fields for now.

lightwalletd and mining clients also do not use verbosity=2, so we don’t support it.

source

fn get_block_header( &self, hash_or_height: String, verbose: Option<bool>, ) -> BoxFuture<Result<GetBlockHeader>>

Returns the requested block header by hash or height, as a GetBlockHeader JSON string.

zcashd reference: getblockheader method: post tags: blockchain

§Parameters
  • hash_or_height: (string, required, example=“1”) The hash or height for the block to be returned.
  • verbose: (bool, optional, default=false, example=true) false for hex encoded data, true for a json object
source

fn get_best_block_hash(&self) -> Result<GetBlockHash>

Returns the hash of the current best blockchain tip block, as a GetBlockHash JSON string.

zcashd reference: getbestblockhash method: post tags: blockchain

source

fn get_best_block_height_and_hash(&self) -> Result<GetBlockHeightAndHash>

Returns the height and hash of the current best blockchain tip block, as a GetBlockHeightAndHash JSON struct.

zcashd reference: none method: post tags: blockchain

source

fn get_raw_mempool(&self) -> BoxFuture<Result<Vec<String>>>

Returns all transaction ids in the memory pool, as a JSON array.

zcashd reference: getrawmempool method: post tags: blockchain

source

fn z_get_treestate( &self, hash_or_height: String, ) -> BoxFuture<Result<GetTreestate>>

Returns information about the given block’s Sapling & Orchard tree state.

zcashd reference: z_gettreestate method: post tags: blockchain

§Parameters
  • hash | height: (string, required, example=“00000000febc373a1da2bd9f887b105ad79ddc26ac26c2b28652d64e5207c5b5”) The block hash or height.
§Notes

The zcashd doc reference above says that the parameter “height can be negative where -1 is the last known valid block”. On the other hand, lightwalletd only uses positive heights, so Zebra does not support negative heights.

source

fn z_get_subtrees_by_index( &self, pool: String, start_index: NoteCommitmentSubtreeIndex, limit: Option<NoteCommitmentSubtreeIndex>, ) -> BoxFuture<Result<GetSubtrees>>

Returns information about a range of Sapling or Orchard subtrees.

zcashd reference: z_getsubtreesbyindex - TODO: fix link method: post tags: blockchain

§Parameters
  • pool: (string, required) The pool from which subtrees should be returned. Either “sapling” or “orchard”.
  • start_index: (number, required) The index of the first 2^16-leaf subtree to return.
  • limit: (number, optional) The maximum number of subtree values to return.
§Notes

While Zebra is doing its initial subtree index rebuild, subtrees will become available starting at the chain tip. This RPC will return an empty list if the start_index subtree exists, but has not been rebuilt yet. This matches zcashd’s behaviour when subtrees aren’t available yet. (But zcashd does its rebuild before syncing any blocks.)

source

fn get_raw_transaction( &self, txid_hex: String, verbose: Option<u8>, ) -> BoxFuture<Result<GetRawTransaction>>

Returns the raw transaction data, as a GetRawTransaction JSON string or structure.

zcashd reference: getrawtransaction method: post tags: transaction

§Parameters
  • txid: (string, required, example=“mytxid”) The transaction ID of the transaction to be returned.
  • verbose: (number, optional, default=0, example=1) If 0, return a string of hex-encoded data, otherwise return a JSON object.
§Notes

We don’t currently support the blockhash parameter since lightwalletd does not use it.

In verbose mode, we only expose the hex and height fields since lightwalletd uses only those: https://github.com/zcash/lightwalletd/blob/631bb16404e3d8b045e74a7c5489db626790b2f6/common/common.go#L119

source

fn get_address_tx_ids( &self, request: GetAddressTxIdsRequest, ) -> BoxFuture<Result<Vec<String>>>

Returns the transaction ids made by the provided transparent addresses.

zcashd reference: getaddresstxids method: post tags: address

§Parameters
  • request: (object, required, example={"addresses": ["tmYXBYJj1K7vhejSec5osXK2QsGa5MTisUQ"], "start": 1000, "end": 2000}) A struct with the following named fields:
    • addresses: (json array of string, required) The addresses to get transactions from.
    • start: (numeric, required) The lower height to start looking for transactions (inclusive).
    • end: (numeric, required) The top height to stop looking for transactions (inclusive).
§Notes

Only the multi-argument format is used by lightwalletd and this is what we currently support: https://github.com/zcash/lightwalletd/blob/631bb16404e3d8b045e74a7c5489db626790b2f6/common/common.go#L97-L102

source

fn get_address_utxos( &self, address_strings: AddressStrings, ) -> BoxFuture<Result<Vec<GetAddressUtxos>>>

Returns all unspent outputs for a list of addresses.

zcashd reference: getaddressutxos method: post tags: address

§Parameters
  • addresses: (array, required, example={"addresses": ["tmYXBYJj1K7vhejSec5osXK2QsGa5MTisUQ"]}) The addresses to get outputs from.
§Notes

lightwalletd always uses the multi-address request, without chaininfo: https://github.com/zcash/lightwalletd/blob/master/frontend/service.go#L402

source

fn stop(&self) -> Result<String>

Stop the running zebrad process.

§Notes
  • Works for non windows targets only.
  • Works only if the network of the running zebrad process is Regtest.

zcashd reference: stop method: post tags: control

Provided Methods§

source

fn to_delegate<M: Metadata>(self) -> IoDelegate<Self, M>

Create an IoDelegate, wiring rpc calls to the trait methods.

Object Safety§

This trait is not object safe.

Implementors§

source§

impl<Mempool, State, Tip> Rpc for RpcImpl<Mempool, State, Tip>
where Mempool: Service<Request, Response = Response, Error = BoxError> + Clone + Send + Sync + 'static, Mempool::Future: Send, State: Service<ReadRequest, Response = ReadResponse, Error = BoxError> + Clone + Send + Sync + 'static, State::Future: Send, Tip: ChainTip + Clone + Send + Sync + 'static,