paritytech / paritytech/polkadot-cli

feat: `dot watch` — btop-style live block & event observer

Open
#228 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
TypeScript
Stars
10
Forks
2
Avg merge
12h 35m
Merged PRs (30d)
4

Description

Part of #226 (live chain observation). Build after `query --follow` proves the subscription plumbing.

What

A terminal-native live view of a chain — the `btop` for Polkadot:

dot watch                  # default chain
dot polkadot.watch         # explicit chain

Follows finalized (and/or new) heads and renders, as blocks arrive:

  • block number + hash
  • block author / validator (where derivable)
  • extrinsic count (and optionally weight/size)
  • a decoded live event tail (most recent N events, pallet.Event with decoded fields)

Why

This is the flagship slice of the streaming capability gap (#226). It gives the currently-blocked subscription RPC methods in `src/commands/rpc.ts` (`chain_subscribeFinalizedHeads`, `chain_subscribeNewHeads`, `state_subscribeStorage`) a real home, and it's differentiated — no good terminal-native Polkadot observer exists (Subscan / PJS-apps are web).

Approach

  • papi observable subscription to finalized/new heads (flag to choose; default finalized).
  • For each block: fetch events, decode with the existing post-tx event decoder in `tx.ts` (papi view-builder → `{ type, value }`).
  • Render with the existing ANSI color infra in `src/core/output.ts`; reuse `Spinner`/redraw patterns.
  • Run until SIGINT; clean teardown of subscription + client.

Output contract

  • TTY: live-updating dashboard (in-place redraw of the header + scrolling event tail).
  • `--json` / non-TTY: newline-delimited JSON, one object per block, drain-safe via `writeStdout`. Depends on #162 / #163 (valid JSON contract).

Open questions

  • New-heads vs finalized default (lean: finalized, with `--new-heads` opt-in).
  • Author derivation: how reliably can we resolve block author across relay/parachains? May ship without author in v1 and add later.
  • Event filtering (`--pallet Balances`, `--event Transfer`) — likely a fast follow, not v1.
  • No TUI lib currently in the repo (no blessed/ink); decide whether plain ANSI redraw is enough (preferred — keeps deps lean) or a lib is warranted.

Verification

  • `dot polkadot.watch` renders a live header + event tail that advances ~every block.
  • `--json` emits one parseable JSON object per block.
  • Ctrl-C exits 0 and closes the WS connection.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with #226 and the subscription methods in src/commands/rpc.ts, then read the post-tx event decoder in tx.ts and ANSI output and redraw utilities in src/core/output.ts. Confirm the subscription plumbing before deciding the finalized/new-heads behavior and rendering approach. Done means dot polkadot.watch advances a live event tail, --json emits one parseable object per block, and Ctrl-C exits 0 while closing the WS connection.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
cli, observability
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.