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

17 KiB
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

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:

create_new_wallet <wallet_path> <wallet_filename>

Expected reply:

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:

register_wallet

Expected reply:

Wallet registered: <short address>

or:

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:

recreate_wallet

Expected reply:

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

recreate_wallet_from_image

Expected reply:

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

save_private_key_image

Expected reply:

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:

private_key_from_image

Expected reply:

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

contractless-submit-key
contractless-submit-key ping
contractless-submit-key status

Expected reply:

Wallet key accepted.

or:

Pong

or:

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:

create_transfer_tx

Expected reply:

transaction: <signed transfer transaction json>

create_tokens_tx

Creates a token definition transaction.

Requires:

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

Usage:

create_tokens_tx

Expected reply:

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:

create_issue_token_tx

Expected reply:

transaction: <signed issue-token transaction json>

create_nft_tx

Creates an NFT transaction.

Requires:

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

Usage:

create_nft_tx

Expected reply:

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:

create_burn_tx

Expected reply:

transaction: <signed burn transaction json>

create_marketing_tx

Creates a marketing transaction.

Requires:

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

Usage:

create_marketing_tx

Expected reply:

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:

create_vanity_tx

Expected reply:

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:

create_swap_tx

Expected reply:

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:

create_loan_tx

Expected reply:

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:

create_loan_payment_tx

Expected reply:

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:

create_collateral_claim_tx

Expected reply:

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:

broadcast_transaction <hash.json>

Expected reply:

successful_broadcast: true
<transaction hash>

or:

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

verify_sign_swap_tx <path/to/file.json>

Expected reply:

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:

verify_sign_loan_tx <path/to/file.json>

Expected reply:

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:

lookup_network_info

Expected reply:

{
  "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:

lookup_node_time

Expected reply:

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:

lookup_height

Expected reply:

123

lookup_difficulty

Returns the next block difficulty reported by the peer.

Requires:

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

Usage:

lookup_difficulty

Expected reply:

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:

lookup_largest_txfee

Expected reply:

1.00000000

lookup_block_by_height

Looks up a block by height.

Requires:

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

Usage:

lookup_block_by_height <block_number>

Expected reply:

{
  "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:

lookup_block_by_hash <block_hash>

Expected reply:

{
  "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:

lookup_transaction <transaction_hash>

Expected reply:

{
  "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:

lookup_total_transactions

Expected reply:

[
  {
    "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:

lookup_token <token_name>

Expected reply:

{
  "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:

lookup_token_list

Expected reply:

[
  "<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:

lookup_nft <nft_name> <item_number>

Expected reply:

{
  "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:

lookup_nft_list

Expected reply:

[
  "<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:

lookup_contract_by_hash <contract_hash>

Expected reply:

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

lookup_contract_by_address <wallet_address>

Expected reply:

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

lookup_remote_balance <address_file>

Expected reply:

CLC = 100.00000000
TOKEN = 50.00000000
NFT:1 = 1.00000000

or:

[]

lookup_local_balance

Reads and prints a local balance sheet file directly.

Requires:

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

Usage:

lookup_local_balance <path/to/file.bal>

Expected reply:

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:

lookup_mempool_tx_count

Expected reply:

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:

lookup_mempool_tx_by_signature <signature>

Expected reply:

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

or:

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:

lookup_mempool_tx_by_address <wallet_address>

Expected reply:

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

or:

[]

lookup_torrent

Looks up torrent metadata by block height.

Requires:

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

Usage:

lookup_torrent <block_number>

Expected reply:

{
  "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:

server_owner_block_ip <ip_address>

Expected reply:

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

server_owner_unblock_ip <ip_address>

Expected reply:

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

average_block_time_checker <start_block> <stop_block> <directory>

Expected reply:

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:

unpack_block_header <block_number>

Expected reply:

{
  "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:

unpack_torrent <block_number>

Expected reply:

{
  "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:

validate_torrent_and_block_headers <block_number>

Expected reply:

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:

postgres_installer

Expected reply:

[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:

sign_message "<message to sign>"

Expected reply:

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:

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

Expected reply:

valid signature

or:

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:

verify_address <address_file>

Expected reply:

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

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:

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

or:

Hash of file <hash>

or:

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