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 and save it under `./transactions/` using the transaction hash as the filename. Creating a transaction does not submit it to the network; broadcast the saved JSON 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 a new 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
Short Address: <short wallet address>
Public Key: <public key>
```

### register_wallet

Registers the wallet with the network. Registration is required before an address can be used.

Requires:

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

Usage:

```text
register_wallet
```

Expected reply:

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

### recreate_wallet

Recreates an encrypted wallet file from a private key. The private key must be obtained with `private_key_from_image`. You must also know the encryption/decryption key used when the wallet was originally created.

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. The image can be a base64 image file or a PNG image file. A base64 image must be stored in a standalone file, not inside the wallet file. You must also know the encryption/decryption key used when the wallet was originally created.

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 a wallet file or base64 image file. This tool does not read private keys from PNG saved images.

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 selected wallet, print the signed JSON and write the same JSON to `./transactions/<transaction_hash>.json`. The transaction is not sent to the network until the saved JSON is submitted with `broadcast_transaction`.

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

Issues more units of an existing token. This can only be used by the token creator, and only when the token was originally created without a hard cap that prevents further issuance.

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

The lender creates this transaction. The tool asks for:

- Loan coin/token: the asset being lent.
- Loan amount: how much of that asset is lent.
- Payment period: `daily`, `weekly` or `monthly`; this sets the payment cadence.
- Payment number: how many payments are required before the loan is considered paid.
- Payment amount: how much the borrower must pay each period.
- Grace period: how many payments may be missed before collateral can be claimed.
- Max late value: how far behind the borrower may be, in payment value, before collateral can be claimed.
- Collateral coin/token/NFT: the asset the borrower puts up as collateral.
- Collateral amount: how much collateral is required; enter `1` for NFT collateral.
- Start date: the date the loan begins, entered as `YYYY-MM-DD`.
- Borrower wallet: the borrower's short address or vanity address.
- Transaction fee: the base-currency fee paid by the lender.

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.

The borrower uses this after the loan contract is active. The tool asks for:

- Loan contract hash: the hash of the loan contract being repaid.
- Payment amount: the amount being paid toward the loan.
- Miner tip: a tip in the loan asset; it must be at least 1% of the payment amount.
- Transaction fee: the base-currency fee paid by the borrower.

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.

The lender uses this when the loan rules allow collateral to be claimed. The tool asks for:

- Loan contract hash: the hash of the loan contract whose collateral is being claimed.
- Transaction fee: the base-currency fee paid by the claimant.

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

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