histsdk/docs/reverse-engineering/grpc-interface-versions.md

2023 R2 gRPC Interface-Version Integers (C3a)

Captured: 2026-06-25
Transport: 2023 R2 gRPC (h2c, unauthenticated GetInterfaceVersion RPCs — no credentials required)
Status: LIVE — integers captured from a real AVEVA Historian 2023 R2 server.

Captured Values

Service	UiVersion / Version	UiError / Error	Notes
History	12	0	Matches HistoryInterfaceVersionGrpc2023R2 = 12
Retrieval	4	0	Matches RetrievalInterfaceVersion = 4 (unchanged from 2020)
Transaction	2	0	Matches TransactionInterfaceVersion = 2 (unchanged from 2020)
Status	4	0	Reachability-only; version integer is not version-gated (see note)

Field-name note: The History, Retrieval, and Status proto responses use UiError/UiVersion fields. The Transaction response uses Error/Version (different naming convention in the proto). Both are captured correctly; the table uses a unified column header for readability.

Status note: StatusService.GetStatusInterfaceVersion returned UiVersion=4, UiError=0 on the live 2023 R2 server. This differs from the historical 0 observed on 2020 WCF — both are reachability-only. Status is classified as reachability-only: its version integer carries no semantic meaning for the SDK's byte serializers, so its UiVersion is not gated and not asserted in tests.

Evidence Test

tests/AVEVA.Historian.Client.Tests/GrpcInterfaceVersionEvidenceTests.cs — GrpcInterfaceVersions_LiveServer_MatchAcceptedSet reads these four RPCs live and asserts:

• history.UiError == 0 and history.UiVersion ∈ {11, 12}
• retrieval.UiError == 0 and retrieval.UiVersion == 4
• transaction.Error == 0 and transaction.Version == 2
• status.UiError == 0 (version not asserted)

The test skips silently when HISTORIAN_GRPC_HOST is absent.

Gap Closed

This document closes the C3a gap: "2023 R2 gRPC server-version integers not yet captured." Prior to this capture, the HistorianServerVersionGate accepted History=12, Retrieval=4, and Transaction=2 on the basis that they were inferred/expected-to-be-unchanged. All four integers are now confirmed from a live 2023 R2 server over the gRPC transport; no widening of AcceptedVersions is required (all captured values were already accepted).

The 2020 WCF baseline (History=11, Retrieval=4, Transaction=2) was captured earlier via the wcf-probe command and is documented in wcf-probe-remote-latest.json and wcf-contract-evidence.md.