@distrohelena/canton-typescript-sdk 0.1.45 → 0.1.47

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

@@ -1,25 +1,42 @@
 import { isProxy } from "node:util/types";
 import { ValidationError } from "../../core/errors/validation-error.js";
+import { TransactionShape } from "../../transports/grpc/generated/canton/com/daml/ledger/api/v2/transaction_filter.js";
 import { mapGrpcQueryContractsRequest } from "../../transports/grpc/mappers/contracts-mapper.js";
 import { QuerySource } from "../query-source.js";
 import { mapGrpcQueryRelationFragment } from "./grpc-relation-mapper.js";
 import { isCanonicalGrpcOffset } from "./grpc-query-snapshot-reader.js";
+const DELTA_DEFAULT_MAX_OFFSET_GAP = 1_000_000;
+const DELTA_MAX_PAGES = 10_000;
 export class GrpcContractCache {
     stateService;
     store;
     ttlMs;
     endpointScope;
     now;
+    maxPageSize;
+    updateService;
+    delta;
     inflight = new Map();
-    constructor(stateService, store, ttlMs, endpointScope, now = Date.now) {
+    constructor(stateService, store, ttlMs, endpointScope, now = Date.now, maxPageSize, updateService, delta = {}) {
         this.stateService = stateService;
         this.store = store;
         this.ttlMs = ttlMs;
         this.endpointScope = endpointScope;
         this.now = now;
+        this.maxPageSize = maxPageSize;
+        this.updateService = updateService;
+        this.delta = delta;
         if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
             throw new ValidationError("Contract cache ttlMs must be a positive finite number.");
         }
+        else if (maxPageSize !== undefined && (!Number.isFinite(maxPageSize) || !Number.isInteger(maxPageSize) || maxPageSize <= 0)) {
+            throw new ValidationError("Contract cache maxPageSize must be a positive integer.");
+        }
+        for (const [name, value] of Object.entries({ maxOffsetGap: delta.maxOffsetGap, maxUpdates: delta.maxUpdates })) {
+            if (value !== undefined && (!Number.isFinite(value) || !Number.isInteger(value) || value < 0)) {
+                throw new ValidationError(`Contract cache delta ${name} must be a non-negative integer.`);
+            }
+        }
     }
     async cacheContracts(args) {
         const parties = normalizeParties(args);
@@ -45,7 +62,7 @@ export class GrpcContractCache {
         if (snapshot === undefined) {
             return undefined;
         }
-        return Object.freeze({ activeAtOffset: snapshot.activeAtOffset, contracts: snapshot.contracts });
+        return Object.freeze({ activeAtOffset: snapshot.activeAtOffset, contracts: snapshot.contracts, creationMetadata: snapshot.creationMetadata });
     }
     async invalidateContractsCache(args) {
         const parties = normalizeParties(args);
@@ -58,7 +75,186 @@ export class GrpcContractCache {
         }
         await this.store.deleteAsync(key);
     }
+    /** Measures the cached snapshot against the current ledger end, without changing anything. */
+    async inspectContractsCacheAsync(args) {
+        const parties = normalizeParties(args);
+        const base = asCompatibleSnapshot(await this.store.getAsync(cacheKey(this.endpointScope, parties)), this.endpointScope, parties, currentEpochMs(this.now), true);
+        if (base === undefined || this.stateService.getLedgerEndAsync === undefined) {
+            return undefined;
+        }
+        const ledgerEnd = parseCacheOffset((await this.stateService.getLedgerEndAsync({})).offset);
+        const activeAt = parseCacheOffset(base.activeAtOffset);
+        if (ledgerEnd === undefined || activeAt === undefined || ledgerEnd < activeAt) {
+            return undefined;
+        }
+        return Object.freeze({
+            activeAtOffset: base.activeAtOffset,
+            ledgerEndOffset: ledgerEnd.toString(),
+            offsetGap: (ledgerEnd - activeAt).toString(),
+            contractCount: base.contracts.length,
+            expiresAt: new Date(base.expiresAtEpochMs),
+        });
+    }
     async populateAsync(parties, key) {
+        // An expired snapshot is still a valid delta base: expiry gates queries, not refreshes.
+        const base = asCompatibleSnapshot(await this.store.getAsync(key), this.endpointScope, parties, currentEpochMs(this.now), true);
+        if (base !== undefined && this.updateService !== undefined && this.delta.enabled === true) {
+            const delta = await this.tryDeltaRefreshAsync(parties, key, base);
+            if (delta !== undefined) {
+                return delta;
+            }
+        }
+        return this.fullRefreshAsync(parties, key, base);
+    }
+    /**
+     * Patches the base snapshot forward from the update stream instead of re-downloading the ACS. Returns
+     * undefined — meaning "do the full download instead" — whenever correctness cannot be proven cheaply:
+     * pruning past the base offset, an offset gap or update count beyond the configured budgets, any
+     * reassignment or topology change in the window (multi-synchronizer moves cannot be patched safely), an
+     * exercised event where ACS_DELTA promises none, or an archive/create inconsistent with the base rows.
+     */
+    async tryDeltaRefreshAsync(parties, key, base) {
+        if (this.stateService.getLedgerEndAsync === undefined || this.stateService.getLatestPrunedOffsetsAsync === undefined || this.updateService === undefined) {
+            return undefined;
+        }
+        try {
+            const baseOffset = parseCacheOffset(base.activeAtOffset);
+            const pruned = parseCacheOffset((await this.stateService.getLatestPrunedOffsetsAsync({})).participantPrunedUpToInclusive);
+            const ledgerEnd = parseCacheOffset((await this.stateService.getLedgerEndAsync({})).offset);
+            if (baseOffset === undefined || pruned === undefined || pruned > baseOffset || ledgerEnd === undefined || ledgerEnd < baseOffset) {
+                return undefined;
+            }
+            const offsetGap = ledgerEnd - baseOffset;
+            if (offsetGap === 0n) {
+                return this.writeSnapshotAsync(parties, key, base.activeAtOffset, base.contracts, base.creationMetadata, { refresh: "noop", offsetGap: "0" });
+            }
+            const maxOffsetGap = BigInt(this.delta.maxOffsetGap ?? DELTA_DEFAULT_MAX_OFFSET_GAP);
+            if (offsetGap > maxOffsetGap) {
+                return undefined;
+            }
+            const window = await this.readDeltaWindowAsync(parties, base, ledgerEnd.toString());
+            if (window === undefined) {
+                return undefined;
+            }
+            const baseIds = new Set(base.contracts.map((row) => row.contractId));
+            const adds = new Map();
+            const removes = new Set();
+            for (const entry of window.entries) {
+                if (entry.kind === "created") {
+                    if (baseIds.has(entry.event.contractId) || adds.has(entry.event.contractId)) {
+                        return undefined;
+                    }
+                    adds.set(entry.event.contractId, { event: entry.event, synchronizerId: entry.synchronizerId });
+                }
+                else if (adds.has(entry.contractId)) {
+                    adds.delete(entry.contractId);
+                }
+                else if (baseIds.has(entry.contractId)) {
+                    removes.add(entry.contractId);
+                }
+                else {
+                    return undefined;
+                }
+            }
+            const survivors = [...adds.values()].map(({ event, synchronizerId }) => ({
+                contractEntry: {
+                    oneofKind: "activeContract",
+                    activeContract: { createdEvent: event, synchronizerId, reassignmentCounter: "0" },
+                },
+            }));
+            const fragment = mapGrpcQueryRelationFragment([], survivors);
+            const contracts = [...base.contracts.filter((row) => !removes.has(row.contractId)), ...fragment.contracts]
+                .sort((left, right) => left.contractId.localeCompare(right.contractId));
+            const addedMetadata = fragment.creationIdentities.map((identity) => ({
+                contractId: identity.contractId,
+                packageName: identity.packageName,
+                representativePackageId: identity.representativePackageId,
+            }));
+            const creationMetadata = [...base.creationMetadata.filter((entry) => !removes.has(entry.contractId)), ...addedMetadata]
+                .sort((left, right) => left.contractId.localeCompare(right.contractId));
+            return await this.writeSnapshotAsync(parties, key, ledgerEnd.toString(), contracts, creationMetadata, {
+                refresh: "delta",
+                offsetGap: offsetGap.toString(),
+                deltaUpdateCount: window.entries.length,
+            });
+        }
+        catch {
+            // Any validation failure in the window falls back to the full download, which re-validates from scratch.
+            return undefined;
+        }
+    }
+    async readDeltaWindowAsync(parties, base, endInclusive) {
+        const eventFormat = mapGrpcQueryContractsRequest(parties === undefined ? { allParties: true } : { parties }).eventFormat;
+        const maxUpdates = this.delta.maxUpdates ?? Math.max(1_000, 2 * base.contracts.length);
+        const entries = [];
+        const seenPageTokens = new Set();
+        const end = parseCacheOffset(endInclusive);
+        let expectedLowestExclusive = parseCacheOffset(base.activeAtOffset);
+        let pageToken;
+        let updatesSeen = 0;
+        for (let pagesRead = 0; pagesRead < DELTA_MAX_PAGES; pagesRead += 1) {
+            const request = {
+                beginOffsetExclusive: base.activeAtOffset,
+                endOffsetInclusive: endInclusive,
+                updateFormat: { includeTransactions: { eventFormat, transactionShape: TransactionShape.ACS_DELTA } },
+                descendingOrder: false,
+                pageToken: pageToken === undefined ? undefined : Uint8Array.from(pageToken),
+            };
+            const response = await this.updateService.getUpdatesPageAsync(request);
+            const lowest = parseCacheOffset(response.lowestPageOffsetExclusive);
+            const highest = parseCacheOffset(response.highestPageOffsetInclusive);
+            if (lowest === undefined || highest === undefined || lowest !== expectedLowestExclusive || highest < lowest || highest > end) {
+                return undefined;
+            }
+            updatesSeen += response.updates.length;
+            if (updatesSeen > maxUpdates) {
+                return undefined;
+            }
+            for (const update of response.updates) {
+                const collected = collectDeltaEntries(update, entries);
+                if (!collected) {
+                    return undefined;
+                }
+            }
+            const nextPageToken = response.nextPageToken;
+            if (nextPageToken === undefined || nextPageToken.length === 0) {
+                return highest === end ? { entries } : undefined;
+            }
+            else if (highest >= end || highest <= lowest) {
+                return undefined;
+            }
+            const tokenKey = Array.from(nextPageToken).join(",");
+            if (seenPageTokens.has(tokenKey)) {
+                return undefined;
+            }
+            seenPageTokens.add(tokenKey);
+            expectedLowestExclusive = highest;
+            pageToken = Uint8Array.from(nextPageToken);
+        }
+        return undefined;
+    }
+    async writeSnapshotAsync(parties, key, activeAtOffset, contracts, creationMetadata, outcome) {
+        const expiresAtEpochMs = effectiveExpiryEpochMs(this.now, this.ttlMs);
+        const snapshot = {
+            version: 2,
+            endpointScope: this.endpointScope,
+            parties,
+            activeAtOffset,
+            expiresAtEpochMs,
+            contracts: copyRows(contracts),
+            creationMetadata: creationMetadata.map((entry) => ({ ...entry })),
+        };
+        await this.store.setAsync(key, snapshot, this.ttlMs);
+        return {
+            source: QuerySource.grpc,
+            cached: true,
+            activeAtOffset,
+            contractCount: contracts.length,
+            expiresAt: new Date(expiresAtEpochMs),
+            ...outcome,
+        };
+    }
+    async fullRefreshAsync(parties, key, base) {
         const activeContracts = [];
         const seenPageTokens = new Set();
         // Every continuation request must be identical to the first page's request apart from the page
@@ -66,7 +262,9 @@ export class GrpcContractCache {
         // 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 });
+        const baseRequest = mapGrpcQueryContractsRequest(parties === undefined
+            ? { allParties: true, maxPageSize: this.maxPageSize }
+            : { parties, maxPageSize: this.maxPageSize });
         let activeAtOffset;
         let pageToken;
         do {
@@ -90,22 +288,35 @@ export class GrpcContractCache {
                 seenPageTokens.add(tokenKey);
             }
         } while (pageToken !== undefined && pageToken.length > 0);
-        const contracts = mapGrpcQueryRelationFragment([], activeContracts).contracts;
+        const fragment = mapGrpcQueryRelationFragment([], activeContracts);
+        const contracts = fragment.contracts;
+        const creationMetadata = fragment.creationIdentities.map((identity) => ({
+            contractId: identity.contractId,
+            packageName: identity.packageName,
+            representativePackageId: identity.representativePackageId,
+        }));
         const expiresAtEpochMs = effectiveExpiryEpochMs(this.now, this.ttlMs);
+        const baseOffset = base === undefined ? undefined : parseCacheOffset(base.activeAtOffset);
+        const newOffset = parseCacheOffset(activeAtOffset);
         const result = {
             source: QuerySource.grpc,
             cached: true,
             activeAtOffset: activeAtOffset,
             contractCount: contracts.length,
             expiresAt: new Date(expiresAtEpochMs),
+            refresh: "full",
+            ...(baseOffset !== undefined && newOffset !== undefined && newOffset >= baseOffset
+                ? { offsetGap: (newOffset - baseOffset).toString() }
+                : {}),
         };
         const snapshot = {
-            version: 1,
+            version: 2,
             endpointScope: this.endpointScope,
             parties,
             activeAtOffset: activeAtOffset,
             expiresAtEpochMs,
             contracts: copyRows(contracts),
+            creationMetadata,
         };
         await this.store.setAsync(key, snapshot, this.ttlMs);
         return result;
@@ -150,7 +361,43 @@ export function normalizeParties(args) {
 function cacheKey(endpointScope, parties) {
     return `grpc-contract-cache:v1:${JSON.stringify([endpointScope, parties])}`;
 }
-function asCompatibleSnapshot(value, endpointScope, parties, nowEpochMs) {
+/** Collects created/archived events from one ACS_DELTA update; false means the window cannot be patched. */
+function collectDeltaEntries(update, entries) {
+    if (update === null || typeof update !== "object") {
+        return false;
+    }
+    const oneof = update.update;
+    if (oneof === undefined || oneof.oneofKind === "offsetCheckpoint") {
+        return oneof !== undefined;
+    }
+    else if (oneof.oneofKind !== "transaction") {
+        // Reassignments and topology changes move contracts between synchronizers/visibility in ways a
+        // row-level patch cannot represent safely.
+        return false;
+    }
+    const transaction = oneof.transaction;
+    const synchronizerId = transaction?.synchronizerId;
+    if (typeof synchronizerId !== "string" || synchronizerId.length === 0 || !Array.isArray(transaction?.events)) {
+        return false;
+    }
+    for (const wrapped of transaction.events) {
+        const event = wrapped?.event;
+        if (event?.oneofKind === "created" && event.created !== undefined) {
+            entries.push({ kind: "created", event: event.created, synchronizerId });
+        }
+        else if (event?.oneofKind === "archived" && typeof event.archived?.contractId === "string" && event.archived.contractId.length > 0) {
+            entries.push({ kind: "archived", contractId: event.archived.contractId });
+        }
+        else {
+            return false;
+        }
+    }
+    return true;
+}
+function parseCacheOffset(value) {
+    return isCanonicalGrpcOffset(value) ? BigInt(value) : undefined;
+}
+function asCompatibleSnapshot(value, endpointScope, parties, nowEpochMs, ignoreExpiry = false) {
     try {
         if (value === null || typeof value !== "object") {
             return undefined;
@@ -163,7 +410,8 @@ function asCompatibleSnapshot(value, endpointScope, parties, nowEpochMs) {
         const activeAtOffset = candidate.activeAtOffset;
         const expiresAtEpochMs = candidate.expiresAtEpochMs;
         const contracts = materializeContractRows(candidate.contracts);
-        if (version !== 1
+        const creationMetadata = materializeCreationMetadata(candidate.creationMetadata, contracts);
+        if (version !== 2
             || storedEndpointScope !== endpointScope
             || (rawParties !== undefined && storedParties === undefined)
             || !sameParties(storedParties, parties)
@@ -174,8 +422,9 @@ function asCompatibleSnapshot(value, endpointScope, parties, nowEpochMs) {
             || typeof expiresAtEpochMs !== "number"
             || !Number.isFinite(expiresAtEpochMs)
             || !Number.isFinite(new Date(expiresAtEpochMs).getTime())
-            || expiresAtEpochMs <= nowEpochMs
-            || contracts === undefined) {
+            || (!ignoreExpiry && expiresAtEpochMs <= nowEpochMs)
+            || contracts === undefined
+            || creationMetadata === undefined) {
             return undefined;
         }
         return {
@@ -185,6 +434,7 @@ function asCompatibleSnapshot(value, endpointScope, parties, nowEpochMs) {
             activeAtOffset,
             expiresAtEpochMs,
             contracts,
+            creationMetadata,
         };
     }
     catch {
@@ -248,6 +498,40 @@ function materializePageToken(value) {
         throw new Error("Active-contracts response nextPageToken is invalid.");
     }
 }
+function materializeCreationMetadata(value, contracts) {
+    if (contracts === undefined) {
+        return undefined;
+    }
+    const entries = materializeIndexedValues(value, materializeCreationMetadataEntry);
+    if (entries === undefined || entries.some((entry) => entry === undefined)) {
+        return undefined;
+    }
+    const materialized = entries;
+    // Coherence: exactly one metadata entry per contract row, so the contractType join can never dangle.
+    const metadataContractIds = new Set(materialized.map((entry) => entry.contractId));
+    if (metadataContractIds.size !== materialized.length
+        || materialized.length !== contracts.length
+        || !contracts.every((row) => metadataContractIds.has(row.contractId))) {
+        return undefined;
+    }
+    return materialized;
+}
+function materializeCreationMetadataEntry(value) {
+    if (value === null || typeof value !== "object") {
+        return undefined;
+    }
+    const candidate = value;
+    const contractId = candidate.contractId;
+    const packageName = candidate.packageName;
+    const representativePackageId = candidate.representativePackageId;
+    if (typeof contractId !== "string"
+        || typeof packageName !== "string"
+        || packageName.length === 0
+        || (typeof representativePackageId !== "string" && representativePackageId !== null)) {
+        return undefined;
+    }
+    return { contractId, packageName, representativePackageId };
+}
 function materializeContractRows(value) {
     const rows = materializeIndexedValues(value, materializeContractRow);
     if (rows === undefined) {

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

@@ -1,9 +1,10 @@
 import type { PackageServiceClient } from "../../services/package/package-service-client.js";
 import type { StateServiceClient } from "../../services/state/state-service-client.js";
 import type { UpdateServiceClient } from "../../services/update/update-service-client.js";
+import type { CantonLogger } from "../../core/types/canton-logger.js";
 import { type QueryDataset } from "../canonical/query-dataset.js";
 import type { NormalizedAggregateQuery, NormalizedCountQuery, NormalizedFindManyQuery, NormalizedFindUniqueQuery, NormalizedGroupByQuery } from "../canonical/query-ast.js";
-import type { ContractCacheArgs, ContractCacheResult, QueryClient } from "../query-client.js";
+import type { ContractCacheArgs, ContractCacheInspection, ContractCacheResult, QueryClient } from "../query-client.js";
 import { QuerySource } from "../query-source.js";
 import { GrpcContractCache } from "./grpc-contract-cache.js";
 type NormalizedQuery = NormalizedFindManyQuery | NormalizedFindUniqueQuery | NormalizedCountQuery | NormalizedAggregateQuery | NormalizedGroupByQuery;
@@ -23,6 +24,14 @@ export interface GrpcQueryClientOptions {
      * the retained window lives for this client's lifetime and its RAM cost is the full replayed history.
      */
     readonly incrementalHistory?: boolean;
+    /**
+     * Opt-in: permit queries that replay ledger history (transactions/events/exercises, and contracts
+     * queries reaching archived state). Off by default — such queries throw HistoryWalkRequiredError so the
+     * replay cost is never paid implicitly.
+     */
+    readonly walkHistory?: boolean;
+    /** Receives SDK diagnostics (e.g. the once-per-relation full-replay warning); defaults to console. */
+    readonly logger?: CantonLogger;
 }
 export declare class GrpcQueryClient implements QueryClient {
     private readonly options;
@@ -41,6 +50,7 @@ export declare class GrpcQueryClient implements QueryClient {
     $queryRaw<TRow>(_sql: string, _values?: readonly unknown[]): Promise<readonly TRow[]>;
     cacheContracts(args?: ContractCacheArgs): Promise<ContractCacheResult>;
     invalidateContractsCache(args?: ContractCacheArgs): Promise<void>;
+    inspectContractsCache(args?: ContractCacheArgs): Promise<ContractCacheInspection | undefined>;
     private delegate;
     private collectionDelegate;
     private execute;