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.

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:

```text
create_new_wallet <wallet_path> <wallet_filename>
```

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 <private_key_file> <output_wallet_file>
```

or:

```text
recreate_wallet <private_key_file> <output_wallet_dir> <output_wallet_filename>
```

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 <base64_or_png_file_path> <output_wallet_file>
```

or:

```text
recreate_wallet_from_image <base64_or_png_file_path> <output_wallet_dir> <output_wallet_filename>
```

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 <wallet_or_image_file> <output_png_path>
```

or:

```text
save_private_key_image <wallet_or_image_file> <output_png_dir> <output_png_filename>
```

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 <wallet_or_image_data_file>
```

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

```text
verify_address <wallet_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 "<message to sign>"
```

Interactive prompts:

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

Expected output:

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

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

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.