zebra_rpc::methods

Trait RpcServer

source 
pub trait RpcServer:
    Sized
    + Send
    + Sync
    + 'static {

Show 16 methods    // Required methods
    fn get_info(&self) -> Result<GetInfo>;
    fn get_blockchain_info<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<GetBlockChainInfo>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn get_address_balance<'life0, 'async_trait>(
        &'life0 self,
        address_strings: AddressStrings,
    ) -> Pin<Box<dyn Future<Output = Result<AddressBalance>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn send_raw_transaction<'life0, 'async_trait>(
        &'life0 self,
        raw_transaction_hex: String,
    ) -> Pin<Box<dyn Future<Output = Result<SentTransactionHash>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn get_block<'life0, 'async_trait>(
        &'life0 self,
        hash_or_height: String,
        verbosity: Option<u8>,
    ) -> Pin<Box<dyn Future<Output = Result<GetBlock>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn get_block_header<'life0, 'async_trait>(
        &'life0 self,
        hash_or_height: String,
        verbose: Option<bool>,
    ) -> Pin<Box<dyn Future<Output = Result<GetBlockHeader>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn get_best_block_hash(&self) -> Result<GetBlockHash>;
    fn get_best_block_height_and_hash(&self) -> Result<GetBlockHeightAndHash>;
    fn get_raw_mempool<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<String>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn z_get_treestate<'life0, 'async_trait>(
        &'life0 self,
        hash_or_height: String,
    ) -> Pin<Box<dyn Future<Output = Result<GetTreestate>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn z_get_subtrees_by_index<'life0, 'async_trait>(
        &'life0 self,
        pool: String,
        start_index: NoteCommitmentSubtreeIndex,
        limit: Option<NoteCommitmentSubtreeIndex>,
    ) -> Pin<Box<dyn Future<Output = Result<GetSubtrees>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn get_raw_transaction<'life0, 'async_trait>(
        &'life0 self,
        txid: String,
        verbose: Option<u8>,
    ) -> Pin<Box<dyn Future<Output = Result<GetRawTransaction>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn get_address_tx_ids<'life0, 'async_trait>(
        &'life0 self,
        request: GetAddressTxIdsRequest,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<String>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn get_address_utxos<'life0, 'async_trait>(
        &'life0 self,
        address_strings: AddressStrings,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<GetAddressUtxos>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn stop(&self) -> Result<String>;

    // Provided method
    fn into_rpc(self) -> RpcModule<Self> { ... }

}
Expand description

Server trait implementation for the Rpc RPC API.

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<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<GetBlockChainInfo>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

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<'life0, 'async_trait>( &'life0 self, address_strings: AddressStrings, ) -> Pin<Box<dyn Future<Output = Result<AddressBalance>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

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<'life0, 'async_trait>( &'life0 self, raw_transaction_hex: String, ) -> Pin<Box<dyn Future<Output = Result<SentTransactionHash>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

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<'life0, 'async_trait>( &'life0 self, hash_or_height: String, verbosity: Option<u8>, ) -> Pin<Box<dyn Future<Output = Result<GetBlock>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

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. if a height was passed or -5 if a hash was passed.

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

Zebra previously partially supported verbosity=1 by returning only the fields required by lightwalletd (lightwalletd only reads the tx field of the result). That verbosity level was migrated to “3”; so while lightwalletd will still work by using verbosity=1, it will sync faster if it is changed to use verbosity=3.

The undocumented chainwork field is not returned.

source

fn get_block_header<'life0, 'async_trait>( &'life0 self, hash_or_height: String, verbose: Option<bool>, ) -> Pin<Box<dyn Future<Output = Result<GetBlockHeader>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

Returns the requested block header by hash or height, as a GetBlockHeader JSON string. If the block is not in Zebra’s state, returns error code -8. if a height was passed or -5 if a hash was passed.

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
§Notes

The undocumented chainwork field is not returned.

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<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<String>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

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

zcashd reference: getrawmempool method: post tags: blockchain

source

fn z_get_treestate<'life0, 'async_trait>( &'life0 self, hash_or_height: String, ) -> Pin<Box<dyn Future<Output = Result<GetTreestate>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

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<'life0, 'async_trait>( &'life0 self, pool: String, start_index: NoteCommitmentSubtreeIndex, limit: Option<NoteCommitmentSubtreeIndex>, ) -> Pin<Box<dyn Future<Output = Result<GetSubtrees>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

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<'life0, 'async_trait>( &'life0 self, txid: String, verbose: Option<u8>, ) -> Pin<Box<dyn Future<Output = Result<GetRawTransaction>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

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<'life0, 'async_trait>( &'life0 self, request: GetAddressTxIdsRequest, ) -> Pin<Box<dyn Future<Output = Result<Vec<String>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

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<'life0, 'async_trait>( &'life0 self, address_strings: AddressStrings, ) -> Pin<Box<dyn Future<Output = Result<Vec<GetAddressUtxos>>> + Send + 'async_trait>>
where Self: 'async_trait, 'life0: 'async_trait,

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 into_rpc(self) -> RpcModule<Self>

Collects all the methods and subscriptions defined in the trait and adds them into a single RpcModule.

Object Safety§

This trait is not object safe.

Implementors§

source§

impl<Mempool, State, Tip> RpcServer 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,