paritytech / paritytech/polkadot-cli
Built-in RPC endpoint updates never reach existing configs; add `dot doctor`
Nobody has claimed this yet.
- 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
parachainIdis not registered on the configured relay (howpaseo-bridge-hub/collectives/coretimewere confirmed dead in #288) - report stale metadata caches and orphaned
chains/<name>/directories --jsonfor 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
- 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 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