v1.1.0

v1.1.0 — 2026-07-02

Highlights

Smart Router v1.1.0 introduces a breaking change to its wire contract by renaming all gRPC service names and telemetry prefixes to smartrouter, requiring operators to upgrade any unmodified Lava peers to maintain interoperability. For production orchestration, this release adds standard Kubernetes /livez and /readyz health probes alongside new diagnostic endpoints, such as GET /debug/runtime-config, to inspect the active configuration state. Operators can now manually clear error states and recover upstream connections using the newly introduced /debug/reset-all and /debug/reset-endpoint-health routes. Routing behavior receives critical fixes, ensuring the gateway correctly fails over from a pinned provider during retries and accepts WebSocket subscriptions even when parameters are omitted. Finally, the release artifacts now include signed SBOMs for supply chain verification, and the bundled configuration examples have been rewritten to demonstrate multi-source cross-validation across networks like Ethereum, Solana, and Bitcoin.

Changes

⚠ Breaking changes

• refactor: rebrand gRPC service names + telemetry to smartrouter (#182) 711679f
  • the gRPC service name is a wire contract with upstream providers/cache; a renamed router no longer interops with unmodified Lava peers.

New Features

• feat(smart-router/debug): recover endpoint health in /debug/reset-all + add /debug/reset-endpoint-health (#144) e01b492
• feat(examples): multi-source CV examples + cross-validation doc (#171) 69d3f44
• feat(examples): retarget example chains to ETH/SOL/BTC/Hyperliquid/Cosmos/Aptos, drop Lava endpoints (#173) 5f72982
• feat(smart-router/debug): add GET /debug/runtime-config (#139) 177b408
• feat(release): two-stage release flow — born prerelease, graduate to move :latest (#180) 523b4ec
• feat(metrics): add /livez + /readyz k8s health probes (#184) 249f35d
• feat(release): allow forcing changelog regen for a recreated tag (#186) 1207705

Bug fixes

• fix(smart-router): fail over from a pinned provider on retry (MAG-2228) (#170) 2f5a784
• fix(examples): allow plaintext gRPC for Polkachu Cosmos upstream (#173) cb5e7d8
• fix(examples): drop Polkachu's non-existent tendermint websocket leg (#173) 9a0930b
• fix(chaintracker): guard nil oldBlockCallback in notUpdated (MAG-2219) (#177) ab65426
• fix(smart-router): accept WS subscriptions with omitted params (MAG-2246) (#176) 7b7fe87
• fix(ci): pin govulncheck to repo-checkout: false (#181) 2968fa5
• fix(ci): run govulncheck directly instead of via wrapper action (#181) f26c3be
• refactor: rebrand gRPC service names + telemetry to smartrouter (#182) 711679f
• fix(release): ship SBOMs by scoping to binary artifacts + sign them (#185) 2b7ccba

Documentation updates

• docs(license): fix inverted defined term for Enterprise uses (#174) c08200d
• docs(contributing): grant commercial relicensing rights on contributions (#174) 86b2d82
• docs: fill empty contact placeholders (#174) 5ceb840
• docs(contributing): drop empty "Join The Project Team" stub (#174) 7bb078e
• docs(license): add SPDX LicenseRef identifier (#174) 4b98860
• docs(license): split commercial terms into LICENSING.md so GitHub detects PolyForm (#175) bdc4864
• docs(readme): align messaging with docs site (#178) 3725826
• docs(readme): add license note + update banner alt text (#178) 374e4a3
• docs(readme): remove license note from top (keep alt text update) (#178) 74d0ed7
• docs: add AI agent setup instructions (#179) c3456d8

Build process updates

• ci: move internal cluster host to a repo variable (#174) 7b559d7

Other work

• Update README.md (#183) 435614e

v1.0.5

v1.0.5 — 2026-06-28

Highlights

Smart Router v1.0.5 introduces an interactive configuration wizard to assist operators in generating upstream routing definitions and gateway settings. To support this setup process, the release now bundles a complete set of example configuration files for all supported chains. Once configured, integrators can validate their deployments using the new smartrouter health CLI command, which executes spec-driven diagnostic checks against the running instance. Finally, this release resolves a cross-origin request bug by ensuring the gateway correctly emits the Access-Control-Allow-Headers: * response header whenever the cors-headers configuration field is empty.

Changes

New Features

• feat(health): add spec-driven smartrouter health CLI command (#140) 5b5679b
• feat(wizard): interactive Go/Charm config wizard for smart-router (#142) 7b71b38
• feat: add example configs for all bundled chains (#160) 89cf8ff

Bug fixes

• fix(cors): emit Access-Control-Allow-Headers "*" when cors-headers is empty (#145) 215c8f4
• fix: correct license typo (#148) 1453612

Documentation updates

• docs(provider-optimizer): correct stale availability-cliff comments (0.90 -> 0.80) (#141) 9774263
• docs(readme): align docker pull docs with public release (#148) e776280

Build process updates

• ci: trigger PR gate after approval (#156) ea5763d
• ci: run PR gate directly after approval (#161) 4be0d2f
• ci: fix PR gate YAML indentation (#162) c8f0998
• ci: restore PR gate approval dispatcher (#164) 21ecc36
• ci: strip legacy concurrent-providers arg in PR gate (#166) de80bed
• ci: fix concurrent-providers YAML indentation (#167) 1f24ae4
• ci: strip legacy provider optimizer args in PR gate (#168) 3875aab
• ci: fix legacy arg stripping in PR gate (#169) 4eff13d

v1.0.4

v1.0.4 — 2026-06-22

Highlights

Smart Router v1.0.4 introduces critical breaking changes to observability and configuration, requiring operators to update dashboards, alerts, and startup scripts before upgrading. All Prometheus metrics have been stripped of the legacy lava prefix, meaning any monitoring infrastructure referencing lava_rpc* or the specific lava_errors_total counter must be migrated to the new smartrouter_* and rpc_* namespaces, with errors now tracked under smartrouter_errors_total. Additionally, the default OpenTelemetry service.name has been changed from lava-rpcsmartrouter to smartrouter, which will break existing trace filtering and aggregation if not adjusted in collector configurations. Finally, the CLI flags used to tune upstream routing weights have been renamed; operators must replace all instances of provider-optimizer-* weight flags with their new qos-* equivalents to prevent unrecognized flag errors during startup.

Changes

⚠ Breaking changes

• refactor!: drop the lava prefix from smart-router metric names (#138) 4e21206
  • All Prometheus metric names emitted by the smart router are renamed. Any dashboard, alerting rule, recording rule, or scrape relabeling that references the old lava_rpc* names must be updated to the new smartrouter_* / rpc_* names. The default OTel service.name also changes from "lava-rpcsmartrouter" to "smartrouter".
• refactor!: rename lava_errors_total -> smartrouter_errors_total (#138) bce3a24
  • The lava_errors_total Prometheus counter is renamed to smartrouter_errors_total. Dashboards/alerts referencing the old name must be updated.
• refactor(flags)!: rename provider-optimizer-* weight flags to qos-* (#137) abe524c

Bug fixes

• fix(ci): align dev-sim-prtests naming (#130) f60a314
• refactor!: drop the lava prefix from smart-router metric names (#138) 4e21206
• refactor!: rename lava_errors_total -> smartrouter_errors_total (#138) bce3a24
• refactor(flags)!: rename provider-optimizer-* weight flags to qos-* (#137) abe524c

Documentation updates

• docs: fix stale lava_errors_* section header in METRICS.md (#138) 028f9dc

v1.0.3

v1.0.3 — 2026-06-21

Highlights

Smart Router v1.0.3 introduces two breaking changes that require immediate operator action: the --geolocation CLI flag has been removed entirely, and the deprecated static-providers: and backup-providers: YAML configuration keys are no longer read. Invocations passing --geolocation will now fail with an "unknown flag" error, and operators must rename the legacy configuration keys to direct-rpc: and backup-direct-rpc: to prevent startup failures, while also updating any dashboards that rely on the dropped geo_location attribute in optimizer-QoS metrics. Beyond these breaking changes, this release implements a group-aware cross-validation engine that evaluates responses across diverse provider sets using per-method policies, exposing validation failures through a new disagreeing-providers header and dedicated mismatch metrics. WebSocket connections now support JSON-formatted requests and assign unique wire IDs to safely multiplex concurrent calls without re-dialing closed sockets. Connection resilience is adjusted by increasing the maximum consecutive connection attempts from 5 to 50 and removing the dead per-socket isHealthy selection gate, while the provider optimizer now calculates sync scores using per-endpoint blocks. Finally, the /debug/pprof endpoint is no longer exposed on the cache metrics port to prevent unintended profiling access.

Changes

⚠ Breaking changes

• chore!: remove geolocation entirely from smart-router (#134) [afe1805]
  • the --geolocation CLI flag is removed. Invocations that pass --geolocation will now fail with "unknown flag". The emitted optimizer-QoS metric also drops its geo_location attribute. Update any scripts, deployments, or dashboards that reference them.
• chore!: drop deprecated static-providers/backup-providers config keys (#135) 1735bdc
  • smart-router no longer reads "static-providers:" or "backup-providers:" YAML keys. Configs still using them must rename to "direct-rpc:" / "backup-direct-rpc:" or the router fails to start with "requires direct-rpc endpoints configuration".

New Features

• feat(cross-validation): add provider group-label spine (Phase 0.1) (#102) [47a337a]
• feat(cross-validation): per-method policy resolver (Phase 1.1 core) (#102) [d8f6808]
• feat(cross-validation): wire per-method policy resolver into selection (Phase 1.1) (#102) 080d114
• feat(cross-validation): group-aware quorum termination + gate (Phase 1.2b/1.2c) (#102) 2388b8c
• feat(cross-validation): group-aware provider selection (Phase 1.2a) (#102) [8f7beab]
• feat(cross-validation): group + finality mismatch metrics (Phase 1.3) (#102) [9ed936d]
• feat(cross-validation): disagreeing-providers header + validation-set scope guard (#102) 0b2a3ac
• feat(cross-validation): per-group quorum (Phase 2.3) (#102) [ff0b56a]
• feat(cross-validation): close PRD-contract gaps + restore golangci-lint (#102) [e3ae66e]
• feat(rpcsmartrouter): warn when CV group-diversity rests on small groups (#102) [f9cd04c]
• feat(changelog): flag breaking changes in Highlights and Changes (#136) [eed776e]

Bug fixes

• fix(smart-router/health): stop gating selection on the per-socket isHealthy bit (#100) [e868552]
• refactor(smart-router/health): rip out the dead per-socket healthy bit & its debug reset (#100) [4f5f208]
• fix(smart-router/health): guard against a nil direct-connection element (#100) [39bbe65]
• fix(protocol/lavasession): increase max consecutive connection attempts from 5 to 50 (#100) 1c67b2f
• fix(cross-validation): address Phase 0/1.1 review findings (#102) [5d2cff8]
• fix(cross-validation): tighten min-groups capacity, float parsing, guard fail-closed (#102) [6bab82c]
• fix(cross-validation): diverse-quorum selection, post-filter capacity, failure reason (#102) [ae4c7ba]
• fix(cross-validation): preserve response hashes + scope mismatch metric to outliers (Section 1.3) (#102) [513409a]
• fix(cross-validation): surface failure-reason header on request-time fail-fast (#102) [cd4f5ad]
• fix(cross-validation): set fail-fast reason on all-sessions-failed-consistency path (#102) [e675c83]
• fix(cross-validation): per-group selection prefers groups that can reach threshold (#102) [6940865]
• fix(cross-validation): per-group nil-reply early-exit + runtime capacity guards (#102) [d8bafac]
• fix(cross-validation): count request-time fail-fast in CV metrics; doc accuracy (#102) [b6f7244]
• fix(scripts): correct make target and config path in setup scripts (#102) [584925f]
• fix(scripts): point UC-1 test at reachable Lava mainnet endpoint; keep router up (#102) [e2aea61]
• fix(cross-validation): close 4 review findings (caller policy weakening, dropped pin, failure-reason + outlier mislabels) (#102) [8e05be4]
• fix(cross-validation): close review findings 5-7 (header MinGroups default, nil early-exit, fail-fast reason precedence) (#102) [ffa38d6]
• fix(relaycore): canonicalize response before cross-validation hashing (#102) [b154d8b]
• refactor(cross-validation): drop intPtr helper for Go 1.26 new(expr) (#102) 22e51f9
• refactor(cross-validation): extract default group label into a constant (#102) [8daa448]
• refactor(lavasession): name the group-blind selection sentinels (#102) [f030eca]
• refactor(relaycore): name the no-cross-validation default knob value (#102) [c81a8b5]
• refactor(relaycore): extract selectQuorumWinner with unit tests (#102) 1b929b0
• refactor(rpcsmartrouter): require integer cross-validation knobs (#102) [5984395]
• refactor(rpcsmartrouter): extract policyKeySeparator constant (#102) 3687599
• refactor(rpcsmartrouter): filter policies by key prefix, not split-compare (#102) [e33eac9]
• fix(cross-validation): reconcile main's CV-mode hashing gate + test signatures after rebase (#102) [f925ac0]
• fix(cache): stop exposing /debug/pprof on the cache metrics endpoint (#128) 10d8464
• fix(provider-optimizer): use per-endpoint block for sync-score (MAG-1748) (#132) [d329b9c]

Documentation updates

• docs(smart-router/health): note the nil-connection guard is defensive (#100) [e57a7b2]
• docs(smart-router/health): spell out the 5→50 backoff leniency tradeoff in the relay-path comment (#100) [3a79c18]
• docs(cross-validation): document CV config, headers, outlier behavior (Phase 2.4) (#102) [61f94fa]
• docs(cross-validation): tighten outlier-behavior accuracy (#102) [6aaef2e]
• docs(metrics): note structural fail-fasts in CV requests/failed totals (#102) [e1a994f]
• docs(relaycore): name common.DefaultProviderGroup in group-folding comments (#102) [df053f3]
• docs(lavasession,rpcsmartrouter): name common.DefaultProviderGroup in group comments (#102) [ba03abc]

Build process updates

• ci: validate PR artifact on dev-sim-prtests (#123) [fe45489]
• ci: rename dev-sim PR validation workflow (#124) 171cfca
• ci: add dev-sim runtime PR validation (#125) [9264e2a]
• ci: add dev-prtests Kubernetes rollout validation (#126) [a15654c]
• ci: run automation readiness in PR gate (#127) [58d64d5]

Other work

• add support for send request as json format to websocket (#68) [92c4013]
• Enhance WebSocketDirectRPCConnection to support unique wire IDs for concurrent requests and ensure closed connections do not re-dial. Added tests for concurrent requests with the same caller ID and verified behavior after connection closure. (#68) [7688977]
• solana init enviroment scripts (#100) 14c3dd9
• docs+test(cross-validation): correct mismatch metric text + glue test (Section 1.3 P3) (#102) [4ffb1fa]
• style(relaycore): gofmt import ordering in two files (#102) [77c70f6]
• chore!: remove geolocation entirely from smart-router (#134) [afe1805]
• chore!: drop deprecated static-providers/backup-providers config keys (#135) 1735bdc

v1.0.2

v1.0.2 — 2026-06-18

Highlights

Smart Router v1.0.2 transitions telemetry to an OpenTelemetry usage pipeline, retiring legacy metrics flags like --show-provider-address-in-metrics and --optimizer-qos-listen while exposing optimizer scores by default. For live operations, the release introduces a debug-mode /debug/logs ring-buffer endpoint and /debug/reset-pairing, enabling SREs to rebuild provider pairings from configuration without restarting the gateway. Upstream routing behavior now correctly categorizes REST 501 responses as non-retryable NodeErrors, and new polling-relief flags allow operators to slow chain-tracker polling and widen the consistency gate to reduce node load. Caching and validation mechanics have been adjusted to isolate explicit lava-extension directives into dedicated cache lanes and canonicalize payloads prior to cross-validation hashing. Finally, integrators can evaluate the gateway using a new self-contained Docker Compose stack that mounts the live SR_CONFIG directly into the local dashboard.

Changes

New Features

• feat(docker): local compose stack + consolidate Dockerfiles under docker/ ebf77bd
• feat(config): EVM example configs (eth, multi-chain, cached) + specs 0294fb4
• feat(smart-router/debug): add /debug/reset-pairing to rebuild pairing from config ec51de4
• feat: add debug-mode-only /debug/logs ring-buffer endpoint ffcc2aa
• feat(docker): self-contained router + dashboard compose stack d4be733
• feat(docker): mount live SR_CONFIG into the dashboard, drop static topology e767abf
• feat(docker): enable dashboard local mode (localhost: URLs) 2cee8ea
• feat(chaintracker): polling-relief flags to slow polling + widen consistency gate 1a8a4a9
• feat: OTel usage pipeline + project-id rename + reporter-flow removal a9efff8

Bug fixes

• fix(rpcsmartrouter): read cache-be from config file too (via viper) c23ad57
• fix(rpcsmartrouter): treat REST 501 as a non-retryable NodeError (MAG-1576) a85ad21
• refactor(metrics): remove dead consumer & provider metrics managers e5e4c9d
• refactor(metrics): retire dead --show-provider-address-in-metrics flag aca7ec5
• refactor(metrics): always expose optimizer scores, drop --optimizer-qos-listen 7cced3b
• refactor(metrics): remove dead lava_health_* metrics server 717f8b5
• refactor(metrics): fold StartHTTPServer into NetworkAddress, gofmt fixup 9d58730
• fix(cache): give explicit lava-extension directives their own cache lane 793c0f8
• refactor(statetracker): drop dead ConsumerStateQuery stub f7d9a20
• refactor(statetracker): remove dead SpecUpdater + always-nil updater param 363d232
• fix: guard debug-buffer sink logger with atomic.Pointer 459ed13
• fix(rpcclient): adapt metrics.Timer to go-ethereum v1.17.0 efad27b
• refactor: remove standalone dead code (unreachable funcs) a8cca59
• refactor(common): remove zero-reference dead helpers 29c0890
• fix(chaintracker): read polling-relief flags after config-file load 3a811bc
• fix(lavasession): renew provider second chance after proven recovery 69491ec
• fix(relaycore): canonicalize response before cross-validation hashing 60826c1

Documentation updates

• docs(metrics): add metrics reference, link from README 1dbdb20
• docs(metrics): drop the Removed families section 5d7b609
• docs(metrics): fix stale source anchors and version comment 03e62fe
• docs(compose): add LOCAL-COMPOSE.md + link it from the README 36051f0
• docs(readme): document dashboard default credentials and overrides c079b6e
• docs(common): drop deleted LogCodedWarning from EmitErrorMetric doc fc436a8
• docs: document removed Kafka/reports/QoS-push flags as breaking cc15e8c
• docs: revert README OTel/Kafka migration table 13d9718
• docs: update source-available license and README notes 50ce5ab
• docs: move RELEASING and error-registry design into docs/ 8aa0347

Build process updates

• ci: add manual PR gate artifact build workflow (#109) 13f0333
• ci: add dev-sim-prtests preflight to PR gate workflow (#111) df90b81
• ci: add dev-sim-prtests preflight to PR gate workflow (#112) e207742
• ci: diagnose ssh key loading in preflight 11722a3
• ci: remove stale binary preflight check 830d443
• ci: validate PR artifact on dev-sim-prtests (#122) 312dbd6

Other work

• Add Dependabot configuration 3bd3380
• perf(relaycore): gate CV hashing on CrossValidation mode + guard trailing data 3bbd313

v1.0.1

v1.0.1 — 2026-06-02

Highlights

Smart Router v1.0.1 introduces the /debug/reset-scores endpoint, allowing operators to manually clear chain-tracker and connection-health state without restarting the gateway. This release resolves multiple WebSocket lifecycle bugs, ensuring the router correctly echoes subscription IDs and explicitly replies to eth_unsubscribe requests instead of hanging the client connection. Upstream routing behavior now properly preserves native Tendermint response fields and prevents gRPC connection pools from tearing down prematurely during probe context cancellations. To support larger payloads and complex queries, the underlying fasthttp ReadBufferSize has been increased to 128 KiB, and the Lava-Retries mechanism now safely absorbs parallel-batch failures. Finally, skipping the synchronous boot epoch tick removes a blocking operation during initialization, allowing the router to accept traffic faster upon startup.

Changes

New Features

• feat(rpcsmartrouter): clear chain-tracker and connection-health state on /debug/reset-scores (#58) 50d969c

Bug fixes

• fix(rpcsmartrouter): echo WS subscribe id + fix unsubscribe race (MAG-1824) (#43) 38c0635
• fix(rpcsmartrouter): preserve upstream Tendermint fields + clarify cleanup ownership (#43) 35fd886
• fix(grpc-connector): don't tear down pool on probe ctx cancellation (MAG-1926) (#54) fa3aabe
• fix(rpcsmartrouter): skip the synchronous boot epoch tick (MAG-1926) (#54) d316750
• fix(rpcsmartrouter): absorb parallel-batch failures in Lava-Retries (#55) 9d3f9fc
• fix(chainlib): reply to eth_unsubscribe instead of hanging the client (#56) f041230
• fix(chainlib): raise fasthttp ReadBufferSize to 128 KiB (#59) ebfbbab

Documentation updates

• docs(readme): make release badge auto-bump per release; switch to static URL (#53) 554cfb1

v1.0.0

v1.0.0 — 2026-05-19

Highlights

Smart Router v1.0.0 is the first stable release of Magma's multi-protocol RPC gateway: a single static binary (or multi-arch Docker image) that proxies JSON-RPC, REST, gRPC, and Tendermint RPC traffic against pools of QoS-scored upstream providers. Unlike generic L4/L7 load balancers, the router speaks each chain's wire format and applies RPC-aware semantics — caching by method and parameters, distinguishing transient timeouts from "block not yet produced", retrying against alternate providers on retryable failures, and backing off providers silently serving stale block data while still returning 200 OK.

Release artifacts ship with a verifiable supply chain: the SHA-256 checksum file is cosign-keyless-signed via GitHub Actions OIDC and Sigstore (no keys to manage; verification recipe in RELEASING.md), the multi-arch Docker image lives at ghcr.io/magma-devs/smart-router:v1.0.0, and native binaries target GOAMD64=v3 (Haswell+) and GOARM64=v8.2 (ARMv8.2+) for modern hardware.