feat(specs): update Starknet spec to JSON-RPC v0.9/v0.10 and WS subscriptions by EliasiOfir · Pull Request #2341 · lavanet/lava

EliasiOfir · 2026-10-16T07:12:42Z

Description

Closes: N/A

Updates the STRK and STRKS specs for Starknet 0.14.3 nodes (pathfinder v0.23+), which serve only JSON-RPC v0.9 and v0.10. Split out of #2318, which carries the runtime code.

Important

Merge gate. Merge only after:

feat(rpcclient): support Starknet v0.9+ websocket subscriptions #2318 is merged and released as protocol 6.2.9.
The STRK providers run 6.2.9 or later. Raising ProviderTarget/ProviderMin to 6.2.9 upgrades providers that run under lavavisor. The lavap binary itself doesn't enforce the minimum, so check the health monitor for STRK providers still off the target version.
Then merge this PR and submit the gov proposal. Restart the STRK providers once it passes: the node router is built at startup, so /rpc/v0_10 isn't served until a restart.

Until providers upgrade, starknet_subscribe* on an old provider either errors (by-name or omitted params, which is what starknet.js sends) or succeeds and then delivers no notifications (positional params). Anyone running --use-static-spec against main picks this spec up as soon as it merges.

Spec changes (STRK and STRKS)

Area	Change
Paths	Add `/rpc/v0_10` and `/ws/rpc/v0_10`. Remove `/rpc/v0_8` and `/ws/rpc/v0_8`, along with the `pending-block-support` check that lived there
New APIs	`starknet_getBlockWithReceipts` (20 CU), `starknet_getCompiledCasm` (100), `starknet_getMessagesStatus` (10), `starknet_getStorageProof` (20), `pathfinder_lastL1AcceptedBlockHashAndNumber` (20)
Subscriptions	`pathfinder_subscribe` / `pathfinder_unsubscribe` replaced by `starknet_subscribeNewHeads`, `starknet_subscribeEvents`, `starknet_subscribeTransactionStatus`, `starknet_subscribeNewTransactions`, `starknet_subscribeNewTransactionReceipts` (1000 CU each) and `starknet_unsubscribe` (10)
Removed APIs	`starknet_pendingTransactions`, `pathfinder_getProof`, `pathfinder_getTransactionStatus`
Parsing	`starknet_estimateFee` reads `block_id` from param index 2 (was 1)
Chain params	`average_block_time` 30000/32000 → 2000 ms (mainnet measures ~1.84 s per block). `allowed_block_lag_for_qos_sync` 2/1 → 5

The provider examples (config/provider_examples/strk*.yml and provider_example_cookbook/starknet_*.yml) now use the v0_9/v0_10 paths. TestJsonRpcInternalPathsMultipleVersionsStarkNet is updated to the new paths.

Consumer ↔ provider impact

No wire-format change. Both sides read the spec, so once it's live:

Change	Effect
Block time 30 s → 2 s	Tx-submit APIs (`starknet_add*Transaction`) get 4 s of extra relay timeout instead of 60 s. Providers already measure the real block time; consumers use the spec value, so this brings them in line
QoS lag 2/1 → 5 blocks	About 9 s of lag tolerated at real block speed, instead of about 4 s
`estimateFee` index	Changes the requested block the consumer sends in relays (caching, archive routing)
v0_8 removed	Calls to v0_8 fall back to the root (v0.9) collection. A provider with a stale v0_8 URL only logs a warning; a missing v0_10 URL is built from the root URL when the provider starts

Testing

go test ./x/spec/keeper/ -run '^TestSpecs$' (loads and validates every mainnet-1 and testnet-2 spec)
go test ./protocol/... ./x/spec/... passes on this branch by itself, without feat(rpcclient): support Starknet v0.9+ websocket subscriptions #2318's code

Author Checklist

All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.

I have...

read the contribution guide
included the correct type prefix in the PR title
confirmed ! in the type prefix if API or client breaking change (removes the v0_8 paths and legacy pathfinder APIs, which upstream nodes no longer serve)
targeted the main branch
provided a link to the relevant issue or specification
reviewed "Files changed" and left comments if necessary
included the necessary unit and integration tests
updated the relevant documentation or specification, including comments for documenting Go code
confirmed all CI checks have passed

Reviewers Checklist

All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.

I have...

confirmed the correct type prefix in the PR title
confirmed all author checklist items have been addressed
reviewed state machine logic, API design and naming, documentation is accurate, tests and test coverage

https://claude.ai/code/session_01NDkG48rHipQHQWQgcAGKM9

Starknet 0.14.3 nodes (pathfinder v0.23+) serve only JSON-RPC v0.9 and v0.10. Update the STRK and STRKS specs and the provider examples: - add /rpc/v0_10 and /ws/rpc/v0_10; drop /rpc/v0_8 and /ws/rpc/v0_8, including the pending-block-support check that lived there - add starknet_getBlockWithReceipts, starknet_getCompiledCasm, starknet_getMessagesStatus and starknet_getStorageProof - replace pathfinder_subscribe/pathfinder_unsubscribe with the starknet_subscribe* family and starknet_unsubscribe - drop starknet_pendingTransactions, pathfinder_getProof and pathfinder_getTransactionStatus; add pathfinder_lastL1AcceptedBlockHashAndNumber - parse starknet_estimateFee block_id from param index 2 - average_block_time 30000/32000 -> 2000 (mainnet measures ~1.84s) and allowed_block_lag_for_qos_sync -> 5 Split out of #2318. Merge only after #2318 is released and providers have upgraded: older providers accept starknet_subscribe* but drop every notification. Claude-Session: https://claude.ai/code/session_01NDkG48rHipQHQWQgcAGKM9

codecov · 2026-10-16T07:18:56Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

Flag	Coverage Δ
consensus	`8.97% <ø> (ø)`
protocol	`39.86% <ø> (-0.05%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 3 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

github-actions · 2026-10-16T07:31:06Z

Test Results

0 tests ±0 0 ✅ ±0 0s ⏱️ ±0s
0 suites ±0 0 💤 ±0
7 files ±0 0 ❌ ±0

Results for commit fb28059. ± Comparison against base commit 49c56ac.

♻️ This comment has been updated with latest results.

Gives the release with the Starknet v0.9+ subscription support its own protocol version, so ProviderMin/ProviderTarget can require it before the Starknet spec (#2341) goes live. Claude-Session: https://claude.ai/code/session_01NDkG48rHipQHQWQgcAGKM9

* feat: update starknet spec for Starknet 0.14.3 / JSON-RPC v0.10 Starknet 0.14.3 (and pathfinder v0.23.0, released 2026-07-20) removed JSON-RPC v0.8 and older; nodes now serve v0.9 (root default) and v0.10 (final v0.10.1 spec on the v0_10 routes). Update STRK and STRKS specs accordingly: - add /rpc/v0_10 and /ws/rpc/v0_10 collections (inheritance-only, mirroring the v0_9 pair) - remove the /rpc/v0_8 and /ws/rpc/v0_8 collections (RPC 0.8 removed by Starknet 0.14.3; pathfinder no longer serves these endpoints) - add missing spec methods: starknet_getBlockWithReceipts, starknet_getCompiledCasm, starknet_getMessagesStatus, starknet_getStorageProof - remove starknet_pendingTransactions (dropped from the RPC spec; no served version supports it) - replace the legacy pathfinder_subscribe/pathfinder_unsubscribe WS API (removed in pathfinder 0.18.0) with the spec WS subscription family: starknet_subscribeNewHeads/Events/TransactionStatus/NewTransactions/ NewTransactionReceipts + starknet_unsubscribe, one SUBSCRIBE parse directive per method (solana-style) - pathfinder extension collection: drop pathfinder_getProof and pathfinder_getTransactionStatus (removed in pathfinder 0.17.0, superseded by starknet_getStorageProof/starknet_getTransactionStatus), add pathfinder_lastL1AcceptedBlockHashAndNumber - average_block_time 30000/32000 -> 2000 for Starknet 0.14.x fast blocks (matches base/optimism convention for ~2s chains) Update TestJsonRpcInternalPathsMultipleVersionsStarkNet to the new path set and refresh the starknet provider example configs (v0_9/v0_10). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MC6w48eT5tW9K8iUNCm7PG * feat: support starknet v0.9+ ws subscription envelope in rpcclient The starknet_subscribe* APIs added to the spec need runtime support the node ws client lacked: - notifications use methods named starknet_subscriptionXxx with params {subscription_id, result}; none of the existing dispatch shapes (ethereum "_subscription" suffix, solana "Notification" suffix, legacy pathfinder top-level result) matched, so they were silently dropped. Add a dedicated predicate and handler keyed by params.subscription_id. - Client.Subscribe rejected the canonical starknet subscribe forms: by-name object params without a tendermint "query" key errored, and omitted params hit "unknown parameters type". Make "query" optional (tendermint-only) and accept nil params. Also apply spec calibration from review: starknet_estimateFee block_id positional index 1 -> 2 (v0.9/v0.10 params are [request, simulation_flags, block_id]) and allowed_block_lag_for_qos_sync -> 5, matching the base/optimism convention for ~2s block chains now that average_block_time is 2000. Adds predicate unit tests and an end-to-end mock-node websocket test covering object params, string subscription ids, envelope delivery and unknown-id drops. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MC6w48eT5tW9K8iUNCm7PG * fix: order subscription registration before unblocking Subscribe caller handleResponse sent op.resp <- msg before writing op.err and registering the subscription in clientSubs, racing with requestOp.wait which reads op.err immediately after receiving. On an error response the caller could observe a stale nil error and treat a failed subscription as successful. The race was previously unreachable in tests; the new starknet subscription end-to-end test tripped it deterministically under -race. Move all op.err writes and subscription registration before the op.resp send for subscription responses (matching upstream go-ethereum's ordering) while preserving this fork's behavior of returning the raw response message to the caller. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MC6w48eT5tW9K8iUNCm7PG * chore: move Starknet spec changes to their own PR Restore the STRK/STRKS spec, the Starknet provider examples and the Starknet internal-path test to main. They move to the ofir/starknet-spec-v010 PR, which must merge only after this code is released and providers have upgraded. This PR keeps the rpcclient runtime support. Claude-Session: https://claude.ai/code/session_01NDkG48rHipQHQWQgcAGKM9 * fix(consumer): match by-name unsubscribe params to subscriptions The consumer only matched an unsubscribe to its subscription when the id came positionally (["0x1"]). starknet.js sends starknet_unsubscribe by name ({"subscription_id": "0x1"}), which got "subscription not found" and left the subscription open until the websocket closed. When the raw params match nothing and they are a single-entry object with a string value, retry with that value. The raw match still runs first, so tendermint (whose id is the whole params object) is unchanged. Claude-Session: https://claude.ai/code/session_01NDkG48rHipQHQWQgcAGKM9 * fix(rpcclient): reject non-string tendermint query param Subscribe stopped erroring when by-name params carried a "query" that was not a string. That subscription then registered under the response id, while tendermint notifications are routed by query, so they were all dropped silently. Error again when "query" is present but not a string. When "query" is absent (starknet by-name params), the id still comes from the response. Claude-Session: https://claude.ai/code/session_01NDkG48rHipQHQWQgcAGKM9 * test(rpcclient): use TestComponent_Scenario names for Starknet tests Rename TestIsStarknetNotification and TestStarknetSubscriptionEndToEnd to TestStarknetNotification_Detection and TestStarknetSubscription_EndToEnd, per the repo's test naming convention. Claude-Session: https://claude.ai/code/session_01NDkG48rHipQHQWQgcAGKM9 * chore: bump protocol TARGET_VERSION to 6.2.9 Gives the release with the Starknet v0.9+ subscription support its own protocol version, so ProviderMin/ProviderTarget can require it before the Starknet spec (#2341) goes live. Claude-Session: https://claude.ai/code/session_01NDkG48rHipQHQWQgcAGKM9 --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Ignacio Rodriguez <ignacio.rsg@gmail.com>

qodo-code-review · 2026-10-27T08:15:11Z

Code Review by Qodo

Sorry, something went wrong

We weren't able to complete the code review on our side. Please try again manually by commenting /agentic_review on this PR.

qodo-code-review · 2026-10-27T08:15:34Z

PR Summary by Qodo

Update Starknet specs for JSON-RPC v0.9/v0.10 and subscriptions

✨ Enhancement ⚙️ Configuration changes 🧪 Tests 🕐 20-40 Minutes

AI Description

• Align STRK and STRKS paths, APIs, and WebSocket subscriptions with Starknet 0.14.3 nodes.
• Correct fee block parsing and block-time and QoS settings for current chain behavior.
• Update provider examples and path tests; deploy only after protocol 6.2.9 reaches providers.

Diagram

graph TD
  Spec["STRK/STRKS spec"] --> Parser["JSON-RPC parser"] --> Router["Provider router"] --> Node["Starknet node"]
  Spec --> WS["WS directives"] --> Router
  Examples["Provider examples"] --> Router
  Tests["Path tests"] --> Parser

High-Level Assessment

Updating the shared spec and matching provider examples is appropriate because both consumers and providers read the spec; retaining v0.8 would advertise paths the target nodes no longer serve. Treat the stated rollout order as a merge gate: release protocol 6.2.9, verify provider upgrades, then activate the spec and restart providers after governance approval.

Files changed (7) +381 / -167

Enhancement (1) +346 / -128

starknet.jsonAlign STRK and STRKS specs with current Starknet RPC +346/-128

Align STRK and STRKS specs with current Starknet RPC

• Adds supported RPC methods and Starknet WebSocket subscription directives, removes obsolete methods and v0.8 paths, and introduces v0.10 HTTP and WebSocket paths. Both chain definitions now parse the estimate-fee block identifier at index 2 and use a 2-second average block time with a five-block QoS lag allowance.

specs/mainnet-1/specs/starknet.json

Tests (1) +5 / -5

jsonRPC_test.goTest Starknet v0.9 and v0.10 HTTP path selection +5/-5

Test Starknet v0.9 and v0.10 HTTP path selection
• Updates the multiple-version parser test to assert that requests on the default, v0.9, and v0.10 paths select their matching API collections.
protocol/chainlib/jsonRPC_test.go

Other (5) +30 / -34

starknet_auto_complete_with_addon.ymlRefresh addon-enabled WebSocket version examples +4/-4

Refresh addon-enabled WebSocket version examples
• Changes the explicit WebSocket upstream paths from v0.7/v0.6 to v0.10/v0.9 while retaining trace addon configuration.
config/provider_examples/provider_example_cookbook/starknet_auto_complete_with_addon.yml

starknet_auto_complete_without_addons.ymlRefresh WebSocket version examples without addons +4/-4

Refresh WebSocket version examples without addons
• Replaces the explicit v0.7/v0.6 WebSocket paths with v0.10/v0.9 paths.
config/provider_examples/provider_example_cookbook/starknet_auto_complete_without_addons.yml

starknet_example_full_internal_path.ymlShow current HTTP and WebSocket internal paths +11/-13

Show current HTTP and WebSocket internal paths
• Replaces older versioned paths with v0.9 and v0.10 examples for both transports and maps the unversioned WebSocket URL to the empty internal path.
config/provider_examples/provider_example_cookbook/starknet_example_full_internal_path.yml

strk_addon_example_with_ws.ymlAdvance STRK WebSocket example paths +2/-2

Advance STRK WebSocket example paths
• Changes the OnFinality WebSocket internal paths to v0.10 and v0.9.
config/provider_examples/strk_addon_example_with_ws.yml

strk_example.ymlAlign STRK provider example with supported versions +9/-11

Align STRK provider example with supported versions
• Shows v0.9/v0.10 HTTP and WebSocket paths instead of older versions and uses the empty internal path for the unversioned WebSocket URL.
config/provider_examples/strk_example.yml

EliasiOfir · 2026-10-27T08:53:49Z

test-protocol failure on fb28059 isn't from this PR.

Failure: protocol/chainlib panicked with send on closed channel at rpcclient/subscription.go:317 during TestSubscriptionManager_MultipleParallelSubscriptionsWithTheSameParams/TendermintRPC.
Cause: a race already on main. Unsubscribe() closes sub.err without waiting for run() (since feat: Avalanche C and P chains specs #2247), and run() may still send on it. Since feat(rpcclient): support Starknet v0.9+ websocket subscriptions #2318, run() starts before the subscriber is unblocked, which widens the race window.
Why not this PR: this PR only changes the Starknet spec, example configs and one path test. ./protocol/... passes locally on this head, and main CI is green on 49c56ac.
Fix: none exists yet. Re-ran the failed jobs once.

Generated by Claude Code

EliasiOfir requested a review from Tomelia1999 October 16, 2026 07:12

pull-request-size Bot added the size/XL label Oct 16, 2026

github-actions Bot added C:protocol Team:Protocol C:specs labels Oct 16, 2026

EliasiOfir mentioned this pull request Oct 16, 2026

feat(rpcclient): support Starknet v0.9+ websocket subscriptions #2318

Merged

6 of 12 tasks

Merge branch 'main' into ofir/starknet-spec-v010

fb28059

EliasiOfir marked this pull request as ready for review October 27, 2026 08:15

EliasiOfir merged commit 132bb18 into main Oct 27, 2026
37 of 38 checks passed

EliasiOfir deleted the ofir/starknet-spec-v010 branch October 27, 2026 09:08

Navigation Menu

Repository navigation

feat(specs): update Starknet spec to JSON-RPC v0.9/v0.10 and WS subscriptions - #2341

feat(specs): update Starknet spec to JSON-RPC v0.9/v0.10 and WS subscriptions#2341
EliasiOfir merged 2 commits into
mainfrom
ofir/starknet-spec-v010

EliasiOfir commented Oct 16, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Oct 16, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 16, 2026 •

edited

Loading

Uh oh!

qodo-code-review Bot commented Oct 27, 2026 •

edited

Loading

Uh oh!

qodo-code-review Bot commented Oct 27, 2026

Uh oh!

EliasiOfir commented Oct 27, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

EliasiOfir commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Spec changes (STRK and STRKS)

Consumer ↔ provider impact

Testing

Author Checklist

Reviewers Checklist

Uh oh!

codecov Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results

Uh oh!

qodo-code-review Bot commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review by Qodo

Sorry, something went wrong

Uh oh!

qodo-code-review Bot commented Oct 27, 2026

PR Summary by Qodo

Uh oh!

EliasiOfir commented Oct 27, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

EliasiOfir commented Oct 16, 2026 •

edited

Loading

codecov Bot commented Oct 16, 2026 •

edited

Loading

github-actions Bot commented Oct 16, 2026 •

edited

Loading

qodo-code-review Bot commented Oct 27, 2026 •

edited

Loading