paritytech / paritytech/polkadot-cli

Built-in RPC endpoint updates never reach existing configs; add `dot doctor`

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

Nobody has claimed this yet.

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

Description

Refreshing the built-in RPC endpoints in #288 revealed that endpoint fixes never reach existing users. Anyone who has run dot before keeps their old endpoint list forever, including endpoints that no longer resolve.

Same chain, same binary — the only difference is whether config.json already existed:

$ DOT_HOME=/tmp/existing dot query System Number --chain paseo-people
Error: Timed out fetching metadata for "paseo-people" after 15s.

$ DOT_HOME=/tmp/fresh    dot query System Number --chain paseo-people
5917892

Root cause

loadConfig() in src/config/store.ts:89 seeds the config file with the entire built-in table on first run:

await saveConfig(DEFAULT_CONFIG);   // writes all chains + all 66 endpoints to disk

and every subsequent load lets the saved copy win:

chains[name] = saved.chains[name]
  ? { ...defaultConfig, ...saved.chains[name] }   // saved.rpc overrides the new default
  : defaultConfig;

So the on-disk copy of a built-in chain is indistinguishable from a deliberate user override, and shadows the shipped list permanently. A second loop re-adds saved keys that are no longer in DEFAULT_CONFIG, which resurrects chains we intentionally removed.

Impact after upgrading to #288

Measured by writing the pre-#288 defaults to $DOT_HOME/config.json and dumping the effective config:

Result
Dead endpoints still in use 36 of 72
Chains with zero working endpoints paseo-people, paseo-bridge-hub, paseo-collectives, paseo-coretime
De-registered Paseo chains resurrected as phantom user chains
Newly added chains (polkadot-bulletin, paseo-bulletin) arrive correctly — no saved entry to shadow them

paseo-people is the sharp edge: still a supported chain, but a pre-existing config pins it to three unreachable hosts, so it is simply broken. dot chain update does not help — it re-fetches metadata, not endpoints.

Proposed fix

1. Stop persisting built-in chains (removes the bug class). Keep config.json for user additions and explicit overrides only, and always read built-ins from DEFAULT_CONFIG at runtime. Then shipping an endpoint change is enough for every user to get it, and there is no per-release migration to maintain.

This needs a way to record an intentional override of a built-in chain (e.g. dot chain add polkadot --rpc ... writes only the fields the user set) and a decision on how dot chain remove marks a built-in as hidden.

2. Add dot doctor for the configs already on disk, and for drift in general. Deliberately not a versioned migration: a table of historical default endpoint lists would have to be carried forever, which is a maintenance burden we do not want.

$ dot doctor
  polkadot         5/12 endpoints unreachable
  paseo-people     3/3 endpoints unreachable — chain unusable
  paseo-coretime   not a registered parachain on paseo
  ...
  run `dot doctor --fix` to reset built-in chains to shipped defaults

$ dot doctor --fix
  reset 9 built-in chains to shipped defaults
  removed 3 chains that no longer exist upstream
  kept 1 user-added chain (my-custom)

Worth considering for scope:

  • probe endpoints concurrently with a short timeout and report per-endpoint reachability
  • flag built-in chains whose parachainId is not registered on the configured relay (how paseo-bridge-hub/collectives/coretime were confirmed dead in #288)
  • report stale metadata caches and orphaned chains/<name>/ directories
  • --json for scripting, and never mutate anything without --fix
  • check workspace .polkadot/ dirs as well as $DOT_HOME, since both can hold a stale config

Reproduction

export DOT_HOME=/tmp/existing
mkdir -p $DOT_HOME
git show <pre-288-sha>:src/config/types.ts   # take DEFAULT_CONFIG.chains
# write it to $DOT_HOME/config.json as {"chains": ...}
dot chains -v                                 # old endpoints, resurrected paseo chains
dot query System Number --chain paseo-people   # times out

Follow-up to #288.

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 loadConfig() at src/config/store.ts:89 and the DEFAULT_CONFIG definitions in src/config/types.ts, then reproduce the stale behavior with dot chains -v and the paseo-people query. Define how built-in overrides and removals are represented before implementing the config behavior and dot doctor. Done means shipped endpoint updates apply to existing configs, intentional user changes remain, and doctor reports drift without changing anything unless --fix is used.

Written by the indexing model from the issue text.

Assessment

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