From 23e165713a7f986420f0dcd5d15af2ca322e1072 Mon Sep 17 00:00:00 2001 From: contractless Date: Sun, 12 Jul 2026 20:17:54 +0000 Subject: [PATCH] Delete docs/CLI_TOOLS.md --- docs/CLI_TOOLS.md | 1356 --------------------------------------------- 1 file changed, 1356 deletions(-) delete mode 100644 docs/CLI_TOOLS.md diff --git a/docs/CLI_TOOLS.md b/docs/CLI_TOOLS.md deleted file mode 100644 index 96bbefc..0000000 --- a/docs/CLI_TOOLS.md +++ /dev/null @@ -1,1356 +0,0 @@ -# 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 -``` - -Expected reply: - -```text -Short Address: -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: -``` - -### 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 - -``` - -### 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 - -``` - -### 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 -``` - -### 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 - -``` - -### 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: -``` - -## 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/.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: -``` - -### 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: -``` - -### 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: -``` - -### 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: -``` - -### 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: -``` - -### 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: -``` - -### 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: -``` - -### 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: -``` - -### 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: -``` - -### 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: -``` - -### 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: -``` - -### 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 -``` - -Expected reply: - -```text -successful_broadcast: true - -``` - -## 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 -``` - -Expected reply: - -```text -Transaction: -``` - -### 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 -``` - -Expected reply: - -```text -Transaction: -``` - -## 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 -``` - -Expected reply: - -```json -{ - "block": "" -} -``` - -### 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 -``` - -Expected reply: - -```json -{ - "block": "" -} -``` - -### lookup_transaction - -Looks up a transaction by transaction hash. - -Requires: - -- Running node: Reachable peer -- Wallet key: Yes -- Writes file: No - -Usage: - -```text -lookup_transaction -``` - -Expected reply: - -```json -{ - "transaction": "" -} -``` - -### 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": "", - "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 -``` - -Expected reply: - -```json -{ - "token": "" -} -``` - -### 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 -[ - "" -] -``` - -### 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 -``` - -Expected reply: - -```json -{ - "nft": "" -} -``` - -### 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 -[ - "" -] -``` - -### lookup_loan_by_hash - -Looks up a loan contract by contract hash. - -Requires: - -- Running node: Reachable peer -- Wallet key: Yes -- Writes file: No - -Usage: - -```text -lookup_loan_by_hash -``` - -Expected reply: - -```json -{ - "contract": "", - "status": "active", - "payments": [] -} -``` - -### lookup_loan_by_address - -Looks up loan contracts by wallet address. - -Requires: - -- Running node: Reachable peer -- Wallet key: Yes -- Writes file: No - -Usage: - -```text -lookup_loan_by_address -``` - -Expected reply: - -```json -{ - "address": "", - "contracts": 1, - "loans": [] -} -``` - -### 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 -``` - -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 -``` - -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 -``` - -Expected reply: - -```json -{ - "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 -``` - -Expected reply: - -```json -[ - { - "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 -``` - -Expected reply: - -```json -{ - "torrent": "" -} -``` - -## 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 -``` - -Expected reply: - -```text - -``` - -### 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 -``` - -Expected reply: - -```text - -``` - -## 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 -``` - -Expected reply: - -```text -Average time difference between blocks and : 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 -``` - -Expected reply: - -```json -{ - "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 -``` - -Expected reply: - -```json -{ - "announce": "", - "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 -``` - -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 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 = -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 "" -``` - -Expected reply: - -```text -message: , 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 "" -``` - -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 -``` - -Expected reply: - -```text - -``` - -### 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 -skein_hasher file large|small -skein_hasher bytes large|small -``` - -Expected reply: - -```text -Hash of text '': -``` - -or: - -```text -Hash of file -``` - -or: - -```text -Hash of bytes through of file '': -```