fix(sdk)!: version the non-unique identity lookup so 4.1 clients keep working

book/src/sdk/identity-keys.md

@@ -444,25 +444,54 @@ let identity_ids = drive.fetch_identity_ids_by_non_unique_public_key_hash(
 
 `getIdentityByNonUniquePublicKeyHash` returns the first matching identity in
 lexicographic identity-ID byte order. `start_after` is exclusive; use the returned
-ID to fetch the next match. A proved response contains one standard `Proof`
-(result field 4). It proves the complete index prefix through that identity and
-all its keys, balance and revision at the same signed root. An absent hash or
-exhausted cursor proves the entire remaining range is empty. A missing identity
-referenced by the index is a proof error, rather than an empty result.
+ID to fetch the next match. The request version chooses the shape of a proved
+answer:
+
+| Request | Proved answer | Served from |
+|---|---|---|
+| V0 | Separate index and identity proofs (`IdentityProvedResponse`, result field 2), as 4.1 nodes send | every protocol version |
+| V1 | One standard `Proof` (result field 2 of response V1) | protocol 14 |
+
+The V0 index proof proves exactly the first index entry after the cursor, or that
+there is none; the identity proof proves that identity's keys, balance and revision.
+Both must have the same root, and an identity proof without an index entry, or an
+index entry without its identity, is a proof error. The V1 proof proves the complete
+index prefix through that identity and all its keys, balance and revision at one
+root. In both shapes an absent hash or exhausted cursor proves the remaining range
+is empty, and a missing identity referenced by the index is a proof error, rather
+than an empty result. Unproved answers (result field 1) are the same in both
+versions.
+
+The response version must equal the request version. The quorum signature covers
+the state, not the envelope, so the SDK refuses an answer of the other version
+instead of reinterpreting it, and the request moves to another node. For a V0
+answer the signed proof is the index proof; `fetch_with_metadata_and_proof` returns
+it, and independent replay of the full verification needs both original blobs.
 
 Clients reconstruct the query using the producer protocol version in signed
-metadata and retain their verification security floor. Unsupported future query
-versions require an SDK update and fail closed. The Rust SDK still returns
-`Option<Identity>`; high-level WASM/JavaScript APIs retain their existing result
-shape. The direct WASM verifier takes one proof blob and returns a root that the
-caller must authenticate independently.
-
-The nested double-proof response (retired field 2) has been removed with no
-fallback. Stable v4.1.1 clients and nodes use that old format and are incompatible
-with this proved endpoint during a mixed rollout. Update clients and nodes
-together; mismatched or unsupported-future-version responses can trigger the
-existing SDK retry and node-ban behavior. Unproved response field 1 and the
-request fields remain unchanged.
+metadata and retain their verification security floor. A producer version newer
+than the SDK is read with the newest query rules the SDK knows; the proof must
+still rebuild the signed root. An absence answer can still verify at an index
+location a newer protocol no longer uses, so relocating this index needs an SDK
+update. The Rust SDK still returns `Option<Identity>`;
+high-level WASM/JavaScript APIs retain their existing result shape. The direct
+WASM verifier takes one V1 proof blob and returns a root that the caller must
+authenticate independently.
+
+**How the SDK picks the request version.** A node that refuses a request version
+is banned for every method, so the SDK sends V1 only when two versions both select
+it: its stored protocol version, and the highest protocol version it has seen in a
+verified, signed answer. Until it has verified one, it sends V0, which every node
+serves. A seeded, pinned or persisted version alone therefore never sends V1 to a
+network that may still run protocol 13. On a network that has just activated
+protocol 14, a node that has not reached the activation block yet refuses V1.
+Each refusal bans it again, for longer each time, until it catches up and answers.
+
+**Older clients.** 4.1.x clients and 5.0 betas up to beta.4 send only V0 and read
+only result field 2, so 4.1 nodes and every node from 5.0.0-rc.8 on answer them,
+before and after protocol 14 activates. The 5.0 prereleases from beta.5 to rc.7
+sent V0 and expected the proof at field 4, which nodes from rc.8 on no longer send;
+they must update.
 
 **Fetch all keys for an identity:**
 ```rust

book/src/versioning/feature-versions.md

@@ -490,10 +490,18 @@ diff:
 ```rust
 // packages/rs-platform-version/src/version/drive_abci_versions/drive_abci_query_versions/v2.rs
 
-/// Differs from v1 in two slots.
+/// Differs from v1 in three slots.
 /// `document_query_helpers.compute_aggregate_mode_and_check_limit` is 2
 /// rather than 0: the ranked and boolean-`HAVING` routing gate. ...
 pub const DRIVE_ABCI_QUERY_VERSIONS_V2: DriveAbciQueryVersions = DriveAbciQueryVersions {
+    identity_based_queries: DriveAbciQueryIdentityVersions {
+        identity_by_non_unique_public_key_hash: FeatureVersionBounds {
+            min_version: 0,
+            max_version: 1,
+            default_current_version: 1,
+        },
+        ..DRIVE_ABCI_QUERY_VERSIONS_V1.identity_based_queries
+    },
     document_query_helpers: DriveAbciDocumentQueryHelperVersions {
         compute_aggregate_mode_and_check_limit: 2,
     },

packages/dapi-grpc/build.rs

@@ -191,9 +191,11 @@ fn configure_platform(mut platform: MappingConfig) -> MappingConfig {
     // - "GetConsensusParamsResponse"
     // - "GetStatusResponse"
     //
+    // The following responses are excluded as they need custom proof handling:
+    // - "GetIdentityByNonUniquePublicKeyHashResponse" (V0 carries two proofs)
+    //
     //  "GetEvonodesProposedEpochBlocksResponse" is used for 2 Requests
-    const VERSIONED_RESPONSES: [&str; 67] = [
-        "GetIdentityByNonUniquePublicKeyHashResponse",
+    const VERSIONED_RESPONSES: [&str; 66] = [
         "GetContractModerationStatusResponse",
         "GetContractModerationEntriesResponse",
         "GetContractDocumentRemovalsResponse",
@@ -283,7 +285,10 @@ fn configure_platform(mut platform: MappingConfig) -> MappingConfig {
     //   - Bumping the matching `FeatureVersionBounds.max_version`
     //     to 1 in `rs-platform-version`.
     //   - Implementing the v1 dispatch arm in `drive-abci`.
-    const VERSIONED_AT_V1_REQUESTS: [&str; 1] = ["GetDocumentsRequest"];
+    const VERSIONED_AT_V1_REQUESTS: [&str; 2] = [
+        "GetDocumentsRequest",
+        "GetIdentityByNonUniquePublicKeyHashRequest",
+    ];
     const VERSIONED_AT_V1_RESPONSES: [&str; 1] = ["GetDocumentsResponse"];
 
     // Derive VersionedGrpcMessage on requests