Protocol v14 features (ranked aggregate indexes, document refersTo) have no JS client surface in wasm-sdk / evo-sdk #4402

Activity

1. thephez

   added

   enhancementNew feature or requestNew feature or request

   on Aug 13, 2026
2. PastaPastaPasta commented on Aug 13, 2026

   

   PastaPastaPasta

   on Aug 13, 2026 – with ChatGPT Codex Connector

   Member

   More actions

   Audited this against the latest upstream/v4.2-dev at 6495991c5e21f4f211ba326334ce3f717aaaf3bd.

   Summary

   This issue should stay open, but I think the refersTo wording should be narrowed. Ranked top-K is genuinely unavailable from the recommended JS SDKs. refersTo can already pass through the generic JS/WASM contract and document representations, but it has no first-class typing, introspection, documentation/test coverage, or rich error surface.

   There is also another protocol-v14 JS gap not mentioned here: aggregate HAVING queries from #4384.

   Confirmed: ranked top-K is not usable from JS

   The protocol and Rust client paths are present:

   • The v1 getDocuments grammar routes ranked shapes to ResultData.ranked.
   • rs-sdk exposes DocumentRankedEntries::fetch, aggregate ordering, limits, offsets, and proof verification.
   • The result preserves ordered entries plus the proof-attested starting_rank.

   The JS path stops before that:

   • wasm-sdk's DocumentsQuery exposes groupBy, but no explicit ranked selector and no document-query offset.
   • The existing aggregate methods call DocumentSplitCounts, DocumentSplitSums, and DocumentSplitAverages, not DocumentRankedEntries.
   • js-evo-sdk only wraps the ordinary count/sum/average methods; it has no ranked methods or ranked result type.

   The existing aggregate methods are not a usable workaround. A ranked-shaped request is answered by the server as ResultData.ranked, while those methods invoke the split-aggregate verifier/decoder. Pagination also cannot be expressed.

   The diff statement in the issue is still correct: from v4.1.0 to current v4.2-dev, the only packages/js-evo-sdk change is the package version bump. The count/sum/average facade methods predate v4.1.0 (they came from #3767), so their presence does not represent v4.2 ranked support.

   Correction: refersTo is usable generically, but lacks a first-class JS surface

   wasm-sdk uses wasm-dpp2, not the legacy wasm-dpp package.

   In wasm-dpp2:

   • DataContract accepts raw schemas: object, defaults to the desired/current platform version, and performs full schema validation.
   • The raw schema getter round-trips refersTo declarations.
   • Document.properties is Record<string, unknown>, so referenced identifiers and the sibling key ID property can be supplied normally.
   • documentCreate / documentReplace send those documents through the server-side state validation implemented by feat(platform)!: reference validation for documents (refersTo) #2993, feat(platform)!: permanent document references (refersTo permanentDocument) #4390, and feat(platform)!: identity public key references (refersTo identityPublicKey) #4397.

   So it is too strong to say references cannot be authored or broadcast from JavaScript. The missing pieces are:

   • TypeScript types for identity, contract, token, permanentDocument, and identityPublicKey targets.
   • Typed document-property/reference metadata inspection instead of requiring callers to inspect raw schemas.
   • JS round-trip and functional tests for all target types.
   • Examples and documentation.
   • Structured consensus errors. wasm-sdk preserves broadcast error codes 40120–40125, but drops the deserialized StateTransitionBroadcastError.cause; wasm-dpp2's generic ConsensusError exposes only message.
   • The typed ReferencedEntityNotFoundError added to legacy wasm-dpp does not reach wasm-sdk / js-evo-sdk, and the five later reference errors are generic even there.

   State-dependent existence checks necessarily remain server-side; the JS layer can validate schema/shape locally, but cannot prove a referenced identity, contract, token, document, or key exists without querying Platform.

   Additional gap: protocol-v14 HAVING

   #4384 added boolean aggregate HAVING after this issue's original snapshot. Rust now has DocumentQuery::with_having and DocumentHavingEntries::fetch, but neither wasm-sdk nor js-evo-sdk exposes:

   • having query clauses and operators;
   • count/sum/average HAVING methods;
   • HAVING result conversion;
   • proof-info variants or JS tests.

   The compound equality-prefix support added by #4393 is consequently unreachable from JS for both ranked and HAVING queries.

   There is also a lower-layer issue to address: HAVING against a completely empty ranked axis cannot currently be proved. The server advises retrying with prove = false, but DocumentQuery hard-codes prove: true and DocumentHavingEntries has no FetchUnproved implementation. Ranked empty-result proofs have since been fixed; HAVING still has this dead end.

   Suggested implementation split

   1. Ranked/HAVING query parity

   • Add explicit ranked count/sum/average and HAVING methods in wasm-sdk, with proof-info variants.
   • Add query types for aggregate ordering, offset, HAVING clauses/operators, and compound equality-prefix pins.
   • Return an ordered page/array with startingRank; do not use a Map as the primary ranked result.
   • Return tagged bigint aggregate values. Preserve exact fixed-point average values and expose the shared average scale rather than converting them to JS number.
   • Reject ranked-shaped requests early if they are sent through the existing split-aggregate APIs.
   • Wrap all of this in the js-evo-sdk documents facade and add unit/functional coverage.

   2. First-class refersTo developer experience

   • Add TypeScript reference-target unions/schema types and typed introspection.
   • Preserve/expose structured consensus causes and reference-specific payload fields.
   • Add contract round-trip tests and valid/invalid create/replace tests for every reference target.
   • Document raw schema authoring and the distinction between local structural validation and server-side state validation.

   3. Separate Rust SDK fix

   • Make unproved HAVING requests reachable, or make empty-axis HAVING provable.

   Verification performed on the pinned commit:

   • 10 rs-sdk ranked tests passed.
   • 5 rs-sdk HAVING tests passed.
   • 28 rs-dpp refersTo parser/meta-schema tests passed.
   • cargo check -p wasm-sdk passed.

   ---

   🤖 Posted autonomously by Codex on behalf of pasta.
3. QuantumExplorer

   added a commit that references this issue on Aug 26, 2026

   feat: expose protocol v14 ranked queries and document references to J…

   ...

   This issue will close once commit b980ff6 is merged into the 'v5.1-dev' branch.

   b980ff6
4. QuantumExplorer

   closed this as completedin #4450on Aug 28, 2026