diff --git a/docs/OTHER_TOOLS.md b/docs/OTHER_TOOLS.md new file mode 100644 index 0000000..ce111d9 --- /dev/null +++ b/docs/OTHER_TOOLS.md @@ -0,0 +1,256 @@ +# Other Tools + +This page covers additional Contractless CLI tools that do not fit into the wallet, transaction, mempool, validation, storage, or fee-specific guides. + +On Windows, add `.exe` to each command name. + +When a tool asks for a wallet path, press `` to search and auto-complete files and folders. + +## average_block_time_checker + +Calculates the average time between block timestamps for a local range of block files. + +This is a local file inspection tool. It does not contact a node. It reads block files from the directory you provide, extracts the timestamp from each block file, sorts those timestamps, and calculates the average difference between consecutive timestamps. + +Usage: + +```bash +./average_block_time_checker +``` + +Example: + +```bash +./average_block_time_checker 30000 35000 ./blocks/testnet +``` + +Expected output: + +```text +The average time between timestamps is 15.21 seconds. +``` + +If the range does not contain enough block files to compare timestamps, the tool prints: + +```text +Not enough data to calculate an average time difference. +``` + +Use this for local difficulty/block-timing checks, especially when reviewing how close a range of blocks stayed to the intended block target. + +## lookup_difficulty + +Asks a configured node for the current network difficulty. + +Usage: + +```bash +./lookup_difficulty +``` + +Interactive prompts: + +```text +Please enter the path to your wallet file: +What is your wallet decryption key? +``` + +Expected output: + +```json +{ + "difficulty": 1806884765625000 +} +``` + +The tool contacts configured peers and stops at the first peer that returns a readable difficulty response or a text error. + +## lookup_height + +Asks a configured node for its current chain height. + +Usage: + +```bash +./lookup_height +``` + +Interactive prompts: + +```text +Please enter the path to your wallet file: +What is your wallet decryption key? +``` + +Expected output: + +```json +{ + "height": 31445 +} +``` + +This is a quick way to confirm what height a reachable peer reports. + +## lookup_network_info + +Asks a configured node for a compact network status snapshot. + +Usage: + +```bash +./lookup_network_info +``` + +Interactive prompts: + +```text +Please enter the path to your wallet file: +What is your wallet decryption key? +``` + +Example output: + +```json +{ + "version": 1, + "network": "testnet", + "time": 1783657720, + "wallet_prefix": "cltc", + "height": 31445, + "next_block_difficulty": 1806884765625000, + "total_block_transactions": 31540, + "total_mempool_transactions": 2, + "largest_tx_fee": 100000000 +} +``` + +Fields: + +`version` + +The protocol/network info version returned by the peer. + +`network` + +The peer's configured network name, such as `testnet` or `mainnet`. + +`time` + +The peer's current UTC timestamp as a Unix timestamp. + +`wallet_prefix` + +The wallet suffix/prefix used by that network, such as `cltc`. + +`height` + +The peer's current chain height. + +`next_block_difficulty` + +The next block difficulty currently reported by the peer. + +`total_block_transactions` + +The number of transactions the peer reports from confirmed block data. + +`total_mempool_transactions` + +The number of transactions currently in the peer's mempool. + +`largest_tx_fee` + +The largest transaction fee currently known from the peer's mempool data. This value is raw atomic units. + +## lookup_node_time + +Asks a configured node for its current UTC time. + +Usage: + +```bash +./lookup_node_time +``` + +Interactive prompts: + +```text +Please enter the path to your wallet file: +What is your wallet decryption key? +``` + +Expected output: + +```json +{ + "timestamp": 1783657720, + "time": "04:28:40 UTC" +} +``` + +Use this to confirm that a node is responding and to compare node time against expected UTC time. Correct system time matters for block timestamps and transaction validation. + +## server_owner_block_ip + +Sends a signed request to block an IP address from the server-side connection layer. + +This is an administrative tool. It is intended for the node/server owner, not normal wallet users. The request signs the exact IP string with the selected wallet, then sends the signed payload to a configured peer. + +Usage: + +```bash +./server_owner_block_ip +``` + +Example: + +```bash +./server_owner_block_ip 203.0.113.10 +``` + +Interactive prompts: + +```text +Please enter the path to your wallet file: +What is your wallet decryption key? +``` + +The node returns a text response indicating whether the request was accepted or rejected. If no configured peer can be reached, the tool prints: + +```text +failed to connect +``` + +Use this carefully. Blocking the wrong IP may prevent a valid peer from connecting to the node receiving the request. + +## server_owner_unblock_ip + +Sends a signed request to remove a previously blocked IP address from the server-side connection layer. + +This is the administrative counterpart to `server_owner_block_ip`. + +Usage: + +```bash +./server_owner_unblock_ip +``` + +Example: + +```bash +./server_owner_unblock_ip 203.0.113.10 +``` + +Interactive prompts: + +```text +Please enter the path to your wallet file: +What is your wallet decryption key? +``` + +The node returns a text response indicating whether the request was accepted or rejected. If no configured peer can be reached, the tool prints: + +```text +failed to connect +```