System architecture

Repository map

Luracoin currently consists of three separately deployable codebases:

Repository	Runtime	Owns
luracoin-python	Python 3.10–3.12	consensus, canonical storage, P2P, mining, RPC, explorer API/index
luracoin-wallet	Node 22.22.2+, Electron/Vite/React	key vault, transaction signing, desktop/browser wallet UX
luracoin-website	Astro static build	public presentation, documentation, explorer frontend

The Python repository is consensus authority. The wallet duplicates only the client-side primitives required to derive keys, validate addresses, serialize/sign transactions, and speak RPC/gateway contracts. The website must not contain consensus or secret-handling authority.

Runtime topology

                         TCP P2P v2
                    ┌──────────────────┐
                    │ controlled peers │
                    └────────┬─────────┘
                             │
┌────────────────────────────▼──────────────────────────┐
│ Python full-node process                              │
│                                                      │
│ Node / sync / relay ─── Block + transaction rules    │
│          │                      │                     │
│          ├── private RPC        ├── block files       │
│          ├── wallet gateway     ├── RocksDB           │
│          └── public Explorer API├── Redis mempool     │
│                                 └── SQLite projection │
└──────────────┬───────────────────────┬───────────────┘
               │ loopback + bearer     │ read-only HTTP
        ┌──────▼───────┐        ┌──────▼──────────────┐
        │ Electron app │        │ Astro explorer      │
        │ keys/signing │        │ Cloudflare Pages    │
        └──────────────┘        └─────────────────────┘

Not every deployment enables every edge. An ordinary node may omit Electron, browser wallet, SQLite, mining, and public API exposure.

Python package responsibilities

Module	Responsibility
config.py	network namespace, paths, sizes, timing, service limits
wallet.py	BIP39/BIP32/secp256k1/address primitives used by Python clients/tests
transactions.py	canonical encoding, IDs, signature validation, mempool admission
blocks.py	block encoding, validation, mining selection, persistence locations
chain.py	accounts, tip, block/transaction/address indexes
helpers.py	hash, compact target, reward, byte conversion helpers
genesis.py	built-in educational network manifests and verification
network/protocol.py	P2P framing and payload codecs
network/peer.py	one TCP peer, handshake, bounded send/receive
network/node.py	server, connection lifecycle, dispatch, sync, inventory, relay
network/sync.py	strict next-block download/application helper
network/miner.py	templates, interruptible PoW, stale-result rejection
rpc.py	private loopback wallet/operator API
wallet_web.py	same-origin browser gateway and static wallet serving
explorer_api.py	public FastAPI core/indexed query contract
explorer_index.py	optional SQLite schema, backfill, aggregates, divergence checks
cli.py	configuration, lifecycle, signal handling, command composition

Crossing a module boundary does not reduce consensus requirements. For example, network code must still invoke full block validation; transport checksum is never acceptance.

Full-node startup

At a high level, luracoin node:

1. resolves network and data directory before mutable services start;
2. fails closed if mainnet is requested without a manifest;
3. ensures directories and validates/creates genesis for an empty supported network;
4. creates the chain and P2P node;
5. creates/loads the private RPC bearer token;
6. starts loopback RPC;
7. optionally starts browser-wallet static gateway;
8. optionally starts core Explorer API and optional indexer;
9. starts P2P listening, maintenance, keepalive, and configured peer connections;
10. runs until signal/controlled shutdown;
11. stops tasks and services without allowing multiple stream readers or writers to linger.

luracoin mine composes the same node services with a miner task bound to one reward address.

Canonical data ownership

The canonical node owns:

blocks/             exact block records
blocks.db           canonical height/hash/transaction locations
accounts.db         current balance + nonce state
chainstate.db       tip and chain metadata
rpc.token           local API credential

Redis owns pending policy state but is not canonical history. SQLite owns public-query acceleration but is a rebuildable projection. Electron local storage owns an encrypted wallet vault but is not a node backup.

No component should “repair” another component’s canonical data silently.

Transaction creation flow

RPC account view
  -> wallet validates network/readiness/mempool
  -> wallet chooses next_nonce and integer amount/fee
  -> renderer requests signing
  -> unlocked vault provides private key in signing boundary
  -> deterministic low-S secp256k1 signature
  -> exact 213-byte transaction
  -> private RPC POST /v1/transactions
  -> Redis atomic nonce reservation + payload
  -> direct peer relay + bounded backlog
  -> miner selects contextually valid sequence
  -> block acceptance commits account state
  -> Redis cleanup and history/index visibility

The private key never belongs in the Python node, RPC request, P2P message, website, or Explorer API. Only public key plus signature enter the transaction.

Received transaction flow

TCP frame
  -> length/checksum/command validation
  -> exact TX payload validation
  -> transaction deserialization and ID derivation
  -> signature/address/chain/context validation
  -> atomic Redis admission
  -> relay to other peers

An invalid transaction does not reach relay. A valid encoding can still fail contextual admission because of account state or nonce reservation.

Block flow

Local mining:

canonical tip + Redis snapshot
  -> deterministic valid transaction selection
  -> leading coinbase subsidy + fees
  -> expected timestamp/bits/predecessor
  -> interruptible nonce search
  -> stale-tip recheck
  -> same canonical acceptance path
  -> block inventory relay

Peer synchronization:

VERSION height advertisement
  -> single best-peer sync task
  -> GETBLOCKS batches of 50
  -> single stream dispatcher
  -> next-height full validation
  -> persistence/state publication
  -> continue until advertised height

Both paths converge on the same validity and save logic. A miner cannot bypass consensus because it produced the block locally.

Wallet architecture

The desktop app separates:

Boundary	Responsibilities
Electron main process	filesystem token access, RPC HTTP, approved IPC, window lifecycle
preload bridge	narrow, typed-ish operation surface; no raw Node exposure
renderer	UX, public state, vault ciphertext, validation, transaction workflow
encrypted vault	mnemonic/private material protected by password-derived AES key

Window security enables context isolation and sandboxing and disables renderer Node integration. RPC bearer material remains main-process only.

The browser build cannot read rpc.token, so the Python gateway attaches it server-side to four allowlisted operations while enforcing same-origin browser signals.

Website architecture

The Astro site is statically generated. It owns:

• product and protocol explanation;
• extensive source-anchored documentation;
• wallet screenshot presentation;
• explorer UI states and public API client;
• no secret, mutation, mining, or canonical database.

The explorer base URL is a public build-time variable. If absent, the site reports its placeholder status instead of synthesizing data.

This separation lets the documentation and application remain globally cacheable while the chain API evolves independently.

Explorer read path

Core lookup:

HTTP GET -> FastAPI validation -> RocksDB location -> exact block read
         -> ID/location recheck -> bounded JSON model

Indexed lookup:

HTTP GET -> capability/index-ready gate -> bounded SQLite query
         -> decimal-string normalization -> response model

The indexer is downstream of canonical storage:

canonical block N -> one SQLite transaction -> metadata commits N/id

It must never feed balances or blocks back into validation.

Concurrency model

Important serialization points are:

• one reader/dispatcher per P2P connection;
• one send lock per P2P connection;
• one active chain synchronization peer;
• one state-transition lock for block acceptance;
• one block-file lock for exact reads/appends;
• Redis Lua scripts for multi-key mempool operations;
• SQLite transactions per projected block;
• one wallet signing action within an authenticated/unlocked UI session.

These solve specific races. They are not interchangeable and do not create an atomic transaction across every store.

Extension rules

Before adding a feature, classify it:

Change	Likely boundary
explorer filter/display field	public API-compatible if additive
new wallet screen	client-only if it does not alter signing/encoding
new RPC read route	local API versioning/security review
new P2P command	protocol-version and resource-bound review
transaction field	consensus-breaking serialization change
address derivation change	wallet/protocol migration
difficulty/reward rule	consensus/network transition
fork choice/reorg	canonical storage and every derived-index lifecycle

Consensus changes require executable vectors, negative tests, migration rules, coordinated network identity/versioning, and documentation updates in the same release.

Architectural non-goals today

The alpha is not:

• a smart-contract platform;
• a multi-asset ledger;
• a UTXO chain;
• a light-client protocol;
• a horizontally sharded node;
• a high-availability replicated database;
• a production public network;
• a custodial wallet service;
• an authenticated public explorer backend.

Keeping these boundaries explicit prevents frontend completeness from being mistaken for protocol completeness.