Account Management

Managing accounts and wallets in Viction

Overview

Viction uses keystore-based account management with encrypted JSON files stored according to the Web3 Secret Storage specification. Account operations are performed through the tomo account command.

Keys are stored under <DATADIR>/keystore. Never share your private keys or keystore files. Make sure you backup your keys regularly.

Account Commands

All account operations are accessed through the tomo account subcommand:

tomo account <command> [options]

List Accounts

Print a summary of all existing accounts:

tomo account list [--datadir <path>] [--keystore <path>]

Options:

• --datadir: Data directory for the databases and keystore
• --keystore: Directory for the keystore (default: <datadir>/keystore)

Example output:

Account #0: {0x1234...5678} keystore:///path/to/keystore/UTC--2024-01-01T00-00-00.000000000Z--1234...5678
Account #1: {0xabcd...ef01} keystore:///path/to/keystore/UTC--2024-01-02T00-00-00.000000000Z--abcd...ef01

Create New Account

Create a new account and save it to the keystore:

tomo account new [options]

Options:

• --datadir: Data directory for the databases and keystore
• --keystore: Directory for the keystore
• --password: Password file for non-interactive mode
• --lightkdf: Reduce KDF memory & CPU usage at expense of security

Interactive example:

tomo account new

You’ll be prompted to enter and confirm a passphrase:

Your new account is locked with a password. Please give a password. Do not forget this password.
Passphrase: 
Repeat passphrase: 
Address: {0x1234567890abcdef1234567890abcdef12345678}

You must remember the passphrase to unlock your account. Without it, you cannot access your account. There is no password recovery mechanism.

Non-interactive example:

echo "my-secure-password" > password.txt
tomo account new --password password.txt

Update Account Password

Update an existing account’s password:

tomo account update <address> [options]

Options:

• --datadir: Data directory for the databases and keystore
• --keystore: Directory for the keystore
• --lightkdf: Reduce KDF memory & CPU usage

Example:

tomo account update 0x1234567890abcdef1234567890abcdef12345678

You’ll be prompted for the old password and then for a new password:

Unlocking account 0x1234567890abcdef1234567890abcdef12345678 | Attempt 1/3
Passphrase: 
Please give a new password. Do not forget this password.
Passphrase: 
Repeat passphrase: 

Import Private Key

Import an unencrypted private key into a new account:

tomo account import <keyfile> [options]

Options:

• --datadir: Data directory for the databases and keystore
• --keystore: Directory for the keystore
• --password: Password file for non-interactive mode
• --lightkdf: Reduce KDF memory & CPU usage

Example:

tomo account import ./my-private-key.txt

The keyfile should contain an unencrypted private key in hexadecimal format.

The private key file should be in plain hexadecimal format. After importing, delete the original unencrypted key file securely. Never expose private keys.

Example keyfile format:

1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

Wallet Commands

Import Presale Wallet

Import an Ethereum presale wallet:

tomo wallet import <keyfile> [options]

Options:

• --datadir: Data directory for the databases and keystore
• --keystore: Directory for the keystore
• --password: Password file for non-interactive mode
• --lightkdf: Reduce KDF memory & CPU usage

Account Unlocking

Accounts can be unlocked when starting the node to enable automatic signing:

tomo --unlock <address> --password <passwordfile>

Example:

tomo --unlock 0x1234567890abcdef1234567890abcdef12345678 --password password.txt

To unlock multiple accounts:

tomo --unlock "0x1234...,0x5678..." --password password.txt

Unlocking accounts on production nodes exposes them to potential security risks. Only unlock accounts when necessary and ensure proper network security measures are in place.

Keystore Location

By default, keystores are located at:

• Linux/macOS: ~/.ethereum/keystore
• Custom: Specify with --keystore flag or --datadir flag

Keystore Security

Keystores use scrypt key derivation function (KDF) for encryption:

Standard KDF (Recommended)

Provides strong security with higher memory and CPU requirements:

tomo account new

Lightweight KDF

Reduces memory/CPU usage but provides less security:

tomo account new --lightkdf

Lightweight KDF is only recommended for testing. Always use standard KDF for production accounts containing real value.

Account Errors

Common account-related errors:

ErrLocked

Error: password or unlock

Cause: Account is locked and requires authentication

Solution: Unlock the account with the correct password

ErrDecrypt

Error: could not decrypt key with given passphrase

Cause: Incorrect password provided

Solution: Verify you’re using the correct passphrase for the account

ErrNoMatch

Error: no key for given address or file

Cause: Account address not found in keystore

Solution: Verify the address is correct and the keystore path is properly configured

Ambiguous Address Error

Multiple key files exist for the same address. The system will test your passphrase against all matching files and identify duplicates to remove.

Best Practices

1. Backup Your Keys: Regularly backup your keystore directory
2. Strong Passphrases: Use long, complex passphrases with mixed characters
3. Secure Storage: Keep backups in multiple secure, offline locations
4. Test Restores: Verify backups work before relying on them
5. Separate Accounts: Use different accounts for different purposes
6. Hardware Wallets: Consider hardware wallets for large amounts
7. Key Rotation: Update passwords periodically using account update

Account Transfer

You can safely transfer accounts between Viction nodes by copying the keystore files:

cp ~/.ethereum/keystore/UTC--* /path/to/new/node/keystore/

The entire keystore directory or individual key files can be transferred.