@distrohelena/canton-typescript-sdk 0.1.35 → 0.1.37

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

@@ -0,0 +1,238 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GrpcQuerySnapshotReader = void 0;
+exports.isCanonicalGrpcOffset = isCanonicalGrpcOffset;
+const validation_error_js_1 = require("../../core/errors/validation-error.js");
+const state_service_js_1 = require("../../transports/grpc/generated/canton/com/daml/ledger/api/v2/state_service.js");
+const update_service_js_1 = require("../../transports/grpc/generated/canton/com/daml/ledger/api/v2/update_service.js");
+const transaction_filter_js_1 = require("../../transports/grpc/generated/canton/com/daml/ledger/api/v2/transaction_filter.js");
+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 = {
+    maxHistoryPages: 10_000,
+    maxHistoryUpdates: 1_000_000,
+    maxActiveContractPages: 10_000,
+    maxActiveContracts: 1_000_000,
+};
+const LEDGER_BEGIN = "0";
+class GrpcQuerySnapshotReader {
+    stateService;
+    updateService;
+    options;
+    constructor(stateService, updateService, options = {}) {
+        this.stateService = stateService;
+        this.updateService = updateService;
+        this.options = validateOptions(options);
+    }
+    async readCurrentHistoryAsync() {
+        const ledgerEnd = await this.stateService.getLedgerEndAsync({});
+        return this.readHistoryAsync(ledgerEnd.offset);
+    }
+    async readHistoryAsync(endInclusive) {
+        const end = parseOffset(endInclusive);
+        if (end === undefined) {
+            throw this.historyError(endInclusive, "invalid-offset");
+        }
+        const pruned = await this.stateService.getLatestPrunedOffsetsAsync({});
+        const prunedUpTo = parseOffset(pruned.participantPrunedUpToInclusive);
+        if (prunedUpTo === undefined || prunedUpTo !== 0n) {
+            throw this.historyError(endInclusive, "participant-pruned");
+        }
+        const updateFormat = freezeDeep(createHistoryUpdateFormat());
+        const updates = [];
+        const observedPageTokens = new Set();
+        let expectedLowestExclusive = 0n;
+        let pageToken;
+        let pagesRead = 0;
+        let previousUpdateOffset;
+        while (true) {
+            if (pagesRead >= this.options.maxHistoryPages) {
+                throw this.historyError(endInclusive, "max-pages-exceeded");
+            }
+            const request = {
+                beginOffsetExclusive: LEDGER_BEGIN,
+                endOffsetInclusive: endInclusive,
+                updateFormat,
+                descendingOrder: false,
+                pageToken: pageToken === undefined ? undefined : Uint8Array.from(pageToken),
+            };
+            const response = await this.updateService.getUpdatesPageAsync(request);
+            pagesRead += 1;
+            const lowest = parseOffset(response.lowestPageOffsetExclusive);
+            const highest = parseOffset(response.highestPageOffsetInclusive);
+            if (lowest === undefined || highest === undefined) {
+                throw this.historyError(endInclusive, "missing-boundary");
+            }
+            else if (lowest !== expectedLowestExclusive || highest < lowest || highest > end) {
+                throw this.historyError(endInclusive, "page-boundary-mismatch");
+            }
+            if (response.updates.length > this.options.maxHistoryUpdates - updates.length) {
+                throw this.historyError(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");
+                }
+                previousUpdateOffset = updateOffset;
+            }
+            updates.push(...response.updates.map(cloneFrozenUpdate));
+            const nextPageToken = response.nextPageToken;
+            if (nextPageToken === undefined || nextPageToken.length === 0) {
+                if (highest !== end) {
+                    throw this.historyError(endInclusive, "nonterminal-page-without-token");
+                }
+                return freezeSnapshot({
+                    endInclusive,
+                    updates: Object.freeze(updates),
+                });
+            }
+            else if (highest >= end) {
+                throw this.historyError(endInclusive, "nonterminal-page-reaches-end");
+            }
+            else if (highest <= lowest) {
+                throw this.historyError(endInclusive, "page-boundary-mismatch");
+            }
+            const tokenKey = tokenKeyFor(nextPageToken);
+            if (observedPageTokens.has(tokenKey)) {
+                throw this.historyError(endInclusive, "repeated-page-token");
+            }
+            observedPageTokens.add(tokenKey);
+            expectedLowestExclusive = highest;
+            pageToken = Uint8Array.from(nextPageToken);
+        }
+    }
+    async readActiveContractsAsync(activeAtOffset, parties) {
+        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 activeContracts = [];
+        const observedPageTokens = new Set();
+        let pageToken;
+        let pagesRead = 0;
+        while (true) {
+            if (pagesRead >= this.options.maxActiveContractPages) {
+                throw this.activeError(activeAtOffset, "max-pages-exceeded");
+            }
+            const request = {
+                activeAtOffset,
+                eventFormat,
+                pageToken: pageToken === undefined ? undefined : Uint8Array.from(pageToken),
+            };
+            const response = await this.stateService.getActiveContractsPageAsync(request);
+            pagesRead += 1;
+            const responseActiveAtOffset = parseOffset(response.activeAtOffset);
+            if (responseActiveAtOffset === undefined) {
+                throw this.activeError(activeAtOffset, "missing-active-at-offset");
+            }
+            else if (parseOffset(activeAtOffset) !== responseActiveAtOffset) {
+                throw this.activeError(activeAtOffset, "active-at-offset-mismatch");
+            }
+            else if (response.activeContracts.length === 0 && response.nextPageToken?.length) {
+                throw this.activeError(activeAtOffset, "empty-active-contract-page");
+            }
+            if (response.activeContracts.length > this.options.maxActiveContracts - activeContracts.length) {
+                throw this.activeError(activeAtOffset, "max-active-contracts-exceeded");
+            }
+            activeContracts.push(...response.activeContracts.map(cloneFrozenActiveContract));
+            const nextPageToken = response.nextPageToken;
+            if (nextPageToken === undefined || nextPageToken.length === 0) {
+                return freezeSnapshot({
+                    activeAtOffset,
+                    activeContracts: Object.freeze(activeContracts),
+                });
+            }
+            const tokenKey = tokenKeyFor(nextPageToken);
+            if (observedPageTokens.has(tokenKey)) {
+                throw this.activeError(activeAtOffset, "repeated-page-token");
+            }
+            observedPageTokens.add(tokenKey);
+            pageToken = Uint8Array.from(nextPageToken);
+        }
+    }
+    historyError(endInclusive, reason) {
+        return new query_snapshot_incomplete_error_js_1.QuerySnapshotIncompleteError({
+            beginExclusive: LEDGER_BEGIN,
+            endInclusive,
+            reason,
+        });
+    }
+    activeError(activeAtOffset, reason) {
+        return new query_snapshot_incomplete_error_js_1.QuerySnapshotIncompleteError({
+            beginExclusive: LEDGER_BEGIN,
+            endInclusive: activeAtOffset ?? "",
+            activeAtOffset,
+            reason,
+        });
+    }
+}
+exports.GrpcQuerySnapshotReader = GrpcQuerySnapshotReader;
+function validateOptions(options) {
+    const validated = { ...DEFAULT_OPTIONS, ...options };
+    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);
+}
+function createHistoryUpdateFormat() {
+    return {
+        includeTransactions: {
+            eventFormat: createAllPartiesEventFormat(),
+            transactionShape: transaction_filter_js_1.TransactionShape.LEDGER_EFFECTS,
+        },
+    };
+}
+function createAllPartiesEventFormat() {
+    return (0, contracts_mapper_js_1.mapGrpcQueryContractsRequest)({ allParties: true }).eventFormat;
+}
+function parseOffset(value) {
+    if (typeof value !== "string" || !/^(?:0|[1-9]\d{0,18})$/.test(value)) {
+        return undefined;
+    }
+    const parsed = BigInt(value);
+    return parsed <= 9223372036854775807n ? parsed : undefined;
+}
+function isCanonicalGrpcOffset(value) {
+    return parseOffset(value) !== undefined;
+}
+function extractUpdateOffset(update) {
+    const oneof = update.update;
+    switch (oneof.oneofKind) {
+        case "transaction": return oneof.transaction?.offset;
+        case "reassignment": return oneof.reassignment?.offset;
+        case "offsetCheckpoint": return oneof.offsetCheckpoint?.offset;
+        case "topologyTransaction": return oneof.topologyTransaction?.offset;
+        default: return undefined;
+    }
+}
+function tokenKeyFor(token) {
+    return Array.from(token).join(",");
+}
+function cloneFrozenUpdate(update) {
+    return freezeDeep(update_service_js_1.GetUpdateResponse.fromBinary(update_service_js_1.GetUpdateResponse.toBinary(update)));
+}
+function cloneFrozenActiveContract(activeContract) {
+    return freezeDeep(state_service_js_1.GetActiveContractsResponse.fromBinary(state_service_js_1.GetActiveContractsResponse.toBinary(activeContract)));
+}
+function freezeSnapshot(snapshot) {
+    return freezeDeep(snapshot);
+}
+function freezeDeep(value) {
+    if (value instanceof Uint8Array) {
+        return (0, query_dataset_js_1.immutableQueryValue)(value);
+    }
+    else if (value === null || typeof value !== "object") {
+        return value;
+    }
+    else if (Object.isFrozen(value)) {
+        return value;
+    }
+    for (const [property, child] of Object.entries(value)) {
+        value[property] = freezeDeep(child);
+    }
+    return Object.freeze(value);
+}

package/dist/cjs/query/grpc/grpc-query-value-mapper.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_GRPC_QUERY_VALUE_DEPTH = void 0;
+exports.mapGrpcQueryValue = mapGrpcQueryValue;
+exports.validPartyId = validPartyId;
+exports.validLedgerString = validLedgerString;
+exports.validNameString = validNameString;
+exports.validDottedNameString = validDottedNameString;
+exports.validPackageIdString = validPackageIdString;
+const validation_error_js_1 = require("../../core/errors/validation-error.js");
+const query_dataset_js_1 = require("../canonical/query-dataset.js");
+const MIN_DATE_EPOCH_DAY = -719_162;
+const MAX_DATE_EPOCH_DAY = 2_932_896;
+const INT64 = /^-?(?:0|[1-9]\d*)$/;
+/** Maximum generated Value nesting accepted before recursive mapping becomes unsafe. */
+exports.MAX_GRPC_QUERY_VALUE_DEPTH = 256;
+/** Maps a verbose Ledger API value to the JSON convention used by PQS predicates and rows. */
+function mapGrpcQueryValue(value) {
+    if (value === undefined || value.sum === undefined) {
+        throw new validation_error_js_1.ValidationError("gRPC query value is missing its sum");
+    }
+    const mapped = mapValue(value, 0);
+    return (0, query_dataset_js_1.immutableQueryValue)(mapped);
+}
+function mapValue(value, depth) {
+    if (depth > exports.MAX_GRPC_QUERY_VALUE_DEPTH) {
+        throw new validation_error_js_1.ValidationError(`gRPC query value exceeds maximum nesting depth ${exports.MAX_GRPC_QUERY_VALUE_DEPTH}`);
+    }
+    switch (value.sum.oneofKind) {
+        case "unit": return {};
+        case "bool": return value.sum.bool;
+        case "int64": return int64(value.sum.int64, "int64");
+        case "date": return date(value.sum.date);
+        case "timestamp": return timestamp(value.sum.timestamp);
+        case "numeric": return numeric(value.sum.numeric);
+        case "party": return validPartyId(value.sum.party);
+        case "text": return value.sum.text;
+        case "contractId": return validLedgerString(value.sum.contractId, "contract id");
+        case "optional": return value.sum.optional.value === undefined ? null : mapValue(value.sum.optional.value, depth + 1);
+        case "list": return value.sum.list.elements.map((entry) => mapValue(entry, depth + 1));
+        case "textMap": return mapTextMap(value.sum.textMap.entries, depth + 1);
+        case "genMap": return mapGenMap(value.sum.genMap.entries, depth + 1);
+        case "record": return mapRecord(value.sum.record.fields, depth + 1);
+        case "variant": {
+            if (value.sum.variant.value === undefined) {
+                throw new validation_error_js_1.ValidationError("gRPC query variant is incomplete");
+            }
+            return { tag: validNameString(value.sum.variant.constructor, "variant constructor"), value: mapValue(value.sum.variant.value, depth + 1) };
+        }
+        case "enum": {
+            return validNameString(value.sum.enum.constructor, "enum constructor");
+        }
+        case undefined: throw new validation_error_js_1.ValidationError("gRPC query value has no active sum");
+    }
+}
+function mapRecord(fields, depth) {
+    const output = Object.create(null);
+    for (const [index, field] of fields.entries()) {
+        if (field.label.length === 0) {
+            throw new validation_error_js_1.ValidationError(`gRPC query record field ${index} is unlabeled; verbose values are required`);
+        }
+        else if (Object.hasOwn(output, field.label)) {
+            throw new validation_error_js_1.ValidationError(`gRPC query record has duplicate label ${field.label}`);
+        }
+        else if (field.value === undefined) {
+            throw new validation_error_js_1.ValidationError(`gRPC query record field ${field.label} has no value`);
+        }
+        defineData(output, validNameString(field.label, `record field ${index} label`), mapValue(field.value, depth));
+    }
+    return output;
+}
+function mapTextMap(entries, depth) {
+    const output = Object.create(null);
+    for (const [index, entry] of entries.entries()) {
+        if (Object.hasOwn(output, entry.key)) {
+            throw new validation_error_js_1.ValidationError(`gRPC query text-map has duplicate key ${entry.key}`);
+        }
+        else if (entry.value === undefined) {
+            throw new validation_error_js_1.ValidationError(`gRPC query text-map entry ${index} has no value`);
+        }
+        defineData(output, entry.key, mapValue(entry.value, depth));
+    }
+    return output;
+}
+function mapGenMap(entries, depth) {
+    const seenKeys = new Set();
+    return entries.map((entry, index) => {
+        if (entry.key === undefined || entry.value === undefined) {
+            throw new validation_error_js_1.ValidationError(`gRPC query gen-map entry ${index} is incomplete`);
+        }
+        const key = mapValue(entry.key, depth);
+        const canonicalKey = canonicalLedgerKey(entry.key);
+        if (seenKeys.has(canonicalKey)) {
+            throw new validation_error_js_1.ValidationError(`gRPC query gen-map has duplicate key at entry ${index}`);
+        }
+        seenKeys.add(canonicalKey);
+        return [key, mapValue(entry.value, depth)];
+    });
+}
+function canonicalLedgerKey(value) {
+    switch (value.sum.oneofKind) {
+        case "unit": return "unit";
+        case "bool": return `bool:${value.sum.bool}`;
+        case "int64": return `int64:${JSON.stringify(value.sum.int64)}`;
+        case "date": return `date:${value.sum.date}`;
+        case "timestamp": return `timestamp:${JSON.stringify(value.sum.timestamp)}`;
+        case "numeric": return `numeric:${canonicalNumeric(value.sum.numeric)}`;
+        case "party": return `party:${JSON.stringify(value.sum.party)}`;
+        case "text": return `text:${JSON.stringify(value.sum.text)}`;
+        case "contractId": return `contractId:${JSON.stringify(value.sum.contractId)}`;
+        case "optional": return value.sum.optional.value === undefined ? "optional:none" : `optional:some(${canonicalLedgerKey(value.sum.optional.value)})`;
+        case "list": return `list:[${value.sum.list.elements.map(canonicalLedgerKey).join(",")}]`;
+        case "textMap": return `textMap:{${[...value.sum.textMap.entries].sort((left, right) => left.key.localeCompare(right.key)).map((entry) => `${JSON.stringify(entry.key)}:${canonicalLedgerKey(entry.value)}`).join(",")}}`;
+        case "genMap": return `genMap:{${value.sum.genMap.entries.map((entry) => `${canonicalLedgerKey(entry.key)}:${canonicalLedgerKey(entry.value)}`).sort().join(",")}}`;
+        case "record": return `record:{${[...value.sum.record.fields].sort((left, right) => left.label.localeCompare(right.label)).map((field) => `${JSON.stringify(field.label)}:${canonicalLedgerKey(field.value)}`).join(",")}}`;
+        case "variant": return `variant:${JSON.stringify(value.sum.variant.constructor)}:${canonicalLedgerKey(value.sum.variant.value)}`;
+        case "enum": return `enum:${JSON.stringify(value.sum.enum.constructor)}`;
+        case undefined: return invalidGenMapKey();
+    }
+}
+function canonicalNumeric(value) {
+    const sign = value.startsWith("-") ? "-" : "";
+    const unsigned = value.replace(/^[+-]/, "");
+    const [whole, fraction = ""] = unsigned.split(".");
+    const normalizedWhole = whole.replace(/^0+(?=\d)/, "");
+    const normalizedFraction = fraction.replace(/0+$/, "");
+    const normalized = `${normalizedWhole}${normalizedFraction.length === 0 ? "" : `.${normalizedFraction}`}`;
+    return /^0(?:\.0*)?$/.test(normalized) ? "0" : `${sign}${normalized}`;
+}
+function invalidGenMapKey() {
+    throw new validation_error_js_1.ValidationError("gRPC query gen-map key cannot be represented as ledger JSON");
+}
+function defineData(target, key, value) {
+    Object.defineProperty(target, key, { value, enumerable: true, configurable: false, writable: false });
+}
+function int64(value, name) {
+    if (!INT64.test(value)) {
+        throw new validation_error_js_1.ValidationError(`gRPC query ${name} is not an integer`);
+    }
+    else if (BigInt(value) < -9223372036854775808n || BigInt(value) > 9223372036854775807n) {
+        throw new validation_error_js_1.ValidationError(`gRPC query ${name} is outside the int64 range`);
+    }
+    return value;
+}
+function timestamp(value) {
+    int64(value, "timestamp");
+    if (BigInt(value) < -62135596800000000n || BigInt(value) > 253402300799999999n) {
+        throw new validation_error_js_1.ValidationError("gRPC query timestamp is outside the Ledger API range");
+    }
+    return value;
+}
+function date(value) {
+    if (!Number.isInteger(value) || value < MIN_DATE_EPOCH_DAY || value > MAX_DATE_EPOCH_DAY) {
+        throw new validation_error_js_1.ValidationError("gRPC query date is outside the Ledger API range");
+    }
+    return value;
+}
+function numeric(value) {
+    if (!/^[+-]?\d{1,38}(?:\.\d{0,37})?$/.test(value)) {
+        throw new validation_error_js_1.ValidationError("gRPC query numeric is invalid");
+    }
+    const unsigned = value.replace(/^[+-]/, "");
+    const [whole, fractional = ""] = unsigned.split(".");
+    const significant = `${whole}${fractional}`.replace(/^0+/, "").length;
+    if (fractional.length > 37 || significant > 38) {
+        throw new validation_error_js_1.ValidationError("gRPC query numeric exceeds DAML Numeric precision");
+    }
+    return value;
+}
+/** Validates a generated PartyIdString without applying those rules to ordinary Text values. */
+function validPartyId(value) {
+    if (!/^[A-Za-z0-9:\-_ ]{1,255}$/.test(value)) {
+        throw new validation_error_js_1.ValidationError("gRPC query party is invalid");
+    }
+    return value;
+}
+/** Validates a generated LedgerString used specifically as a contract identifier. */
+function validLedgerString(value, name = "ledger string") {
+    if (!/^[A-Za-z0-9#:\-_/ ]{1,255}$/.test(value)) {
+        throw new validation_error_js_1.ValidationError(`gRPC query ${name} is invalid`);
+    }
+    return value;
+}
+/** Validates a generated NameString used by identifiers, choices, and verbose value labels. */
+function validNameString(value, name = "name") {
+    if (!/^[A-Za-z$_][A-Za-z0-9$_]{0,999}$/.test(value)) {
+        throw new validation_error_js_1.ValidationError(`gRPC query ${name} is invalid`);
+    }
+    return value;
+}
+/** Validates an Identifier module or entity name as nonempty dot-separated NameString segments. */
+function validDottedNameString(value, name = "dotted name") {
+    for (const segment of value.split(".")) {
+        validNameString(segment, name);
+    }
+    return value;
+}
+/** Validates a generated PackageIdString without applying it to arbitrary package-name text. */
+function validPackageIdString(value, name = "package id") {
+    if (!/^[A-Za-z0-9\-_ ]{1,64}$/.test(value)) {
+        throw new validation_error_js_1.ValidationError(`gRPC query ${name} is invalid`);
+    }
+    return value;
+}