Contractless/docs/OTHER_TOOLS.md

# 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 `<Tab>` 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 <start_block> <stop_block> <directory>
```

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 <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 <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
```