Contractless/docs/CLI_TOOLS.md

# Contractless CLI Tools

This file lists the command-line tools built from `src/bin`. On Windows, add `.exe` to each tool name. Most network lookup tools prompt for the wallet decryption key because the RPC handshake is authenticated before the request is sent.

Transaction creator tools produce signed transaction JSON. After creating a transaction, broadcast it with `broadcast_transaction`.

## Table of Contents

- [Wallet Tools](#wallet-tools)
- [Transaction Creation Tools](#transaction-creation-tools)
- [Transaction Signing Tools](#transaction-signing-tools)
- [Lookup Tools](#lookup-tools)
- [Server Owner Tools](#server-owner-tools)
- [Block and Torrent Tools](#block-and-torrent-tools)
- [Utility Tools](#utility-tools)

## Wallet Tools

### create_new_wallet

Creates or loads an encrypted wallet file at the requested path.

Requires:

- Running node: No
- Wallet key: Yes
- Writes file: Yes

Usage:

```text
create_new_wallet <wallet_path> <wallet_filename>
```

Expected reply:

```text
Long Address: <long wallet address>
Short Address: <short wallet address>
Vanity Address: <optional vanity address>
Public Key: <public key>
```

### register_wallet

Registers the configured wallet short-address to long-address mapping with a peer.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
register_wallet
```

Expected reply:

```text
Wallet registered: <short address>
```

or:

```text
Wallet registration failed.
```

### recreate_wallet

Recreates an encrypted wallet file from a private key.

Requires:

- Running node: No
- Wallet key: Yes
- Writes file: Yes

Usage:

```text
recreate_wallet
```

Expected reply:

```text
<recreated wallet display>
```

### recreate_wallet_from_image

Recreates an encrypted wallet file from a private-key image.

Requires:

- Running node: No
- Wallet key: Yes
- Writes file: Yes

Usage:

```text
recreate_wallet_from_image
```

Expected reply:

```text
<recreated wallet display>
```

### save_private_key_image

Saves the wallet private key into an image file for offline backup.

Requires:

- Running node: No
- Wallet key: Yes
- Writes file: Yes

Usage:

```text
save_private_key_image
```

Expected reply:

```text
Private key image saved to <path>
```

### private_key_from_image

Reads a private key back from an image file.

Requires:

- Running node: No
- Wallet key: No
- Writes file: No

Usage:

```text
private_key_from_image
```

Expected reply:

```text
<private key>
```

### contractless-submit-key

Submits the wallet decryption key to the Windows service process. This tool is Windows-only.

Requires:

- Running node: Windows service
- Wallet key: Yes
- Writes file: No

Usage:

```text
contractless-submit-key
contractless-submit-key ping
contractless-submit-key status
```

Expected reply:

```text
Wallet key accepted.
```

or:

```text
Pong
```

or:

```text
Service state: <state>
```

## Transaction Creation Tools

These tools prompt for the fields needed by each transaction type, sign the transaction with the configured wallet and print the signed JSON. The same JSON is also written to the transaction output folder when the tool creates the output file successfully.

### create_transfer_tx

Creates a transfer transaction for base currency, tokens or NFTs.

Requires:

- Running node: No
- Wallet key: Yes
- Writes file: Yes

Usage:

```text
create_transfer_tx
```

Expected reply:

```text
transaction: <signed transfer transaction json>
```

### create_tokens_tx

Creates a token definition transaction.

Requires:

- Running node: No
- Wallet key: Yes
- Writes file: Yes

Usage:

```text
create_tokens_tx
```

Expected reply:

```text
transaction: <signed create-token transaction json>
```

### create_issue_token_tx

Creates an issue-token transaction for an existing token.

Requires:

- Running node: No
- Wallet key: Yes
- Writes file: Yes

Usage:

```text
create_issue_token_tx
```

Expected reply:

```text
transaction: <signed issue-token transaction json>
```

### create_nft_tx

Creates an NFT transaction.

Requires:

- Running node: No
- Wallet key: Yes
- Writes file: Yes

Usage:

```text
create_nft_tx
```

Expected reply:

```text
transaction: <signed NFT transaction json>
```

### create_burn_tx

Creates a burn transaction. Base currency cannot be burned with this transaction type.

Requires:

- Running node: No
- Wallet key: Yes
- Writes file: Yes

Usage:

```text
create_burn_tx
```

Expected reply:

```text
transaction: <signed burn transaction json>
```

### create_marketing_tx

Creates a marketing transaction.

Requires:

- Running node: No
- Wallet key: Yes
- Writes file: Yes

Usage:

```text
create_marketing_tx
```

Expected reply:

```text
transaction: <signed marketing transaction json>
```

### create_vanity_tx

Creates a vanity-address registration transaction. The vanity address is registered on chain, while normal block records continue using the real short address.

Requires:

- Running node: No
- Wallet key: Yes
- Writes file: Yes

Usage:

```text
create_vanity_tx
```

Expected reply:

```text
transaction: <signed vanity-address transaction json>
```

### create_swap_tx

Creates the first side of a swap transaction. The second party signs the transaction with `verify_sign_swap_tx`.

Requires:

- Running node: No
- Wallet key: Yes
- Writes file: Yes

Usage:

```text
create_swap_tx
```

Expected reply:

```text
transaction: <partially signed swap transaction json>
```

### create_loan_tx

Creates the first side of a loan contract transaction. The second party signs the transaction with `verify_sign_loan_tx`.

Requires:

- Running node: No
- Wallet key: Yes
- Writes file: Yes

Usage:

```text
create_loan_tx
```

Expected reply:

```text
transaction: <partially signed loan transaction json>
```

### create_loan_payment_tx

Creates a loan payment transaction for an existing loan contract.

Requires:

- Running node: No
- Wallet key: Yes
- Writes file: Yes

Usage:

```text
create_loan_payment_tx
```

Expected reply:

```text
transaction: <signed loan-payment transaction json>
```

### create_collateral_claim_tx

Creates a collateral claim transaction for an eligible loan contract.

Requires:

- Running node: No
- Wallet key: Yes
- Writes file: Yes

Usage:

```text
create_collateral_claim_tx
```

Expected reply:

```text
transaction: <signed collateral-claim transaction json>
```

### broadcast_transaction

Broadcasts one signed transaction JSON file to the network.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: Only when a successful vanity transaction updates the saved wallet display

Usage:

```text
broadcast_transaction <hash.json>
```

Expected reply:

```text
successful_broadcast: true
<transaction hash>
```

or:

```text
<error returned by peer>
```

## Transaction Signing Tools

### verify_sign_swap_tx

Validates and signs the second side of a swap transaction JSON file.

Requires:

- Running node: No
- Wallet key: Yes
- Writes file: Yes

Usage:

```text
verify_sign_swap_tx <path/to/file.json>
```

Expected reply:

```text
Transaction: <fully signed swap transaction json>
```

### verify_sign_loan_tx

Validates and signs the second side of a loan transaction JSON file.

Requires:

- Running node: No
- Wallet key: Yes
- Writes file: Yes

Usage:

```text
verify_sign_loan_tx <path/to/file.json>
```

Expected reply:

```text
Transaction: <fully signed loan transaction json>
```

## Lookup Tools

Network lookup tools send binary RPC requests to a peer. Some tools print decoded JSON for readability, but JSON is not sent across the TCP stream.

### lookup_network_info

Returns a summary of the connected peer state.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_network_info
```

Expected reply:

```json
{
  "version": 1,
  "network": "testnet",
  "time": 1234567890,
  "wallet_prefix": "CLTC",
  "height": 5,
  "next_block_difficulty": 1183350000000000,
  "total_block_transactions": 6,
  "total_mempool_transactions": 0,
  "largest_tx_fee": 0
}
```

### lookup_node_time

Returns the peer timestamp as a Unix timestamp and UTC time string.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_node_time
```

Expected reply:

```text
timestamp: 1234567890
time: 2009-02-13 23:31:30 UTC
```

### lookup_height

Returns the connected peer chain height.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_height
```

Expected reply:

```text
123
```

### lookup_difficulty

Returns the next block difficulty reported by the peer.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_difficulty
```

Expected reply:

```text
1183350000000000
```

### lookup_largest_txfee

Returns the largest transaction fee currently available for miner selection.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_largest_txfee
```

Expected reply:

```text
1.00000000
```

### lookup_block_by_height

Looks up a block by height.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_block_by_height <block_number>
```

Expected reply:

```json
{
  "block": "<decoded block data>"
}
```

### lookup_block_by_hash

Looks up a block by its 64-character block hash.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_block_by_hash <block_hash>
```

Expected reply:

```json
{
  "block": "<decoded block data>"
}
```

### lookup_transaction

Looks up a transaction by transaction hash.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_transaction <transaction_hash>
```

Expected reply:

```json
{
  "transaction": "<decoded transaction data>"
}
```

### lookup_total_transactions

Returns total transaction counts by transaction category.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_total_transactions
```

Expected reply:

```json
[
  {
    "transaction_type": "<type>",
    "count": 0
  }
]
```

### lookup_token

Looks up one token by token name.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_token <token_name>
```

Expected reply:

```json
{
  "token": "<decoded token data>"
}
```

### lookup_token_list

Returns the token list from the connected peer.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_token_list
```

Expected reply:

```json
[
  "<token name>"
]
```

### lookup_nft

Looks up one NFT. Use item number `0` for a 1/1 NFT.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_nft <nft_name> <item_number>
```

Expected reply:

```json
{
  "nft": "<decoded NFT data>"
}
```

### lookup_nft_list

Returns the NFT list from the connected peer.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_nft_list
```

Expected reply:

```json
[
  "<nft name>"
]
```

### lookup_contract_by_hash

Looks up a loan contract by contract hash.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_contract_by_hash <contract_hash>
```

Expected reply:

```text
<contract data or peer error>
```

### lookup_contract_by_address

Looks up loan contracts by wallet address.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_contract_by_address <wallet_address>
```

Expected reply:

```text
<contract data or peer error>
```

### lookup_remote_balance

Looks up the network balance sheet for an address file.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_remote_balance <address_file>
```

Expected reply:

```text
CLC = 100.00000000
TOKEN = 50.00000000
NFT:1 = 1.00000000
```

or:

```text
[]
```

### lookup_local_balance

Reads and prints a local balance sheet file directly.

Requires:

- Running node: No
- Wallet key: No
- Writes file: No

Usage:

```text
lookup_local_balance <path/to/file.bal>
```

Expected reply:

```text
100.00000000
```

### lookup_mempool_tx_count

Returns the number of transactions currently in the peer mempool records.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_mempool_tx_count
```

Expected reply:

```text
0
```

### lookup_mempool_tx_by_signature

Looks up one mempool transaction by signature.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_mempool_tx_by_signature <signature>
```

Expected reply:

```json
{
  "transaction": "<decoded mempool transaction>"
}
```

or:

```text
Transaction not found in mempool.
```

### lookup_mempool_tx_by_address

Looks up mempool transactions by wallet address.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_mempool_tx_by_address <wallet_address>
```

Expected reply:

```json
[
  {
    "transaction": "<decoded mempool transaction>"
  }
]
```

or:

```text
[]
```

### lookup_torrent

Looks up torrent metadata by block height.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
lookup_torrent <block_number>
```

Expected reply:

```json
{
  "torrent": "<decoded torrent metadata>"
}
```

## Server Owner Tools

These tools are meant for the node operator. They send owner-style RPC commands to the configured peer.

### server_owner_block_ip

Blocks an IP address.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
server_owner_block_ip <ip_address>
```

Expected reply:

```text
<peer confirmation or peer error>
```

### server_owner_unblock_ip

Unblocks an IP address.

Requires:

- Running node: Reachable peer
- Wallet key: Yes
- Writes file: No

Usage:

```text
server_owner_unblock_ip <ip_address>
```

Expected reply:

```text
<peer confirmation or peer error>
```

## Block and Torrent Tools

These tools inspect local block or torrent files. They do not ask the network for data unless the tool name starts with `lookup_`.

### average_block_time_checker

Calculates the average time between local block files in a block range.

Requires:

- Running node: No
- Wallet key: No
- Writes file: No

Usage:

```text
average_block_time_checker <start_block> <stop_block> <directory>
```

Expected reply:

```text
Average time difference between blocks <start> and <stop>: <seconds> seconds
```

### unpack_block_header

Reads a local block file and prints the decoded block header.

Requires:

- Running node: No
- Wallet key: No
- Writes file: No

Usage:

```text
unpack_block_header <block_number>
```

Expected reply:

```json
{
  "header": "<decoded block header>"
}
```

### unpack_torrent

Reads a local torrent file and prints decoded torrent metadata.

Requires:

- Running node: No
- Wallet key: No
- Writes file: No

Usage:

```text
unpack_torrent <block_number>
```

Expected reply:

```json
{
  "announce": "<peer address>",
  "info": "<torrent info>"
}
```

### validate_torrent_and_block_headers

Compares a local torrent file against the matching local block file and prints each validation check.

Requires:

- Running node: No
- Wallet key: No
- Writes file: No

Usage:

```text
validate_torrent_and_block_headers <block_number>
```

Expected reply:

```text
timestamp match: passed
nonce match: passed
wallet address match: passed
block difficulty check: passed
VRF match: passed
file size check: passed
block header hash check: passed
VRF validation check: passed
VRF Proof check: passed
piece 0 hash check: passed
block hash check: passed

Block <block_number> fully validated.
```

## Utility Tools

### postgres_installer

Installs or configures PostgreSQL and prints settings values for `settings.ini`.

Requires:

- Running node: No
- Wallet key: No
- Writes file: May install or configure PostgreSQL

Usage:

```text
postgres_installer
```

Expected reply:

```ini
[Postgres]
host = 127.0.0.1
port = 5432
user = contractless
password = <password>
dbname = contractless_db
```

On Windows, the tool also prints `[Postgres-Testnet]`.

### sign_message

Signs a plain text message with the configured wallet.

Requires:

- Running node: No
- Wallet key: Yes
- Writes file: Yes

Usage:

```text
sign_message "<message to sign>"
```

Expected reply:

```text
message: <message>, signature: <signature>
```

### verify_message

Verifies a signed message using an address file and signature file.

Requires:

- Running node: No
- Wallet key: No
- Writes file: No

Usage:

```text
verify_message "<message to verify>" <address_file> <signature_file>
```

Expected reply:

```text
valid signature
```

or:

```text
invalid signature
```

### verify_address

Verifies an address file and prints the message hash used by the verification flow.

Requires:

- Running node: No
- Wallet key: No
- Writes file: No

Usage:

```text
verify_address <address_file>
```

Expected reply:

```text
<message hash>
```

### skein_hasher

Hashes text, an entire file or a byte range from a file.

Requires:

- Running node: No
- Wallet key: No
- Writes file: No

Usage:

```text
skein_hasher text large|small <value>
skein_hasher file large|small <file_path>
skein_hasher bytes large|small <start_byte> <stop_byte> <file_path>
```

Expected reply:

```text
Hash of text '<value>': <hash>
```

or:

```text
Hash of file <hash>
```

or:

```text
Hash of bytes <start_byte> through <stop_byte> of file '<file_path>': <hash>
```