From 3b0fca08971617757f15d47b87864bfe66811a12 Mon Sep 17 00:00:00 2001 From: contractless Date: Sun, 12 Jul 2026 17:06:44 +0000 Subject: [PATCH] Add docs/WALLET_TOOLS.md --- docs/WALLET_TOOLS.md | 283 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 283 insertions(+) create mode 100644 docs/WALLET_TOOLS.md diff --git a/docs/WALLET_TOOLS.md b/docs/WALLET_TOOLS.md new file mode 100644 index 0000000..5af3f7d --- /dev/null +++ b/docs/WALLET_TOOLS.md @@ -0,0 +1,283 @@ +# 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. + +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 `` 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: + +```text +create_new_wallet +``` + +Interactive prompts: + +```text +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: + +```text +recreate_wallet +``` + +or: + +```text +recreate_wallet +``` + +Interactive prompts: + +```text +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: + +```text +recreate_wallet_from_image +``` + +or: + +```text +recreate_wallet_from_image +``` + +Interactive prompts: + +```text +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: + +```text +save_private_key_image +``` + +or: + +```text +save_private_key_image +``` + +Interactive prompts: + +```text +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: + +```text +private_key_from_image +``` + +Interactive prompts: + +```text +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: + +```text +register_wallet +``` + +Interactive prompts: + +```text +Please enter the path to your wallet file: +What is your wallet decryption key? +``` + +Expected success output: + +```text +Wallet registered: +``` + +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: + +```text +verify_address +``` + +Interactive prompt: + +```text +Please enter the wallet address: +``` + +Expected output: + +```text +true +``` + +or: + +```text +false +``` + +This command expects the address itself, not a path to a file containing the 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: + +```text +sign_message "" +``` + +Interactive prompts: + +```text +Please enter the path to your wallet file: +What is your wallet decryption key? +``` + +Expected output: + +```text +message: , 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: + +```text +verify_message "" +``` + +Interactive prompts: + +```text +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: + +```text +valid signature +``` + +or: + +```text +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. +