Trait FlorestaRPC

pub trait FlorestaRPC {
    // Required methods
    fn get_block_filter(&self, height: u32) -> Result<String, Error>;
    fn get_blockchain_info(&self) -> Result<GetBlockchainInfoRes, Error>;
    fn get_best_block_hash(&self) -> Result<BlockHash, Error>;
    fn get_block_hash(&self, height: u32) -> Result<BlockHash, Error>;
    fn get_block_header(&self, hash: BlockHash) -> Result<BlockHeader, Error>;
    fn get_transaction(
        &self,
        tx_id: Txid,
        verbosity: Option<bool>,
    ) -> Result<Value, Error>;
    fn get_txout_proof(
        &self,
        txids: Vec<Txid>,
        blockhash: Option<BlockHash>,
    ) -> Option<String>;
    fn load_descriptor(&self, descriptor: String) -> Result<bool, Error>;
    fn rescanblockchain(
        &self,
        start_block: Option<u32>,
        stop_block: Option<u32>,
        use_timestamp: bool,
        confidence: RescanConfidence,
    ) -> Result<bool, Error>;
    fn get_block_count(&self) -> Result<u32, Error>;
    fn send_raw_transaction(&self, tx: String) -> Result<Txid, Error>;
    fn get_roots(&self) -> Result<Vec<String>, Error>;
    fn get_peer_info(&self) -> Result<Vec<PeerInfo>, Error>;
    fn get_block(
        &self,
        hash: BlockHash,
        verbosity: Option<u32>,
    ) -> Result<GetBlockRes, Error>;
    fn get_tx_out(&self, tx_id: Txid, outpoint: u32) -> Result<GetTxOut, Error>;
    fn stop(&self) -> Result<String, Error>;
    fn add_node(
        &self,
        node: String,
        command: AddNodeCommand,
        v2transport: bool,
    ) -> Result<Value, Error>;
    fn disconnect_node(
        &self,
        node_address: String,
        node_id: Option<usize>,
    ) -> Result<Value, Error>;
    fn find_tx_out(
        &self,
        tx_id: Txid,
        outpoint: u32,
        script: String,
        height_hint: u32,
    ) -> Result<Value, Error>;
    fn get_memory_info(&self, mode: String) -> Result<GetMemInfoRes, Error>;
    fn get_rpc_info(&self) -> Result<GetRpcInfoRes, Error>;
    fn uptime(&self) -> Result<u32, Error>;
    fn list_descriptors(&self) -> Result<Vec<String>, Error>;
    fn ping(&self) -> Result<(), Error>;
}

A trait specifying all possible methods for floresta’s json-rpc

Required Methods

fn get_block_filter(&self, height: u32) -> Result<String, Error>

Get the BIP158 filter for a given block height

BIP158 filters are a compact representation of the set of transactions in a block, designed for efficient light client synchronization. This method returns the filter for a given block height, encoded as a hexadecimal string. You need to have enabled block filters by setting the blockfilters=1 option

fn get_blockchain_info(&self) -> Result<GetBlockchainInfoRes, Error>

Returns general information about the chain we are on

This method returns a bunch of information about the chain we are on, including the current height, the best block hash, the difficulty, and whether we are currently in IBD (Initial Block Download) mode.

fn get_best_block_hash(&self) -> Result<BlockHash, Error>

Returns the hash of the best (tip) block in the most-work fully-validated chain.

fn get_block_hash(&self, height: u32) -> Result<BlockHash, Error>

Returns the hash of the block at the given height

This method returns the hash of the block at the given height. If the height is invalid, an error is returned.

fn get_block_header(&self, hash: BlockHash) -> Result<BlockHeader, Error>

Returns the block header for the given block hash

This method returns the block header for the given block hash, as defined in the Bitcoin protocol specification. A header contains the block’s version, the previous block hash, the merkle root, the timestamp, the difficulty target, and the nonce.

fn get_transaction( &self, tx_id: Txid, verbosity: Option<bool>, ) -> Result<Value, Error>

Gets a transaction from the blockchain

This method returns a transaction that’s cached in our wallet. If the verbosity flag is set to false, the transaction is returned as a hexadecimal string. If the verbosity flag is set to true, the transaction is returned as a json object.

fn get_txout_proof( &self, txids: Vec<Txid>, blockhash: Option<BlockHash>, ) -> Option<String>

Returns the proof that one or more transactions were included in a block

This method returns the Merkle proof, showing that a transaction was included in a block. The pooof is returned as a vector hexadecimal string.

fn load_descriptor(&self, descriptor: String) -> Result<bool, Error>

Loads up a descriptor into the wallet

This method loads up a descriptor into the wallet. If the rescan option is not None, the wallet will be rescanned for transactions matching the descriptor. If you have compact block filters enabled, this process will be much faster and use less bandwidth. The rescan parameter is the height at which to start the rescan, and should be at least as old as the oldest transaction this descriptor could have been used in.

fn rescanblockchain( &self, start_block: Option<u32>, stop_block: Option<u32>, use_timestamp: bool, confidence: RescanConfidence, ) -> Result<bool, Error>

rescanblockchain

Sends a request to the node for rescan the blockchain searching for transactions related to the wallet’s cached addresses.

Usage

Synopsis

floresta-cli rescanblockchain <--t or --timestamp> <start_block> <stop_block> <high|medium|low|exact)>

Examples

# Rescan from height 100 to 200

floresta-cli rescanblockchain 100 200

# Rescan from height 100 to tip

floresta-cli rescanblockchain 100

# Rescan from timestamp 1231006505 (genesis) until 133456789

floresta-cli rescanblockchain -t 1231006505 1752516460 --confidence high

# Rescan from timestamp 0 (alias for genesis) until the tip

floresta-cli rescanblockchain --timestamp 0 1752516460 -c high

Arguments

start_block (numeric, optional, default=0): The initial block to start the blockchain rescan.

stop_block (numeric, optional, default=0): The block limit to stop rescanning. (0 disables it)

use_timestamp (boolean flag, optional, default=false): When present in the command the provided values will be treated as UNIX timestamps. These timestamps do not need to be directly from a block and can be used for finding addresses and UTXOs from meaningful timestamp values.

confidence (string, optional, default=medium): In cases where use_timestamp is set, tells how much confidence the user wants for finding its addresses from this rescan request, a higher confidence will add more lookback seconds to the targeted timestamp and rescanning more blocks.

Under the hood this uses an Exponential distribution cumulative distribution function (CDF) where the parameter $\lambda$ (rate) is $\frac{1}{600}$ (1 block every 600 seconds, 10 minutes). The supplied string can be one of:

• high: 99% confidence interval.
• medium (default): 95% confidence interval.
• low: 90% confidence interval.
• exact: Doesnt apply any lookback seconds.

Returns

Ok Response

When the rescan request successfully starts you will receive an Ok(true). After the rescan finishes, you’ll see a log message telling all the blocks that may have any transactions to your wallet

Error Enum

This RPC command can only fail if:

• we can’t communicate with the headers database;
• if invalid values are provided. That is, the start of the request being less than the stop value.

If timestamp is true, apart the previous rules, if any of the values is smaller than the genesis block (1231006505 for mainnet) or greater than the tip time, the execution will also fail.

Furthermore, the request will be aborted if the node still syncing with the blockchain.

Notes

• Be sure to not insert invalid values, e.g. the start being greater than the stop.

• This rescan relies on BIP 158 block filters.

• You dont need to be picky with timestamps but, when using uncertain timestamps you mostly want to set a high confidence which is not necessary for precise timestamps.

fn get_block_count(&self) -> Result<u32, Error>

Returns the current height of the blockchain

fn send_raw_transaction(&self, tx: String) -> Result<Txid, Error>

Sends a hex-encoded transaction to the network

This method sends a transaction to the network. The transaction should be encoded as a hexadecimal string. If the transaction is valid, it will be broadcast to the network, and return the transaction id. If the transaction is invalid, an error will be returned.

fn get_roots(&self) -> Result<Vec<String>, Error>

Gets the current accumulator for the chain we’re on

This method returns the current accumulator for the chain we’re on. The accumulator is a set of roots, that let’s us prove that a UTXO exists in the chain. This method returns a vector of hexadecimal strings, each of which is a root in the accumulator.

fn get_peer_info(&self) -> Result<Vec<PeerInfo>, Error>

Gets information about the peers we’re connected with

This method returns information about the peers we’re connected with. This includes the peer’s IP address, the peer’s version, the peer’s user agent, the transport protocol and the peer’s current height.

fn get_block( &self, hash: BlockHash, verbosity: Option<u32>, ) -> Result<GetBlockRes, Error>

Returns a block, given a block hash

This method returns a block, given a block hash. If the verbosity flag is 0, the block is returned as a hexadecimal string. If the verbosity flag is 1, the block is returned as a json object.

fn get_tx_out(&self, tx_id: Txid, outpoint: u32) -> Result<GetTxOut, Error>

Return a cached transaction output

This method returns a cached transaction output. If the output is not in the cache, or is spent, an empty object is returned. If you want to find a utxo that’s not in the cache, you can use the findtxout method.

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

Stops the florestad process

This can be used to gracefully stop the florestad process.

fn add_node( &self, node: String, command: AddNodeCommand, v2transport: bool, ) -> Result<Value, Error>

Tells florestad to connect with a peer

You can use this to connect with a given node, providing it’s IP address and port. If the v2transport option is set, we won’t retry connecting using the old, unencrypted P2P protocol.

addnode

Attempts to add or remove a node from the addnode list.

Usage

Synopsis

floresta-cli addnode <ip:[port]> <add|remove|onetry> [true|false]

Examples

floresta-cli addnode 192.168.0.1 add true
floresta-cli addnode 192.168.0.1 add false
floresta-cli addnode 192.168.0.1 remove # does not accept the boolean for v2transport
floresta-cli addnode 192.168.0.1 onetry true
floresta-cli addnode 192.168.0.1 onetry false

Arguments

node - (string, required) The IP:[PORT] address of the peer to connect to.

command - (string, required) ‘add’ to add a node to the list, ‘remove’ to remove a node from the list, ‘onetry’ to try a connection to the node once.

v2transport - (boolean, optional) Only tries to connect with this address using BIP0324 P2P V2 protocol. ignored for ‘remove’ command.

Returns

Ok response

• json null

Error response

• InvalidAddress - The provided address is not a valid socket address or IP address
• InvalidAddnodeCommand - The command is not one of ‘add’, ‘remove’, or ‘onetry’

Notes

• Will use v2transport if available unless the param is specified to false
• Implementation detail for addnode: on bitcoin-core, the node doesn’t connect immediately after adding a peer, it just adds it to the added_peers list. Here we do almost the same, but we do an early connection attempt to the peer, so we can start communicating with.

fn disconnect_node( &self, node_address: String, node_id: Option<usize>, ) -> Result<Value, Error>

Immediately disconnect from a peer.

The peer can be referenced either by node_address or node_id. If referencing by node_id, an empty string must be passed as the node_address.

fn find_tx_out( &self, tx_id: Txid, outpoint: u32, script: String, height_hint: u32, ) -> Result<Value, Error>

Finds an specific utxo in the chain

You can use this to look for a utxo. If it exists, it will return the amount and scriptPubKey of this utxo. It returns an empty object if the utxo doesn’t exist. You must have enabled block filters by setting the blockfilters=1 option.

fn get_memory_info(&self, mode: String) -> Result<GetMemInfoRes, Error>

Returns statistics about Floresta’s memory usage.

Returns zeroed values for all runtimes that are not *-gnu or MacOS.

fn get_rpc_info(&self) -> Result<GetRpcInfoRes, Error>

Returns stats about our RPC server

fn uptime(&self) -> Result<u32, Error>

Returns for how long florestad has been running, in seconds

fn list_descriptors(&self) -> Result<Vec<String>, Error>

Returns a list of all descriptors currently loaded in the wallet

fn ping(&self) -> Result<(), Error>

Sends a ping to all peers, checking if they are still alive

Implementors

impl<T: JsonRPCClient> FlorestaRPC for T