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

[thephez]

Expected Behavior

The protocol v14 features on v4.2-dev should be usable from the recommended JavaScript SDK:

• Ranked aggregate indexes / provable top-K queries (feat: ranked aggregate indexes with provable top-K queries (protocol v14) #4266) — queryable from evo-sdk.
• Document references, refersTo (feat(platform)!: reference validation for documents (refersTo) #2993, feat(platform)!: permanent document references (refersTo permanentDocument) #4390, feat(platform)!: identity public key references (refersTo identityPublicKey) #4397) — permanentDocument and identityPublicKey targets supported when building and validating documents.

Current Behavior

Neither has a JS surface. Both are implemented in Drive/DPP and reachable over gRPC, but the client path stops before JavaScript.

packages/js-evo-sdk has exactly one change between v4.1.0 and v4.2-dev: the package.json version bump from the release commit (#4379). No source file changed.

Since evo-sdk is a thin wrapper over @dashevo/wasm-sdk, the gap starts a layer down: the only ranked-index-related code in wasm-sdk is a GroveElementType declaration plus sum projection in src/queries/system.rs (from #4266). That is low-level GroveDB element typing, not a top-K query API. refersTo has no wasm-sdk plumbing at all.

Client-side v14 work landed in packages/rs-sdk, so these features are currently Rust-only for clients.

Possible Solution

1. wasm-sdk: expose ranked/top-K document queries over the existing RankedEntry / RankedEntries messages in platform.proto.
2. wasm-sdk: surface refersTo reference metadata and its consensus errors.
3. evo-sdk: wrap both in the documents and contracts facades.

Alternatives Considered

N/A

Additional Context

Filed to track the gap, not to report a defect: v4.2-dev is active and these commits landed recently, so the binding work may just be lagging. Close if already planned.

Compared v4.1.0 .. v4.2-dev at eaf3a4890b; v4.2-dev is a moving target.

[PastaPastaPasta]

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.