@distrohelena/canton-typescript-sdk 0.1.36 → 0.1.37

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

@@ -0,0 +1,43 @@
+import { CantonError } from "../../core/errors/canton-error.js";
+import { DamlLfPackageLoader } from "../../daml-lf/daml-lf-package-loader.js";
+import { type GetPackageResponse, type ListPackagesResponse } from "../../transports/grpc/generated/canton/com/daml/ledger/api/v2/package_service.js";
+export interface GrpcPackageService {
+    listPackagesAsync(request: {}): Promise<ListPackagesResponse>;
+    getPackageAsync(request: {
+        packageId: string;
+    }): Promise<GetPackageResponse>;
+}
+export interface GrpcPackageChoiceMetadata {
+    readonly choice: string;
+    readonly consuming: boolean;
+    readonly aliases: readonly string[];
+    readonly choiceFqn: string;
+}
+export interface GrpcPackageTemplateMetadata {
+    readonly moduleName: string;
+    readonly entityName: string;
+    readonly payloadType: "template" | "interface";
+    readonly aliases: readonly string[];
+    readonly templateFqn: string;
+    readonly choices: readonly GrpcPackageChoiceMetadata[];
+}
+export interface GrpcPackageMetadata {
+    readonly id: string;
+    readonly name: string;
+    readonly version: string;
+    readonly templates: readonly GrpcPackageTemplateMetadata[];
+}
+/** An explicit package-service/LF decoding failure; callers never receive partial package rows. */
+export declare class GrpcPackageRelationError extends CantonError {
+    readonly packageId: string;
+    constructor(packageId: string, message: string);
+}
+/** Loads LF package metadata. Each call owns its promise map, so no package data enters QueryCacheStore. */
+export declare class GrpcPackageRelationReader {
+    private readonly packageService;
+    private readonly packageLoader;
+    constructor(packageService: GrpcPackageService, packageLoader?: DamlLfPackageLoader);
+    readAllAsync(): Promise<readonly GrpcPackageMetadata[]>;
+    readPackagesAsync(packageIds: readonly string[]): Promise<readonly GrpcPackageMetadata[]>;
+    private readPackageAsync;
+}

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

@@ -0,0 +1,213 @@
+import { createHash } from "node:crypto";
+import { CantonError } from "../../core/errors/canton-error.js";
+import { DamlLfPackageLoader } from "../../daml-lf/daml-lf-package-loader.js";
+import { DamlLfTemplate } from "../../daml-lf/model/daml-lf-template.js";
+import { Lf2ModelMapper } from "../../daml-lf/model/lf-2-model-mapper.js";
+import { Archive, HashFunction as ArchiveHashFunction } from "../../transports/grpc/generated/canton/com/digitalasset/daml/lf/archive/daml_lf.js";
+import { HashFunction as PackageServiceHashFunction } from "../../transports/grpc/generated/canton/com/daml/ledger/api/v2/package_service.js";
+import { validDottedNameString, validNameString, validPackageIdString } from "./grpc-query-value-mapper.js";
+/** An explicit package-service/LF decoding failure; callers never receive partial package rows. */
+export class GrpcPackageRelationError extends CantonError {
+    packageId;
+    constructor(packageId, message) {
+        super(`gRPC query package ${packageId} could not be materialized: ${message}`);
+        this.packageId = packageId;
+        Object.freeze(this);
+    }
+}
+/** Loads LF package metadata. Each call owns its promise map, so no package data enters QueryCacheStore. */
+export class GrpcPackageRelationReader {
+    packageService;
+    packageLoader;
+    constructor(packageService, packageLoader = new DamlLfPackageLoader()) {
+        this.packageService = packageService;
+        this.packageLoader = packageLoader;
+    }
+    async readAllAsync() {
+        let packageIds;
+        try {
+            packageIds = packageIdsSnapshot(await this.packageService.listPackagesAsync({}));
+        }
+        catch (error) {
+            throw new GrpcPackageRelationError("<list>", errorMessage(error));
+        }
+        const packages = await this.readPackagesAsync(packageIds);
+        return Object.freeze(packages.filter((pkg) => pkg.templates.length > 0));
+    }
+    async readPackagesAsync(packageIds) {
+        const uniquePackageIds = new Set();
+        for (const packageId of packageIds) {
+            try {
+                validPackageDigest(packageId);
+            }
+            catch (error) {
+                throw new GrpcPackageRelationError(typeof packageId === "string" ? packageId : "<invalid>", errorMessage(error));
+            }
+            uniquePackageIds.add(packageId);
+        }
+        const packages = await Promise.all([...uniquePackageIds].map((packageId) => this.readPackageAsync(packageId)));
+        return Object.freeze(packages.slice().sort((left, right) => left.id.localeCompare(right.id)));
+    }
+    async readPackageAsync(packageId) {
+        let response;
+        try {
+            response = await this.packageService.getPackageAsync({ packageId });
+        }
+        catch (error) {
+            throw new GrpcPackageRelationError(packageId, errorMessage(error));
+        }
+        try {
+            if (response.hash !== packageId) {
+                throw new Error("Package Service response hash does not match its request");
+            }
+            else if (!(response.archivePayload instanceof Uint8Array) || response.archivePayload.length === 0) {
+                throw new Error("Package Service response archive payload is missing");
+            }
+            else if (response.hashFunction !== PackageServiceHashFunction.SHA256) {
+                throw new Error("Package Service response uses an unsupported hash function");
+            }
+            const digest = createHash("sha256").update(response.archivePayload).digest("hex");
+            if (digest !== packageId || digest !== response.hash) {
+                throw new Error("Package Service response archive payload does not match its SHA-256 hash");
+            }
+            const archive = Archive.toBinary({
+                hashFunction: ArchiveHashFunction.SHA256,
+                payload: response.archivePayload,
+                hash: response.hash,
+            });
+            const result = this.packageLoader.loadRawPackageOrThrow(archive);
+            const pkg = Lf2ModelMapper.mapPackage(result.packageId, result.rawPackage, result.languageVersion);
+            const packageName = requiredPackageText(pkg.packageName, "name");
+            const templates = [
+                ...pkg.modules.flatMap((module) => module.definitions
+                    .filter((definition) => definition instanceof DamlLfTemplate)
+                    .map((template) => templateMetadata(packageId, packageName, module.name, template))),
+                ...interfaceMetadata(packageId, packageName, result.rawPackage),
+            ];
+            return Object.freeze({
+                id: packageId,
+                name: packageName,
+                version: requiredPackageText(pkg.packageVersion, "version"),
+                templates: Object.freeze(templates),
+            });
+        }
+        catch (error) {
+            throw isGrpcPackageRelationError(error) ? error : new GrpcPackageRelationError(packageId, errorMessage(error));
+        }
+    }
+}
+function packageIdsSnapshot(response) {
+    if (response === null || typeof response !== "object") {
+        throw new Error("Package Service returned no package IDs");
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(response, "packageIds");
+    if (descriptor === undefined || !("value" in descriptor) || !Array.isArray(descriptor.value)) {
+        throw new Error("Package Service returned no package IDs");
+    }
+    const packageIds = Array.from(descriptor.value, validPackageDigest);
+    if (packageIds.length === 0) {
+        throw new Error("Package Service returned no package IDs");
+    }
+    return Object.freeze(packageIds);
+}
+function validPackageDigest(value) {
+    if (typeof value !== "string") {
+        throw new Error("Package Service package ID is invalid");
+    }
+    validPackageIdString(value, "package id");
+    if (!/^[0-9a-f]{64}$/.test(value)) {
+        throw new Error("Package Service package ID is not a lowercase SHA-256 digest");
+    }
+    return value;
+}
+function templateMetadata(packageId, packageName, moduleName, template) {
+    validDottedNameString(moduleName, "DAML-LF module name");
+    validDottedNameString(template.templateId.templateName, "DAML-LF template name");
+    const entityName = template.templateId.templateName;
+    const templateFqn = `${packageName}:${moduleName}:${entityName}`;
+    return Object.freeze({
+        moduleName,
+        entityName,
+        payloadType: "template",
+        aliases: contractTypeAliases(packageName, moduleName, entityName),
+        templateFqn,
+        choices: Object.freeze(template.choices.map((choice) => {
+            validNameString(choice.name, "DAML-LF choice name");
+            return Object.freeze({ choice: choice.name, consuming: choice.consuming, aliases: exerciseTypeAliases(packageName, moduleName, entityName, choice.name), choiceFqn: `${templateFqn}:${choice.name}` });
+        }).sort((left, right) => left.choice.localeCompare(right.choice))),
+    });
+}
+function interfaceMetadata(packageId, packageName, rawPackage) {
+    return rawPackage.modules.flatMap((module) => {
+        const moduleName = resolveInternedDottedName(rawPackage, module.nameInternedDname);
+        return module.interfaces.map((definition) => rawInterfaceMetadata(packageId, packageName, moduleName, definition, rawPackage));
+    });
+}
+function rawInterfaceMetadata(packageId, packageName, moduleName, definition, rawPackage) {
+    validDottedNameString(moduleName, "DAML-LF module name");
+    const entityName = resolveInternedDottedName(rawPackage, definition.tyconInternedDname);
+    validDottedNameString(entityName, "DAML-LF interface name");
+    const templateFqn = `${packageName}:${moduleName}:${entityName}`;
+    return Object.freeze({
+        moduleName,
+        entityName,
+        payloadType: "interface",
+        aliases: contractTypeAliases(packageName, moduleName, entityName),
+        templateFqn,
+        choices: Object.freeze(definition.choices.map((choice) => rawInterfaceChoiceMetadata(packageId, packageName, moduleName, entityName, choice, rawPackage))
+            .sort((left, right) => left.choice.localeCompare(right.choice))),
+    });
+}
+function rawInterfaceChoiceMetadata(packageId, packageName, moduleName, entityName, choice, rawPackage) {
+    const choiceName = resolveInternedString(rawPackage, choice.nameInternedStr);
+    validNameString(choiceName, `DAML-LF package ${packageId} interface choice name`);
+    return Object.freeze({
+        choice: choiceName,
+        consuming: choice.consuming,
+        aliases: exerciseTypeAliases(packageName, moduleName, entityName, choiceName),
+        choiceFqn: `${packageName}:${moduleName}:${entityName}:${choiceName}`,
+    });
+}
+function contractTypeAliases(packageName, moduleName, entityName) {
+    return Object.freeze([`${packageName}:${moduleName}:${entityName}`, `${moduleName}:${entityName}`, entityName]);
+}
+function exerciseTypeAliases(packageName, moduleName, entityName, choiceName) {
+    return Object.freeze([`${packageName}:${moduleName}:${entityName}:${choiceName}`, `${moduleName}:${entityName}:${choiceName}`, `${entityName}:${choiceName}`, choiceName]);
+}
+function resolveInternedDottedName(rawPackage, index) {
+    const dottedName = rawPackage.internedDottedNames[index];
+    if (dottedName === undefined) {
+        throw new Error("DAML-LF interface references a missing interned dotted name");
+    }
+    return dottedName.segmentsInternedStr.map((segment) => resolveInternedString(rawPackage, segment)).join(".");
+}
+function resolveInternedString(rawPackage, index) {
+    const value = rawPackage.internedStrings[index];
+    if (value === undefined) {
+        throw new Error("DAML-LF interface references a missing interned string");
+    }
+    return value;
+}
+function requiredPackageText(value, name) {
+    if (value.length === 0) {
+        throw new Error(`DAML-LF package ${name} is missing`);
+    }
+    return value;
+}
+function errorMessage(error) {
+    try {
+        const message = error instanceof Error ? error.message : String(error);
+        return typeof message === "string" ? message : "Unknown package service error";
+    }
+    catch {
+        return "Unknown package service error";
+    }
+}
+function isGrpcPackageRelationError(error) {
+    try {
+        return error instanceof GrpcPackageRelationError;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,42 @@
+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 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 { QuerySource } from "../query-source.js";
+import { GrpcContractCache } from "./grpc-contract-cache.js";
+type NormalizedQuery = NormalizedFindManyQuery | NormalizedFindUniqueQuery | NormalizedCountQuery | NormalizedAggregateQuery | NormalizedGroupByQuery;
+/** The sole transport boundary used by every typed gRPC query delegate. */
+interface GrpcQueryDataProvider {
+    readDatasetAsync(query: NormalizedQuery): Promise<QueryDataset>;
+}
+export interface GrpcQueryClientOptions {
+    readonly stateService: Pick<StateServiceClient, "getLedgerEndAsync" | "getLatestPrunedOffsetsAsync" | "getActiveContractsPageAsync">;
+    readonly updateService: Pick<UpdateServiceClient, "getUpdatesPageAsync">;
+    readonly packageService: Pick<PackageServiceClient, "listPackagesAsync" | "getPackageAsync">;
+    readonly contractCache?: GrpcContractCache;
+    readonly endpointScope?: string;
+}
+export declare class GrpcQueryClient implements QueryClient {
+    private readonly options;
+    readonly source = QuerySource.grpc;
+    private readonly evaluator;
+    private readonly dataProvider;
+    readonly contracts: QueryClient["contracts"];
+    readonly contractTypes: QueryClient["contractTypes"];
+    readonly events: QueryClient["events"];
+    readonly exercises: QueryClient["exercises"];
+    readonly exerciseTypes: QueryClient["exerciseTypes"];
+    readonly packages: QueryClient["packages"];
+    readonly transactions: QueryClient["transactions"];
+    readonly watermark: QueryClient["watermark"];
+    constructor(options: GrpcQueryClientOptions, dataProvider?: GrpcQueryDataProvider);
+    $queryRaw<TRow>(_sql: string, _values?: readonly unknown[]): Promise<readonly TRow[]>;
+    cacheContracts(args?: ContractCacheArgs): Promise<ContractCacheResult>;
+    invalidateContractsCache(args?: ContractCacheArgs): Promise<void>;
+    private delegate;
+    private collectionDelegate;
+    private execute;
+}
+export {};

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

@@ -0,0 +1,245 @@
+import { ValidationError } from "../../core/errors/validation-error.js";
+import { QueryCapabilityError } from "../errors/query-capability-error.js";
+import { InMemoryQueryEvaluator } from "../canonical/in-memory-query-evaluator.js";
+import { createQueryDataset } from "../canonical/query-dataset.js";
+import { normalizeAggregate, normalizeCount, normalizeFindMany, normalizeFindUnique, normalizeGroupBy } from "../canonical/query-normalizer.js";
+import { queryRelationEdges, queryRelations } from "../canonical/query-schema.js";
+import { QuerySource } from "../query-source.js";
+import { createGrpcQueryDataset, mapGrpcQueryRelationFragment, referencedGrpcPackageIds } from "./grpc-relation-mapper.js";
+import { GrpcPackageRelationReader } from "./grpc-package-relation-reader.js";
+import { GrpcQuerySnapshotReader } from "./grpc-query-snapshot-reader.js";
+export class GrpcQueryClient {
+    options;
+    source = QuerySource.grpc;
+    evaluator = new InMemoryQueryEvaluator();
+    dataProvider;
+    contracts = this.delegate("contracts");
+    contractTypes = this.delegate("contractTypes");
+    events = this.delegate("events");
+    exercises = this.collectionDelegate("exercises");
+    exerciseTypes = this.delegate("exerciseTypes");
+    packages = this.delegate("packages");
+    transactions = this.delegate("transactions");
+    watermark = this.delegate("watermark");
+    constructor(options, dataProvider) {
+        this.options = options;
+        this.dataProvider = dataProvider ?? new DefaultGrpcQueryDataProvider(options);
+    }
+    async $queryRaw(_sql, _values = []) {
+        throw new QueryCapabilityError(QuerySource.grpc, "query.$queryRaw");
+    }
+    async cacheContracts(args) {
+        if (this.options.contractCache === undefined) {
+            throw new ValidationError("gRPC contract caching requires configured cache storage and ttlMs.");
+        }
+        return this.options.contractCache.cacheContracts(args);
+    }
+    async invalidateContractsCache(args) {
+        await this.options.contractCache?.invalidateContractsCache(args);
+    }
+    delegate(relation) {
+        return {
+            findMany: async (args = {}) => this.execute(normalizeFindMany(relation, args)),
+            findUnique: async (args) => this.execute(normalizeFindUnique(relation, args)),
+            count: async (args = {}) => this.execute(normalizeCount(relation, args)),
+            aggregate: async (args) => this.execute(normalizeAggregate(relation, args)),
+            groupBy: async (args) => this.execute(normalizeGroupBy(relation, args)),
+        };
+    }
+    collectionDelegate(relation) {
+        const delegate = this.delegate(relation);
+        delete delegate.findUnique;
+        return delegate;
+    }
+    async execute(query) {
+        const dataset = await this.dataProvider.readDatasetAsync(query);
+        return this.evaluator.execute(dataset, query);
+    }
+}
+class DefaultGrpcQueryDataProvider {
+    options;
+    snapshots;
+    packages;
+    constructor(options) {
+        this.options = options;
+        this.snapshots = new GrpcQuerySnapshotReader(options.stateService, options.updateService);
+        this.packages = new GrpcPackageRelationReader(options.packageService);
+    }
+    async readDatasetAsync(query) {
+        const closure = relationClosure(query);
+        const needsHistory = requiresHistory(query);
+        const activeOnly = query.relation === "contracts" && isActiveOnly(query);
+        const cached = activeOnly && this.options.contractCache !== undefined
+            ? await this.options.contractCache.readSnapshotAsync({ parties: partiesFor(query) })
+            : undefined;
+        if (cached !== undefined && !needsHistory && !requiresPackageMetadata(closure)) {
+            return cachedContractsDataset(cached.contracts, cached.activeAtOffset, this.options.endpointScope ?? "ledger");
+        }
+        else if (needsHistory) {
+            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] : []);
+            const fragment = mapGrpcQueryRelationFragment(transactions);
+            const packageMetadata = !requiresPackageMetadata(closure)
+                ? []
+                : query.relation === "packages" || query.relation === "contractTypes" || query.relation === "exerciseTypes"
+                    ? await this.packages.readAllAsync()
+                    : await this.packages.readPackagesAsync(referencedGrpcPackageIds(fragment));
+            return packageMetadata.length === 0
+                ? fragmentDataset(fragment, endInclusive, this.options.endpointScope ?? "ledger")
+                : createGrpcQueryDataset(fragment, packageMetadata, endInclusive, this.options.endpointScope ?? "ledger");
+        }
+        const endInclusive = cached?.activeAtOffset ?? (await this.options.stateService.getLedgerEndAsync({})).offset;
+        if (query.relation === "packages" || query.relation === "contractTypes" || query.relation === "exerciseTypes") {
+            return createGrpcQueryDataset(mapGrpcQueryRelationFragment([]), await this.packages.readAllAsync(), endInclusive, this.options.endpointScope ?? "ledger");
+        }
+        else if (query.relation === "watermark") {
+            return createGrpcQueryDataset(mapGrpcQueryRelationFragment([]), [], endInclusive, this.options.endpointScope ?? "ledger");
+        }
+        const active = await this.snapshots.readActiveContractsAsync(endInclusive, partiesFor(query));
+        const fragment = mapGrpcQueryRelationFragment([], active.activeContracts);
+        return requiresPackageMetadata(closure)
+            ? createGrpcQueryDataset(fragment, await this.packages.readPackagesAsync(referencedGrpcPackageIds(fragment)), endInclusive, this.options.endpointScope ?? "ledger")
+            : fragmentDataset(fragment, endInclusive, this.options.endpointScope ?? "ledger", false);
+    }
+}
+function requiresHistory(query) {
+    if (query.relation === "transactions" || query.relation === "events" || query.relation === "exercises") {
+        return true;
+    }
+    else if (query.relation === "contracts" && !isActiveOnly(query)) {
+        return true;
+    }
+    return predicateRequiresHistory(query.relation, query.predicate) || includesRequireHistory(query.relation, includesFor(query));
+}
+function partiesFor(query) {
+    return query.kind === "findMany" || query.kind === "count" ? query.parties : undefined;
+}
+function includesFor(query) {
+    return query.kind === "findMany" || query.kind === "findUnique" ? query.includes : [];
+}
+function isActiveOnly(query) {
+    if (query.kind === "findMany" || query.kind === "count") {
+        return query.activeOnly;
+    }
+    return predicateProvesActive(query.predicate);
+}
+function predicateProvesActive(predicate) {
+    if (predicate === undefined) {
+        return false;
+    }
+    else if (predicate.kind === "scalar") {
+        return predicate.path.length === 1 && predicate.path[0] === "active" && predicate.operator === "equals" && predicate.value === true;
+    }
+    else if (predicate.kind === "and") {
+        return predicate.children.some(predicateProvesActive);
+    }
+    else if (predicate.kind === "or") {
+        return predicate.children.length > 0 && predicate.children.every(predicateProvesActive);
+    }
+    return false;
+}
+function requiresPackageMetadata(closure) {
+    return closure.has("packages") || closure.has("contractTypes") || closure.has("exercises") || closure.has("exerciseTypes");
+}
+function predicateRequiresHistory(relation, predicate) {
+    if (predicate === undefined || predicate.kind === "scalar") {
+        return false;
+    }
+    else if (predicate.kind === "not") {
+        return predicateRequiresHistory(relation, predicate.child);
+    }
+    else if (predicate.kind === "and" || predicate.kind === "or") {
+        return predicate.children.some((child) => predicateRequiresHistory(relation, child));
+    }
+    else if (predicate.kind !== "relation") {
+        return false;
+    }
+    const target = queryRelationEdges[relation]?.[predicate.edge]?.target;
+    return target === "contracts" || target === "transactions" || target === "events" || target === "exercises" || target !== undefined && predicateRequiresHistory(target, predicate.predicate);
+}
+function includesRequireHistory(relation, includes) {
+    return includes.some((include) => include.relation === "contracts" || include.relation === "transactions" || include.relation === "events" || include.relation === "exercises" || predicateRequiresHistory(include.relation, include.predicate) || includesRequireHistory(include.relation, include.includes));
+}
+function relationClosure(query) {
+    const relations = new Set([query.relation]);
+    const visitPredicate = (relation, predicate) => {
+        if (predicate === undefined || predicate.kind === "scalar") {
+            return;
+        }
+        else if (predicate.kind === "relation") {
+            const target = queryRelationEdges[relation]?.[predicate.edge]?.target;
+            if (target !== undefined) {
+                relations.add(target);
+                visitPredicate(target, predicate.predicate);
+            }
+        }
+        else if (predicate.kind === "not") {
+            visitPredicate(relation, predicate.child);
+        }
+        else {
+            predicate.children.forEach((child) => visitPredicate(relation, child));
+        }
+    };
+    const visitIncludes = (relation, includes) => {
+        for (const include of includes) {
+            relations.add(include.relation);
+            visitPredicate(include.relation, include.predicate);
+            visitIncludes(include.relation, include.includes);
+        }
+    };
+    visitPredicate(query.relation, query.predicate);
+    visitIncludes(query.relation, includesFor(query));
+    if (query.kind === "groupBy") {
+        for (const group of query.by) {
+            addRelationPath(query.relation, group.path, relations);
+        }
+    }
+    else if (query.kind === "findMany") {
+        for (const order of query.orderBy) {
+            addRelationPath(query.relation, order.path, relations);
+        }
+    }
+    return relations;
+}
+function addRelationPath(relation, path, relations) {
+    if (path.length > 1) {
+        const target = queryRelationEdges[relation]?.[path[0]]?.target;
+        if (target !== undefined) {
+            relations.add(target);
+        }
+    }
+}
+function cachedContractsDataset(contracts, offset, instanceId) {
+    const empty = [];
+    return basicDataset({ contracts: contracts, transactions: empty, events: empty, exercises: empty }, offset, instanceId, false);
+}
+function fragmentDataset(fragment, offset, instanceId, completeHistoryEdges = true) {
+    return basicDataset(fragment, offset, instanceId, completeHistoryEdges);
+}
+function basicDataset(rows, offset, instanceId, completeHistoryEdges = true) {
+    const empty = [];
+    return createQueryDataset({
+        rows: { contracts: rows.contracts, contractTypes: empty, events: rows.events, exercises: rows.exercises, exerciseTypes: empty, packages: empty, transactions: rows.transactions, watermark: [{ singleton: true, ix: offset, offset, instanceId }] },
+        uniqueKeys: { contracts: [["contractId"]], contractTypes: [["pk"]], events: [["pk"]], exercises: [["tpePk", "contractTpePk", "exerciseEventPk", "contractId"]], exerciseTypes: [["pk"]], packages: [["pk"], ["id"]], transactions: [["ix"], ["offset"]], watermark: [["singleton"]] },
+        edges: Object.fromEntries(queryRelations.map((relation) => [relation, Object.fromEntries(Object.keys(queryRelationEdges[relation] ?? {}).map((edge) => [edge, { ...cachedEdgePaths(relation, edge), ...(completeHistoryEdges ? completeFragmentEdge(relation, edge) : { complete: false }) }]))])),
+    });
+}
+function completeFragmentEdge(relation, edge) {
+    const complete = new Set([
+        "contracts.createdTransaction", "contracts.archivedTransaction", "contracts.exercises",
+        "events.transaction", "events.exercises",
+        "exercises.event", "exercises.transaction", "exercises.contract",
+        "transactions.events", "transactions.createdContracts", "transactions.archivedContracts", "transactions.exercises",
+    ]);
+    return complete.has(`${relation}.${edge}`) ? {} : { complete: false };
+}
+function cachedEdgePaths(relation, edge) {
+    const paths = {
+        "contracts.contractType": { from: ["contractId"], to: ["pk"] }, "contracts.createdTransaction": { from: ["createdEventOffset"], to: ["ix"] }, "contracts.archivedTransaction": { from: ["archivedEventOffset"], to: ["ix"] }, "contracts.exercises": { from: ["contractId"], to: ["contractId"] },
+        "contractTypes.contracts": { from: ["pk"], to: ["contractId"] }, "contractTypes.exercises": { from: ["pk"], to: ["contractTpePk"] }, "events.transaction": { from: ["txIx"], to: ["ix"] }, "events.exercises": { from: ["pk"], to: ["exerciseEventPk"] },
+        "exercises.exerciseType": { from: ["tpePk"], to: ["pk"] }, "exercises.contractType": { from: ["contractTpePk"], to: ["pk"] }, "exercises.event": { from: ["exerciseEventPk"], to: ["pk"] }, "exercises.transaction": { from: ["exercisedAtIx"], to: ["ix"] }, "exercises.package": { from: ["packagePk"], to: ["pk"] }, "exercises.contract": { from: ["contractId"], to: ["contractId"] },
+        "exerciseTypes.exercises": { from: ["pk"], to: ["tpePk"] }, "packages.exercises": { from: ["pk"], to: ["packagePk"] }, "transactions.events": { from: ["ix"], to: ["txIx"] }, "transactions.createdContracts": { from: ["ix"], to: ["createdEventOffset"] }, "transactions.archivedContracts": { from: ["ix"], to: ["archivedEventOffset"] }, "transactions.exercises": { from: ["ix"], to: ["exercisedAtIx"] },
+    };
+    return paths[`${relation}.${edge}`];
+}

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

@@ -0,0 +1,33 @@
+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";
+type StateSnapshotReader = Pick<StateServiceClient, "getLedgerEndAsync" | "getLatestPrunedOffsetsAsync" | "getActiveContractsPageAsync">;
+type UpdateSnapshotReader = Pick<UpdateServiceClient, "getUpdatesPageAsync">;
+export interface GrpcHistorySnapshot {
+    readonly endInclusive: string;
+    readonly updates: readonly GetUpdateResponseType[];
+}
+export interface GrpcActiveContractSnapshot {
+    readonly activeAtOffset: string;
+    readonly activeContracts: readonly GetActiveContractsResponseType[];
+}
+export interface GrpcQuerySnapshotReaderOptions {
+    readonly maxHistoryPages?: number;
+    readonly maxHistoryUpdates?: number;
+    readonly maxActiveContractPages?: number;
+    readonly maxActiveContracts?: number;
+}
+export declare class GrpcQuerySnapshotReader {
+    private readonly stateService;
+    private readonly updateService;
+    private readonly options;
+    constructor(stateService: StateSnapshotReader, updateService: UpdateSnapshotReader, options?: GrpcQuerySnapshotReaderOptions);
+    readCurrentHistoryAsync(): Promise<GrpcHistorySnapshot>;
+    readHistoryAsync(endInclusive: string): Promise<GrpcHistorySnapshot>;
+    readActiveContractsAsync(activeAtOffset: string, parties?: readonly string[]): Promise<GrpcActiveContractSnapshot>;
+    private historyError;
+    private activeError;
+}
+export declare function isCanonicalGrpcOffset(value: unknown): value is string;
+export {};