Contractless/docs/WALLET_TOOLS.md

Wallet Tools

Contractless wallet tools create wallets, restore wallets, export private-key image backups, register wallet addresses with the network, and sign or verify messages.

This page also covers balance lookup helpers:

• lookup_local_balance
• lookup_remote_balance

On Windows, add .exe to each command name.

When a tool asks for a wallet path, image path, private-key path, or output directory, press <Tab> to search and auto-complete files and folders.

Private Key Images and Encryption Keys

Contractless wallets use a private key image as a backup format. This is original to Contractless: the wallet private key can be represented as image data, and that image data can be saved as a PNG backup.

A private key image is not enough by itself. To restore a wallet from a private key image, you also need the encryption/decryption key used to protect that image. Always back up both pieces:

• Store the private key image digitally in a safe location.
• Store the encryption/decryption key offline and securely.
• Do not store the image and the encryption/decryption key together.

If you lose the private key image, you may not be able to restore the wallet. If you lose the encryption/decryption key for the image, you may not be able to decrypt the image and recover the wallet.

The raw private key itself does not require the encryption/decryption key after it has been recovered. However, the raw private key can only be retrieved from wallet/image data with private_key_from_image. Treat the raw private key as the most sensitive form of the wallet: anyone who has it can recreate the wallet and sign as that address.

The normal wallet file is encrypted and opened with the wallet encryption/decryption key. If the node starts and the configured wallet file does not exist, the node can create a wallet automatically. These tools are for manual wallet creation, backup, restoration, registration, and message signing.

create_new_wallet

Creates a new encrypted wallet file at the requested path and filename.

Use this when you want to create a wallet manually instead of letting the node create one during startup.

Usage:

create_new_wallet <wallet_path> <wallet_filename>

Interactive prompts:

Please enter the path to your wallet file:
Please enter wallet filename:
Please enter your wallet encryption key, if you do not have a wallet yet, enter a new encryption key here:

The wallet_path is the folder where the wallet file should be created. The wallet_filename is the file name to write inside that folder.

The tool refuses to overwrite an existing wallet file. After creation, it prints the wallet display information, including the wallet address information.

recreate_wallet

Recreates an encrypted wallet file from a raw private key stored in a file.

Use this after recovering the raw private key with private_key_from_image, or when you already have the raw private key saved separately. This tool does not require the old wallet file. It uses the private key to rebuild the wallet file and asks for an encryption key for the rebuilt wallet/private-key image data.

Usage:

recreate_wallet <private_key_file> <output_wallet_file>

or:

recreate_wallet <private_key_file> <output_wallet_dir> <output_wallet_filename>

Interactive prompts:

Please enter the path to the file containing your wallet private key:
Please enter the directory path where the rebuilt wallet JSON should be written:
Please enter the filename for the rebuilt wallet JSON:
Please enter your encryption key:

The output is a rebuilt wallet JSON file. If a registered vanity address exists for the wallet, the tool attempts to include it in the rebuilt wallet file.

recreate_wallet_from_image

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

Use this when restoring from a private key image backup. The input can be a PNG image file or a file containing base64 image data. You must know the encryption/decryption key for that private key image.

Usage:

recreate_wallet_from_image <base64_or_png_file_path> <output_wallet_file>

or:

recreate_wallet_from_image <base64_or_png_file_path> <output_wallet_dir> <output_wallet_filename>

Interactive prompts:

Please enter the path to the Base64 or PNG image file:
Please enter the directory path where the rebuilt wallet JSON should be written:
Please enter the filename for the rebuilt wallet JSON:
Please enter your encryption key:

The output is a rebuilt wallet JSON file. If a registered vanity address exists for the wallet, the tool attempts to include it in the rebuilt wallet file.

save_private_key_image

Writes the wallet private key image data to a PNG file.

Use this to create a digital image backup from an existing wallet file or from a file that already contains private-key image data. This tool does not print the raw private key. It only writes the image backup.

Usage:

save_private_key_image <wallet_or_image_file> <output_png_path>

or:

save_private_key_image <wallet_or_image_file> <output_png_dir> <output_png_filename>

Interactive prompts:

Please enter the path to the wallet/image file:
Please enter the directory path where the PNG should be written:
Please enter the filename for the PNG:

The source file can be a wallet JSON file or a file containing base64 private-key image data. The output is a PNG file.

Remember: this PNG backup still needs the encryption/decryption key to restore the wallet.

private_key_from_image

Extracts the raw private key from wallet/image data.

Use this only when you truly need the raw private key, such as before using recreate_wallet. The tool reads wallet/image data, asks for the encryption/decryption key, decrypts the private-key image data, and prints the raw private key.

Usage:

private_key_from_image <wallet_or_image_data_file>

Interactive prompts:

Please enter the path to the file containing the wallet/image data:
Please enter your encryption key:

The input file can be a wallet JSON file or a file containing base64 private-key image data.

The printed private key does not require the encryption/decryption key after it has been recovered. Protect it carefully and do not leave it in terminal scrollback, screenshots, cloud notes, chat messages, or unsecured text files.

register_wallet

Registers the wallet with the network wallet registry.

Important: a wallet must be registered before it can receive funds or be used in any transaction. If the wallet is not registered, other nodes cannot validate the address and public key relationship needed for normal wallet activity.

Wallet registration submits a signed short-address to public-key mapping to a reachable peer. This lets other tools and nodes look up the wallet public key when they need to verify signatures for that address.

Usage:

register_wallet

Interactive prompts:

Please enter the path to your wallet file:
What is your wallet decryption key?

Expected success output:

Wallet registered: <short address>

Run this after creating or restoring a wallet if the address is not already registered with the network.

verify_address

Checks whether a directly pasted address is valid.

Use this to quickly test short addresses or vanity addresses before using them in a transaction or sharing them with someone else.

Usage:

verify_address <wallet_address>

Interactive prompt:

Please enter the wallet address:

Expected output:

true

or:

false

This command expects the address itself, not a path to a file containing the address.

create_vanity_tx

Creates and signs a vanity address registration transaction for the selected wallet.

A vanity address is a human-readable alias that maps back to the wallet's real short address. The vanity name is not a separate wallet and does not create a new private key. It is a registered address alias owned by the wallet that signs the transaction.

Usage:

create_vanity_tx <vanity_name> <txfee>

Interactive prompts:

Enter the vanity name to register (letters only, up to 20 characters):
Please enter the vanity registration fee: (e.g. 1.0, minimum fee 5.00000000):
Please enter the path to your wallet file:
What is your wallet decryption key?

Vanity name rules:

• 1 to 20 characters
• letters only
• no numbers
• no punctuation
• no spaces

The tool automatically lowercases the vanity address and appends the correct wallet/network suffix. For example, entering:

BruceBates

may create a vanity address like:

brucebates.cltc

The transaction fee is entered as a decimal amount. The minimum vanity registration fee is:

5.00000000

The tool saves the signed transaction JSON into:

./transactions/<transaction_hash>.json

Creating the file does not register the vanity address by itself. Broadcast the saved transaction with broadcast_transaction.

After the transaction confirms, tools that support address resolution can use the vanity address as an alias for the wallet's real short address.

sign_message

Signs a plain-text message with the selected wallet.

Use this to prove control of a wallet address without sending a transaction. The message text is hashed and then signed with the wallet private key.

Usage:

sign_message "<message to sign>"

Interactive prompts:

Please enter the path to your wallet file:
What is your wallet decryption key?

Expected output:

message: <message>, signature: <signature>

The exact message matters. If someone later verifies the signature, they must verify the same text.

verify_message

Verifies a message signature against a wallet address.

Use this when someone gives you a message, wallet address, and signature, and you want to confirm that the address signed that exact message.

Usage:

verify_message "<message to verify>" <wallet_address> <signature>

Interactive prompts:

Please enter the message to verify:
Please enter the wallet address:
Please enter the signature:
Please enter the path to your wallet file:
What is your wallet decryption key?

Expected output:

valid signature

or:

invalid signature

This command expects the wallet address and signature directly, not paths to files containing them. The tool uses the selected wallet to authenticate the network lookup needed to retrieve the public key for the address being checked.

lookup_local_balance

Reads a local balance file from disk and prints the stored balance as a decimal value.

This is a low-level local inspection tool. It does not ask a node for current wallet state, does not include mempool changes, and does not prove that the value is the current network balance. It simply decodes the first 8 bytes of a local balance file as a little-endian u64.

Usage:

lookup_local_balance <path/to/file.bal>

Interactive prompt:

Please enter the path to the balance file:

When entering the path interactively, press <Tab> to search and auto-complete files and folders.

Expected output:

{
  "balance": "123.45678900"
}

Use this mainly for debugging or manually inspecting local balance-sheet files.

lookup_remote_balance

Asks a configured node for all known asset balances for one wallet address.

Unlike lookup_local_balance, this is a network lookup. It contacts a peer, authenticates with the selected wallet, resolves short/long/vanity address input, and returns balances for the requested address.

Usage:

lookup_remote_balance <address_file>

Interactive prompts:

Please enter the path to the file containing the wallet address:
Please enter the path to your wallet file:
What is your wallet decryption key?

The address file may contain either:

• a plain wallet address
• a wallet JSON file containing short_address or vanity_address

When entering file paths interactively, press <Tab> to search and auto-complete files and folders.

Expected output:

{
  "balances": [
    {
      "asset": "CLTC",
      "nft_series": 0,
      "balance": "100.00000000"
    },
    {
      "asset": "testcoin",
      "nft_series": 0,
      "balance": "25.00000000"
    }
  ]
}

asset is the base coin, token, or NFT asset name.

nft_series is 0 for normal base-coin/token balances and 1-of-1 NFTs. For numbered NFT collections, it identifies the numbered item.

balance is displayed with 8 decimal places.