CKB TUI design

[chenyukang]

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.

┌──────────────────────────────────────────────────────────────────────────────┐
│                            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: 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: 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.

[chenyukang]

The implementation for this design is working on: https://github.com/Officeyutong/ckb-tui

The WIP prototype from @Officeyutong

[RetricSu]

This is great! Since it is a tui, I am thinking maybe we can integrate it into tools like offckb, so users can easily run a devnet node and watch its status with ckb-tui, cmd might be like this:

offckb node --watch

[Officeyutong]

Current UI by 2025/10/15

• Panel Logs isn't written yet, since we have not determined how to provide streamed logs in RPC

[Officeyutong]

Missing metrics by 2025/10/15

• Estimated Epoch Time/Average Block Time
• Difficulty
• Hash Rate
• Commiting Txs in pool
• System basic information like CPU/memory/disk usage, disk/network IO
• Live Cells and Occupied Capacity
• Scripts
• Tx throughput (Tx In/Tx Out)
• Rejected tx count, rejection rate, details of recently rejected txs
• Latest incoming transactions
• Latency of connected peers, warning of peers (How to measure latency of a peer? How to determine which warning to be displayed for a peer?)
• Streamed logs

These metrics should be provided by CKB in order to be displayed in ckb-tui