[ma2bd]

Motivation

linera-version/api-hashes.json had not changed since #2347 (2024-08-03), even though the RPC snapshot, the GraphQL schema and the WIT files all changed since — main and testnet_conway shipped the same three hashes despite having different WIT files. Two things kept it that way:

• tests/up_to_date.rs compared VersionInfo::get() against VersionInfo::default(). The latter is baked in by build.rs, which calls the same trace_get, so in a workspace checkout both sides were computed from the live files and the file was never consulted. The test could not fail.
• The command it recommended, cargo run -p linera-version > linera-version/api-hashes.json, truncates the file before the binary starts, and trace_get read it eagerly, so regenerating failed with JSON error: EOF while parsing a value at line 1 column 0.

The deeper question is whether the file should exist. It is read only when the API source files cannot be found, which happens in exactly one situation: trace_get runs cargo metadata from linera-version's own directory, and in a published crate that resolves the package standalone, without linera-rpc, linera-sdk or linera-service-graphql-client in the graph. In that situation the recorded hashes are a constant of the release — a pure function of crate_version, which the peer already receives — so they carry no information. Worse, with one frozen file every registry build of every version reported the same triple, and is_compatible_with accepts when api_hashes() match, so unrelated builds declared each other compatible. Missing information was being turned into a forged match.

Proposal

Make the hashes Option, absent when they cannot be computed, and delete the file.

• rpc_hash, graphql_hash and wit_hash become Option<Hash>; ApiHashes fields become Option<String>.
• is_compatible_with requires the hashes to be known before comparing them, so absent never means equal. It still falls through to the semver arm, which is the right answer for a build that cannot attest its own API surface.
• Display and linera wallet/query-validator output print unknown for an absent hash.
• Over gRPC an unknown hash travels as the empty string, so rpc.proto is unchanged.
• Deleted: api-hashes.json, tests/up_to_date.rs, and src/main.rs, whose only purpose was regenerating the file. anyhow is no longer used by the crate.
• Added tests/compatibility.rs covering the rule the old test was meant to protect.

This changes the BCS encoding of RpcMessage::VersionInfoResponse (variant 22), so the format snapshot is updated. That is why this is not backported as-is: on testnet_conway the same change would alter a wire format on a live network and flip the RPC hash, so #6819 keeps the file there and only makes it verified.

Test Plan

• cargo test -p linera-version — the new tests pin that identical known hashes still bridge a patch gap, and that unknown hashes never establish compatibility while leaving the semver arm intact.

• Packaged the crate and built it standalone, to reproduce a published-crate build:

  Linera protocol: v0.16.0
  RPC API hash: unknown
  GraphQL API hash: unknown
  WIT API hash: unknown
  

  Previously this reported the three constants from August 2024.

• cargo check --workspace --all-targets, pinned-nightly cargo fmt, cargo clippy --all-targets --all-features on linera-version/linera-rpc/linera-client, taplo fmt --check and cargo machete are clean.

Release Plan

• Nothing to do / These changes follow the usual release cycle.

Links

• Check linera-version's API hash cache in CI and make it regenerable #6819 keeps the file verified on testnet_conway, where the wire change is not acceptable.
• Related: Add names and semantic versioning to application ABIs #773 (semantic versioning for application ABIs), Generalize version checks to catch more failure scenarios #2268 (generalize version checks).
• reviewer checklist

🤖 Generated with Claude Code