paritytech / paritytech/polkadot-cli
feat: `dot watch` — btop-style live block & event observer
Nobody has claimed this yet.
- 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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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