contractless
/
Contractless
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity
Contractless/docs/CLI_TOOLS.md

1336 lines
17 KiB
Markdown
Raw Blame History

# 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>
```
Reference in New Issue View Git Blame Copy Permalink