Console UI¶
Fukuii includes an enhanced Terminal User Interface (TUI) for monitoring node status in real-time.
Features¶
The Console UI provides a rich, visual interface with:
- Real-time Status Updates: Live display of node state without scrolling
- Grid Layout: Organized sections for different metrics
- Network Information: Current network, peer connections, and connection status
- Blockchain Sync Progress: Current block, best block, progress bar, and estimated sync time
- ASCII Art: Ethereum Classic logo and visual indicators
- Color-Coded Status: Green for healthy, yellow for warnings, red for errors
- Interactive Commands: Keyboard shortcuts for control
- Clean Exit: Proper terminal cleanup on shutdown
Usage¶
Starting with Standard Logging (Default)¶
By default, Fukuii uses standard logging output:
Note: The console UI is currently disabled by default while under further development.
Enabling Console UI¶
To enable the enhanced console UI for interactive monitoring:
The console UI is useful when: - Monitoring node status in real-time - Running interactively in a terminal - Viewing sync progress with visual indicators - Using keyboard shortcuts for control
Display Layout¶
┌────────────────────────────────────────────────────────────────┐
│ ◆ FUKUII ETHEREUM CLIENT ◆ │
├────────────────────────────────────────────────────────────────┤
│ [Ethereum Classic Logo] │
├────────────────────────────────────────────────────────────────┤
│ ● NETWORK & CONNECTION │
│ Network: ETHEREUM CLASSIC │
│ Connection: ● Connected │
│ Peers: 25 / 50 ◆◆◆◆◆◆◆◆◆◆ │
├────────────────────────────────────────────────────────────────┤
│ ● BLOCKCHAIN │
│ Current Block: 15,234,567 │
│ Best Block: 15,234,890 │
│ Sync Status: Syncing │
│ Sync Progress: [████████████████░░░░░░] 98.45% │
│ Blocks Remaining: 323 │
│ Est. Sync Time: 2m 15s │
│ Sync Speed: 2.35 blocks/sec │
├────────────────────────────────────────────────────────────────┤
│ ● RUNTIME │
│ Uptime: 1h 23m 45s │
├────────────────────────────────────────────────────────────────┤
│ Commands: [Q]uit | [R]efresh | [D]isable UI │
└────────────────────────────────────────────────────────────────┘
Keyboard Commands¶
| Key | Action |
|---|---|
Q |
Quit the application |
R |
Refresh/redraw the display |
D |
Disable the console UI (switch to standard logging) |
Commands are case-insensitive (both q and Q work).
Color Scheme¶
The console UI uses a green color scheme to match the Ethereum Classic branding:
- Green: Section headers, progress bars, healthy status, connected peers
- Cyan: Labels and field names
- White: Values and information
- Yellow: Warning states (low peers, initializing)
- Red: Error states (no peers, connection failures)
Technical Details¶
Implementation¶
- Built with JLine 3 for cross-platform terminal control
- Keyboard input is read with a bounded timeout (never JLine's
0 == wait forever) - Terminal resize is detected each frame and triggers a full redraw
- Runs in the alternate screen buffer; on exit the terminal mode, cursor and scrollback are restored
Terminal Requirements¶
The console UI works best with: - Terminal size: minimum 80x24 characters (larger recommended) - UTF-8 encoding support for special characters - ANSI color support
Compatibility¶
Tested on: - Linux (various distributions) - macOS - Windows (with proper terminal emulators)
For Windows users, we recommend: - Windows Terminal - ConEmu - Git Bash - WSL
Fallback Behavior¶
If the console UI fails to initialize (no TTY — output redirected, docker run without -t, a systemd unit — or a dumb terminal), Fukuii will automatically:
1. Log a warning message
2. Fall back to standard logging mode
3. Continue running normally
Architecture¶
All TUI code lives in com.chipprbots.ethereum.console:
| Component | Role |
|---|---|
Tui |
Owns the terminal: raw mode, alternate screen, frame drawing, key input, teardown. Refuses dumb/non-TTY terminals so escape codes never land in a log stream. |
TuiRenderer |
Pure function TuiState × width × height → lines. Every frame is exactly height rows of exactly width columns, so drawing it never scrolls or wraps; the command footer always stays on the bottom row. |
TuiState |
Immutable view model. Sync speed/ETA are measured from the first block the TUI observed (not from genesis). |
TuiStatusProbe |
Polls the node: handshaked peers (PeerManagerActor.GetPeersCmd, same as net_peerCount), sync status (SyncProtocol.GetStatus, same as eth_syncing), local best block, and the latest SNAP progress sample. A slow actor shows as "Unresponsive" rather than freezing the display. |
TuiUpdater |
Daemon thread looping poll → render → wait up to updateIntervalMs for a key. The key wait is the frame pacing. |
TuiLogSuppressor |
Detaches the console appender while the TUI is active (file logging continues). |
Lifecycle¶
Fukuii.mainsees--tui, validates config (errors are still printed to the console), then initializes the TUI and registers a JVM shutdown hook that restores the terminal.StdNode.start()→startTuiUpdater()wires the probe and starts the updater.Qexits the JVM; the node's shutdown hook stops the updater and restores the terminal.Drestores the terminal and console logging and the node keeps running.Ctrl-Cbehaves as without the TUI.
Testing¶
TuiSpec, TuiUpdaterSpec and TuiStatusProbeSpec (under src/test/.../console/) drive the real classes against an in-memory xterm (TuiTestTerminal) and stub actors; TuiRendererSpec and TuiStateSpec cover layout and state.
Future Enhancements¶
Potential improvements for future releases:
- Additional Views: Toggle between different information panels (logs, peers, transactions)
- Detailed Peer Info: Show individual peer details
- Transaction Pool: Display pending transaction count and details
- Mining Status: Show mining statistics when enabled
- Configuration: Terminal settings and color schemes
- Log Viewer: Browse recent log entries in the UI
- Performance Metrics: CPU, memory, disk usage
Troubleshooting¶
Console UI not displaying correctly¶
- Check terminal size:
echo $COLUMNS x $LINES - Verify UTF-8 support:
echo $LANG - Try different terminal emulator
- Remove
--tuiflag to use standard logging as fallback
Terminal not cleaning up properly¶
If the terminal is left in a bad state after exit:
Colors not working¶
Ensure your terminal supports ANSI colors: