fix(docgen): probe member converters to document their real JSON kind

[hudem1]

Resolves #12838

Follow-up to #12868 (now merged), addressing the per-member converter case raised in review (#12868 (comment)).

Changes

#12868 derives JSON-RPC docs from the serializer contract and already fixes the plain-int case (int/uint → _integer_). The remaining #12838 gap is that a member's CLR type alone doesn't determine its wire form: a field with an explicit [JsonConverter] can emit something other than the hex-quantity string its type implies — the classic case being two ulong fields where one carries a raw-number converter (struct-log gas vs transaction gas).

Rather than hard-code the raw-number converter types, this probes the member's converter: it serializes a sample value through that converter and reads back the JSON token.

• Number/True/False → override the type-based label (_integer_/_number_/_boolean_).
• String → fall through and keep the editorial flavour (hex data, hash, …).

It works for any converter, not a fixed list — the same "ask the serializer, don't guess" principle as #12868. Probing is deliberately scoped to explicit member converters: probing a type's default serialization is unsound for value-dependent unions (e.g. eth_syncing returns false or an object; a default-value probe would collapse it to _boolean_).

Result / verification

Diffed the generated docs against master. The only changes are the intended fields flipping hex-string → _integer_:

• trace_* result blockNumber
• debug_* Geth struct-log entries: gas, gasCost, pc, refund, step

eth_syncing, byte-buffer fields, hashes, addresses and all other shapes are unchanged. Together with #12868, every field reported in #12838 is now correct and matches the wire format (Geth/OpenEthereum/Erigon).

No RPC-module code changes: the implementation already matched the reference clients; only the generated docs were wrong.

Types of changes

• Bugfix (a non-breaking change that fixes an issue)
• Documentation update

Testing

Requires testing

• No

Notes on testing

The DocGen tool has no test project (consistent with #12858/#12868). Verified by regenerating the docs on this branch and diffing against master, confirming only the raw-number-converter fields change.

Documentation

Requires documentation update

• Yes

Regenerating the docs from this branch updates the NethermindEth/docs JSON-RPC pages.

Requires explanation in Release Notes

• No

🤖 Generated with Claude Code

[claude]

Claude finished @hudem1's task in 4m 6s —— View job

---

Review: docgen integer types

• Read the diff and surrounding generator code
• Verify the claimed serialization behaviour of int, [ULongRawJsonConverter], [LongRawJsonConverter]
• Check for missed cases (other raw-number converters, class-level converters, nullables)
• Post review findings

The diagnosis is correct and the fix is in the right place. I verified each claim against the serializer:

• IntConverter.Write → writer.WriteNumberValue(value) (Nethermind.Serialization.Json/IntConverter.cs:36), and it is globally registered (EthereumJsonSerializer.cs:109), with NullableIntConverter wrapping it for int? — so Int32 → _integer_ is right, and the Nullable unwrap at the top of GetJsonTypeName(Type) makes int? land on the same arm.
• LongRawJsonConverter / ULongRawJsonConverter do write raw numbers, and the fields named in the PR body check out: PortsInfo.Discovery/Listener (int), ParityNetPeers.Active/Connected/Max (int), ParityTxTraceFromStore.BlockNumber ([ULongRawJsonConverter]), Subtraces/TransactionPosition (int/int?), and the Geth struct-log entries in GethTxTraceEntry.cs:20,26,29,37.
• Checking the attribute before unwrapping Nullable<T> is deliberate-looking and correct — GethTxTraceEntry.Refund is long? with [LongRawJsonConverter] and would otherwise be missed.
• No regression risk on the Int32 arm: I found no int property in the RPC surface carrying a converter that emits hex, so nothing that legitimately renders as a hex quantity gets downgraded.

Findings

Medium — two raw-number converters are still unhandled (tools/DocGen/JsonRpcGenerator.cs:307-310)
NullableRawLongConverter and NullableRawULongConverter (Nethermind.Serialization.Json/NullableLongConvertercs.cs:16,39) also WriteNumberValue, and NullableRawULongConverter is applied to step in Nethermind.Facade/Eth/BlockForRpc.cs:139 and Nethermind.Facade/Eth/BlockHeaderForRpc.cs:77. Both types are expanded by the generator, so step in the eth_getBlockBy* docs will still be published as _string_ (hex integer) despite being a raw number — the identical bug, one converter name away. Suggested patch posted inline. Fix this →

Low — converter matching by Name string literal
DocGen project-references Nethermind.Runner and already consumes Nethermind.JsonRpc.Modules types directly, so typeof(ULongRawJsonConverter) is available and compile-checked. Repo style prefers type/nameof references over string literals, and since this tool has no test project a rename or move would silently regress the docs with no signal. See the inline suggestion.

Low — nonce has the same class of mismatch
BlockNonceConverter (Nethermind.Facade/Eth/BlockNonceConverter.cs:36-40) writes a zero-padded 8-byte hex string, but nonce is documented as _string_ (hex integer). Pre-existing and strictly out of scope, but the new property-aware hook is exactly where a _string_ (hex data) mapping would go if you want to close it in the same pass.

Low — no regression test
.agents/rules / AGENTS.md ask for a regression test with every bug fix; the PR acknowledges DocGen has no test project (consistent with #12858). Reasonable, but the string-literal coupling above is the kind of thing that only a test would catch — worth a follow-up issue rather than more scope here.

Notes

• The comment on lines 305-306 and 328-329 explain why, are concise and reference the converters — in line with the repo comment guidelines.
• I could not compile locally (build command not permitted in this environment), so the change is reviewed by reading only; JsonConverterAttribute.ConverterType and the is "A" or "B" pattern are valid against the existing using System.Text.Json.Serialization; / System.Reflection imports.
• No production RPC behaviour is touched — I agree with the decision not to "fix" the modules to emit hex, which would diverge from Geth/Parity/Erigon.

Nothing here is a correctness or security risk in the client itself; the Medium is an incomplete-fix gap in the generated docs.
• branch fix/12838-docgen-integer-types

[claude]

Medium — this covers only two of the four raw-number converters in the repo. NullableRawLongConverter / NullableRawULongConverter (src/Nethermind/Nethermind.Serialization.Json/NullableLongConvertercs.cs:16,39) also WriteNumberValue, and they are used on step in both BlockForRpc.cs:139 and BlockHeaderForRpc.cs:77 — both of which the generator expands (they are eth_getBlockBy* / AuRa results). Those fields will still be documented as _string_ (hex integer) while the wire value is a raw number, i.e. exactly the bug this PR fixes.

Second, matching converters by Name string literal is fragile: DocGen already project-references Nethermind.Runner (and uses Nethermind.JsonRpc.Modules types directly), so Nethermind.Serialization.Json types are reachable and a typeof comparison would be compile-checked. With no test project behind this tool, a rename/move would silently reintroduce wrong docs.

Suggested change

	// A property may override the default numeric serialization with a converter that writes a raw JSON
	// number (e.g. trace/debug block numbers) instead of the hex-quantity string implied by its CLR type.
	private static string GetJsonTypeName(PropertyInfo prop) =>
	prop.GetCustomAttribute<JsonConverterAttribute>()?.ConverterType?.Name is "ULongRawJsonConverter" or "LongRawJsonConverter"
	? "_integer_"
	: GetJsonTypeName(prop.PropertyType);
	// A property may override the default numeric serialization with a converter that writes a raw JSON
	// number (e.g. trace/debug block numbers) instead of the hex-quantity string implied by its CLR type.
	private static readonly Type[] _rawNumberConverters = [
	typeof(LongRawJsonConverter),
	typeof(ULongRawJsonConverter),
	typeof(NullableRawLongConverter),
	typeof(NullableRawULongConverter)
	];
	private static string GetJsonTypeName(PropertyInfo prop) =>
	prop.GetCustomAttribute<JsonConverterAttribute>()?.ConverterType is Type converterType &&
	Array.IndexOf(_rawNumberConverters, converterType) >= 0
	? "_integer_"
	: GetJsonTypeName(prop.PropertyType);

(needs using Nethermind.Serialization.Json; at the top; the field would read better next to _assemblies/_objectTypeName at the top of the class.)

The base branch was changed.

[dipkakwani]

Need to rebase, since the base PR got merged before the stacked PR 😅

[wurdum]

InvokeConverterWrite looks up Write using the member's CLR type after the nullable unwrap, so for BlockForRpc.Step it asks for Write(..., ulong, ...) against a JsonConverter<ulong?> and succeeds only because the reflection binder widens. A JsonConverterFactory declares no Write, so GetMethod returns null and the ! throws into the blanket catch. Taking the value type from the converter's own JsonConverter<T> base would make both explicit.

private static Type? ConverterValueType(Type converterType)
{
    for (Type? t = converterType; t is not null; t = t.BaseType)
        if (t.IsGenericType && t.GetGenericTypeDefinition() == typeof(JsonConverter<>))
            return t.GetGenericArguments()[0];

    return null;
}