Quickstart

Scope and safety

This quickstart produces a local educational testnet node and a local wallet. It does not connect you to a public Luracoin network: no public seed nodes, faucet, or production infrastructure are configured in the current source. Testnet and devnet use a genesis allocation whose historical private material is publicly known. Their balances are test data with no real-world value.

Mainnet is not merely hidden in the UI. The Python node has no mainnet genesis manifest and fails closed before it initializes chain data. Do not remove that guard to create an ad-hoc network and call it mainnet.

The node, wallet, consensus implementation, P2P stack, and build pipeline have not received an independent security audit. Use disposable data and keys while learning.

Runtime topology

A normal local setup contains four distinct pieces:

Component	Process or store	Default testnet endpoint	Responsibility
Full node	Python luracoin node	P2P :9999	Validates and persists the canonical linear chain, peers, and relays.
Mempool	Redis	127.0.0.1:6379, DB 1	Stores pending transaction bytes and atomic sender/nonce reservations.
Private RPC	Started inside the node	127.0.0.1:18444	Authenticated wallet-facing status, account, history, block, and submit routes.
Explorer API	Started inside the node	127.0.0.1:18000	Read-only chain data; the historical SQLite projection is opt-in.
Wallet	Electron, or a localhost SPA served by the node	Electron or 127.0.0.1:8080	Derives and encrypts keys locally, signs canonical transactions, and calls the node.

The RPC and explorer API are separate security domains. The RPC controls transaction admission and requires a bearer token. The explorer API is unauthenticated and read-only. Never point a public explorer frontend at the RPC.

Prerequisites

The current release metadata requires:

• Python 3.10, 3.11, or 3.12. Python 3.9 and 3.13 are outside the declared support range.
• Redis; Redis 7 is the recommended development target.
• A platform supported by rocksdict.
• Node.js 22.22.2 or newer for the wallet and website.
• Git and a C toolchain only if your platform cannot use prebuilt dependency wheels.
• uv for the fully locked CI/release workflow, although a standard virtual environment works for local exploration.

Install Redis on macOS:

brew install redis
brew services start redis
redis-cli ping

Install Redis on Ubuntu or Debian:

sudo apt update
sudo apt install -y python3 python3-venv redis-server
sudo systemctl enable --now redis-server
redis-cli ping

The final command must print PONG before transaction admission or mining can use the mempool.

Install the Python reference implementation

git clone https://github.com/luracoin/luracoin-python.git
cd luracoin-python
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

Verify the interpreter, package, and tests:

python --version
luracoin --version
luracoin --help
pytest -q

For a reproducible environment matching CI, use the committed lockfile instead:

uv lock --check
uv sync --frozen --extra dev
uv run pytest -q

Start one isolated full node

Use a dedicated directory and bind P2P to loopback for the first run:

luracoin node \
  --network testnet \
  --data-dir /tmp/luracoin-quickstart \
  --host 127.0.0.1 \
  --port 9999 \
  --rpc-port 18444 \
  --explorer-port 18000

On first start, the process:

1. Selects the testnet chain ID and magic bytes.
2. Creates the data and block directories.
3. Constructs and validates the fixed testnet genesis manifest.
4. Persists genesis, account state, and indexes.
5. Starts the P2P listener, authenticated RPC, and read-only explorer API.
6. Creates rpc.token inside the selected data directory with private permissions.
7. Prints one JSON service summary and waits for SIGINT or SIGTERM.

A node with zero peers can report ready: true because it is initialized and caught up with every peer it currently knows. That is local readiness, not proof that it sees a wider network.

Verify the node

In another terminal, with the same virtual environment active:

luracoin get-info --network testnet --data-dir /tmp/luracoin-quickstart
luracoin get-block --network testnet --data-dir /tmp/luracoin-quickstart 0
curl -s http://127.0.0.1:18000/health
curl -s http://127.0.0.1:18000/api/v1/status

The testnet genesis block ID must be:

0000009e2bcc8e56cee8b5e0fbdac9edc04513542af5c5791ea6165179c468bf

Swagger UI is available locally at http://127.0.0.1:18000/docs; the machine-readable contract is /openapi.json.

To query the authenticated RPC directly, keep the token out of shell history when practical:

TOKEN_FILE=/tmp/luracoin-quickstart/rpc.token
curl -s \
  -H "Authorization: Bearer $(<"$TOKEN_FILE")" \
  http://127.0.0.1:18444/v1/status

Do not paste the output token into documentation, issues, URLs, frontend variables, or screenshots.

Open the Electron wallet

Clone and start the wallet in a third terminal:

git clone https://github.com/luracoin/luracoin-wallet.git
cd luracoin-wallet
npm ci
LURACOIN_DATA_DIR=/tmp/luracoin-quickstart npm run electron:dev

Electron reads /tmp/luracoin-quickstart/rpc.token in its main process. The React renderer receives only a narrow IPC API and never sees the bearer. In the wallet:

1. Create a wallet with a local password of at least 12 characters.
2. Reveal and record the 24-word BIP39 phrase offline.
3. Verify words 3, 11, 17, and 22.
4. Select the only enabled network, testnet.
5. Confirm that the Node screen identifies the local process and chain height.

The wallet stores an AES-256-GCM encrypted vault in its Electron profile storage. The password-derived key uses PBKDF2-SHA256 with 250,000 iterations. The public address and compressed public key remain outside the ciphertext so the lock screen can identify the wallet; secret material is inside the encrypted payload.

Optional localhost browser wallet

The wallet can also run as a browser SPA, but only behind the Python node’s local gateway. Build the renderer:

cd luracoin-wallet
npm ci
npm run build

Stop the earlier node and restart it from the Python repository:

luracoin node \
  --network testnet \
  --data-dir /tmp/luracoin-quickstart \
  --host 127.0.0.1 \
  --port 9999 \
  --rpc-port 18444 \
  --wallet-dir ../luracoin-wallet/dist \
  --wallet-host 127.0.0.1 \
  --wallet-port 8080

Open http://127.0.0.1:8080/. The browser calls only same-origin /wallet-api/* routes. The Python gateway attaches the bearer during its private loopback hop and rejects direct /v1/*, disallowed methods, redirects, foreign Host/Origin, and cross-site fetch metadata.

Obtain test funds by mining

There is no public faucet. Copy the wallet’s testnet address, stop the foreground node, and run the miner using the same data directory:

luracoin mine \
  --network testnet \
  --data-dir /tmp/luracoin-quickstart \
  --address <YOUR_TESTNET_ADDRESS> \
  --host 127.0.0.1 \
  --port 9999 \
  --rpc-port 18444 \
  --explorer-port 18000

mine starts its own full node and services. Do not run node and mine simultaneously against the same directory or ports. Mining executes proof of work in a worker thread, pauses while the node is behind a known peer, and restarts its template if a peer wins the expected height.

Build a two-node local lab

Every process needs a unique data directory, Redis database, P2P port, RPC port, and explorer port. Start node A:

LURACOIN_REDIS_DB=3 luracoin node \
  --network testnet \
  --data-dir /tmp/luracoin-node-a \
  --host 127.0.0.1 --port 19999 \
  --rpc-port 19444 --explorer-port 19000

Start node B and seed it from A:

LURACOIN_REDIS_DB=4 luracoin node \
  --network testnet \
  --data-dir /tmp/luracoin-node-b \
  --host 127.0.0.1 --port 29999 \
  --rpc-port 29444 --explorer-port 29000 \
  --seed 127.0.0.1:19999

Both nodes share the same fixed genesis but maintain independent canonical state. The seed is only an initial address. After the v2 handshake, peers exchange addresses and node B requests consecutive blocks in batches of at most 50.

Next reading

• Use Full node operations before keeping a long-lived node.
• Use Wallet operations for backup, signing, locking, and browser/Electron boundaries.
• Begin protocol implementation with Protocol overview and Addresses & keys.
• Integrate read-only data through the Explorer API, never through the private RPC.