Dash Platform gRPC API Reference

Table of Contents

AddToCreditsOperations

A collection of add-to-credits operations, each tagged with block height

This allows clients to determine which adds to apply based on their sync height

AddressBalanceChange

AddressBalanceUpdateEntries

AddressInfoEntries

AddressInfoEntry

AllKeys

AllKeys is an empty message used to signify a request for all keys

BalanceAndNonce

BlockAddressBalanceChanges

BlockHeightCreditEntry

Entry for block height to credits mapping in AddToCreditsOperations

BroadcastStateTransitionRequest

BroadcastStateTransitionResponse

CompactedAddressBalanceChange

Compacted address balance change supporting block-aware credit operations

For SetCredits: the final balance value

For AddToCreditsOperations: preserves individual adds with their block heights

CompactedAddressBalanceUpdateEntries

CompactedBlockAddressBalanceChanges

GetAddressInfoRequest

GetAddressInfoRequest.GetAddressInfoRequestV0

GetAddressInfoResponse

GetAddressInfoResponse.GetAddressInfoResponseV0

GetAddressesBranchStateRequest

GetAddressesBranchStateRequest.GetAddressesBranchStateRequestV0

GetAddressesBranchStateResponse

GetAddressesBranchStateResponse.GetAddressesBranchStateResponseV0

GetAddressesInfosRequest

GetAddressesInfosRequest.GetAddressesInfosRequestV0

GetAddressesInfosResponse

GetAddressesInfosResponse.GetAddressesInfosResponseV0

GetAddressesTrunkStateRequest

GetAddressesTrunkStateRequest.GetAddressesTrunkStateRequestV0

GetAddressesTrunkStateResponse

GetAddressesTrunkStateResponse.GetAddressesTrunkStateResponseV0

GetConsensusParamsRequest

GetConsensusParamsRequest.GetConsensusParamsRequestV0

GetConsensusParamsResponse

GetConsensusParamsResponse.ConsensusParamsBlock

GetConsensusParamsResponse.ConsensusParamsEvidence

GetConsensusParamsResponse.GetConsensusParamsResponseV0

GetContestedResourceIdentityVotesRequest

How did an identity vote?

GetContestedResourceIdentityVotesRequest.GetContestedResourceIdentityVotesRequestV0

GetContestedResourceIdentityVotesRequest.GetContestedResourceIdentityVotesRequestV0.StartAtVotePollIdInfo

GetContestedResourceIdentityVotesResponse

GetContestedResourceIdentityVotesResponse.GetContestedResourceIdentityVotesResponseV0

GetContestedResourceIdentityVotesResponse.GetContestedResourceIdentityVotesResponseV0.ContestedResourceIdentityVote

GetContestedResourceIdentityVotesResponse.GetContestedResourceIdentityVotesResponseV0.ContestedResourceIdentityVotes

GetContestedResourceIdentityVotesResponse.GetContestedResourceIdentityVotesResponseV0.ResourceVoteChoice

GetContestedResourceVoteStateRequest

What's the state of a contested resource vote? (ie who is winning?)

GetContestedResourceVoteStateRequest.GetContestedResourceVoteStateRequestV0

GetContestedResourceVoteStateRequest.GetContestedResourceVoteStateRequestV0.StartAtIdentifierInfo

GetContestedResourceVoteStateResponse

GetContestedResourceVoteStateResponse.GetContestedResourceVoteStateResponseV0

GetContestedResourceVoteStateResponse.GetContestedResourceVoteStateResponseV0.Contender

GetContestedResourceVoteStateResponse.GetContestedResourceVoteStateResponseV0.ContestedResourceContenders

GetContestedResourceVoteStateResponse.GetContestedResourceVoteStateResponseV0.FinishedVoteInfo

GetContestedResourceVotersForIdentityRequest

Who voted for a contested resource to go to a specific identity?

GetContestedResourceVotersForIdentityRequest.GetContestedResourceVotersForIdentityRequestV0

GetContestedResourceVotersForIdentityRequest.GetContestedResourceVotersForIdentityRequestV0.StartAtIdentifierInfo

GetContestedResourceVotersForIdentityResponse

GetContestedResourceVotersForIdentityResponse.GetContestedResourceVotersForIdentityResponseV0

GetContestedResourceVotersForIdentityResponse.GetContestedResourceVotersForIdentityResponseV0.ContestedResourceVoters

GetContestedResourcesRequest

GetContestedResourcesRequest.GetContestedResourcesRequestV0

GetContestedResourcesRequest.GetContestedResourcesRequestV0.StartAtValueInfo

GetContestedResourcesResponse

GetContestedResourcesResponse.GetContestedResourcesResponseV0

GetContestedResourcesResponse.GetContestedResourcesResponseV0.ContestedResourceValues

GetCurrentQuorumsInfoRequest

GetCurrentQuorumsInfoRequest.GetCurrentQuorumsInfoRequestV0

GetCurrentQuorumsInfoResponse

GetCurrentQuorumsInfoResponse.GetCurrentQuorumsInfoResponseV0

GetCurrentQuorumsInfoResponse.ValidatorSetV0

GetCurrentQuorumsInfoResponse.ValidatorV0

GetDataContractHistoryRequest

GetDataContractHistoryRequest.GetDataContractHistoryRequestV0

GetDataContractHistoryResponse

GetDataContractHistoryResponse.GetDataContractHistoryResponseV0

GetDataContractHistoryResponse.GetDataContractHistoryResponseV0.DataContractHistory

Collection of data contract history entries

GetDataContractHistoryResponse.GetDataContractHistoryResponseV0.DataContractHistoryEntry

Represents a single entry in the data contract's history

GetDataContractRequest

GetDataContractRequest.GetDataContractRequestV0

GetDataContractResponse

GetDataContractResponse.GetDataContractResponseV0

GetDataContractsRequest

GetDataContractsRequest.GetDataContractsRequestV0

GetDataContractsResponse

GetDataContractsResponse.DataContractEntry

GetDataContractsResponse.DataContracts

DataContracts is a collection of data contract entries.

GetDataContractsResponse.GetDataContractsResponseV0

GetDocumentHistoryRequest

GetDocumentHistoryRequest.GetDocumentHistoryRequestV0

GetDocumentHistoryResponse

GetDocumentHistoryResponse.GetDocumentHistoryResponseV0

GetDocumentHistoryResponse.GetDocumentHistoryResponseV0.DocumentHistory

Collection of document history entries

GetDocumentHistoryResponse.GetDocumentHistoryResponseV0.DocumentHistoryEntry

Represents a single entry in a document's history

GetDocumentsRequest

GetDocumentsRequest.DocumentFieldValue

Tagged scalar (or list) operand for a `WhereClause`. The

variant the caller picks names the wire-level primitive type

only — the **document type's schema** is the source of truth

for the indexed field's actual type, and the server coerces

each variant through the schema-driven

`document_type.serialize_value_for_key(field, value, …)` path

(the same path the CBOR-shaped v0 request flows through). That

means:

- Identifier-typed fields accept either a `bytes_value` (raw

32 bytes) **or** a `text` (base58-encoded). The schema

decides; callers don't need a dedicated identifier variant.

- Fixed-width byte fields (e.g. `Bytes20`/`Bytes36`) accept

`bytes_value` of the appropriate length; the schema

validates the size.

- Numeric fields accept the closest-fit signed (`int64_value`)

or unsigned (`uint64_value`) variant; the schema coerces to

the indexed type (`u8` … `u64`/`i8` … `i64`/`u128`/`i128`).

- String / bool fields accept `text` / `bool_value`.

The `null_value` variant is the typed-wire equivalent of a CBOR

`null` operand on the v0 path. Callers should NOT use it for

"no clause" — empty where-clauses are still expressed by

leaving `GetDocumentsRequestV1.where_clauses` empty. It exists

for clauses that legitimately compare against `null` (e.g.

queries on schema-nullable index entries from the v0 wire that

round-trip through the v1 surface).

GetDocumentsRequest.DocumentFieldValue.ValueList

Recursive list — operand for `IN` (candidate values) and

`BETWEEN*` (exactly 2 values `[lower, upper]`). Nested

`list` is structurally allowed but every supported document

index value-type is currently scalar, so callers should not

need to nest.

GetDocumentsRequest.GetDocumentsRequestV0

GetDocumentsRequest.GetDocumentsRequestV1

SQL-shaped successor to v0 that unifies `getDocuments` and

`getDocumentsCount` under a single request type with a typed

`select` projection and optional `group_by` / `having` clauses.

Mode is determined by `select` × `group_by` × `having`:

* `select = DOCUMENTS, group_by = []`: return matched documents

(identical semantics to v0).

* `select = COUNT, group_by = []`: return a single aggregate

count. With an `In` clause the server fans out per-In via

`query_aggregate_count` and sums (O(|In| × log n), see

`RangeNoProof`'s compound-summed path); with a range clause

it uses `AggregateCountOnRange`.

* `select = COUNT, group_by = []`: return per-group

`CountEntry` rows. Only supported when the grouping field

matches an `In`-constrained or range-constrained where clause;

other shapes return `Unsupported` (see supported-shape table

below).

**Ranked mode** is served from protocol v14 and is selected by

`group_by` + a single `order_by` naming the selected aggregate —

SQL's own top-n spelling, `ORDER BY DESC LIMIT n OFFSET m`.

It returns `ResultData.ranked`. See `order_by` and the

supported-shape table below.

**Having-range mode** is served from protocol v14: a single

`having` clause whose aggregate is the selected aggregate turns

the request into a bounded range read over the same per-axis

secondary ranked mode walks, answered in `ResultData.ranked`.

On protocol v13 and earlier every non-empty `having` is rejected

(`"HAVING clause is not yet implemented"`). `having` carries no

ranking spelling: an earlier draft put cross-group ranking on the

right of a `HAVING` (`HAVING AVG(grade) IN TOP(5)`) and that

grammar was removed before release in favour of `ORDER BY` +

`LIMIT`. See the supported-shape table below.

**Supported shapes** (everything else rejects with a typed

`QuerySyntaxError::Unsupported` so callers can detect un-wired

capabilities without parsing prose). Bullets are kept

single-line so the generated Rust doc comments don't trip

rustdoc's `list_item_without_indent` lint on continuation

lines.

`select=DOCUMENTS, group_by=[]`: any where shape v0 supports.

`select=COUNT, group_by=[]`:

- empty where → `documentsCountable: true` doctype.

- `==` only → `countable: true` index covering the fields.

- one `In` → `countable: true` index covering the fields (per-In aggregate fan-out).

- one range → `rangeCountable: true` index.

- one `In` + one range → `rangeCountable: true` compound index (per-In aggregate fan-out on no-proof; rejected on prove because the aggregate proof primitive can't fork).

`select=COUNT, group_by=[g]`:

- g is the In clause's field → `countable: true` index, grouped by g (PerInValue on no-proof, CountTree element proof per In branch on prove).

- g is the range clause's field → `rangeCountable: true` index, grouped by g (RangeDistinct on no-proof, distinct range proof on prove).

`select=COUNT, group_by=[a, b]`:

- a is the In field AND b is the range field, in that order → existing compound distinct shape; entries carry both `in_key` (= a's value) and `key` (= b's value).

`select=, group_by=[p], order_by=[]` (protocol v14+) — **ranked mode**:

- exactly one `group_by` property, exactly one `order_by` clause naming the select's aggregate (`f` for `SUM(f)` / `AVG(f)`, the `$count` sentinel for `COUNT(*)`), a `limit` in `1 ..= 100`, an optional `offset`, and no `having` / `start_at`, on an index declaring the matching `rankedCountable` / `rankedSummable` / `rankedAverageable` axis → ranked executor, answered in `ResultData.ranked`. On a single-property ranked index no `where` is accepted; on a compound ranked index every leading index property must be pinned (one clause per property, `group_by` names the trailing property) — `EQUAL` pins one prefix, and **at most one** clause may be `IN` (2..=10 distinct elements, `null` legal; a single-element `IN` normalizes to the equality pin; an element whose prefix was never written — at any depth of its pinned chain — contributes an empty branch, union semantics), fanning the walk out across one prefix branch per element and merging by `(aggregate, encoded prefix, group key)`; merged entries carry `in_key`. A non-zero `offset` is rejected together with `IN` (rank-skip is per-secondary; `OFFSET 0` is the offset-free request).

- `DESC` is the "top n" reading (walk the axis from the largest aggregate down), `ASC` the "bottom n" reading. Worked example: `SELECT AVG(grade) GROUP BY restaurantId ORDER BY grade DESC LIMIT 1 OFFSET 4` is the 5th-best restaurant.

`select=, group_by=[p], having=[ ]` (protocol v14+) — **having-range mode**:

- exactly one `group_by` property, exactly one `having` clause whose aggregate is the select's aggregate, an operator describing one contiguous range (`EQUAL`, `GREATER_THAN[_OR_EQUALS]`, `LESS_THAN[_OR_EQUALS]`, `BETWEEN*`; `NOT_EQUAL` / `IN` rejected), a `limit` in `1 ..= 100`, an optional `order_by` naming the same aggregate (walk direction; ascending by default), and no `offset` / `start_at` / `start_after`, on an index declaring the matching ranked axis → having-range executor, answered in `ResultData.ranked`. `where` follows the same rule as ranked mode: none on a single-property ranked index; exactly one pin per leading index property on a compound ranked index, at most one of them an `IN` (2..=10 distinct elements; a never-written element contributes an empty branch) that fans the bound out across prefix branches and merges, entries carrying `in_key`.

- no offset or cursor pagination: a page cut at `limit` continues only by tightening the bound past the last *distinct* aggregate value seen; a cut inside a tie (several groups sharing the boundary aggregate) cannot be continued, so size `limit` above the widest expected tie.

**Rejected shapes** (return `Unsupported`):

- any non-empty `having` on protocol v13 and earlier; at v14+, any `having` shape outside having-range mode above (multiple clauses, an aggregate other than the select's, `NOT_EQUAL` / `IN` as the having operator, a `where` shape other than the compound-index prefix pins above — equality pins plus at most one bounded `IN` — or a carried `offset` / cursor).

- at v14+: a ranked-shaped request carrying a `where` shape other than the compound-index prefix pins above (an operator other than `EQUAL` or the one permitted `IN`, more than one `IN`, a `null` pin combined with an `IN`, a repeated or non-leading property, or a missing pin), a `start_at` / `start_after` cursor, more than one `order_by`, or an `order_by` naming anything but the selected aggregate.

- `select=DOCUMENTS` with non-empty `group_by`.

- `select=COUNT` with `group_by` on a field that is not constrained by an `In` or range where clause.

- `select=COUNT` with `group_by.len() > 2`.

- `select=COUNT` with 2-field `group_by` that does not match the `(in_field, range_field)` shape above.

**Absent-from-tree branches on `In`-grouped queries**: when

`select=COUNT, group_by=[in_field]` and an `In` value has no

matching documents, the underlying merk index has nothing to

emit (zero-count branches aren't materialized as CountTree

elements), so the wire `CountEntries.entries` list contains

only the In values that exist.

The SDK's proof decoder surfaces this by **omission**, not by

a sentinel `count` value: the current point-lookup path query

doesn't set `absence_proofs_for_non_existing_searched_keys:

true`, so grovedb's `verify_query` silently drops absent-Key

branches from the verified elements stream. The drive-side

verifier (`verify_point_lookup_count_proof`) therefore emits

one `SplitCountEntry` per **present** In branch and the SDK

wraps those into `CountEntry`. Callers that need to detect

"queried but absent" diff their request's In array against

the returned entries by `key` (each entry's `key` is the

serialized In value, recoverable via

`document_type.serialize_value_for_key(in_field, v, …)`).

`SplitCountEntry::count`'s `Option` and the `None`

variant exist for a future absence-proof variant; today the

wire `CountEntry.count` is plain `uint64`.

For range-grouped queries the walker only emits keys that

exist in the index, which IS SQL-conformant; no equivalent

reconstruction step because the range itself is unbounded and

the caller has no explicit "expected keys" list to compare

against.

GetDocumentsRequest.GetDocumentsRequestV1.Select

Projection over the matched row set. `(function, field)`

pair — analogous to `HavingAggregate`'s shape but with an

additional `DOCUMENTS` variant for the row-fetch path.

Determines what the response carries:

- `DOCUMENTS`: `ResultData.documents` (matched rows;

`field` must be empty).

- `COUNT`: `ResultData.counts` carrying row counts. Empty

`field` is `COUNT(*)` (group cardinality); non-empty is

`COUNT(field)` (non-null `field` values).

- `SUM` / `AVG`: `ResultData` carrying numeric

aggregate(s); `field` is required and must be a

numeric-typed schema field.

Single-aggregate vs per-group response shape comes from

`group_by` (empty → single, non-empty → per-group entries) —

same rule as today's `COUNT` routing.

**Server capability today**: `DOCUMENTS`, `COUNT(*)` (empty

`field`), `SUM()`, and `AVG()` are evaluated

end-to-end (no-proof and proof paths route through the drive

count / sum / average dispatchers). `COUNT()` (non-null

value counting on a specific field), `MIN()`, and

`MAX()` are wire-stable but rejected at routing time

with `Unsupported("SELECT … is not yet implemented")` so the

surface is shipped first and execution lands later without

another version bump. MIN/MAX in particular wait on a grovedb

primitive — there's no min/max aggregate on count or sum

trees today, and the order-by-then-LIMIT-1 emulation has the

wrong proof shape for the cryptographic verifier.

GetDocumentsRequest.HavingAggregate

Per-group aggregate operand for the left side of a

`HavingClause`, and the aggregate-function target of an

`OrderClause`. Only the per-group aggregates live here —

`HAVING` is a boolean predicate over one group's own aggregate,

and nothing on this message reaches across groups. Cross-group

ranking ("which groups score highest?") is expressed with SQL's

ordering surface instead: `ORDER BY

DESC LIMIT n [OFFSET m]`. See `GetDocumentsRequestV1.order_by`.

**Field semantics by function**:

- `COUNT`: empty `field` means `COUNT(*)` (group cardinality);

non-empty `field` means `COUNT(field)` (count of non-null

values of `field` in the group).

- `SUM` / `AVG`: `field` is required.

GetDocumentsRequest.HavingClause

Single `HAVING ` clause. Multiple

entries in `GetDocumentsRequestV1.having` combine with

implicit AND — same semantics as multiple `where_clauses`

entries. `HAVING COUNT(*) > 5 AND SUM(amount) > 100` is two

`HavingClause` rows, not a tree.

**`HAVING` is a boolean per-group predicate and nothing else.**

Its right operand is always a literal `DocumentFieldValue`; it

never names another group or the set of groups. Cross-group

ranking — "the 5 highest-scoring groups" — is `ORDER BY

selected aggregate> DESC LIMIT 5`, exactly as in SQL, and is

served by the ranked executor (protocol v14+). An earlier draft

of this surface carried the ranking on the right of a `HAVING`

(`HAVING AVG(grade) IN TOP(5)`); that spelling was removed

before release rather than deprecated, because it invented

non-SQL grammar for something SQL already expresses.

**From protocol v14 a single `HAVING` clause is served as a

bounded range read** (having-range mode): `SELECT GROUP BY

p HAVING [ORDER BY ASC|DESC]

LIMIT n` answers from the same per-axis secondary as ranked

mode, on an index declaring the matching ranked axis. The

clause's aggregate must be the selected aggregate, the operator

must describe one contiguous range (`NOT_EQUAL` / `IN` are

rejected), and the optional `ORDER BY` picks the walk direction

using the same order-key spelling as ranked mode: `f` for

`SUM(f)` / `AVG(f)`, the `$count` sentinel for `COUNT(*)` —

never an explicit `OrderClause.aggregate` target, which is

rejected. See the supported-shape table on

`GetDocumentsRequestV1`. On protocol v13 and earlier every

non-empty `having` stays rejected with `Unsupported`, exactly as

before.

The operator set mirrors `WhereOperator` minus `STARTS_WITH`

(prefix matching has no natural meaning against a scalar

aggregate result, even a string-typed one). `BETWEEN*` and

`IN` operand semantics match `WhereOperator`: `BETWEEN*`

expects a 2-element `DocumentFieldValue.list` carrying

`[lower, upper]`, and `IN` expects a `list` of candidate

values.

The `right` oneof exists (rather than a bare

`DocumentFieldValue` field) so the "unset right operand" case

stays distinguishable from "the literal null value"; the wire

rejects an unset `right`.

GetDocumentsRequest.OrderClause

Single `ORDER BY ` clause. Multi-field

ordering is expressed by repeating this message at the

request level (`repeated OrderClause order_by = 4`), matching

SQL's `ORDER BY a ASC, b DESC` shape.

The `target` oneof carries either a plain field name

(`ORDER BY field`) or an aggregate function applied to a

field (`ORDER BY COUNT(*)`, `ORDER BY SUM(amount)`).

**Two distinct roles ride the `field` target.**

1. *Row ordering* — `select = DOCUMENTS`. `field` names a

document property and the matched rows come back in that

order. This is v0's behaviour, unchanged.

2. *Aggregate ordering* — the **ranked** surface (protocol

v14+). With a `GROUP BY` and a single aggregate `select`,

exactly one `order_by` clause naming that select's

aggregate orders the *groups* by their aggregate value and

routes the request to the ranked executor:

```text

SELECT AVG(grade) GROUP BY restaurantId

ORDER BY grade DESC LIMIT 3 -- 3 best restaurants

SELECT COUNT(*) GROUP BY restaurantId

ORDER BY $count DESC LIMIT 10 OFFSET 10 -- busiest, page 2

```

`SUM(f)` / `AVG(f)` are named by `f` — the same property the

projection aggregates, which is how `ORDER BY avg(grade)`

reads once `SELECT` has already fixed the function.

`COUNT(*)` aggregates no property, so it is named by the

reserved sentinel **`$count`**. The `$` prefix is what keeps

the sentinel from colliding with a real document property:

document properties cannot start with `$` (that namespace is

the system fields' `$id` / `$ownerId` / …), so `$count` can

never be mistaken for a column. `DESC` is the "top n"

reading, `ASC` the "bottom n" reading.

An `order_by` naming anything other than the selected

aggregate — a second clause, the `GROUP BY` property, an

unrelated field — is rejected rather than normalized: it

asks for an ordering the ranked secondary cannot produce.

**Aggregate target still rejected** with

`Unsupported("ORDER BY on aggregate keys is not yet

implemented")`. It is the *explicit* spelling of role 2

(`ORDER BY AVG(grade)` rather than `ORDER BY grade` under a

`SELECT AVG(grade)`) and is wire-stable so it can start being

evaluated without another version bump; today the field-target

spelling above is the one the ranked executor reads.

GetDocumentsRequest.WhereClause

Single `field value` clause. The server reassembles a

`Vec` from the request's `where_clauses` field,

runs the same `WhereClause::group_clauses` validator (rejects

duplicate / conflicting same-field clauses) and the same

`> AND <` → `between*` canonicalizer the CBOR-shaped path uses,

then hands the structured clauses to the executor. Wire

semantics are identical to v0's CBOR `[field, op, value]`

triples — only the envelope differs.

GetDocumentsResponse

GetDocumentsResponse.GetDocumentsResponseV0

GetDocumentsResponse.GetDocumentsResponseV0.Documents

Represents a collection of documents

GetDocumentsResponse.GetDocumentsResponseV1

v1 response. Two-variant outer `oneof` mirrors every other

`Get*Response`: a non-proof result at position 1, the proof at

position 2. The non-proof result is itself a `oneof` because

a single v1 request can produce either matched documents (for

`select=DOCUMENTS`) or count results (for `select=COUNT`) —

wrapping them in an inner `ResultData` keeps the outer shape

canonical without flattening to a three-variant oneof.

Wire shape by `request.select` × `group_by` × `prove`:

- `select=DOCUMENTS` (no prove) → `result.data.documents`.

- `select=COUNT, group_by=[]` (no prove) → `result.data.counts.aggregate_count`.

- `select=COUNT, group_by=[…]` (no prove) → `result.data.counts.entries`.

- `select=SUM, group_by=[]` (no prove) → `result.data.sums.aggregate_sum`.

- `select=SUM, group_by=[…]` (no prove) → `result.data.sums.entries`.

- `select=AVG, group_by=[]` (no prove) → `result.data.averages.aggregate_average`.

- `select=AVG, group_by=[…]` (no prove) → `result.data.averages.entries`.

- any select (prove) → `result.proof`.

**SUM / AVG status**: all four shapes above are wired

end-to-end on the drive dispatcher (no-proof and proof paths

both terminate at grovedb's aggregate-sum / sum-tree-walk

primitives, not at a `NotYetImplemented` stub). The four

resolved-mode tables (`compute_aggregate_mode_and_check_limit_v0`,

`detect_count_mode`, `detect_sum_mode`, AVG mirror) decide which

executor to run from the (mode × range × group_by × prove)

tuple; the executors compose count and sum walks for AVG so

there's no separate average primitive on the grovedb side.

Routing details live in

`packages/rs-drive/src/query/drive_document_{sum,average}_query/`.

`CountResults` / `CountEntry` / `CountEntries` are nested in

`GetDocumentsResponseV1` rather than re-exported from a

top-level message — the v0 `getDocumentsCount` endpoint that

previously owned them has been removed in this version (it

shipped briefly in #3623 and never had stable callers); v1 is

the single home for the count wire types.

GetDocumentsResponse.GetDocumentsResponseV1.AverageAggregate

Aggregate average across all matched documents (no group_by).

Same `(count, sum)` shape as a single entry — the client

computes `avg = sum / count` itself.

GetDocumentsResponse.GetDocumentsResponseV1.AverageEntries

GetDocumentsResponse.GetDocumentsResponseV1.AverageEntry

Average-side analog of `SumEntry` — one per matched key for

`select=AVG, group_by=[…]` queries. Each entry carries BOTH

the count and the sum for its group; the client divides

`sum / count` to compute the actual average.

Why no `average` field on the wire? Returning the (count, sum)

pair preserves full precision and lets the client pick the

representation it wants (integer-truncated division, floating-

point, decimal). Returning a single pre-computed `average`

would force the server to choose, and any choice loses

information for callers that wanted a different one.

This shape is produced by grovedb's `AggregateCountAndSumOnRange`

primitive (one root-hash-committed traversal returning both

metrics) which lands as part of grovedb PR 670 alongside the

PCPS (`ProvableCountProvableSumTree`) tree element.

GetDocumentsResponse.GetDocumentsResponseV1.AverageResults

Non-proof average result. Same outer shape as

`CountResults` / `SumResults`; the variants mirror them:

* `aggregate_average`: `select=AVG, group_by=[]` — single

`(count, sum)` pair with no per-key breakdown.

* `entries`: `select=AVG, group_by=[…]` — one AverageEntry

per distinct group, each carrying its own `(count, sum)`.

GetDocumentsResponse.GetDocumentsResponseV1.CountEntries

GetDocumentsResponse.GetDocumentsResponseV1.CountEntry

A single per-key entry. Carries `in_key` for compound

queries (`In` on a prefix property of a `range_countable`

index plus a range clause on the terminator) where each

entry is keyed by both the In-fork's prefix value (`in_key`)

and the terminator value (`key`). Cross-fork aggregation is

intentionally NOT done server-side — callers get the

unmerged per-`(in_key, key)` view and can reduce client-side

if they want a flat histogram.

GetDocumentsResponse.GetDocumentsResponseV1.CountResults

Non-proof count result. Shape is mode-dependent and made

explicit on the wire via the inner `variant` oneof:

* `aggregate_count`: `select=COUNT, group_by=[]` —

single u64 with no per-key breakdown.

* `entries`: `select=COUNT, group_by=[…]` — one

CountEntry per distinct group, in serialized-key order

(subject to the first `order_by` clause's direction and

`limit`).

GetDocumentsResponse.GetDocumentsResponseV1.Documents

Documents result variant — matches the v0 `Documents`

message field-for-field (kept distinct so v1 doesn't reach

into v0's namespace once v0 is eventually retired).

GetDocumentsResponse.GetDocumentsResponseV1.RankedEntries

Ranked result entries. **Entry order IS the ranking order** —

best-first for `ORDER BY DESC`, worst-first for `ASC`.

Clients must not re-sort; ties (equal aggregates) come back in

group-key order in the direction of the walk, which is

descending group-key order for `DESC`.

Fewer than `limit` entries is normal — the index simply has

fewer groups than requested — and is not an error.

GetDocumentsResponse.GetDocumentsResponseV1.RankedEntry

One group in a ranked (`GROUP BY … ORDER BY LIMIT n`)

result: the group's index key plus the aggregate it was ranked

by.

`key` is the raw index-key bytes of the GROUP BY property's

value — the same bytes that name the group's value tree under

the index (for a `string` property, its UTF-8 bytes). Clients

that want the typed value decode it with the document type's

key deserialization; the wire carries bytes so prover and

verifier agree without a schema round-trip.

Exactly one `value` variant is set, determined by the

request's SELECT function:

* `count` — `SELECT COUNT(*)`, ranked on the index's

`rankedCountable` axis.

* `sum` — `SELECT SUM(field)`, `rankedSummable` axis.

Signed for the same reason `SumEntry.sum` is.

* `avg` — `SELECT AVG(field)`,

`rankedAverageable` axis.

GetDocumentsResponse.GetDocumentsResponseV1.ResultData

Non-proof result wrapper. The outer `oneof result` switches

between this and `proof`; this inner oneof switches between

the non-proof shapes the v1 surface can return.

GetDocumentsResponse.GetDocumentsResponseV1.SumEntries

GetDocumentsResponse.GetDocumentsResponseV1.SumEntry

Sum-side analog of `CountEntry` — one per matched key for

`select=SUM, group_by=[...]` queries. `in_key` carries the

outer prefix value for compound `(In, range)` shapes; `key`

carries the terminator value. `sum` is signed because grovedb's

SumTree values are `i64` and sums can in principle be negative

(deliberate i64-overflow signaling — see the sum-tree book

chapter's "Signed `i64` overflow" note). For tip-jar-style

non-negative sums this stays >= 0 in practice.

GetDocumentsResponse.GetDocumentsResponseV1.SumResults

Non-proof sum result. Same shape as `CountResults` for the

sum surface — the variants mirror count's:

* `aggregate_sum`: `select=SUM, group_by=[]` — single signed

sum with no per-key breakdown.

* `entries`: `select=SUM, group_by=[…]` — one SumEntry per

distinct group.

GetEpochsInfoRequest

GetEpochsInfoRequest.GetEpochsInfoRequestV0

GetEpochsInfoResponse

GetEpochsInfoResponse.GetEpochsInfoResponseV0

GetEpochsInfoResponse.GetEpochsInfoResponseV0.EpochInfo

EpochInfo represents information about a single epoch

GetEpochsInfoResponse.GetEpochsInfoResponseV0.EpochInfos

EpochInfos holds a collection of epoch information entries

GetEvonodesProposedEpochBlocksByIdsRequest

GetEvonodesProposedEpochBlocksByIdsRequest.GetEvonodesProposedEpochBlocksByIdsRequestV0

GetEvonodesProposedEpochBlocksByRangeRequest

GetEvonodesProposedEpochBlocksByRangeRequest.GetEvonodesProposedEpochBlocksByRangeRequestV0

GetEvonodesProposedEpochBlocksResponse

GetEvonodesProposedEpochBlocksResponse.GetEvonodesProposedEpochBlocksResponseV0

GetEvonodesProposedEpochBlocksResponse.GetEvonodesProposedEpochBlocksResponseV0.EvonodeProposedBlocks

GetEvonodesProposedEpochBlocksResponse.GetEvonodesProposedEpochBlocksResponseV0.EvonodesProposedBlocks

GetFinalizedEpochInfosRequest

GetFinalizedEpochInfosRequest.GetFinalizedEpochInfosRequestV0

GetFinalizedEpochInfosResponse

GetFinalizedEpochInfosResponse.GetFinalizedEpochInfosResponseV0

GetFinalizedEpochInfosResponse.GetFinalizedEpochInfosResponseV0.BlockProposer

BlockProposer represents a block proposer and their block count

GetFinalizedEpochInfosResponse.GetFinalizedEpochInfosResponseV0.FinalizedEpochInfo

FinalizedEpochInfo represents finalized information about a single epoch

GetFinalizedEpochInfosResponse.GetFinalizedEpochInfosResponseV0.FinalizedEpochInfos

FinalizedEpochInfos holds a collection of finalized epoch information

entries

GetGroupActionSignersRequest

GetGroupActionSignersRequest.GetGroupActionSignersRequestV0

GetGroupActionSignersResponse

GetGroupActionSignersResponse.GetGroupActionSignersResponseV0

GetGroupActionSignersResponse.GetGroupActionSignersResponseV0.GroupActionSigner

GetGroupActionSignersResponse.GetGroupActionSignersResponseV0.GroupActionSigners

GetGroupActionsRequest

GetGroupActionsRequest.GetGroupActionsRequestV0

GetGroupActionsRequest.StartAtActionId

GetGroupActionsResponse

GetGroupActionsResponse.GetGroupActionsResponseV0

GetGroupActionsResponse.GetGroupActionsResponseV0.BurnEvent

Burn event

GetGroupActionsResponse.GetGroupActionsResponseV0.ContractEvent

GetGroupActionsResponse.GetGroupActionsResponseV0.ContractUpdateEvent

GetGroupActionsResponse.GetGroupActionsResponseV0.DestroyFrozenFundsEvent

Destroy frozen funds event

GetGroupActionsResponse.GetGroupActionsResponseV0.DocumentCreateEvent

GetGroupActionsResponse.GetGroupActionsResponseV0.DocumentEvent

GetGroupActionsResponse.GetGroupActionsResponseV0.EmergencyActionEvent

Emergency action event

GetGroupActionsResponse.GetGroupActionsResponseV0.FreezeEvent

Freeze event

GetGroupActionsResponse.GetGroupActionsResponseV0.GroupActionEntry

GetGroupActionsResponse.GetGroupActionsResponseV0.GroupActionEvent

Event associated with this action

GetGroupActionsResponse.GetGroupActionsResponseV0.GroupActions

GetGroupActionsResponse.GetGroupActionsResponseV0.MintEvent

Mint event

GetGroupActionsResponse.GetGroupActionsResponseV0.PersonalEncryptedNote

Personal encrypted note

GetGroupActionsResponse.GetGroupActionsResponseV0.SharedEncryptedNote

Shared encrypted note

GetGroupActionsResponse.GetGroupActionsResponseV0.TokenConfigUpdateEvent

Token config update event

GetGroupActionsResponse.GetGroupActionsResponseV0.TokenEvent

Details for token events

GetGroupActionsResponse.GetGroupActionsResponseV0.UnfreezeEvent

Unfreeze event

GetGroupActionsResponse.GetGroupActionsResponseV0.UpdateDirectPurchasePriceEvent

UpdatePrice event

GetGroupActionsResponse.GetGroupActionsResponseV0.UpdateDirectPurchasePriceEvent.PriceForQuantity

GetGroupActionsResponse.GetGroupActionsResponseV0.UpdateDirectPurchasePriceEvent.PricingSchedule

GetGroupInfoRequest

GetGroupInfoRequest.GetGroupInfoRequestV0

GetGroupInfoResponse

GetGroupInfoResponse.GetGroupInfoResponseV0

GetGroupInfoResponse.GetGroupInfoResponseV0.GroupInfo

GetGroupInfoResponse.GetGroupInfoResponseV0.GroupInfoEntry

GetGroupInfoResponse.GetGroupInfoResponseV0.GroupMemberEntry

GetGroupInfosRequest

GetGroupInfosRequest.GetGroupInfosRequestV0

GetGroupInfosRequest.StartAtGroupContractPosition

GetGroupInfosResponse

GetGroupInfosResponse.GetGroupInfosResponseV0

GetGroupInfosResponse.GetGroupInfosResponseV0.GroupInfos

GetGroupInfosResponse.GetGroupInfosResponseV0.GroupMemberEntry

GetGroupInfosResponse.GetGroupInfosResponseV0.GroupPositionInfoEntry

GetIdentitiesBalancesRequest

GetIdentitiesBalancesRequest.GetIdentitiesBalancesRequestV0

GetIdentitiesBalancesResponse

GetIdentitiesBalancesResponse.GetIdentitiesBalancesResponseV0

GetIdentitiesBalancesResponse.GetIdentitiesBalancesResponseV0.IdentitiesBalances

GetIdentitiesBalancesResponse.GetIdentitiesBalancesResponseV0.IdentityBalance

GetIdentitiesContractKeysRequest

GetIdentitiesContractKeysRequest.GetIdentitiesContractKeysRequestV0

GetIdentitiesContractKeysResponse

GetIdentitiesContractKeysResponse.GetIdentitiesContractKeysResponseV0

GetIdentitiesContractKeysResponse.GetIdentitiesContractKeysResponseV0.IdentitiesKeys

GetIdentitiesContractKeysResponse.GetIdentitiesContractKeysResponseV0.IdentityKeys

GetIdentitiesContractKeysResponse.GetIdentitiesContractKeysResponseV0.PurposeKeys

GetIdentitiesTokenBalancesRequest

GetIdentitiesTokenBalancesRequest.GetIdentitiesTokenBalancesRequestV0

GetIdentitiesTokenBalancesResponse

GetIdentitiesTokenBalancesResponse.GetIdentitiesTokenBalancesResponseV0

GetIdentitiesTokenBalancesResponse.GetIdentitiesTokenBalancesResponseV0.IdentityTokenBalanceEntry

GetIdentitiesTokenBalancesResponse.GetIdentitiesTokenBalancesResponseV0.IdentityTokenBalances

GetIdentitiesTokenInfosRequest

GetIdentitiesTokenInfosRequest.GetIdentitiesTokenInfosRequestV0

GetIdentitiesTokenInfosResponse

GetIdentitiesTokenInfosResponse.GetIdentitiesTokenInfosResponseV0

GetIdentitiesTokenInfosResponse.GetIdentitiesTokenInfosResponseV0.IdentityTokenInfos

GetIdentitiesTokenInfosResponse.GetIdentitiesTokenInfosResponseV0.TokenIdentityInfoEntry

GetIdentitiesTokenInfosResponse.GetIdentitiesTokenInfosResponseV0.TokenInfoEntry

GetIdentityBalanceAndRevisionRequest

GetIdentityBalanceAndRevisionRequest.GetIdentityBalanceAndRevisionRequestV0

GetIdentityBalanceAndRevisionResponse

GetIdentityBalanceAndRevisionResponse.GetIdentityBalanceAndRevisionResponseV0

GetIdentityBalanceAndRevisionResponse.GetIdentityBalanceAndRevisionResponseV0.BalanceAndRevision

GetIdentityBalanceRequest

GetIdentityBalanceRequest.GetIdentityBalanceRequestV0

GetIdentityBalanceResponse

GetIdentityBalanceResponse.GetIdentityBalanceResponseV0

GetIdentityByNonUniquePublicKeyHashRequest

GetIdentityByNonUniquePublicKeyHashRequest.GetIdentityByNonUniquePublicKeyHashRequestV0

GetIdentityByNonUniquePublicKeyHashResponse

GetIdentityByNonUniquePublicKeyHashResponse.GetIdentityByNonUniquePublicKeyHashResponseV0

GetIdentityByNonUniquePublicKeyHashResponse.GetIdentityByNonUniquePublicKeyHashResponseV0.IdentityProvedResponse

GetIdentityByNonUniquePublicKeyHashResponse.GetIdentityByNonUniquePublicKeyHashResponseV0.IdentityResponse

GetIdentityByPublicKeyHashRequest

GetIdentityByPublicKeyHashRequest.GetIdentityByPublicKeyHashRequestV0

GetIdentityByPublicKeyHashResponse

GetIdentityByPublicKeyHashResponse.GetIdentityByPublicKeyHashResponseV0

GetIdentityContractNonceRequest

GetIdentityContractNonceRequest.GetIdentityContractNonceRequestV0

GetIdentityContractNonceResponse

GetIdentityContractNonceResponse.GetIdentityContractNonceResponseV0

GetIdentityKeysRequest

GetIdentityKeysRequest.GetIdentityKeysRequestV0

GetIdentityKeysResponse

GetIdentityKeysResponse.GetIdentityKeysResponseV0

GetIdentityKeysResponse.GetIdentityKeysResponseV0.Keys

GetIdentityNonceRequest