From 4515f801b13c2939ab183b3440eb28c374bd4193 Mon Sep 17 00:00:00 2001 From: Davidson Souza Date: Fri, 2 Aug 2024 14:47:01 -0300 Subject: [PATCH] rpc-client: fix docs --- crates/floresta-cli/README.md | 216 +++++++++++++++++++++++--------- crates/floresta-cli/src/lib.rs | 10 -- crates/floresta-cli/src/main.rs | 6 - 3 files changed, 158 insertions(+), 74 deletions(-) diff --git a/crates/floresta-cli/README.md b/crates/floresta-cli/README.md index bb09e999..cb89d816 100644 --- a/crates/floresta-cli/README.md +++ b/crates/floresta-cli/README.md @@ -1,6 +1,7 @@ ## Command line utility This is a simple cli utility to interact with your node. To run it, just call + ```bash $ floresta-cli [] ``` @@ -17,8 +18,10 @@ Available commands: - [getblockheader](#getblockheader) - [loaddescriptor](#loaddescriptor) - [getroots](#getroots) + - [stop](#stop) + - [addnode](#addnode) -### getblockchaininfo +## getblockchaininfo This command takes no params and returns some useful data about the current active network @@ -27,22 +30,35 @@ This command takes no params and returns some useful data about the current acti **Return** `best_block`: The best block we have headers for + `chain`: The name of the current active network(eg: bitcoin, testnet, regtest) + `difficulty`: Current network difficulty + `height`: The height of the best block we have headers for + `ibd`: Whether we are currently in initial block download + `latest_block_time`: The time in which the latest block was mined + `latest_work`: The work of the latest block (e.g the amount of hashes needed to mine it, on average) + `leaf_count`: The amount of leaves in our current forest state + `progress`: The percentage of blocks we have validated so far + `root_count`: The amount of roots in our current forest state + `root_hashes`: The hashes of the roots in our current forest state + `validated`: The amount of blocks we have validated so far + `verification_progress`: The percentage of blocks we have verified so far -### getblockhash +## getblockhash Returns the block hash associated with a given height + **Args** `height`: A numerical identifier for a block @@ -52,21 +68,23 @@ Returns the block hash associated with a given height `block_hash`: A string containing a hex-encoded block hash -### gettxout +## gettxout Returns a cached transaction output. The output itself doesn't have to be ours. But the transaction containing it should be cached by our internal wallet. + **Args** `tx_id`: A transaction id + `vout`: A index for the desired output **Returns** -`value`: The amount of satoshis in this output, -`spk`: The redeem script for this output +`value`: The amount of satoshis in this output +`spk`: The redeem script for this output -### getrawtransaction +## getrawtransaction Returns a transaction data, given its id. The transaction itself doesn't have to be ours. But it should be cached by our internal wallet or in the mempool. @@ -76,54 +94,82 @@ Returns a transaction data, given its id. The transaction itself doesn't have to **Returns** - `blockhash`: The hash of the block containing this transaction, if it is in a block - `blocktime`: Time when the block containing this transaction was mined, if it is in a block - `confirmations`: The amount of confirmations this transaction has, if it is in a block - `hash`: The hash of this transaction, a.k.a wtxid - `hex`: The hex-encoded transaction - `in_active_chain`: Whether this transaction is in the active chain - `locktime`: The locktime value of this transaction. - `size`: The size of this transaction in bytes. - `time`: The time when this transaction was mined, if it is in a block - `txid`: The id of this transaction. Only for witness transactions, this is `different` from the wtxid - `version`: The version of this transaction - `vin`: A vector of inputs - `script_sig`: The script signature for this input - `asm`: The disassembled script signature - `hex`: Raw hex-encoded script signature - `sequence`: The nSequence value for this input - `txid`: The id of the transaction containing the output we are spending - `vout`: The index of the output we are spending - `witness`: A vector of witness data - `vout`: A vector of outputs - `n`: The index of this output - `script_pub_key`: The script pubkey for this output - `address`: The address this output pays to, if it's a standard output - `asm`: The disassembled script pubkey - `hex`: Raw hex-encoded script pubkey - `req_sigs`: The amount of signatures required to spend this output (Deprecated) - `type`: The type of this output (e.g pubkeyhash, scripthash, etc) - `value`: The amount of satoshis in this output - `vsize`: The size of this transaction, in virtual bytes - `weight`: The weight of this transaction - -### rescan - -Tells our node to rescan blocks. This will make our node download all blocks all over again, which may be network intensive. -This rpc is useful if you add another address, descriptor or xpub to our wallet, and you know it have historical transactions that are not indexed yet. +`blockhash`: The hash of the block containing this transaction, if it is in a block -**Args** +`blocktime`: Time when the block containing this transaction was mined, if it is in a block + +`confirmations`: The amount of confirmations this transaction has, if it is in a block + +`hash`: The hash of this transaction, a.k.a wtxid + +`hex`: The hex-encoded transaction -`height`: The height we should start +`in_active_chain`: Whether this transaction is in the active chain + +`locktime`: The locktime value of this transaction. + +`size`: The size of this transaction in bytes. + +`time`: The time when this transaction was mined, if it is in a block + +`txid`: The id of this transaction. Only for witness transactions, this is `different` from the wtxid + +`version`: The version of this transaction + +`vin`: A vector of inputs + + `script_sig`: The script signature for this input + + `asm`: The disassembled script signature + + `hex`: Raw hex-encoded script signature + + `sequence`: The nSequence value for this input + + `txid`: The id of the transaction containing the output we are spending + + `vout`: The index of the output we are spending + + `witness`: A vector of witness data + +`vout`: A vector of outputs + + `n`: The index of this output + + `script_pub_key`: The script pubkey for this output + + `address`: The address this output pays to, if it's a standard output + + `asm`: The disassembled script pubkey + + `hex`: Raw hex-encoded script pubkey + + `req_sigs`: The amount of signatures required to spend this output (Deprecated) + + `type`: The type of this output (e.g pubkeyhash, scripthash, etc) + + `value`: The amount of satoshis in this output + +`vsize`: The size of this transaction, in virtual bytes + +`weight`: The weight of this transaction + +## rescan + +Tells our node to rescan blocks. This rpc will only work if the node is not in IBD and it was started with the `--cfilters` flag. +This will rescan for all scripts in our internal wallet within the range of blocks you've downloaded filters for (which can be set +with the `--filters-start-height` flag). If we don't see any error in early stages, the rescan will continue in the background, and +you'll get a `true` as a response. Once the process is finished, you'll see a log message in the node's log saying that the rescan is done. + +**Args**: None **Return** `success`: Whether we successfully started rescanning +## sendrawtransaction -### sendrawtransaction - -Submits a transaction to the network +Submits a transaction to the network. This will broadcast the transaction to our peers, and if it's valid, it will be included in a block. **Args** @@ -133,8 +179,7 @@ Submits a transaction to the network `tx_id`: The transaction id if we succeed - -### getblockheader +## getblockheader Returns the header of a block, giving its hash @@ -145,68 +190,123 @@ Returns the header of a block, giving its hash **Return**: `bits`: A compact representation of the block target + `merkle_root`: The root of a tree formed by all transactions in this block + `nonce`: The nonce used to mine this block + `prev_blockhash`: The hash of this block's ancestor + `time`: The time in which this block was created + `version`: This block's version -### loaddescriptor +## loaddescriptor -Tells our wallet to follow this new descriptor. Optionally, whether we should rescan the blockchain if there's any historical transaction associated with this descriptor. +Tells our wallet to follow this new descriptor. This method will also make our wallet rescan the blockchain for transactions that match this descriptor. Due to that, you can only use this method when the node is not in IBD and if it was started with the `--cfilters` flag. **Args** -`descriptor`: A output descriptor +`descriptor`: An output descriptor **Return** `status`: Whether we succeed loading this descriptor -### getroots +## getroots Returns the roots of our current forest state **Args**: None + **Return** `roots`: A vec of hashes -### getblock +## getblock -Returns a full block, given its hash. Notice that this rpc will cause a actual network request to our node, so it may be slow, and if used too often, may cause more network usage. +Returns a full block, given its hash. Notice that this rpc will cause a actual network request to our node, so it may be slow, and if used too often, may cause more network usage. The returns for this rpc are identical to bitcoin core's `getblock` rpc as of version 27.0 **Args** +`block_hash`: The hash of the block you need to get + +**Return** + `block_hash`: The hash of a block + `bits`: A compact representation of the block target + `chainwork`: The combined work of all blocks in this blockchain + `confirmations`: The amount of confirmations this block has + `difficulty`: This block's difficulty + `hash`: This block's hash + `height`: This block's height + `mediantime`: The median of the timestamps of the last 11 blocks + `merkleroot`: The root of a tree formed by all transactions in this block + `n_tx`: The amount of transactions in this block + `nextblockhash`": The hash of the next block, if any + `nonce`: The nonce used to mine this block + `previousblockhash`": The hash of this block's ancestor + `size`: The size of this block in bytes + `strippedsize`: The size of this block in bytes, excluding witness data + `time`: The time in which this block was created + `tx`: A txid vector of transactions in this block + `version`: This block's version + `versionHex`: This block's version, in hex + `weight`: The weight of this block -### getpeerinfo +## getpeerinfo Returns a list of peers connected to our node, and some useful information about them. **Args**: None **Returns** + `peers`: A vector of peers connected to our node - `address`: This peer's network address - `services`: The services this peer announces as supported - `user_agent`: A string representing this peer's software \ No newline at end of file + + `address`: This peer's network address + + `services`: The services this peer announces as supported + + `user_agent`: A string representing this peer's software + +## stop + +Gracefully stops the node + +**Args**: None + +**Return** + +`success`: Whether we successfully stopped the node + +## addnode + +Adds a new node to our list of peers. This will make our node try to connect to this peer. + +**Args** + +`node`: A network address with the format `ip[:port]` + +**Return** + +`success`: Whether we successfully added this node to our list of peers diff --git a/crates/floresta-cli/src/lib.rs b/crates/floresta-cli/src/lib.rs index c93516ec..38de2456 100644 --- a/crates/floresta-cli/src/lib.rs +++ b/crates/floresta-cli/src/lib.rs @@ -164,16 +164,6 @@ mod tests { assert_eq!(block_header.block_hash(), blockhash); } - #[test] - fn test_get_block_filter() { - let (_proc, client) = start_florestad(); - - let block_filter = client.get_block_filter(0); - - // this should err, because there is no filter for genesis block - assert!(block_filter.is_err()); - } - #[test] fn test_get_height() { let (_proc, client) = start_florestad(); diff --git a/crates/floresta-cli/src/main.rs b/crates/floresta-cli/src/main.rs index d925d0eb..5caf9033 100644 --- a/crates/floresta-cli/src/main.rs +++ b/crates/floresta-cli/src/main.rs @@ -66,9 +66,6 @@ fn do_request(cmd: &Cli, client: ReqwestClient) -> anyhow::Result { Methods::GetPeerInfo => serde_json::to_string_pretty(&client.get_peer_info()?)?, Methods::Stop => serde_json::to_string_pretty(&client.stop()?)?, Methods::AddNode { node } => serde_json::to_string_pretty(&client.add_node(node)?)?, - Methods::GetFilters { height } => { - serde_json::to_string_pretty(&client.get_block_filter(height)?)? - } }) } @@ -150,7 +147,4 @@ pub enum Methods { /// Usage: addnode #[command(name = "addnode")] AddNode { node: String }, - /// Returns the filters for a given block - #[command(name = "getfilter")] - GetFilters { height: u32 }, }