docs: document per-spec release scope and versioning

[odednaor]

Changes

The problem. All specs here share one version number, but a release usually changes only one of them. 0.10.3 and 0.10.4 changed only the wallet API, yet appeared to supersede the 0.10.2 that up-to-date full nodes correctly report — so a load-balanced RPC serving both Pathfinder and Juno returned different spec versions, and consumers read the lower one as out of date.

What this documents:

• README.md — which specs this repo publishes, which call advertises each, and the version each is currently at.
• api/release.md — a Release Scope section: each release changes exactly one spec, release notes state which one, and an implementation bumps the version it advertises only when a release changes the spec it implements. Applies from v0.10.4 onward.
• starknet_specVersion, wallet_supportedWalletApi, wallet_supportedSpecs — the same distinction stated where implementers actually read it, rather than only in the release-process doc.

Editorial only — no schema, type, or wire format changes, so no version bump. Same category as the PROOF/PROOF_FACTS extraction in 0.10.3.

Checklist:

• Validated the specification files - npm run validate_all
• Applied formatting - npm run format
• Performed code self-review
• Checked if this PR resolves any issues
• If making a new release, check out the guidelines

🤖 Generated with Claude Code

[CHr15F0x]

@odednaor , also looking at your general comment:

starknet_specVersion wording. (...) so the wire format is unchanged and 0.10.2 remains correct. The README scopes the rules to v0.10.4 onward, which covers this, but say the word if you'd rather the method text spell out that editorial changes don't count.

IMO it should be explicitly stated that editorial changes don't count. Otherwise there still is ambiguity. I.e. spec changes transparent to the node should not require the spec version to be bumped, because the implementation does not change.

[odednaor]

@CHr15F0x Do you have a suggestion on how to phrase it?

[CHr15F0x]

How about:

Returns the version of the full node JSON-RPC specification that this node implements. This is the version of the most recent specification release that changed the full node JSON-RPC API in a way that required changes to the node implementation. Changes that are transparent to the node implementation, such as editorial changes or specification refactoring that does not require any implementation change, do not affect the reported version.

[CHr15F0x]

Consumers treating the advertised version as a minimum is not stated anywhere in this PR. It was the other half of the discussion — relevant to strict version checks like the one in starknet-go. Worth adding, or intentionally left out?

If this is the de facto expectation placed on consumers, then I’d opt for an explicit statement.

[odednaor]

Consumers treating the advertised version as a minimum is not stated anywhere in this PR. It was the other half of the discussion — relevant to strict version checks like the one in starknet-go. Worth adding, or intentionally left out?

If this is the de facto expectation placed on consumers, then I’d opt for an explicit statement.

@CHr15F0x, I removed this question from the discussion. As agreed, Full Nodes should only return the latest release that changed the JSON RPC spec.