paritytech / paritytech/polkadot-cli
Live chain observation: streaming/subscription support (`--follow`, `dot watch`)
Nobody has claimed this yet.
- 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)
- `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`.
- `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
- 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 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