@distrohelena/canton-typescript-sdk 0.1.31 → 0.1.33

package/README.md

@@ -86,6 +86,12 @@ Participant 3.5.7. In particular, external-party allocation signs the generated
 combined topology hash (`multi_hash`) rather than each topology transaction
 individually.
 
+The decentralized Ed25519 example was also run end-to-end against an isolated
+Canton Participant 3.5.8 sidecar. On both 3.5.7 and 3.5.8 it creates the same
+topology shape: a serial-1 decentralized namespace definition, one self-root
+namespace certificate per owner, and a PartyToParticipant containing the party
+signing key. No deprecated PartyToKeyMapping is created.
+
 ## Localnet launchers
 
 The published package includes launchers for an existing CN Quickstart checkout.
@@ -110,6 +116,56 @@ npm exec --package @distrohelena/canton-typescript-sdk canton-localnet-stop
 These commands launch and stop CN Quickstart; they do not provision a
 Quickstart checkout.
 
+### Optional Canton 3.5.8 participant sidecar
+
+For SDK compatibility work, an isolated Canton 3.5.8 participant can join an
+already-running CN Quickstart localnet without changing its files or Compose
+project:
+
+```bash
+canton-localnet-participant-358-start
+canton-localnet-participant-358-stop
+```
+
+The sidecar owns `.generated/participant-358`, its `canton-participant-358`
+Compose project, its Postgres container, and host ports `8901` (Ledger), `8902`
+(Admin), and `8975` (JSON). The start launcher reads the existing localnet's
+registered synchronizer via its Admin API, stores the exported connection
+configuration in the sidecar runtime directory, and connects the sidecar with
+its own Admin API. It generates a five-minute 3.5.8-compatible development JWT
+at `.generated/participant-358/ledger-api-user.token` and prints both live-test
+and example endpoint/token exports when the connection is healthy.
+`cn-quickstart` is strictly read-only: this launcher never writes to, starts,
+or stops the normal Quickstart stack.
+
+After copying the printed `SDK_EXAMPLE_*` exports into the current shell, run
+the standalone decentralized-party comparison example with:
+
+```bash
+npm run example:party:decentralized
+```
+
+The defaults target the normal insecure shared-secret localnet at
+`localhost:3902` on its `quickstart` Docker network. Override them when your
+localnet differs:
+
+```bash
+PARTICIPANT_358_SOURCE_ADMIN_ENDPOINT=localhost:3902 \
+PARTICIPANT_358_SOURCE_ADMIN_BEARER_TOKEN="$TOKEN" \
+PARTICIPANT_358_NETWORK=quickstart \
+canton-localnet-participant-358-start
+```
+
+Use `PARTICIPANT_358_CANTON_IMAGE`, `PARTICIPANT_358_PROJECT_NAME`,
+`PARTICIPANT_358_RUNTIME_DIR`, `PARTICIPANT_358_LEDGER_PORT`,
+`PARTICIPANT_358_ADMIN_PORT`, and `PARTICIPANT_358_JSON_PORT` to make an
+explicitly isolated variant. The opt-in Docker check requires a running
+localnet and is never part of the normal test suite:
+
+```bash
+PARTICIPANT_358_SMOKE_TEST=1 npm run test:participant-358-sidecar-smoke
+```
+
 ### Optional ES256 bearer tokens
 
 Set `LOCALNET_ES256_JWT=1` when starting the localnet to add ES256 JWT

package/dist/cjs/services/party-management/decentralized-party-lifecycle.js

@@ -15,6 +15,17 @@ async function prepareDecentralizedPartyAsync(request, localParticipant, topolog
     const partyId = `${request.partyHint}::${decentralizedNamespace}`;
     const owners = request.owners.map(toTopologyKey);
     const partyKeys = request.partySigningKeys.map(toTopologyKey);
+    const store = {
+        store: {
+            oneofKind: "synchronizer",
+            synchronizer: {
+                kind: {
+                    oneofKind: "id",
+                    id: request.synchronizer,
+                },
+            },
+        },
+    };
     const participants = [
         {
             participantUid: localParticipant.participantId,
@@ -30,6 +41,7 @@ async function prepareDecentralizedPartyAsync(request, localParticipant, topolog
             {
                 operation: topology_js_1.Enums_TopologyChangeOp.ADD_REPLACE,
                 serial: 1,
+                store,
                 mapping: {
                     mapping: {
                         oneofKind: "decentralizedNamespaceDefinition",
@@ -41,14 +53,15 @@ async function prepareDecentralizedPartyAsync(request, localParticipant, topolog
                     },
                 },
             },
-            ...owners.map((targetKey) => ({
+            ...owners.map((targetKey, index) => ({
                 operation: topology_js_1.Enums_TopologyChangeOp.ADD_REPLACE,
                 serial: 1,
+                store,
                 mapping: {
                     mapping: {
                         oneofKind: "namespaceDelegation",
                         namespaceDelegation: {
-                            namespace: decentralizedNamespace,
+                            namespace: ownerFingerprints[index],
                             targetKey,
                             isRootDelegation: true,
                             restriction: { oneofKind: undefined },
@@ -59,6 +72,7 @@ async function prepareDecentralizedPartyAsync(request, localParticipant, topolog
             {
                 operation: topology_js_1.Enums_TopologyChangeOp.ADD_REPLACE,
                 serial: 1,
+                store,
                 mapping: {
                     mapping: {
                         oneofKind: "partyToParticipant",

package/dist/services/party-management/decentralized-party-lifecycle.js

@@ -12,6 +12,17 @@ export async function prepareDecentralizedPartyAsync(request, localParticipant,
     const partyId = `${request.partyHint}::${decentralizedNamespace}`;
     const owners = request.owners.map(toTopologyKey);
     const partyKeys = request.partySigningKeys.map(toTopologyKey);
+    const store = {
+        store: {
+            oneofKind: "synchronizer",
+            synchronizer: {
+                kind: {
+                    oneofKind: "id",
+                    id: request.synchronizer,
+                },
+            },
+        },
+    };
     const participants = [
         {
             participantUid: localParticipant.participantId,
@@ -27,6 +38,7 @@ export async function prepareDecentralizedPartyAsync(request, localParticipant,
             {
                 operation: Enums_TopologyChangeOp.ADD_REPLACE,
                 serial: 1,
+                store,
                 mapping: {
                     mapping: {
                         oneofKind: "decentralizedNamespaceDefinition",
@@ -38,14 +50,15 @@ export async function prepareDecentralizedPartyAsync(request, localParticipant,
                     },
                 },
             },
-            ...owners.map((targetKey) => ({
+            ...owners.map((targetKey, index) => ({
                 operation: Enums_TopologyChangeOp.ADD_REPLACE,
                 serial: 1,
+                store,
                 mapping: {
                     mapping: {
                         oneofKind: "namespaceDelegation",
                         namespaceDelegation: {
-                            namespace: decentralizedNamespace,
+                            namespace: ownerFingerprints[index],
                             targetKey,
                             isRootDelegation: true,
                             restriction: { oneofKind: undefined },
@@ -56,6 +69,7 @@ export async function prepareDecentralizedPartyAsync(request, localParticipant,
             {
                 operation: Enums_TopologyChangeOp.ADD_REPLACE,
                 serial: 1,
+                store,
                 mapping: {
                     mapping: {
                         oneofKind: "partyToParticipant",

package/node/participant-358-synchronizer.mjs

@@ -0,0 +1,142 @@
+import { createHmac } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { credentials } from "@grpc/grpc-js";
+import { GrpcTransport } from "@protobuf-ts/grpc-transport";
+import { SynchronizerConnectivityServiceClient } from "../dist/transports/grpc/generated/canton/com/digitalasset/canton/admin/participant/v30/synchronizer_connectivity_service.client.js";
+import { ListRegisteredSynchronizersResponse_Status } from "../dist/transports/grpc/generated/canton/com/digitalasset/canton/admin/participant/v30/synchronizer_connectivity_service.js";
+import { SequencerConnectionValidation } from "../dist/transports/grpc/generated/canton/com/digitalasset/canton/admin/sequencer/v30/sequencer_connection.js";
+import { VersionServiceClient } from "../dist/transports/grpc/generated/canton/com/daml/ledger/api/v2/version_service.client.js";
+
+function getRequiredEnvironment(name) {
+    const value = process.env[name];
+    if (!value) throw new Error(`${name} must be set.`);
+    return value;
+}
+
+function createSharedSecretToken() {
+    const secret = process.env.PARTICIPANT_358_SOURCE_SHARED_SECRET ?? "unsafe";
+    const audience = process.env.PARTICIPANT_358_SOURCE_AUTH_AUDIENCE
+        ?? "https://canton.network.global";
+    const subject = process.env.PARTICIPANT_358_SOURCE_AUTH_SUBJECT
+        ?? "ledger-api-user";
+    const ttlSeconds = Number.parseInt(
+        process.env.PARTICIPANT_358_TOKEN_TTL_SECONDS ?? "300",
+        10,
+    );
+    if (!Number.isSafeInteger(ttlSeconds) || ttlSeconds <= 0) {
+        throw new Error("PARTICIPANT_358_TOKEN_TTL_SECONDS must be a positive integer.");
+    }
+    const issuedAt = Math.floor(Date.now() / 1000);
+    const header = Buffer.from(JSON.stringify({ alg: "HS256", typ: "JWT" })).toString("base64url");
+    const payload = Buffer.from(JSON.stringify({
+        aud: audience,
+        sub: subject,
+        iat: issuedAt,
+        exp: issuedAt + ttlSeconds,
+    })).toString("base64url");
+    const signature = createHmac("sha256", secret)
+        .update(`${header}.${payload}`)
+        .digest("base64url");
+    return `${header}.${payload}.${signature}`;
+}
+
+async function writeLedgerToken() {
+    const targetFile = getRequiredEnvironment("PARTICIPANT_358_LEDGER_TOKEN_FILE");
+    await writeFile(targetFile, `${createSharedSecretToken()}\n`, { mode: 0o600 });
+}
+
+function createClient(endpoint, token) {
+    const transport = new GrpcTransport({
+        host: endpoint.replace(/^https?:\/\//, ""),
+        channelCredentials: credentials.createInsecure(),
+    });
+    const options = token ? { meta: { authorization: `Bearer ${token}` } } : undefined;
+    return { client: new SynchronizerConnectivityServiceClient(transport), options, transport };
+}
+
+function encode(value) {
+    if (value instanceof Uint8Array) return { $bytes: Buffer.from(value).toString("base64") };
+    if (Array.isArray(value)) return value.map(encode);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, encode(nested)]));
+    }
+    return value;
+}
+
+function decode(value) {
+    if (Array.isArray(value)) return value.map(decode);
+    if (value && typeof value === "object") {
+        if (typeof value.$bytes === "string") return Buffer.from(value.$bytes, "base64");
+        return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, decode(nested)]));
+    }
+    return value;
+}
+
+async function exportSynchronizerConfig() {
+    const targetFile = getRequiredEnvironment("PARTICIPANT_358_SYNCHRONIZER_CONFIG");
+    const sourceEndpoint = getRequiredEnvironment("PARTICIPANT_358_SOURCE_ADMIN_ENDPOINT");
+    const sourceToken = process.env.PARTICIPANT_358_SOURCE_ADMIN_BEARER_TOKEN ?? createSharedSecretToken();
+    const { client, options, transport } = createClient(sourceEndpoint, sourceToken);
+    try {
+        const response = await client.listRegisteredSynchronizers({ allStatuses: false }, options).response;
+        const connected = response.results.filter((result) => result.connected && result.config);
+        if (connected.length !== 1) {
+            throw new Error(`Expected exactly one connected synchronizer from ${sourceEndpoint}; found ${connected.length}. Set PARTICIPANT_358_SOURCE_ADMIN_ENDPOINT to a participant with one connected synchronizer.`);
+        }
+        await writeFile(targetFile, `${JSON.stringify(encode(connected[0].config), null, 2)}\n`, { mode: 0o600 });
+    } finally {
+        transport.close();
+    }
+}
+
+async function connectSynchronizer() {
+    const configFile = getRequiredEnvironment("PARTICIPANT_358_SYNCHRONIZER_CONFIG");
+    const targetEndpoint = getRequiredEnvironment("PARTICIPANT_358_ADMIN_ENDPOINT");
+    const targetToken = process.env.PARTICIPANT_358_ADMIN_BEARER_TOKEN ?? createSharedSecretToken();
+    const config = decode(JSON.parse(await readFile(configFile, "utf8")));
+    const { client, options, transport } = createClient(targetEndpoint, targetToken);
+    try {
+        const connectResponse = await client.connectSynchronizer({
+            config,
+            sequencerConnectionValidation: SequencerConnectionValidation.ALL,
+        }, options).response;
+        if (!connectResponse.connectedSuccessfully) {
+            throw new Error("ConnectSynchronizer completed without a healthy connection.");
+        }
+        const registered = await client.listRegisteredSynchronizers({ allStatuses: false }, options).response;
+        const isHealthy = registered.results.some(
+            (result) => result.connected
+                && result.status === ListRegisteredSynchronizersResponse_Status.ACTIVE
+                && result.config?.synchronizerAlias === config.synchronizerAlias,
+        );
+        if (!isHealthy) throw new Error("Synchronizer did not reach active/connected state.");
+    } finally {
+        transport.close();
+    }
+}
+
+async function readLedgerApiVersion() {
+    const endpoint = getRequiredEnvironment("PARTICIPANT_358_LEDGER_ENDPOINT");
+    const token = process.env.PARTICIPANT_358_LEDGER_BEARER_TOKEN ?? createSharedSecretToken();
+    const { options, transport } = createClient(endpoint, token);
+    try {
+        const response = await new VersionServiceClient(transport)
+            .getLedgerApiVersion({}, options).response;
+        process.stdout.write(`${response.version}\n`);
+    } finally {
+        transport.close();
+    }
+}
+
+const command = process.argv[2];
+if (command === "export") {
+    await exportSynchronizerConfig();
+} else if (command === "connect") {
+    await connectSynchronizer();
+} else if (command === "ledger-api-version") {
+    await readLedgerApiVersion();
+} else if (command === "mint-ledger-token") {
+    await writeLedgerToken();
+} else {
+    throw new Error("Expected 'export', 'connect', 'ledger-api-version', or 'mint-ledger-token'.");
+}

package/node/start-local-participant-358.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd -- "$SCRIPT_DIR/.." && pwd)"
+RUNTIME_DIR="${PARTICIPANT_358_RUNTIME_DIR:-$REPO_ROOT/.generated/participant-358}"
+PROJECT_NAME="${PARTICIPANT_358_PROJECT_NAME:-canton-participant-358}"
+CANTON_IMAGE="${PARTICIPANT_358_CANTON_IMAGE:-ghcr.io/digital-asset/decentralized-canton-sync/docker/canton:0.6.12}"
+POSTGRES_IMAGE="${PARTICIPANT_358_POSTGRES_IMAGE:-postgres:16}"
+NETWORK_NAME="${PARTICIPANT_358_NETWORK:-quickstart}"
+LEDGER_PORT="${PARTICIPANT_358_LEDGER_PORT:-8901}"
+ADMIN_PORT="${PARTICIPANT_358_ADMIN_PORT:-8902}"
+JSON_PORT="${PARTICIPANT_358_JSON_PORT:-8975}"
+SOURCE_ADMIN_ENDPOINT="${PARTICIPANT_358_SOURCE_ADMIN_ENDPOINT:-localhost:3902}"
+DOCKER_COMPOSE_CMD=()
+
+resolve_docker_compose_cmd() {
+  if docker compose version >/dev/null 2>&1; then DOCKER_COMPOSE_CMD=(docker compose); return; fi
+  if docker-compose version >/dev/null 2>&1; then DOCKER_COMPOSE_CMD=(docker-compose); return; fi
+  echo "Unable to find a working Docker Compose command." >&2
+  exit 1
+}
+
+validate_port() {
+  local value="$1"
+  [[ "$value" =~ ^[1-9][0-9]{0,4}$ ]] && (( value <= 65535 )) || { echo "Invalid port: $value" >&2; exit 1; }
+}
+
+for port in "$LEDGER_PORT" "$ADMIN_PORT" "$JSON_PORT"; do validate_port "$port"; done
+if [[ "$LEDGER_PORT" == "$ADMIN_PORT" || "$LEDGER_PORT" == "$JSON_PORT" || "$ADMIN_PORT" == "$JSON_PORT" ]]; then
+  echo "Participant 3.5.8 Ledger, Admin, and JSON ports must be distinct." >&2
+  exit 1
+fi
+for normal_port in 3901 3902 3975; do
+  if [[ "$LEDGER_PORT" == "$normal_port" || "$ADMIN_PORT" == "$normal_port" || "$JSON_PORT" == "$normal_port" ]]; then
+    echo "Participant 3.5.8 ports must not collide with CN Quickstart ports." >&2
+    exit 1
+  fi
+done
+
+assert_host_port_available() {
+  local port="$1"
+  if command -v ss >/dev/null 2>&1 && ss -ltn "sport = :$port" | tail -n +2 | grep -q .; then
+    echo "Host port $port is already in use. Set the corresponding PARTICIPANT_358_*_PORT value." >&2
+    exit 1
+  fi
+}
+for port in "$LEDGER_PORT" "$ADMIN_PORT" "$JSON_PORT"; do assert_host_port_available "$port"; done
+
+mkdir -p "$RUNTIME_DIR"
+chmod 700 "$RUNTIME_DIR"
+SYNCHRONIZER_CONFIG="$RUNTIME_DIR/registered-synchronizer.json"
+LEDGER_TOKEN_FILE="$RUNTIME_DIR/ledger-api-user.token"
+PARTICIPANT_358_LEDGER_TOKEN_FILE="$LEDGER_TOKEN_FILE" \
+  node "$SCRIPT_DIR/participant-358-synchronizer.mjs" mint-ledger-token
+cat > "$RUNTIME_DIR/participant-358.env" <<EOF
+PARTICIPANT_358_SYNCHRONIZER_CONFIG=$SYNCHRONIZER_CONFIG
+PARTICIPANT_358_SOURCE_ADMIN_ENDPOINT=$SOURCE_ADMIN_ENDPOINT
+PARTICIPANT_358_ADMIN_ENDPOINT=localhost:$ADMIN_PORT
+PARTICIPANT_358_LEDGER_TOKEN_FILE=$LEDGER_TOKEN_FILE
+EOF
+chmod 600 "$RUNTIME_DIR/participant-358.env"
+
+cat > "$RUNTIME_DIR/canton.conf" <<EOF
+canton {
+  parameters { manual-start = no }
+  participants.participant358 {
+    storage {
+      type = postgres
+      config {
+        dataSourceClass = "org.postgresql.ds.PGSimpleDataSource"
+        properties {
+          serverName = \${?DB_SERVER}
+          portNumber = 5432
+          databaseName = participant358
+          currentSchema = participant358
+          user = \${?DB_USER}
+          password = \${?DB_PASSWORD}
+        }
+      }
+    }
+    init {
+      generate-topology-transactions-and-keys = true
+      identity.type = auto
+    }
+    admin-api {
+      address = "0.0.0.0"
+      port = 5002
+    }
+    ledger-api {
+      address = "0.0.0.0"
+      port = 5001
+      auth-services = [{
+        type = unsafe-jwt-hmac-256
+        target-audience = "https://canton.network.global"
+        secret = "unsafe"
+      }]
+      user-management-service.additional-admin-user-id = "ledger-api-user"
+    }
+    http-ledger-api {
+      address = "0.0.0.0"
+      port = 7575
+    }
+    monitoring.http-health-server {
+      address = "0.0.0.0"
+      port = 7000
+    }
+  }
+}
+EOF
+
+cat > "$RUNTIME_DIR/compose.yaml" <<EOF
+name: $PROJECT_NAME
+services:
+  postgres:
+    image: $POSTGRES_IMAGE
+    environment:
+      POSTGRES_DB: participant358
+      POSTGRES_USER: participant358
+      POSTGRES_PASSWORD: participant358
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U participant358 -d participant358"]
+      interval: 2s
+      timeout: 3s
+      retries: 30
+  participant358:
+    image: $CANTON_IMAGE
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      DB_SERVER: postgres
+      DB_USER: participant358
+      DB_PASSWORD: participant358
+    volumes:
+      - "$RUNTIME_DIR/canton.conf:/app/app.conf:ro"
+    ports:
+      - "127.0.0.1:$LEDGER_PORT:5001"
+      - "127.0.0.1:$ADMIN_PORT:5002"
+      - "127.0.0.1:$JSON_PORT:7575"
+    networks:
+      - default
+      - localnet
+networks:
+  localnet:
+    external: true
+    name: $NETWORK_NAME
+EOF
+
+if [[ "${PARTICIPANT_358_SKIP_SYNCHRONIZER_CONNECT:-0}" != "1" ]]; then
+  PARTICIPANT_358_SYNCHRONIZER_CONFIG="$SYNCHRONIZER_CONFIG" \
+  PARTICIPANT_358_SOURCE_ADMIN_ENDPOINT="$SOURCE_ADMIN_ENDPOINT" \
+  PARTICIPANT_358_SOURCE_ADMIN_BEARER_TOKEN="${PARTICIPANT_358_SOURCE_ADMIN_BEARER_TOKEN:-}" \
+  node "$SCRIPT_DIR/participant-358-synchronizer.mjs" export
+fi
+
+resolve_docker_compose_cmd
+"${DOCKER_COMPOSE_CMD[@]}" --project-name "$PROJECT_NAME" --file "$RUNTIME_DIR/compose.yaml" up -d
+
+if [[ "${PARTICIPANT_358_SKIP_SYNCHRONIZER_CONNECT:-0}" != "1" ]]; then
+  deadline=$((SECONDS + ${PARTICIPANT_358_CONNECT_TIMEOUT_SECONDS:-90}))
+  until PARTICIPANT_358_SYNCHRONIZER_CONFIG="$SYNCHRONIZER_CONFIG" \
+    PARTICIPANT_358_ADMIN_ENDPOINT="localhost:$ADMIN_PORT" \
+    PARTICIPANT_358_ADMIN_BEARER_TOKEN="${PARTICIPANT_358_ADMIN_BEARER_TOKEN:-}" \
+    node "$SCRIPT_DIR/participant-358-synchronizer.mjs" connect
+  do
+    if (( SECONDS >= deadline )); then
+      echo "Participant 3.5.8 sidecar did not become ready. Inspect: ${DOCKER_COMPOSE_CMD[*]} --project-name $PROJECT_NAME --file $RUNTIME_DIR/compose.yaml logs participant358" >&2
+      exit 1
+    fi
+    sleep 2
+  done
+fi
+
+cat <<EOF
+Participant 3.5.8 sidecar is ready.
+export SDK_TEST_LEDGER_ENDPOINT=localhost:$LEDGER_PORT
+export SDK_TEST_LEDGER_ADMIN_ENDPOINT=localhost:$LEDGER_PORT
+export SDK_TEST_PARTICIPANT_ADMIN_ENDPOINT=localhost:$ADMIN_PORT
+export SDK_EXAMPLE_LEDGER_ENDPOINT=localhost:$LEDGER_PORT
+export SDK_EXAMPLE_LEDGER_ADMIN_ENDPOINT=localhost:$LEDGER_PORT
+export SDK_EXAMPLE_PARTICIPANT_ADMIN_ENDPOINT=localhost:$ADMIN_PORT
+export SDK_EXAMPLE_BEARER_TOKEN="\$(cat $LEDGER_TOKEN_FILE)"
+EOF

package/node/start-local.sh

@@ -911,7 +911,7 @@ extra_participants_healthy() {
     local prefix=$((index + 4))
     local health_port
     health_port="$(participant_port "$prefix" "$CANTON_HTTP_HEALTHCHECK_PORT_SUFFIX")"
-    checks+=("curl -sf --max-time 2 http://localhost:${health_port}/health > /dev/null")
+    checks+=("wget -q --timeout=2 --tries=1 -O /dev/null http://localhost:${health_port}/health")
   done
 
   local joined_checks
@@ -968,7 +968,7 @@ container_health_is_ready() {
   local _container="$1"
   local _lifecycle_state="$2"
   local health_status="$3"
-  [[ "$health_status" == "healthy" ]]
+  [[ "$lifecycle_state" == "running" && "$health_status" == "healthy" ]]
 }
 
 canton_and_extras_are_ready() {
@@ -976,7 +976,8 @@ canton_and_extras_are_ready() {
   local _lifecycle_state="$2"
   local health_status="$3"
   local extra_participants="$4"
-  [[ "$health_status" == "healthy" ]] && extra_participants_healthy "$extra_participants"
+  [[ "$lifecycle_state" == "running" && "$health_status" == "healthy" ]] \
+    && extra_participants_healthy "$extra_participants"
 }
 
 print_container_logs() {
@@ -1008,7 +1009,7 @@ wait_for_container_readiness() {
     lifecycle_state="${lifecycle_state:-missing}"
     health_status="${health_status:-unknown}"
 
-    if [[ "$lifecycle_state" != "running" ]]; then
+    if [[ "$lifecycle_state" != "running" && "$lifecycle_state" != "restarting" ]]; then
       echo "$container is not running (state: $lifecycle_state)." >&2
       print_container_logs "$container"
       return 1

package/node/stop-local-participant-358.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd -- "$SCRIPT_DIR/.." && pwd)"
+RUNTIME_DIR="${PARTICIPANT_358_RUNTIME_DIR:-$REPO_ROOT/.generated/participant-358}"
+PROJECT_NAME="${PARTICIPANT_358_PROJECT_NAME:-canton-participant-358}"
+DOCKER_COMPOSE_CMD=()
+
+if [[ ! -f "$RUNTIME_DIR/compose.yaml" ]]; then
+  echo "Participant 3.5.8 sidecar is not configured. Nothing to stop."
+  exit 0
+fi
+if docker compose version >/dev/null 2>&1; then DOCKER_COMPOSE_CMD=(docker compose); elif docker-compose version >/dev/null 2>&1; then DOCKER_COMPOSE_CMD=(docker-compose); else
+  echo "Unable to find a working Docker Compose command." >&2
+  exit 1
+fi
+"${DOCKER_COMPOSE_CMD[@]}" --project-name "$PROJECT_NAME" --file "$RUNTIME_DIR/compose.yaml" down --volumes --remove-orphans

package/node/test-participant-358-sidecar-smoke.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "${PARTICIPANT_358_SMOKE_TEST:-0}" != "1" ]]; then
+  echo "Set PARTICIPANT_358_SMOKE_TEST=1 to run this Docker smoke test against an already-running CN Quickstart localnet."
+  exit 0
+fi
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd -- "$SCRIPT_DIR/.." && pwd)"
+trap 'bash "$SCRIPT_DIR/stop-local-participant-358.sh"' EXIT
+
+bash "$SCRIPT_DIR/start-local-participant-358.sh"
+version="$(PARTICIPANT_358_LEDGER_ENDPOINT="localhost:${PARTICIPANT_358_LEDGER_PORT:-8901}" node "$SCRIPT_DIR/participant-358-synchronizer.mjs" ledger-api-version)"
+[[ "$version" == 3.5.8* ]] || {
+  echo "Expected Canton 3.5.8 Ledger API response, received: $version" >&2
+  exit 1
+}
+echo "Participant 3.5.8 Ledger API response: $version"

package/node/test-participant-358-sidecar.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
+START_SCRIPT="$REPO_ROOT/node/start-local-participant-358.sh"
+STOP_SCRIPT="$REPO_ROOT/node/stop-local-participant-358.sh"
+
+[[ -x "$START_SCRIPT" ]]
+[[ -x "$STOP_SCRIPT" ]]
+grep -Fq 'export SDK_EXAMPLE_LEDGER_ENDPOINT=localhost:$LEDGER_PORT' "$START_SCRIPT"
+grep -Fq 'export SDK_EXAMPLE_LEDGER_ADMIN_ENDPOINT=localhost:$LEDGER_PORT' "$START_SCRIPT"
+grep -Fq 'export SDK_EXAMPLE_PARTICIPANT_ADMIN_ENDPOINT=localhost:$ADMIN_PORT' "$START_SCRIPT"
+
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "$tmpdir"' EXIT
+
+stubbin="$tmpdir/bin"
+mkdir -p "$stubbin"
+cat > "$stubbin/docker" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+printf '%s\n' "$*" >> "$DOCKER_LOG"
+if [[ "$1" == "compose" && "$2" == "version" ]]; then
+  exit 0
+fi
+EOF
+chmod +x "$stubbin/docker"
+
+runtime_dir="$tmpdir/runtime"
+docker_log="$tmpdir/docker.log"
+PATH="$stubbin:$PATH" \
+DOCKER_LOG="$docker_log" \
+PARTICIPANT_358_RUNTIME_DIR="$runtime_dir" \
+PARTICIPANT_358_SKIP_SYNCHRONIZER_CONNECT=1 \
+"$START_SCRIPT"
+
+grep -Fqx 'name: canton-participant-358' "$runtime_dir/compose.yaml"
+grep -Fqx '  participant358:' "$runtime_dir/compose.yaml"
+if grep -Fqx '  canton:' "$runtime_dir/compose.yaml"; then
+  echo 'sidecar must not claim the quickstart canton DNS alias' >&2
+  exit 1
+fi
+grep -Fqx '    image: ghcr.io/digital-asset/decentralized-canton-sync/docker/canton:0.6.12' "$runtime_dir/compose.yaml"
+grep -Fqx '    image: postgres:16' "$runtime_dir/compose.yaml"
+grep -Fqx '      - default' "$runtime_dir/compose.yaml"
+grep -Fqx '      - localnet' "$runtime_dir/compose.yaml"
+grep -Fqx '          databaseName = participant358' "$runtime_dir/canton.conf"
+grep -Fqx '    admin-api {' "$runtime_dir/canton.conf"
+grep -Fqx '      address = "0.0.0.0"' "$runtime_dir/canton.conf"
+grep -Fqx '      port = 5002' "$runtime_dir/canton.conf"
+grep -Fqx '      - "127.0.0.1:8901:5001"' "$runtime_dir/compose.yaml"
+grep -Fqx '      port = 5002' "$runtime_dir/canton.conf"
+grep -Fqx '      port = 7575' "$runtime_dir/canton.conf"
+grep -Fq 'PARTICIPANT_358_SYNCHRONIZER_CONFIG=' "$runtime_dir/participant-358.env"
+grep -Fq 'PARTICIPANT_358_LEDGER_TOKEN_FILE=' "$runtime_dir/participant-358.env"
+test -s "$runtime_dir/ledger-api-user.token"
+node -e '
+const token = require("node:fs").readFileSync(process.argv[1], "utf8").trim();
+const payload = JSON.parse(Buffer.from(token.split(".")[1], "base64url"));
+if (payload.sub !== "ledger-api-user") throw new Error("unexpected token subject");
+if (payload.aud !== "https://canton.network.global") throw new Error("unexpected token audience");
+if (!Number.isInteger(payload.iat)) throw new Error("token is missing iat");
+if (!Number.isInteger(payload.exp) || payload.exp <= payload.iat) throw new Error("token is missing a future exp");
+if (payload.exp - payload.iat !== 300) throw new Error("token lifetime must be 300 seconds");
+' "$runtime_dir/ledger-api-user.token"
+grep -F -- '--project-name canton-participant-358' "$docker_log"
+grep -Fqx '    name: quickstart' "$runtime_dir/compose.yaml"
+
+if PATH="$stubbin:$PATH" PARTICIPANT_358_LEDGER_PORT=3901 "$START_SCRIPT" >/dev/null 2>&1; then
+  echo 'sidecar launcher accepted a CN Quickstart Ledger port' >&2
+  exit 1
+fi
+
+PATH="$stubbin:$PATH" \
+DOCKER_LOG="$docker_log" \
+PARTICIPANT_358_RUNTIME_DIR="$runtime_dir" \
+"$STOP_SCRIPT"
+
+grep -F -- '--project-name canton-participant-358' "$docker_log"
+if grep -Eq -- '(^| )down( |$).*quickstart|quickstart.*(^| )down( |$)' "$docker_log"; then
+  echo 'stop launcher targeted quickstart' >&2
+  exit 1
+fi