feat(openrpc): curated description overrides for params, types, and results

[akobrin1]

Summary

Replaces auto-generated "Go type: bool"-style descriptions in docs/openrpc.json with curated, Lumera-specific descriptions sourced from human-written JSON override files.

Three new override layers, all under docs/openrpc/:

File	Keyed by	Entries	What it covers
param_overrides.json	(method, param-name)	115	Every previously-ugly top-level param across debug_*, eth_*, miner_*, personal_*, txpool_*, web3_*.
type_overrides.json	(Go type, field-name)	types.TraceConfig (11) + types.ChainConfig (24) = 35	Nested struct fields. One entry deduplicates across every method that consumes the same struct (e.g. TraceConfig.debug is reused by all 5 debug_trace* methods).
result_overrides.json	method	83	All previously-ugly result descriptions, with Lumera-specific notes (chain_id = 0x494c1a9, no-uncles post-merge, miner_* are no-ops on CometBFT, etc.).

Also moves the pre-existing docs/openrpc_examples_overrides.json into docs/openrpc/ for co-location and drops the redundant openrpc_ filename prefix.

Mechanism

Each override file is loaded once at generation time by tools/openrpcgen and applied as the highest-precedence layer, after AST source comments and the existing in-Go paramDescriptorOverride function. Missing entries fall through to the prior behavior — adoption is incremental.

Generator flags:

• -params docs/openrpc/param_overrides.json
• -types docs/openrpc/type_overrides.json
• -results docs/openrpc/result_overrides.json

Updated Makefile passes all three by default; the Makefile inputs list also tracks the JSONs so docs/openrpc.json rebuilds when overrides change.

Effect

Metric	Before	After
Top-level params with "Parameter \...`. Go type: ..."`	115	0
Results with "Go type: ..."	83	0
Nested struct fields with "Go type: ..."	325	181 (remaining are seeds for future work: TransactionArgs, FilterCriteria, TypedData)

Test plan

• make openrpc regenerates docs/openrpc.json and app/openrpc/openrpc.json.gz
• jq confirms 0 top-level params and 0 results retain the "Go type: ..." default
• Spot-check across reuse points (e.g. TraceConfig.debug reads identically in debug_traceCall, debug_traceBlockByHash, debug_traceTransaction)
• go test ./tools/openrpcgen/... ./app/openrpc/... passes
• make lint → 0 issues
• OpenRPC playground (/openrpc.json endpoint) renders the new descriptions

Future work

Top remaining types with auto-generated nested-field descriptions, ranked by impact:

• types.TransactionArgs (18 fields, appears in 7+ methods)
• filters.FilterCriteria (5 fields, appears in eth_getLogs and eth_newFilter)
• apitypes.TypedData (4 fields, appears in eth_signTypedData)

Each is one JSON entry away — no further code changes required.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0cdd51328a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Adds a new “curated overrides” layer to the OpenRPC generator so human-authored JSON files can replace the auto-generated Go type: ... descriptions for method params, nested struct fields, and results, and regenerates docs/openrpc.json accordingly.

Changes:

• Extend tools/openrpcgen to load/apply external JSON overrides for params, struct fields (type-keyed), and results (method-keyed).
• Add curated override JSON files under docs/openrpc/ and relocate the examples overrides file into the same directory.
• Update the Makefile OpenRPC generation rule/inputs and refresh docs/openrpc.json plus related documentation references.

Reviewed changes

Copilot reviewed 11 out of 15 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tools/openrpcgen/type_overrides.go	Adds loader/lookup for type+field keyed overrides and a global handle used during schema recursion.
tools/openrpcgen/schema.go	Applies type-field overrides when expanding struct properties in JSON Schema.
tools/openrpcgen/param_overrides.go	Adds loader/lookup for method+param overrides and method-keyed result overrides.
tools/openrpcgen/main.go	Adds flags, loads override files at startup, and applies param/result overrides during descriptor building.
tools/openrpcgen/main_test.go	Updates tests to the new collectMethods signature.
Makefile	Wires new override files into the OpenRPC generation command and dependency inputs.
docs/openrpc/param_overrides.json	Adds curated parameter descriptions (and optional schema/required knobs) by method+param.
docs/openrpc/type_overrides.json	Adds curated nested-field descriptions keyed by Go type name + JSON field name.
docs/openrpc/result_overrides.json	Adds curated result descriptions keyed by method name.
docs/openrpc/examples_overrides.json	Relocates curated examples overrides under docs/openrpc/.
docs/openrpc.json	Regenerated OpenRPC document reflecting curated descriptions and updated externalDocs URL.
docs/evm-integration/testing/tests/unit-openrpc.md	Updates doc reference to the new examples overrides path.
docs/evm-integration/architecture/app-changes.md	Updates the documented OpenRPC inputs list (but currently incomplete).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.