@distrohelena/canton-typescript-sdk 0.1.43 → 0.1.44

package/dist/cjs/query/grpc/grpc-contract-cache.js

@@ -65,12 +65,19 @@ class GrpcContractCache {
     async populateAsync(parties, key) {
         const activeContracts = [];
         const seenPageTokens = new Set();
+        // Every continuation request must be identical to the first page's request apart from the page
+        // token: the participant validates each token against the request it was minted for, so adopting
+        // the response's now-explicit activeAtOffset into page 2+ makes it reject the token
+        // (INVALID_ACS_PAGE_TOKEN) — the token was prepared for a request with the field absent. The token
+        // itself pins the snapshot offset; the echoed offset is only tracked to validate it stays constant.
+        const baseRequest = (0, contracts_mapper_js_1.mapGrpcQueryContractsRequest)(parties === undefined ? { allParties: true } : { parties });
         let activeAtOffset;
         let pageToken;
         do {
-            const page = materializeActiveContractsPage(await this.stateService.getActiveContractsPageAsync((0, contracts_mapper_js_1.mapGrpcQueryContractsRequest)(parties === undefined
-                ? { allParties: true, activeAtOffset, pageToken }
-                : { parties, activeAtOffset, pageToken })));
+            const page = materializeActiveContractsPage(await this.stateService.getActiveContractsPageAsync({
+                ...baseRequest,
+                pageToken: pageToken === undefined ? undefined : Uint8Array.from(pageToken),
+            }));
             if (activeAtOffset === undefined) {
                 activeAtOffset = page.activeAtOffset;
             }

package/dist/cjs/query/grpc/grpc-query-client.js

@@ -11,6 +11,7 @@ const query_source_js_1 = require("../query-source.js");
 const grpc_relation_mapper_js_1 = require("./grpc-relation-mapper.js");
 const grpc_package_relation_reader_js_1 = require("./grpc-package-relation-reader.js");
 const grpc_query_snapshot_reader_js_1 = require("./grpc-query-snapshot-reader.js");
+const grpc_query_value_mapper_js_1 = require("./grpc-query-value-mapper.js");
 class GrpcQueryClient {
     options;
     source = query_source_js_1.QuerySource.grpc;
@@ -66,7 +67,7 @@ class DefaultGrpcQueryDataProvider {
     packages;
     constructor(options) {
         this.options = options;
-        this.snapshots = new grpc_query_snapshot_reader_js_1.GrpcQuerySnapshotReader(options.stateService, options.updateService);
+        this.snapshots = new grpc_query_snapshot_reader_js_1.GrpcQuerySnapshotReader(options.stateService, options.updateService, { incrementalHistory: options.incrementalHistory });
         this.packages = new grpc_package_relation_reader_js_1.GrpcPackageRelationReader(options.packageService);
     }
     async readDatasetAsync(query) {
@@ -80,10 +81,16 @@ class DefaultGrpcQueryDataProvider {
             return cachedContractsDataset(cached.contracts, cached.activeAtOffset, this.options.endpointScope ?? "ledger");
         }
         else if (needsHistory) {
-            console.warn(`[GrpcQueryClient] Falling back to a full ledger replay from offset 0 for a "${query.relation}" query. `
-                + "This is expensive and should be an extreme edge case. It is usually triggered by a \"contracts\" query "
-                + "that does not explicitly prove `active: true` (so archived contracts may be in scope), or by querying "
-                + "\"transactions\"/\"events\"/\"exercises\" directly. Add an explicit active:true filter if only current state is needed.");
+            // With a warm incremental window only the new offsets are fetched, which is no longer worth a warning.
+            if (!(this.options.incrementalHistory === true && this.snapshots.hasHistoryCache)) {
+                console.warn(`[GrpcQueryClient] Falling back to a full ledger replay from offset 0 for a "${query.relation}" query. `
+                    + "This is expensive and should be an extreme edge case. It is usually triggered by a \"contracts\" query "
+                    + "that does not explicitly prove `active: true` (so archived contracts may be in scope), or by querying "
+                    + "\"transactions\"/\"events\"/\"exercises\" directly. Add an explicit active:true filter if only current state is needed"
+                    + (this.options.incrementalHistory === true
+                        ? "; incrementalHistory is enabled, so later history queries will fetch only new offsets."
+                        : ", or enable the incrementalHistory option to fetch only new offsets on repeat history queries."));
+            }
             const endInclusive = cached?.activeAtOffset ?? (await this.options.stateService.getLedgerEndAsync({})).offset;
             const history = await this.snapshots.readHistoryAsync(endInclusive);
             const transactions = history.updates.flatMap((response) => response.update.oneofKind === "transaction" ? [response.update.transaction] : []);
@@ -120,7 +127,7 @@ class DefaultGrpcQueryDataProvider {
         else if (query.relation === "watermark") {
             return (0, grpc_relation_mapper_js_1.createGrpcQueryDataset)((0, grpc_relation_mapper_js_1.mapGrpcQueryRelationFragment)([]), [], endInclusive, this.options.endpointScope ?? "ledger");
         }
-        const active = await this.snapshots.readActiveContractsAsync(endInclusive, partiesFor(query));
+        const active = await this.snapshots.readActiveContractsAsync(endInclusive, partiesFor(query), pushdownTemplateRefsFor(query));
         const fragment = (0, grpc_relation_mapper_js_1.mapGrpcQueryRelationFragment)([], active.activeContracts);
         if (!requiresPackageMetadata(closure)) {
             return fragmentDataset(fragment, endInclusive, this.options.endpointScope ?? "ledger", false);
@@ -181,6 +188,110 @@ function predicateProvesActive(predicate) {
 function requiresPackageMetadata(closure) {
     return closure.has("packages") || closure.has("contractTypes") || closure.has("exercises") || closure.has("exerciseTypes");
 }
+const MAX_PUSHDOWN_TEMPLATE_FILTERS = 25;
+/**
+ * Extracts template filters the ACS request itself can apply, so non-matching contracts are never
+ * downloaded or materialized. The participant scans its whole ACS either way — the win is wire volume and
+ * client-side decode/freeze work, not node time. Correctness rule: the evaluator re-applies the complete
+ * predicate over whatever rows come back, so a pushed filter set only has to be a SUPERSET of possible
+ * matches — over-fetching is fine, under-fetching never happens because pins are only read from top-level
+ * AND conjuncts (anything under or/not is ignored) and any single conjunct constrains every matching row.
+ * Returns undefined (wildcard fetch) when no full package/module/entity pin can be proven or a pinned value
+ * is not a syntactically valid identifier (a malformed value can never match, but pushing it would make the
+ * node reject the request instead of returning the empty result the evaluator would produce).
+ */
+function pushdownTemplateRefsFor(query) {
+    if (query.relation !== "contracts") {
+        return undefined;
+    }
+    const stringValues = (operator, value) => operator === "equals" && typeof value === "string"
+        ? [value]
+        : operator === "in" && Array.isArray(value) && value.every((item) => typeof item === "string") ? value : undefined;
+    let packageRefs;
+    let moduleNames;
+    let entityNames;
+    let fqnRefs;
+    for (const conjunct of flattenAndConjuncts(query.predicate)) {
+        if (conjunct.kind === "scalar" && conjunct.path.length === 2 && conjunct.path[0] === "templateId") {
+            const values = stringValues(conjunct.operator, conjunct.value);
+            if (values === undefined) {
+                continue;
+            }
+            else if (conjunct.path[1] === "packageId") {
+                packageRefs ??= values;
+            }
+            else if (conjunct.path[1] === "moduleName") {
+                moduleNames ??= values;
+            }
+            else if (conjunct.path[1] === "entityName") {
+                entityNames ??= values;
+            }
+        }
+        else if (conjunct.kind === "relation" && conjunct.edge === "contractType" && conjunct.quantifier === "one") {
+            for (const inner of flattenAndConjuncts(conjunct.predicate)) {
+                if (inner.kind !== "scalar" || inner.path.length !== 1) {
+                    continue;
+                }
+                const values = stringValues(inner.operator, inner.value);
+                if (values === undefined) {
+                    continue;
+                }
+                else if (inner.path[0] === "packageName") {
+                    packageRefs ??= values.map((name) => `#${name}`);
+                }
+                else if (inner.path[0] === "moduleName") {
+                    moduleNames ??= values;
+                }
+                else if (inner.path[0] === "entityName") {
+                    entityNames ??= values;
+                }
+                else if (inner.path[0] === "templateFqn") {
+                    const triples = values.map(templateRefFromFqn);
+                    if (triples.every((triple) => triple !== undefined)) {
+                        fqnRefs ??= triples;
+                    }
+                }
+            }
+        }
+    }
+    const refs = fqnRefs ?? (packageRefs !== undefined && moduleNames !== undefined && entityNames !== undefined
+        ? packageRefs.flatMap((packageId) => moduleNames.flatMap((moduleName) => entityNames.map((entityName) => ({ packageId, moduleName, entityName }))))
+        : undefined);
+    return refs !== undefined && refs.length > 0 && refs.length <= MAX_PUSHDOWN_TEMPLATE_FILTERS && refs.every(isValidTemplateRef)
+        ? refs
+        : undefined;
+}
+function flattenAndConjuncts(predicate) {
+    if (predicate === undefined) {
+        return [];
+    }
+    else if (predicate.kind === "and") {
+        return predicate.children.flatMap(flattenAndConjuncts);
+    }
+    return [predicate];
+}
+function templateRefFromFqn(fqn) {
+    const parts = fqn.split(":");
+    return parts.length === 3 && parts.every((part) => part.length > 0)
+        ? { packageId: `#${parts[0]}`, moduleName: parts[1], entityName: parts[2] }
+        : undefined;
+}
+function isValidTemplateRef(ref) {
+    const validPackage = ref.packageId.startsWith("#")
+        ? /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(ref.packageId.slice(1))
+        : /^[0-9a-f]{64}$/.test(ref.packageId);
+    if (!validPackage) {
+        return false;
+    }
+    try {
+        (0, grpc_query_value_mapper_js_1.validDottedNameString)(ref.moduleName, "template filter module name");
+        (0, grpc_query_value_mapper_js_1.validDottedNameString)(ref.entityName, "template filter entity name");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * True when contractType metadata can be derived from the fetched creation events alone (see
  * contractTypeMetadataFromCreations), instead of decoding LF packages. Every CreatedEvent already carries its

package/dist/cjs/query/grpc/grpc-query-snapshot-reader.js

@@ -9,7 +9,7 @@ const transaction_filter_js_1 = require("../../transports/grpc/generated/canton/
 const contracts_mapper_js_1 = require("../../transports/grpc/mappers/contracts-mapper.js");
 const query_dataset_js_1 = require("../canonical/query-dataset.js");
 const query_snapshot_incomplete_error_js_1 = require("../errors/query-snapshot-incomplete-error.js");
-const DEFAULT_OPTIONS = {
+const DEFAULT_LIMITS = {
     maxHistoryPages: 10_000,
     maxHistoryUpdates: 1_000_000,
     maxActiveContractPages: 10_000,
@@ -20,11 +20,16 @@ class GrpcQuerySnapshotReader {
     stateService;
     updateService;
     options;
+    historyCache;
     constructor(stateService, updateService, options = {}) {
         this.stateService = stateService;
         this.updateService = updateService;
         this.options = validateOptions(options);
     }
+    /** Whether an incremental history window is already held, meaning the next read only fetches new offsets. */
+    get hasHistoryCache() {
+        return this.historyCache !== undefined;
+    }
     async readCurrentHistoryAsync() {
         const ledgerEnd = await this.stateService.getLedgerEndAsync({});
         return this.readHistoryAsync(ledgerEnd.offset);
@@ -32,26 +37,49 @@ class GrpcQuerySnapshotReader {
     async readHistoryAsync(endInclusive) {
         const end = parseOffset(endInclusive);
         if (end === undefined) {
-            throw this.historyError(endInclusive, "invalid-offset");
+            throw this.historyError(LEDGER_BEGIN, endInclusive, "invalid-offset");
+        }
+        const cached = this.options.incrementalHistory ? this.historyCache : undefined;
+        // History is append-only, so a cached window ending at or past the requested offset already contains
+        // the complete answer: an exact hit is returned as-is, a shorter request is a prefix of the window.
+        if (cached !== undefined && cached.end >= end) {
+            const updates = cached.end === end
+                ? cached.updates
+                : cached.updates.filter((update) => {
+                    const offset = parseOffset(extractUpdateOffset(update));
+                    return offset !== undefined && offset <= end;
+                });
+            return freezeSnapshot({ endInclusive, updates: Object.freeze([...updates]) });
+        }
+        const beginExclusive = cached?.end ?? 0n;
+        const snapshot = await this.readHistoryRangeAsync(beginExclusive, end, endInclusive, cached?.updates ?? []);
+        if (this.options.incrementalHistory && (this.historyCache === undefined || this.historyCache.end < end)) {
+            this.historyCache = { end, updates: snapshot.updates };
         }
+        return snapshot;
+    }
+    async readHistoryRangeAsync(beginExclusive, end, endInclusive, seed) {
+        const begin = beginExclusive.toString();
         const pruned = await this.stateService.getLatestPrunedOffsetsAsync({});
         const prunedUpTo = parseOffset(pruned.participantPrunedUpToInclusive);
-        if (prunedUpTo === undefined || prunedUpTo !== 0n) {
-            throw this.historyError(endInclusive, "participant-pruned");
+        // Offsets at or below beginExclusive are already held (or not requested), so pruning only breaks the
+        // read when it reaches past the range start.
+        if (prunedUpTo === undefined || prunedUpTo > beginExclusive) {
+            throw this.historyError(begin, endInclusive, "participant-pruned");
         }
         const updateFormat = freezeDeep(createHistoryUpdateFormat());
         const updates = [];
         const observedPageTokens = new Set();
-        let expectedLowestExclusive = 0n;
+        let expectedLowestExclusive = beginExclusive;
         let pageToken;
         let pagesRead = 0;
         let previousUpdateOffset;
         while (true) {
             if (pagesRead >= this.options.maxHistoryPages) {
-                throw this.historyError(endInclusive, "max-pages-exceeded");
+                throw this.historyError(begin, endInclusive, "max-pages-exceeded");
             }
             const request = {
-                beginOffsetExclusive: LEDGER_BEGIN,
+                beginOffsetExclusive: begin,
                 endOffsetInclusive: endInclusive,
                 updateFormat,
                 descendingOrder: false,
@@ -62,18 +90,18 @@ class GrpcQuerySnapshotReader {
             const lowest = parseOffset(response.lowestPageOffsetExclusive);
             const highest = parseOffset(response.highestPageOffsetInclusive);
             if (lowest === undefined || highest === undefined) {
-                throw this.historyError(endInclusive, "missing-boundary");
+                throw this.historyError(begin, endInclusive, "missing-boundary");
             }
             else if (lowest !== expectedLowestExclusive || highest < lowest || highest > end) {
-                throw this.historyError(endInclusive, "page-boundary-mismatch");
+                throw this.historyError(begin, endInclusive, "page-boundary-mismatch");
             }
-            if (response.updates.length > this.options.maxHistoryUpdates - updates.length) {
-                throw this.historyError(endInclusive, "max-updates-exceeded");
+            if (response.updates.length > this.options.maxHistoryUpdates - seed.length - updates.length) {
+                throw this.historyError(begin, endInclusive, "max-updates-exceeded");
             }
             for (const update of response.updates) {
                 const updateOffset = parseOffset(extractUpdateOffset(update));
                 if (updateOffset === undefined || updateOffset <= lowest || updateOffset > highest || (previousUpdateOffset !== undefined && updateOffset <= previousUpdateOffset)) {
-                    throw this.historyError(endInclusive, "page-boundary-mismatch");
+                    throw this.historyError(begin, endInclusive, "page-boundary-mismatch");
                 }
                 previousUpdateOffset = updateOffset;
             }
@@ -81,33 +109,36 @@ class GrpcQuerySnapshotReader {
             const nextPageToken = response.nextPageToken;
             if (nextPageToken === undefined || nextPageToken.length === 0) {
                 if (highest !== end) {
-                    throw this.historyError(endInclusive, "nonterminal-page-without-token");
+                    throw this.historyError(begin, endInclusive, "nonterminal-page-without-token");
                 }
                 return freezeSnapshot({
                     endInclusive,
-                    updates: Object.freeze(updates),
+                    updates: Object.freeze([...seed, ...updates]),
                 });
             }
             else if (highest >= end) {
-                throw this.historyError(endInclusive, "nonterminal-page-reaches-end");
+                throw this.historyError(begin, endInclusive, "nonterminal-page-reaches-end");
             }
             else if (highest <= lowest) {
-                throw this.historyError(endInclusive, "page-boundary-mismatch");
+                throw this.historyError(begin, endInclusive, "page-boundary-mismatch");
             }
             const tokenKey = tokenKeyFor(nextPageToken);
             if (observedPageTokens.has(tokenKey)) {
-                throw this.historyError(endInclusive, "repeated-page-token");
+                throw this.historyError(begin, endInclusive, "repeated-page-token");
             }
             observedPageTokens.add(tokenKey);
             expectedLowestExclusive = highest;
             pageToken = Uint8Array.from(nextPageToken);
         }
     }
-    async readActiveContractsAsync(activeAtOffset, parties) {
+    async readActiveContractsAsync(activeAtOffset, parties, templateRefs) {
         if (parseOffset(activeAtOffset) === undefined) {
             throw this.activeError(activeAtOffset, "invalid-offset");
         }
-        const eventFormat = freezeDeep(parties === undefined ? createAllPartiesEventFormat() : (0, contracts_mapper_js_1.mapGrpcQueryContractsRequest)({ parties }).eventFormat);
+        const eventFormat = freezeDeep((0, contracts_mapper_js_1.mapGrpcQueryContractsRequest)({
+            ...(parties === undefined ? { allParties: true } : { parties }),
+            ...(templateRefs === undefined || templateRefs.length === 0 ? {} : { templateRefs: [...templateRefs] }),
+        }).eventFormat);
         const activeContracts = [];
         const observedPageTokens = new Set();
         let pageToken;
@@ -152,9 +183,9 @@ class GrpcQuerySnapshotReader {
             pageToken = Uint8Array.from(nextPageToken);
         }
     }
-    historyError(endInclusive, reason) {
+    historyError(beginExclusive, endInclusive, reason) {
         return new query_snapshot_incomplete_error_js_1.QuerySnapshotIncompleteError({
-            beginExclusive: LEDGER_BEGIN,
+            beginExclusive,
             endInclusive,
             reason,
         });
@@ -170,13 +201,17 @@ class GrpcQuerySnapshotReader {
 }
 exports.GrpcQuerySnapshotReader = GrpcQuerySnapshotReader;
 function validateOptions(options) {
-    const validated = { ...DEFAULT_OPTIONS, ...options };
+    const { incrementalHistory = false, ...limits } = options;
+    if (typeof incrementalHistory !== "boolean") {
+        throw new validation_error_js_1.ValidationError("incrementalHistory must be a boolean.");
+    }
+    const validated = { ...DEFAULT_LIMITS, ...limits };
     for (const [name, value] of Object.entries(validated)) {
         if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
             throw new validation_error_js_1.ValidationError(`${name} must be a finite positive integer.`);
         }
     }
-    return Object.freeze(validated);
+    return Object.freeze({ ...validated, incrementalHistory });
 }
 function createHistoryUpdateFormat() {
     return {

package/dist/cjs/transports/grpc/mappers/contracts-mapper.js

@@ -56,6 +56,17 @@ function createFilters(request) {
             },
         });
     }
+    for (const ref of request.templateRefs ?? []) {
+        cumulative.push({
+            identifierFilter: {
+                oneofKind: "templateFilter",
+                templateFilter: {
+                    templateId: { packageId: ref.packageId, moduleName: ref.moduleName, entityName: ref.entityName },
+                    includeCreatedEventBlob,
+                },
+            },
+        });
+    }
     if (request.interfaceId) {
         cumulative.push({
             identifierFilter: {

package/dist/query/grpc/grpc-contract-cache.js

@@ -61,12 +61,19 @@ export class GrpcContractCache {
     async populateAsync(parties, key) {
         const activeContracts = [];
         const seenPageTokens = new Set();
+        // Every continuation request must be identical to the first page's request apart from the page
+        // token: the participant validates each token against the request it was minted for, so adopting
+        // the response's now-explicit activeAtOffset into page 2+ makes it reject the token
+        // (INVALID_ACS_PAGE_TOKEN) — the token was prepared for a request with the field absent. The token
+        // itself pins the snapshot offset; the echoed offset is only tracked to validate it stays constant.
+        const baseRequest = mapGrpcQueryContractsRequest(parties === undefined ? { allParties: true } : { parties });
         let activeAtOffset;
         let pageToken;
         do {
-            const page = materializeActiveContractsPage(await this.stateService.getActiveContractsPageAsync(mapGrpcQueryContractsRequest(parties === undefined
-                ? { allParties: true, activeAtOffset, pageToken }
-                : { parties, activeAtOffset, pageToken })));
+            const page = materializeActiveContractsPage(await this.stateService.getActiveContractsPageAsync({
+                ...baseRequest,
+                pageToken: pageToken === undefined ? undefined : Uint8Array.from(pageToken),
+            }));
             if (activeAtOffset === undefined) {
                 activeAtOffset = page.activeAtOffset;
             }

package/dist/query/grpc/grpc-query-client.d.ts

@@ -17,6 +17,12 @@ export interface GrpcQueryClientOptions {
     readonly packageService: Pick<PackageServiceClient, "listPackagesAsync" | "getPackageAsync">;
     readonly contractCache?: GrpcContractCache;
     readonly endpointScope?: string;
+    /**
+     * Opt-in: after the first history replay, keep the materialized window in memory and only fetch offsets
+     * past it on later history queries — turning repeat full replays into delta reads. Off by default because
+     * the retained window lives for this client's lifetime and its RAM cost is the full replayed history.
+     */
+    readonly incrementalHistory?: boolean;
 }
 export declare class GrpcQueryClient implements QueryClient {
     private readonly options;

package/dist/query/grpc/grpc-query-client.js

@@ -8,6 +8,7 @@ import { QuerySource } from "../query-source.js";
 import { contractTypeMetadataFromCreations, createGrpcQueryDataset, mapGrpcQueryRelationFragment, referencedGrpcPackageIds } from "./grpc-relation-mapper.js";
 import { GrpcPackageRelationReader } from "./grpc-package-relation-reader.js";
 import { GrpcQuerySnapshotReader } from "./grpc-query-snapshot-reader.js";
+import { validDottedNameString } from "./grpc-query-value-mapper.js";
 export class GrpcQueryClient {
     options;
     source = QuerySource.grpc;
@@ -62,7 +63,7 @@ class DefaultGrpcQueryDataProvider {
     packages;
     constructor(options) {
         this.options = options;
-        this.snapshots = new GrpcQuerySnapshotReader(options.stateService, options.updateService);
+        this.snapshots = new GrpcQuerySnapshotReader(options.stateService, options.updateService, { incrementalHistory: options.incrementalHistory });
         this.packages = new GrpcPackageRelationReader(options.packageService);
     }
     async readDatasetAsync(query) {
@@ -76,10 +77,16 @@ class DefaultGrpcQueryDataProvider {
             return cachedContractsDataset(cached.contracts, cached.activeAtOffset, this.options.endpointScope ?? "ledger");
         }
         else if (needsHistory) {
-            console.warn(`[GrpcQueryClient] Falling back to a full ledger replay from offset 0 for a "${query.relation}" query. `
-                + "This is expensive and should be an extreme edge case. It is usually triggered by a \"contracts\" query "
-                + "that does not explicitly prove `active: true` (so archived contracts may be in scope), or by querying "
-                + "\"transactions\"/\"events\"/\"exercises\" directly. Add an explicit active:true filter if only current state is needed.");
+            // With a warm incremental window only the new offsets are fetched, which is no longer worth a warning.
+            if (!(this.options.incrementalHistory === true && this.snapshots.hasHistoryCache)) {
+                console.warn(`[GrpcQueryClient] Falling back to a full ledger replay from offset 0 for a "${query.relation}" query. `
+                    + "This is expensive and should be an extreme edge case. It is usually triggered by a \"contracts\" query "
+                    + "that does not explicitly prove `active: true` (so archived contracts may be in scope), or by querying "
+                    + "\"transactions\"/\"events\"/\"exercises\" directly. Add an explicit active:true filter if only current state is needed"
+                    + (this.options.incrementalHistory === true
+                        ? "; incrementalHistory is enabled, so later history queries will fetch only new offsets."
+                        : ", or enable the incrementalHistory option to fetch only new offsets on repeat history queries."));
+            }
             const endInclusive = cached?.activeAtOffset ?? (await this.options.stateService.getLedgerEndAsync({})).offset;
             const history = await this.snapshots.readHistoryAsync(endInclusive);
             const transactions = history.updates.flatMap((response) => response.update.oneofKind === "transaction" ? [response.update.transaction] : []);
@@ -116,7 +123,7 @@ class DefaultGrpcQueryDataProvider {
         else if (query.relation === "watermark") {
             return createGrpcQueryDataset(mapGrpcQueryRelationFragment([]), [], endInclusive, this.options.endpointScope ?? "ledger");
         }
-        const active = await this.snapshots.readActiveContractsAsync(endInclusive, partiesFor(query));
+        const active = await this.snapshots.readActiveContractsAsync(endInclusive, partiesFor(query), pushdownTemplateRefsFor(query));
         const fragment = mapGrpcQueryRelationFragment([], active.activeContracts);
         if (!requiresPackageMetadata(closure)) {
             return fragmentDataset(fragment, endInclusive, this.options.endpointScope ?? "ledger", false);
@@ -177,6 +184,110 @@ function predicateProvesActive(predicate) {
 function requiresPackageMetadata(closure) {
     return closure.has("packages") || closure.has("contractTypes") || closure.has("exercises") || closure.has("exerciseTypes");
 }
+const MAX_PUSHDOWN_TEMPLATE_FILTERS = 25;
+/**
+ * Extracts template filters the ACS request itself can apply, so non-matching contracts are never
+ * downloaded or materialized. The participant scans its whole ACS either way — the win is wire volume and
+ * client-side decode/freeze work, not node time. Correctness rule: the evaluator re-applies the complete
+ * predicate over whatever rows come back, so a pushed filter set only has to be a SUPERSET of possible
+ * matches — over-fetching is fine, under-fetching never happens because pins are only read from top-level
+ * AND conjuncts (anything under or/not is ignored) and any single conjunct constrains every matching row.
+ * Returns undefined (wildcard fetch) when no full package/module/entity pin can be proven or a pinned value
+ * is not a syntactically valid identifier (a malformed value can never match, but pushing it would make the
+ * node reject the request instead of returning the empty result the evaluator would produce).
+ */
+function pushdownTemplateRefsFor(query) {
+    if (query.relation !== "contracts") {
+        return undefined;
+    }
+    const stringValues = (operator, value) => operator === "equals" && typeof value === "string"
+        ? [value]
+        : operator === "in" && Array.isArray(value) && value.every((item) => typeof item === "string") ? value : undefined;
+    let packageRefs;
+    let moduleNames;
+    let entityNames;
+    let fqnRefs;
+    for (const conjunct of flattenAndConjuncts(query.predicate)) {
+        if (conjunct.kind === "scalar" && conjunct.path.length === 2 && conjunct.path[0] === "templateId") {
+            const values = stringValues(conjunct.operator, conjunct.value);
+            if (values === undefined) {
+                continue;
+            }
+            else if (conjunct.path[1] === "packageId") {
+                packageRefs ??= values;
+            }
+            else if (conjunct.path[1] === "moduleName") {
+                moduleNames ??= values;
+            }
+            else if (conjunct.path[1] === "entityName") {
+                entityNames ??= values;
+            }
+        }
+        else if (conjunct.kind === "relation" && conjunct.edge === "contractType" && conjunct.quantifier === "one") {
+            for (const inner of flattenAndConjuncts(conjunct.predicate)) {
+                if (inner.kind !== "scalar" || inner.path.length !== 1) {
+                    continue;
+                }
+                const values = stringValues(inner.operator, inner.value);
+                if (values === undefined) {
+                    continue;
+                }
+                else if (inner.path[0] === "packageName") {
+                    packageRefs ??= values.map((name) => `#${name}`);
+                }
+                else if (inner.path[0] === "moduleName") {
+                    moduleNames ??= values;
+                }
+                else if (inner.path[0] === "entityName") {
+                    entityNames ??= values;
+                }
+                else if (inner.path[0] === "templateFqn") {
+                    const triples = values.map(templateRefFromFqn);
+                    if (triples.every((triple) => triple !== undefined)) {
+                        fqnRefs ??= triples;
+                    }
+                }
+            }
+        }
+    }
+    const refs = fqnRefs ?? (packageRefs !== undefined && moduleNames !== undefined && entityNames !== undefined
+        ? packageRefs.flatMap((packageId) => moduleNames.flatMap((moduleName) => entityNames.map((entityName) => ({ packageId, moduleName, entityName }))))
+        : undefined);
+    return refs !== undefined && refs.length > 0 && refs.length <= MAX_PUSHDOWN_TEMPLATE_FILTERS && refs.every(isValidTemplateRef)
+        ? refs
+        : undefined;
+}
+function flattenAndConjuncts(predicate) {
+    if (predicate === undefined) {
+        return [];
+    }
+    else if (predicate.kind === "and") {
+        return predicate.children.flatMap(flattenAndConjuncts);
+    }
+    return [predicate];
+}
+function templateRefFromFqn(fqn) {
+    const parts = fqn.split(":");
+    return parts.length === 3 && parts.every((part) => part.length > 0)
+        ? { packageId: `#${parts[0]}`, moduleName: parts[1], entityName: parts[2] }
+        : undefined;
+}
+function isValidTemplateRef(ref) {
+    const validPackage = ref.packageId.startsWith("#")
+        ? /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(ref.packageId.slice(1))
+        : /^[0-9a-f]{64}$/.test(ref.packageId);
+    if (!validPackage) {
+        return false;
+    }
+    try {
+        validDottedNameString(ref.moduleName, "template filter module name");
+        validDottedNameString(ref.entityName, "template filter entity name");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * True when contractType metadata can be derived from the fetched creation events alone (see
  * contractTypeMetadataFromCreations), instead of decoding LF packages. Every CreatedEvent already carries its

package/dist/query/grpc/grpc-query-snapshot-reader.d.ts

@@ -2,6 +2,7 @@ import { StateServiceClient } from "../../services/state/state-service-client.js
 import { UpdateServiceClient } from "../../services/update/update-service-client.js";
 import { type GetActiveContractsResponse as GetActiveContractsResponseType } from "../../transports/grpc/generated/canton/com/daml/ledger/api/v2/state_service.js";
 import { type GetUpdateResponse as GetUpdateResponseType } from "../../transports/grpc/generated/canton/com/daml/ledger/api/v2/update_service.js";
+import { type GrpcQueryTemplateRef } from "../../transports/grpc/mappers/contracts-mapper.js";
 type StateSnapshotReader = Pick<StateServiceClient, "getLedgerEndAsync" | "getLatestPrunedOffsetsAsync" | "getActiveContractsPageAsync">;
 type UpdateSnapshotReader = Pick<UpdateServiceClient, "getUpdatesPageAsync">;
 export interface GrpcHistorySnapshot {
@@ -17,15 +18,25 @@ export interface GrpcQuerySnapshotReaderOptions {
     readonly maxHistoryUpdates?: number;
     readonly maxActiveContractPages?: number;
     readonly maxActiveContracts?: number;
+    /**
+     * Opt-in: retain the last replayed history window in memory and only fetch offsets past it on later
+     * reads. Off by default because the retained window lives for this reader's lifetime — its RAM cost is
+     * the full materialized history, bounded only by maxHistoryUpdates.
+     */
+    readonly incrementalHistory?: boolean;
 }
 export declare class GrpcQuerySnapshotReader {
     private readonly stateService;
     private readonly updateService;
     private readonly options;
+    private historyCache;
     constructor(stateService: StateSnapshotReader, updateService: UpdateSnapshotReader, options?: GrpcQuerySnapshotReaderOptions);
+    /** Whether an incremental history window is already held, meaning the next read only fetches new offsets. */
+    get hasHistoryCache(): boolean;
     readCurrentHistoryAsync(): Promise<GrpcHistorySnapshot>;
     readHistoryAsync(endInclusive: string): Promise<GrpcHistorySnapshot>;
-    readActiveContractsAsync(activeAtOffset: string, parties?: readonly string[]): Promise<GrpcActiveContractSnapshot>;
+    private readHistoryRangeAsync;
+    readActiveContractsAsync(activeAtOffset: string, parties?: readonly string[], templateRefs?: readonly GrpcQueryTemplateRef[]): Promise<GrpcActiveContractSnapshot>;
     private historyError;
     private activeError;
 }

package/dist/query/grpc/grpc-query-snapshot-reader.js

@@ -5,7 +5,7 @@ import { TransactionShape } from "../../transports/grpc/generated/canton/com/dam
 import { mapGrpcQueryContractsRequest } from "../../transports/grpc/mappers/contracts-mapper.js";
 import { immutableQueryValue } from "../canonical/query-dataset.js";
 import { QuerySnapshotIncompleteError } from "../errors/query-snapshot-incomplete-error.js";
-const DEFAULT_OPTIONS = {
+const DEFAULT_LIMITS = {
     maxHistoryPages: 10_000,
     maxHistoryUpdates: 1_000_000,
     maxActiveContractPages: 10_000,
@@ -16,11 +16,16 @@ export class GrpcQuerySnapshotReader {
     stateService;
     updateService;
     options;
+    historyCache;
     constructor(stateService, updateService, options = {}) {
         this.stateService = stateService;
         this.updateService = updateService;
         this.options = validateOptions(options);
     }
+    /** Whether an incremental history window is already held, meaning the next read only fetches new offsets. */
+    get hasHistoryCache() {
+        return this.historyCache !== undefined;
+    }
     async readCurrentHistoryAsync() {
         const ledgerEnd = await this.stateService.getLedgerEndAsync({});
         return this.readHistoryAsync(ledgerEnd.offset);
@@ -28,26 +33,49 @@ export class GrpcQuerySnapshotReader {
     async readHistoryAsync(endInclusive) {
         const end = parseOffset(endInclusive);
         if (end === undefined) {
-            throw this.historyError(endInclusive, "invalid-offset");
+            throw this.historyError(LEDGER_BEGIN, endInclusive, "invalid-offset");
+        }
+        const cached = this.options.incrementalHistory ? this.historyCache : undefined;
+        // History is append-only, so a cached window ending at or past the requested offset already contains
+        // the complete answer: an exact hit is returned as-is, a shorter request is a prefix of the window.
+        if (cached !== undefined && cached.end >= end) {
+            const updates = cached.end === end
+                ? cached.updates
+                : cached.updates.filter((update) => {
+                    const offset = parseOffset(extractUpdateOffset(update));
+                    return offset !== undefined && offset <= end;
+                });
+            return freezeSnapshot({ endInclusive, updates: Object.freeze([...updates]) });
+        }
+        const beginExclusive = cached?.end ?? 0n;
+        const snapshot = await this.readHistoryRangeAsync(beginExclusive, end, endInclusive, cached?.updates ?? []);
+        if (this.options.incrementalHistory && (this.historyCache === undefined || this.historyCache.end < end)) {
+            this.historyCache = { end, updates: snapshot.updates };
         }
+        return snapshot;
+    }
+    async readHistoryRangeAsync(beginExclusive, end, endInclusive, seed) {
+        const begin = beginExclusive.toString();
         const pruned = await this.stateService.getLatestPrunedOffsetsAsync({});
         const prunedUpTo = parseOffset(pruned.participantPrunedUpToInclusive);
-        if (prunedUpTo === undefined || prunedUpTo !== 0n) {
-            throw this.historyError(endInclusive, "participant-pruned");
+        // Offsets at or below beginExclusive are already held (or not requested), so pruning only breaks the
+        // read when it reaches past the range start.
+        if (prunedUpTo === undefined || prunedUpTo > beginExclusive) {
+            throw this.historyError(begin, endInclusive, "participant-pruned");
         }
         const updateFormat = freezeDeep(createHistoryUpdateFormat());
         const updates = [];
         const observedPageTokens = new Set();
-        let expectedLowestExclusive = 0n;
+        let expectedLowestExclusive = beginExclusive;
         let pageToken;
         let pagesRead = 0;
         let previousUpdateOffset;
         while (true) {
             if (pagesRead >= this.options.maxHistoryPages) {
-                throw this.historyError(endInclusive, "max-pages-exceeded");
+                throw this.historyError(begin, endInclusive, "max-pages-exceeded");
             }
             const request = {
-                beginOffsetExclusive: LEDGER_BEGIN,
+                beginOffsetExclusive: begin,
                 endOffsetInclusive: endInclusive,
                 updateFormat,
                 descendingOrder: false,
@@ -58,18 +86,18 @@ export class GrpcQuerySnapshotReader {
             const lowest = parseOffset(response.lowestPageOffsetExclusive);
             const highest = parseOffset(response.highestPageOffsetInclusive);
             if (lowest === undefined || highest === undefined) {
-                throw this.historyError(endInclusive, "missing-boundary");
+                throw this.historyError(begin, endInclusive, "missing-boundary");
             }
             else if (lowest !== expectedLowestExclusive || highest < lowest || highest > end) {
-                throw this.historyError(endInclusive, "page-boundary-mismatch");
+                throw this.historyError(begin, endInclusive, "page-boundary-mismatch");
             }
-            if (response.updates.length > this.options.maxHistoryUpdates - updates.length) {
-                throw this.historyError(endInclusive, "max-updates-exceeded");
+            if (response.updates.length > this.options.maxHistoryUpdates - seed.length - updates.length) {
+                throw this.historyError(begin, endInclusive, "max-updates-exceeded");
             }
             for (const update of response.updates) {
                 const updateOffset = parseOffset(extractUpdateOffset(update));
                 if (updateOffset === undefined || updateOffset <= lowest || updateOffset > highest || (previousUpdateOffset !== undefined && updateOffset <= previousUpdateOffset)) {
-                    throw this.historyError(endInclusive, "page-boundary-mismatch");
+                    throw this.historyError(begin, endInclusive, "page-boundary-mismatch");
                 }
                 previousUpdateOffset = updateOffset;
             }
@@ -77,33 +105,36 @@ export class GrpcQuerySnapshotReader {
             const nextPageToken = response.nextPageToken;
             if (nextPageToken === undefined || nextPageToken.length === 0) {
                 if (highest !== end) {
-                    throw this.historyError(endInclusive, "nonterminal-page-without-token");
+                    throw this.historyError(begin, endInclusive, "nonterminal-page-without-token");
                 }
                 return freezeSnapshot({
                     endInclusive,
-                    updates: Object.freeze(updates),
+                    updates: Object.freeze([...seed, ...updates]),
                 });
             }
             else if (highest >= end) {
-                throw this.historyError(endInclusive, "nonterminal-page-reaches-end");
+                throw this.historyError(begin, endInclusive, "nonterminal-page-reaches-end");
             }
             else if (highest <= lowest) {
-                throw this.historyError(endInclusive, "page-boundary-mismatch");
+                throw this.historyError(begin, endInclusive, "page-boundary-mismatch");
             }
             const tokenKey = tokenKeyFor(nextPageToken);
             if (observedPageTokens.has(tokenKey)) {
-                throw this.historyError(endInclusive, "repeated-page-token");
+                throw this.historyError(begin, endInclusive, "repeated-page-token");
             }
             observedPageTokens.add(tokenKey);
             expectedLowestExclusive = highest;
             pageToken = Uint8Array.from(nextPageToken);
         }
     }
-    async readActiveContractsAsync(activeAtOffset, parties) {
+    async readActiveContractsAsync(activeAtOffset, parties, templateRefs) {
         if (parseOffset(activeAtOffset) === undefined) {
             throw this.activeError(activeAtOffset, "invalid-offset");
         }
-        const eventFormat = freezeDeep(parties === undefined ? createAllPartiesEventFormat() : mapGrpcQueryContractsRequest({ parties }).eventFormat);
+        const eventFormat = freezeDeep(mapGrpcQueryContractsRequest({
+            ...(parties === undefined ? { allParties: true } : { parties }),
+            ...(templateRefs === undefined || templateRefs.length === 0 ? {} : { templateRefs: [...templateRefs] }),
+        }).eventFormat);
         const activeContracts = [];
         const observedPageTokens = new Set();
         let pageToken;
@@ -148,9 +179,9 @@ export class GrpcQuerySnapshotReader {
             pageToken = Uint8Array.from(nextPageToken);
         }
     }
-    historyError(endInclusive, reason) {
+    historyError(beginExclusive, endInclusive, reason) {
         return new QuerySnapshotIncompleteError({
-            beginExclusive: LEDGER_BEGIN,
+            beginExclusive,
             endInclusive,
             reason,
         });
@@ -165,13 +196,17 @@ export class GrpcQuerySnapshotReader {
     }
 }
 function validateOptions(options) {
-    const validated = { ...DEFAULT_OPTIONS, ...options };
+    const { incrementalHistory = false, ...limits } = options;
+    if (typeof incrementalHistory !== "boolean") {
+        throw new ValidationError("incrementalHistory must be a boolean.");
+    }
+    const validated = { ...DEFAULT_LIMITS, ...limits };
     for (const [name, value] of Object.entries(validated)) {
         if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
             throw new ValidationError(`${name} must be a finite positive integer.`);
         }
     }
-    return Object.freeze(validated);
+    return Object.freeze({ ...validated, incrementalHistory });
 }
 function createHistoryUpdateFormat() {
     return {

package/dist/transports/grpc/mappers/contracts-mapper.d.ts

@@ -1,10 +1,17 @@
 import { QueryContractsResponse } from "../../../core/types/responses/query-contracts-response.js";
 import { GetActiveContractsPageRequest } from "../generated/canton/com/daml/ledger/api/v2/state_service.js";
+/** A fully qualified template reference; packageId is a concrete package id or a "#package-name" reference. */
+export interface GrpcQueryTemplateRef {
+    readonly packageId: string;
+    readonly moduleName: string;
+    readonly entityName: string;
+}
 export declare function mapGrpcQueryContractsRequest(request: {
     party?: string;
     parties?: readonly string[];
     allParties?: boolean;
     templateId?: string;
+    templateRefs?: readonly GrpcQueryTemplateRef[];
     interfaceId?: string;
     includeInterfaceView?: boolean;
     includeCreatedEventBlob?: boolean;

package/dist/transports/grpc/mappers/contracts-mapper.js

@@ -52,6 +52,17 @@ function createFilters(request) {
             },
         });
     }
+    for (const ref of request.templateRefs ?? []) {
+        cumulative.push({
+            identifierFilter: {
+                oneofKind: "templateFilter",
+                templateFilter: {
+                    templateId: { packageId: ref.packageId, moduleName: ref.moduleName, entityName: ref.entityName },
+                    includeCreatedEventBlob,
+                },
+            },
+        });
+    }
     if (request.interfaceId) {
         cumulative.push({
             identifierFilter: {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@distrohelena/canton-typescript-sdk",
-    "version": "0.1.43",
+    "version": "0.1.44",
     "license": "Apache-2.0",
     "type": "module",
     "main": "./dist/index.js",