nervosnetwork / nervosnetwork/ckb

CKB TUI design

Open
#4,965 4 comments 0 reactions 0 assignees View on GitHub
design t:enhancement
Dominant language
Rust
Stars
1.2k
Forks
266
Avg merge
10d 5h
Merged PRs (30d)
4

Description

From a UX perspective, running a full node is not a friendly experience. I don't think this is something we can fix with just better docs. The core problem is the lack of a clear, direct connection and instant feedback between the user and the system.

## Key Pain Points

1. **No Clear Sync Progress**

1. After running `ckb run`, the terminal just floods you with logs. You have no idea how far along the sync is or when it might finish.
2. Current solution:
(1) Run `ckb-cli rpc sync_state` to see if the `ibd` field is `false`.
(2) Call `ckb-cli rpc get_tip_header` to get the current tip block height and then check it against a CKB explorer.
3. Problems with the current solution:
(1) It's a hassle. You have to manually run multiple commands, sometimes across different tools.
(2) You need to understand RPC calls, which isn't beginner-friendly.
(3) There's no progress bar or percentage. Users can't tell how much is left or get a time estimate (the log sometimes shows it, but it gets buried in other messages).

2. **Node Status Isn't Obvious**

1. It's hard to tell if the node is connected to the network, if it has found peers, or if it's stable.
2. Current solution: (1) Call `ckb-cli rpc local_node_info` to get basic node info. (2) Use `ckb-cli rpc get_peers` to see a list of all connected peers and their details.
3. Problems with the current solution:
(1) The output is a dense wall of text with lots of rarely-needed info. It’s hard to read and buries the key information users actually care about.
(2) There are no graphics or simple status indicators (like Online/Offline, uptime, etc.) to help beginners.

3. **Users Don't Feel Like They're Contributing**

1. Even after setting up a node, users have no sense of how they are actually helping the network. There's no dashboard or stats to give users the feeling that "you're doing something important." This is especially discouraging for new users and gives them little reason to keep their node running long-term.

4. **Tools Are a Mess**

1. Right now you need to juggle multiple tools and command lines (e.g., ckb, ckb-cli, ckb explorer, node probe, etc.). There's no single place to see all the status info, which makes for a fragmented and clunky experience.

-----

## Proposed solution

Instead of a full GUI, a Terminal UI (TUI) would be a better fit for our users right now. Most people running CKB nodes are developers or tech-savvy community members, and a TUI fits right into their workflow. For example, just letting a user type `ckb-cli monitor` to get a clean, organized status screen is way more intuitive and efficient than digging through logs or juggling multiple commands.

```bash
┌──────────────────────────────────────────────────────────────────────────────┐
│ CKB Node Monitor │
│ [Overview] [Peers] [Network Impact] [System Info] [Tx Pool] │
├──────────────────────────────────────────────────────────────────────────────┤
│ [Sync Status] │
│ • Current block: #120301 │
│ • Syncing: 87.5% │
│ • Estimated time left: ~12min │
│ │
│ [Peers] │
│ • Connected: 8 (6 outbound / 2 inbound) │
│ • Avg latency: 54ms │
├──────────────────────────────────────────────────────────────────────────────┤
│ [Network Impact] │
│ • You're 1 of ~950 full nodes online │
│ • Currently relaying data to 6 peers │
│ • Your node is reachable ✓ │
├──────────────────────────────────────────────────────────────────────────────┤
│ [System Info] | [Tx Pool] │
│ • CPU: 14% | • Pending: 120 txs │
│ • RAM: 2.3GB / 8GB | • Last incoming tx: 15s ago │
│ • Disk: 122GB / 150GB | │
├──────────────────────────────────────────────────────────────────────────────┤
│ Press [Q] to quit, [Tab] to switch panels, [R] to refresh │
└──────────────────────────────────────────────────────────────────────────────┘

```

## Technical Implementation

To build a TUI application, we need to choose a suitable library, the current plan is to use cursive. It's based on ncurses, which is mature and has a long history, and it's also easier to code with.

Some other options we looked at:
- [ratatui](https://github.com/ratatui/ratatui): Similar to traditional UI frameworks, but the functions it provides are relatively low-level, and you need to control the drawing of components by yourself
- [iocraft](https://github.com/ccbrown/iocraft): It is not based on ncurses and provides React-style interfaces, but the functions it offers are very low-level, components that are not encapsulated.

Contributor guide

Open the contributing guide

Research direction

The issue names no implementation files or tests. Start by reviewing the proposed ckb-cli monitor entry point and the cursive option, then define the scope for sync, peer, network-impact, system-info, and transaction-pool views. Done requires an agreed TUI design and implementation plan before coding can begin.

Written by the indexing model from the issue text.

Assessment

Tech stack
blockchain, rust
Domain
cli, observability
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.