@distrohelena/canton-typescript-sdk 0.1.49 → 0.1.50

package/dist/cjs/core/errors/grpc-transport-error.js

@@ -9,14 +9,16 @@ class GrpcTransportError extends transport_error_js_1.TransportError {
     methodName;
     metadata;
     status;
+    errorInfo;
     cause;
-    constructor(message, rawError, metadata, status) {
+    constructor(message, rawError, metadata, status, errorInfo) {
         super(message);
         this.grpcCode = rawError.code;
         this.serviceName = rawError.serviceName;
         this.methodName = rawError.methodName;
         this.metadata = metadata;
         this.status = status;
+        this.errorInfo = errorInfo;
         this.cause = rawError;
     }
     static fromUnknown(error) {
@@ -25,7 +27,8 @@ class GrpcTransportError extends transport_error_js_1.TransportError {
         }
         const metadata = copyMetadata(error.meta);
         const status = decodeStatusDetails(error.meta);
-        return new GrpcTransportError(formatMessage(error), error, metadata, status);
+        const errorInfo = decodeErrorInfo(status);
+        return new GrpcTransportError(formatMessage(error, status, errorInfo), error, metadata, status, errorInfo);
     }
 }
 exports.GrpcTransportError = GrpcTransportError;
@@ -71,10 +74,140 @@ function toBinary(value) {
     }
     return value instanceof Uint8Array ? value : undefined;
 }
-function formatMessage(error) {
+/**
+ * Decodes the google.rpc.ErrorInfo entry from a status' packed details. The message type is small and
+ * stable (reason/domain/metadata), so it is read directly off the wire instead of adding the whole
+ * google.rpc.error_details surface to the generated bindings. Anything malformed yields undefined rather
+ * than masking the original RPC failure.
+ */
+function decodeErrorInfo(status) {
+    for (const detail of status?.details ?? []) {
+        if (typeof detail.typeUrl !== "string" || !detail.typeUrl.endsWith("/google.rpc.ErrorInfo") || !(detail.value instanceof Uint8Array)) {
+            continue;
+        }
+        const decoded = readErrorInfo(detail.value);
+        if (decoded !== undefined) {
+            return decoded;
+        }
+    }
+    return undefined;
+}
+function readErrorInfo(bytes) {
+    try {
+        let reason = "";
+        let domain = "";
+        const metadata = {};
+        const reader = wireReader(bytes);
+        while (reader.remaining()) {
+            const tag = reader.varint();
+            const field = Math.floor(tag / 8);
+            const wireType = tag % 8;
+            if (field === 1 && wireType === 2) {
+                reason = reader.string();
+            }
+            else if (field === 2 && wireType === 2) {
+                domain = reader.string();
+            }
+            else if (field === 3 && wireType === 2) {
+                const entry = wireReader(reader.bytes());
+                let key = "";
+                let value = "";
+                while (entry.remaining()) {
+                    const entryTag = entry.varint();
+                    if (Math.floor(entryTag / 8) === 1 && entryTag % 8 === 2) {
+                        key = entry.string();
+                    }
+                    else if (Math.floor(entryTag / 8) === 2 && entryTag % 8 === 2) {
+                        value = entry.string();
+                    }
+                    else {
+                        entry.skip(entryTag % 8);
+                    }
+                }
+                if (key.length > 0) {
+                    metadata[key] = value;
+                }
+            }
+            else {
+                reader.skip(wireType);
+            }
+        }
+        return reason.length === 0 ? undefined : Object.freeze({ reason, domain, metadata: Object.freeze(metadata) });
+    }
+    catch {
+        return undefined;
+    }
+}
+function wireReader(bytes) {
+    let offset = 0;
+    const varint = () => {
+        let result = 0;
+        let shift = 1;
+        for (let index = 0; index < 8; index += 1) {
+            const byte = bytes[offset];
+            if (byte === undefined) {
+                throw new Error("truncated varint");
+            }
+            offset += 1;
+            result += (byte & 0x7f) * shift;
+            if ((byte & 0x80) === 0) {
+                return result;
+            }
+            shift *= 128;
+        }
+        throw new Error("varint too long");
+    };
+    const rawBytes = () => {
+        const length = varint();
+        if (offset + length > bytes.length) {
+            throw new Error("truncated bytes");
+        }
+        const slice = bytes.subarray(offset, offset + length);
+        offset += length;
+        return slice;
+    };
+    return {
+        remaining: () => offset < bytes.length,
+        varint,
+        bytes: rawBytes,
+        string: () => new TextDecoder("utf-8", { fatal: true }).decode(rawBytes()),
+        skip: (wireType) => {
+            if (wireType === 0) {
+                varint();
+            }
+            else if (wireType === 1) {
+                offset += 8;
+            }
+            else if (wireType === 2) {
+                rawBytes();
+            }
+            else if (wireType === 5) {
+                offset += 4;
+            }
+            else {
+                throw new Error(`unsupported wire type ${wireType}`);
+            }
+            if (offset > bytes.length) {
+                throw new Error("truncated field");
+            }
+        },
+    };
+}
+function formatMessage(error, status, errorInfo) {
     const operation = [error.serviceName, error.methodName]
         .filter((part) => part !== undefined)
         .join(".");
     const location = operation.length > 0 ? ` from ${operation}` : "";
-    return `gRPC ${error.code}${location}: ${error.message}`;
+    const parts = [];
+    // Participants often pair a generic transport message with the real explanation in the status trailer.
+    if (status !== undefined && status.message.length > 0 && status.message !== error.message) {
+        parts.push(`status: ${status.message}`);
+    }
+    if (errorInfo !== undefined) {
+        const metadataEntries = Object.entries(errorInfo.metadata);
+        parts.push(`reason: ${errorInfo.reason}`
+            + (metadataEntries.length === 0 ? "" : ` (${metadataEntries.map(([key, value]) => `${key}=${value}`).join(", ")})`));
+    }
+    const suffix = parts.length === 0 ? "" : ` [${parts.join("; ")}]`;
+    return `gRPC ${error.code}${location}: ${error.message}${suffix}`;
 }

package/dist/core/errors/grpc-transport-error.d.ts

@@ -1,6 +1,12 @@
 import type { Status as GrpcStatusDetails } from "../../transports/grpc/generated/canton/google/rpc/status.js";
 import { TransportError } from "./transport-error.js";
 export type GrpcErrorMetadata = Readonly<Record<string, readonly string[]>>;
+/** The decoded google.rpc.ErrorInfo detail: the machine-readable reason behind a gRPC failure. */
+export interface GrpcErrorInfo {
+    readonly reason: string;
+    readonly domain: string;
+    readonly metadata: Readonly<Record<string, string>>;
+}
 export type { GrpcStatusDetails };
 export declare class GrpcTransportError extends TransportError {
     readonly grpcCode: string;
@@ -8,6 +14,7 @@ export declare class GrpcTransportError extends TransportError {
     readonly methodName?: string;
     readonly metadata: GrpcErrorMetadata;
     readonly status?: GrpcStatusDetails;
+    readonly errorInfo?: GrpcErrorInfo;
     readonly cause: Error;
     private constructor();
     static fromUnknown(error: unknown): GrpcTransportError | undefined;

package/dist/core/errors/grpc-transport-error.js

@@ -6,14 +6,16 @@ export class GrpcTransportError extends TransportError {
     methodName;
     metadata;
     status;
+    errorInfo;
     cause;
-    constructor(message, rawError, metadata, status) {
+    constructor(message, rawError, metadata, status, errorInfo) {
         super(message);
         this.grpcCode = rawError.code;
         this.serviceName = rawError.serviceName;
         this.methodName = rawError.methodName;
         this.metadata = metadata;
         this.status = status;
+        this.errorInfo = errorInfo;
         this.cause = rawError;
     }
     static fromUnknown(error) {
@@ -22,7 +24,8 @@ export class GrpcTransportError extends TransportError {
         }
         const metadata = copyMetadata(error.meta);
         const status = decodeStatusDetails(error.meta);
-        return new GrpcTransportError(formatMessage(error), error, metadata, status);
+        const errorInfo = decodeErrorInfo(status);
+        return new GrpcTransportError(formatMessage(error, status, errorInfo), error, metadata, status, errorInfo);
     }
 }
 function isRpcErrorLike(error) {
@@ -67,10 +70,140 @@ function toBinary(value) {
     }
     return value instanceof Uint8Array ? value : undefined;
 }
-function formatMessage(error) {
+/**
+ * Decodes the google.rpc.ErrorInfo entry from a status' packed details. The message type is small and
+ * stable (reason/domain/metadata), so it is read directly off the wire instead of adding the whole
+ * google.rpc.error_details surface to the generated bindings. Anything malformed yields undefined rather
+ * than masking the original RPC failure.
+ */
+function decodeErrorInfo(status) {
+    for (const detail of status?.details ?? []) {
+        if (typeof detail.typeUrl !== "string" || !detail.typeUrl.endsWith("/google.rpc.ErrorInfo") || !(detail.value instanceof Uint8Array)) {
+            continue;
+        }
+        const decoded = readErrorInfo(detail.value);
+        if (decoded !== undefined) {
+            return decoded;
+        }
+    }
+    return undefined;
+}
+function readErrorInfo(bytes) {
+    try {
+        let reason = "";
+        let domain = "";
+        const metadata = {};
+        const reader = wireReader(bytes);
+        while (reader.remaining()) {
+            const tag = reader.varint();
+            const field = Math.floor(tag / 8);
+            const wireType = tag % 8;
+            if (field === 1 && wireType === 2) {
+                reason = reader.string();
+            }
+            else if (field === 2 && wireType === 2) {
+                domain = reader.string();
+            }
+            else if (field === 3 && wireType === 2) {
+                const entry = wireReader(reader.bytes());
+                let key = "";
+                let value = "";
+                while (entry.remaining()) {
+                    const entryTag = entry.varint();
+                    if (Math.floor(entryTag / 8) === 1 && entryTag % 8 === 2) {
+                        key = entry.string();
+                    }
+                    else if (Math.floor(entryTag / 8) === 2 && entryTag % 8 === 2) {
+                        value = entry.string();
+                    }
+                    else {
+                        entry.skip(entryTag % 8);
+                    }
+                }
+                if (key.length > 0) {
+                    metadata[key] = value;
+                }
+            }
+            else {
+                reader.skip(wireType);
+            }
+        }
+        return reason.length === 0 ? undefined : Object.freeze({ reason, domain, metadata: Object.freeze(metadata) });
+    }
+    catch {
+        return undefined;
+    }
+}
+function wireReader(bytes) {
+    let offset = 0;
+    const varint = () => {
+        let result = 0;
+        let shift = 1;
+        for (let index = 0; index < 8; index += 1) {
+            const byte = bytes[offset];
+            if (byte === undefined) {
+                throw new Error("truncated varint");
+            }
+            offset += 1;
+            result += (byte & 0x7f) * shift;
+            if ((byte & 0x80) === 0) {
+                return result;
+            }
+            shift *= 128;
+        }
+        throw new Error("varint too long");
+    };
+    const rawBytes = () => {
+        const length = varint();
+        if (offset + length > bytes.length) {
+            throw new Error("truncated bytes");
+        }
+        const slice = bytes.subarray(offset, offset + length);
+        offset += length;
+        return slice;
+    };
+    return {
+        remaining: () => offset < bytes.length,
+        varint,
+        bytes: rawBytes,
+        string: () => new TextDecoder("utf-8", { fatal: true }).decode(rawBytes()),
+        skip: (wireType) => {
+            if (wireType === 0) {
+                varint();
+            }
+            else if (wireType === 1) {
+                offset += 8;
+            }
+            else if (wireType === 2) {
+                rawBytes();
+            }
+            else if (wireType === 5) {
+                offset += 4;
+            }
+            else {
+                throw new Error(`unsupported wire type ${wireType}`);
+            }
+            if (offset > bytes.length) {
+                throw new Error("truncated field");
+            }
+        },
+    };
+}
+function formatMessage(error, status, errorInfo) {
     const operation = [error.serviceName, error.methodName]
         .filter((part) => part !== undefined)
         .join(".");
     const location = operation.length > 0 ? ` from ${operation}` : "";
-    return `gRPC ${error.code}${location}: ${error.message}`;
+    const parts = [];
+    // Participants often pair a generic transport message with the real explanation in the status trailer.
+    if (status !== undefined && status.message.length > 0 && status.message !== error.message) {
+        parts.push(`status: ${status.message}`);
+    }
+    if (errorInfo !== undefined) {
+        const metadataEntries = Object.entries(errorInfo.metadata);
+        parts.push(`reason: ${errorInfo.reason}`
+            + (metadataEntries.length === 0 ? "" : ` (${metadataEntries.map(([key, value]) => `${key}=${value}`).join(", ")})`));
+    }
+    const suffix = parts.length === 0 ? "" : ` [${parts.join("; ")}]`;
+    return `gRPC ${error.code}${location}: ${error.message}${suffix}`;
 }

package/dist/index.d.ts

@@ -301,6 +301,7 @@ export { AuthenticationError } from "./core/errors/authentication-error.js";
 export { AuthorizationError } from "./core/errors/authorization-error.js";
 export { TransportError } from "./core/errors/transport-error.js";
 export { GrpcTransportError } from "./core/errors/grpc-transport-error.js";
+export type { GrpcErrorInfo } from "./core/errors/grpc-transport-error.js";
 export type { GrpcErrorMetadata, GrpcStatusDetails, } from "./core/errors/grpc-transport-error.js";
 export { SigningError } from "./core/errors/signing-error.js";
 export { TimeoutError } from "./core/errors/timeout-error.js";

package/node/start-local.sh

@@ -929,7 +929,19 @@ prerequisite_services() {
   printf '%s\n' "${services[@]}"
 }
 
+resolve_pqs_enabled() {
+  local value="${LOCALNET_PQS:-1}"
+  if [[ "$value" != "0" && "$value" != "1" ]]; then
+    echo "LOCALNET_PQS must be 0 or 1." >&2
+    return 1
+  fi
+  printf '%s\n' "$value"
+}
+
 dependent_services() {
+  if [[ "$(resolve_pqs_enabled)" == "0" ]]; then
+    return 0
+  fi
   printf '%s\n' pqs-app-provider pqs-sv
 }
 
@@ -1042,6 +1054,23 @@ wait_for_canton_health() {
   wait_for_container_readiness canton canton_and_extras_are_ready "$extra_participants"
 }
 
+container_is_healthy() {
+  local _container="$1"
+  local lifecycle_state="$2"
+  local health_status="$3"
+  [[ "$lifecycle_state" == "running" && "$health_status" == "healthy" ]]
+}
+
+wait_for_onboarding_health() {
+  local onboarding_container
+  onboarding_container="$(docker ps -a --filter name=splice-onboarding --format '{{.Names}}' | head -n 1)"
+  if [[ -z "$onboarding_container" ]]; then
+    echo "Unable to resolve the splice-onboarding container for readiness." >&2
+    return 1
+  fi
+  wait_for_container_readiness "$onboarding_container" container_is_healthy
+}
+
 provision_extra_pqs() {
   local count="$1"
   if (( count == 0 )); then
@@ -1235,7 +1264,13 @@ start_ledger_stack() {
   # gating so its healthcheck can retry until those apps are ready; PQS still
   # starts afterward and retains its onboarding health dependency.
   start_splice_services compose_args
-  docker_compose "${compose_args[@]}" up -d --no-recreate "${followup_services[@]}"
+  if (( ${#followup_services[@]} > 0 )); then
+    docker_compose "${compose_args[@]}" up -d --no-recreate "${followup_services[@]}"
+  else
+    # Without PQS nothing carries a service_healthy dependency on splice-onboarding, so wait explicitly —
+    # the participant is not usable until onboarding finishes.
+    wait_for_onboarding_health
+  fi
 
   if (( extra_participants > 0 )); then
     wait_for_container_readiness splice container_health_is_ready

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@distrohelena/canton-typescript-sdk",
-    "version": "0.1.49",
+    "version": "0.1.50",
     "license": "Apache-2.0",
     "type": "module",
     "main": "./dist/index.js",
@@ -140,6 +140,8 @@
         "test": "vitest run --exclude 'tests/live/**' --maxWorkers=1 --testTimeout=15000",
         "test:property": "vitest run tests/property --maxWorkers=1 --testTimeout=15000",
         "test:live": "vitest run --dir tests/live --maxWorkers=1 --testTimeout=15000",
+        "test:live:matrix": "node scripts/live-matrix.mjs",
+        "test:full": "npm run test && node scripts/live-matrix.mjs",
         "test:live:fuzz": "vitest run tests/live/specs/live-stateful-fuzzing.test.ts --maxWorkers=1 --testTimeout=300000",
         "test:unit": "vitest run tests/unit",
         "verify:pack": "node ./scripts/verify-npm-pack.mjs"