Fix multiple OpenRPC schema issues

[onmax]

I have an automation that checks the JSON schema specification against my TypeScript (TS) library. I perform a lot of validations to ensure that my TS library is up to date. At the end of the process, I also use GPT-5 to validate the implementation with an LLM (https://github.com/onmax/albatross-rpc-client-ts/blob/main/scripts/validate-schema.ts#L237-L264). I run this validation once a month.

Yesterday, I fixed the problems that the AI found in my library. See closed issues: https://github.com/onmax/albatross-rpc-client-ts/issues?q=sort%3Aupdated-desc%20is%3Aissue%20state%3Aclosed. However, there are some issues that are part of the JSON schema generation process. This PR attempts to address these issues.

For each fix, you will see all the affected methods with two links:

1. The first link is to the Dev Center with the 'official' JSON schema.
2. The second link is to the Dev Center with the fixed JSON schema, making it easy to compare.

Important

The code written in this PR has been 100% AI. Maybe it is not the most optimal solution!

Summary

Fixes #3499, #3500, #3501, #3503, #3504, #3505 - Multiple OpenRPC schema corrections

This PR fixes 6 issues in the OpenRPC schema generator to accurately reflect the actual Rust implementation.

Changes

#3500: Optional parameters (565d67e)

📋 Details

Issue: Option<T> parameters always marked as required
Fix: Enable nullable params by checking for Option wrapper with AST-based detection (tools/src/rpc-schema/parser.rs:273)
Example: new_signing_secret_key: Option<String> now has required: false

Affected:

• Before: createUpdateValidatorTransaction, sendUpdateValidatorTransaction
• After: createUpdateValidatorTransaction, sendUpdateValidatorTransaction

Schema Comparison:

Parameter	Before (❌ Incorrect)	After (✅ Fixed)
newSigningSecretKey	"required": true	"required": false
newVotingSecretKey	"required": true	"required": false
newRewardAddress	"required": true	"required": false
newSignalData	"required": true	"required": false

#3501: Underscore field names (8fbfd4b)

📋 Details

Issue: Fields like _0, _1 converted to "0", "1" in schema
Fix: Preserve underscore prefixes, only camelCase other fields (tools/src/rpc-schema/parser.rs:50, 160)
Example: MempoolInfo now has "_0", "_1" fields

Affected:

• Before: mempoolContent
• After: mempoolContent

Schema Comparison:

Field	Before (❌ Incorrect)	After (✅ Fixed)
Fee bucket 0	"0": { "type": "number" }	"_0": { "type": "number" }
Fee bucket 1	"1": { "type": "number" }	"_1": { "type": "number" }
Fee bucket 2	"2": { "type": "number" }	"_2": { "type": "number" }
Fee bucket 5	"5": { "type": "number" }	"_5": { "type": "number" }

#3503: BitSet type mapping (a4ab5c8)

📋 Details

Issue: BitSet mapped as object instead of array
Fix: Map BitSet as array of numbers (tools/src/rpc-schema/parser.rs:87, 133)
Example: disabled: BitSet now generates { "type": "array", "items": { "type": "number" } }

Affected:

• Before: getCurrentPenalizedSlots, getPreviousPenalizedSlots
• After: getCurrentPenalizedSlots, getPreviousPenalizedSlots

Schema Comparison:

Property	Before (❌ Incorrect)	After (✅ Fixed)
Type	"object"	"array"
Items	(not specified)	{ "type": "number" }
Example Value	(would be {})	[] or [5, 12, 33]

#3504: ValidityStartHeight union type (25b86ce)

📋 Details

Issue: ValidityStartHeight only accepts number, but deserializer supports string ("+N" syntax)
Fix: Use oneOf to accept both string and number (tools/src/rpc-schema/parser.rs:429)
Example: validityStartHeight now accepts "string" or number

Affected:

• Before: createBasicTransaction, and all other transaction methods
• After: createBasicTransaction, and all other transaction methods

Schema Comparison:

	Before (❌ Incorrect)	After (✅ Fixed)
Type	"number" only	oneOf: ["string", "number"]
Accepts	1000000 ✅ "+150" ❌	1000000 ✅ "+150" ✅

#3505: RPCData envelope (25b86ce)

📋 Details

Issue: Results documented as raw values, but server wraps in { data, metadata }
Fix: Generate object schema with data and metadata properties, including required fields (tools/src/rpc-schema/parser.rs:344)
Example: All method results now show RPCData envelope structure with required fields

Affected:

• Before: All RPC methods (e.g., getBlockNumber)
• After: All RPC methods (e.g., getBlockNumber)

Schema Comparison:

Property	Before (❌ Incorrect)	After (✅ Fixed)
Result Type	"number" (direct value)	"object" (envelope)
Properties	(none)	data + metadata
Required Fields	(not specified)	["data", "metadata"]
Example Response	31832934	{ "data": 31832934, "metadata": null }

Bonus fix: Generic type panic (25b86ce)

📋 Details

Issue: Parser panicked on non-Path generic arguments (e.g., tuple types)
Fix: Handle all generic argument types gracefully (tools/src/rpc-schema/parser.rs:549)

Schema Comparison

Files available at: https://github.com/nimiq/developer-center/pull/158/files#diff-0c6879564246475a0e967d833463378cb40a07da8cdb8561884cf920f3c98475