EOS Private Chain Setup: Node, Wallet, Keys, and Account

This guide provides a step-by-step walkthrough for setting up a private EOS blockchain, creating wallets, importing keys, and managing accounts using EOS V1.0.5. It assumes you have already compiled the EOS source code successfully.

Core Concepts in EOS

EOSIO Software Components

The EOSIO software suite consists of several key modules that work together:

• nodeos: The core EOSIO node daemon. It runs in the background and can be configured with various plugins to enable different functionalities like API access and wallet management.
• cleos: A command-line interface (CLI) tool used to interact with the blockchain and manage wallets. It sends commands to nodeos and keosd.
• keosd: A secure wallet manager that handles key storage and signing operations. It typically runs locally and is often started automatically by cleos.

These components form the backbone of interacting with an EOS network, whether it's a private testnet or the public mainnet.

Understanding Wallets, Keys, and Accounts

To effectively use EOS, it's crucial to understand the relationship between its core elements. Here’s a breakdown using a simple analogy:

• Wallet: Think of a wallet as a secure keychain owned by a landlord. A single node (your local machine) can hold multiple wallets, just as a city has many landlords. Each wallet is a secure file that stores cryptographic keys.
• Keys: These are the actual tools for access. A cryptographic key pair consists of a public key (like your bank account number, which you can share) and a private key (like your ATM PIN, which must be kept secret). You import a private key into a wallet to gain the ability to sign transactions for the associated accounts.

• Account: An account is like a specific house or property. An account is created on the blockchain and is controlled by keys. Importantly, an EOS account has two permission levels, each with its own key pair:

  • Owner Permission: This is the master key, representing ultimate ownership. It should be kept extremely secure and used rarely, typically only for recovering the account.
  • Active Permission: This key is used for daily operations like transferring funds, voting, and deploying contracts. It's the key you use regularly.

You can create powerful and secure setups by understanding how wallets hold keys that control the permissions of on-chain accounts.

Step-by-Step Setup Guide

Starting the Private Chain

The first step is to launch the necessary services for your private blockchain.

1. Launch keosd (Wallet Manager)

Open a terminal and start the wallet manager, specifying the HTTP server address.

keosd --http-server-address=127.0.0.1:8900

A successful startup will show a list of initialized API endpoints. By default, keosd stores wallet files in the ~/eosio-wallet directory.

2. Launch nodeos (Blockchain Node)

Open a new terminal window to start your private blockchain node.

cd ~/eos/build/programs/nodeos
./nodeos -e -p eosio --plugin eosio::wallet_plugin --plugin eosio::chain_api_plugin --plugin eosio::history_api_plugin --replay-blockchain

Key Parameters Explained:

• -e: Enables block production even on a stale chain (essential for a single-node private chain).
• -p eosio: Specifies the block producer name (using the default eosio account).
• --plugin: Loads essential plugins for wallet, chain, and history API functionality.
• --replay-blockchain: Rebuilds the chain state from the block log. If you encounter a "database dirty flag" error on startup, you must use this flag after deleting the data directory inside ~/.local/share/eosio/nodeos/.

Wallet Management

With your node running, you can begin managing wallets.

Creating a Wallet

Use cleos to create a new wallet. The -n flag names it.

cleos wallet create -n mywallet

This command returns a password. Save this password securely, as you will need it to unlock the wallet in the future. Verify the wallet was created:

cleos wallet list

Importing the Default System Key

The eosio system account is the default superuser on a private chain. Import its private key into your wallet to authorize privileged actions.

cleos wallet import 5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3 -n mywallet

You can now check the system account's resources and permissions:

cleos get account eosio

Deploying the BIOS Contract

The eosio.bios contract is a fundamental system contract that allows you direct control over resource allocation and lets you invoke privileged API calls on your private chain. Deploy it using the eosio account.

cleos set contract eosio build/contracts/eosio.bios -p eosio

The -p eosio flag signs the transaction with the active permission of the eosio account, which you just imported the key for.

Account Creation

To create regular user accounts, you first need a new key pair.

1. Generate a New Key Pair

cleos create key

This outputs a new private and public key. Always keep private keys secure.

2. Import the New Private Key

Import the new private key into your wallet so cleos can use it to sign transactions.

cleos wallet import your_new_private_key_here -n mywallet

Verify the key is in your wallet:

cleos wallet keys

3. Create a New Account

Account names on EOS must be up to 12 characters long and can only use the characters a-z, 1-5, and .. Use the eosio account to create a new user account, specifying the new public key for both owner and active permissions.

cleos create account eosio newaccountname EOS6YourNewPublicKey... EOS6YourNewPublicKey...

Upon success, your private chain is fully operational with a system contract deployed and a user account ready to interact with smart contracts.

Frequently Asked Questions

What is the difference between nodeos, keosd, and cleos?
nodeos is the core node software that runs the blockchain. keosd is a separate wallet manager that securely stores private keys. cleos is a command-line tool that sends instructions to both nodeos and keosd, allowing you to interact with the blockchain and your wallets.

Why do I need to import the eosio account's key?
The eosio account is the default superuser or privileged account on a new EOS chain. Importing its private key into your wallet allows you to authorize important actions like deploying system contracts and creating new user accounts, which are restricted to privileged accounts.

What happens if I lose my wallet password?
The wallet password encrypts the wallet file on disk. If you lose the password, you cannot decrypt the wallet and access the private keys stored inside. You must save the password given when you first create the wallet. Without it, the imported keys are irrecoverable.

Can I use the same key for owner and active permissions?
While technically possible, it is a poor security practice. The owner key has ultimate control over the account and should be used infrequently and stored cold. The active key is for daily transactions. Using different keys minimizes risk if your active key is compromised.

Why would I get an "account already exists" error?
This error occurs if you try to create an account with a name that is already registered on the blockchain. All account names must be unique. Use the cleos get accounts command with a public key to see if it's already associated with an existing account.

Where can I find more advanced tools and resources?
For those looking to dive deeper into development and advanced node operations, a wealth of community-driven tools and documentation is available. 👉 Explore more strategies and developer resources to enhance your EOS development workflow.