paritytech / paritytech/polkadot-cli

Live chain observation: streaming/subscription support (`--follow`, `dot watch`)

Open
#226 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

The gap

polkadot-cli is entirely one-shot request/response. There is no general way to subscribe to / follow / watch new blocks, finalized heads, storage changes, or a live event stream. The only streaming code path is the single-tx finality watcher in `src/commands/tx.ts` (`watchTransaction` / `watchTransactionJson`, RxJS over a papi `Observable`), which is hardcoded to one tx's lifecycle and not reusable.

Subscription RPC methods are in fact explicitly blocked today: `src/commands/rpc.ts` rejects `chain_subscribeNewHeads`, `chain_subscribeFinalizedHeads`, `state_subscribeStorage`, etc. with "subscription method (requires a follow session) and is not callable as a one-shot."

This is the one missing capability rather than a variation on the existing model — every other backlog item is a refinement of one-shot query/tx. A terminal-native live view is also differentiated (Subscan / polkadot-js apps are web).

Scope (two slices, ship smallest first)

  1. `query --follow` — subscribe to a storage item and print on change. See child issue. Smallest viable streaming feature; proves the subscription plumbing by reusing the existing storage-decode path in `query.ts`.
  2. `dot watch` — `btop`-style live view: follow finalized/new heads, show block number/hash/author, extrinsic count, and a decoded live event tail. See child issue. This is where the currently-blocked subscription methods in `rpc.ts` get a real home.

Reuse / building blocks

  • papi observables (already used in `tx.ts`)
  • `Spinner` + ANSI color infra in `src/core/output.ts`
  • the post-tx event decoder in `tx.ts` (papi view-builder → `{ type, value }`)
  • `writeStdout` drain-safe write helper (avoid piped-output truncation)

Output contract (must hold for both slices)

  • TTY: pretty, re-rendering / streaming view.
  • `--json` / pipes: newline-delimited JSON (one object per event/change), drain-safe.
  • This depends on the `--json` contract being correct first — see Prerequisites.

Prerequisites (harden the JSON contract first)

  • #163 — error output must honor `--json` (JSON envelope on errors)
  • #162 — `--json` must emit valid JSON for empty values

A streaming feature emits a lot of JSON; the envelope/empty-value semantics should be settled before building on them.

Sub-issues

  • `query --follow` (live storage subscription)
  • `dot watch` (btop-style block/event observer)

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 by reading src/commands/tx.ts for the existing RxJS transaction watcher, src/commands/rpc.ts for blocked subscription methods, and query.ts for the storage-decode path. Review #163 and #162 before choosing a slice; done means a follow or watch command with TTY and newline-delimited JSON behavior, using drain-safe output.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, cli
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.