@distrohelena/canton-typescript-sdk 0.1.30 → 0.1.32

package/README.md

@@ -81,6 +81,11 @@ not an exact Numeric value.
 
 The repository also supports a live SDK validation suite against an already-running CN quickstart localnet.
 
+The current party-creation flows were developed and live-tested against Canton
+Participant 3.5.7. In particular, external-party allocation signs the generated
+combined topology hash (`multi_hash`) rather than each topology transaction
+individually.
+
 ## Localnet launchers
 
 The published package includes launchers for an existing CN Quickstart checkout.

package/dist/cjs/services/party-management/party-management-service-client.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PartyManagementServiceClient = void 0;
-const external_party_onboarding_transaction_js_1 = require("../../core/types/external-party/external-party-onboarding-transaction.js");
 const external_party_signature_js_1 = require("../../core/types/external-party/external-party-signature.js");
 const validation_error_js_1 = require("../../core/errors/validation-error.js");
 const decentralized_party_lifecycle_js_1 = require("./decentralized-party-lifecycle.js");
@@ -132,21 +131,12 @@ class PartyManagementServiceClient {
             confirmationThreshold: request.confirmationThreshold,
             observingParticipantUids: [...request.observingParticipantUids],
         }), options);
-        const onboardingTransactions = [];
-        for (const transaction of generated.topologyTransactions) {
-            onboardingTransactions.push(new external_party_onboarding_transaction_js_1.ExternalPartyOnboardingTransaction({
-                transaction,
-                signatures: [
-                    await this.signExternalPartyPayloadAsync(request, transaction, "topology-transaction", generated.partyId, generated.publicKeyFingerprint),
-                ],
-            }));
-        }
         const multiHashSignature = await this.signExternalPartyPayloadAsync(request, generated.multiHash, "multi-hash", generated.partyId, generated.publicKeyFingerprint);
         return this.allocateExternalPartyAsync(party_management_service_js_1.AllocateExternalPartyRequest.create({
             synchronizer: request.synchronizer,
-            onboardingTransactions: onboardingTransactions.map((transaction) => ({
-                transaction: transaction.transaction,
-                signatures: transaction.signatures.map(toGeneratedSignature),
+            onboardingTransactions: generated.topologyTransactions.map((transaction) => ({
+                transaction,
+                signatures: [],
             })),
             multiHashSignatures: [toGeneratedSignature(multiHashSignature)],
             identityProviderId: request.identityProviderId,

package/dist/services/party-management/party-management-service-client.js

@@ -1,4 +1,3 @@
-import { ExternalPartyOnboardingTransaction } from "../../core/types/external-party/external-party-onboarding-transaction.js";
 import { ExternalPartySignature } from "../../core/types/external-party/external-party-signature.js";
 import { ValidationError } from "../../core/errors/validation-error.js";
 import { prepareDecentralizedPartyAsync } from "./decentralized-party-lifecycle.js";
@@ -129,21 +128,12 @@ export class PartyManagementServiceClient {
             confirmationThreshold: request.confirmationThreshold,
             observingParticipantUids: [...request.observingParticipantUids],
         }), options);
-        const onboardingTransactions = [];
-        for (const transaction of generated.topologyTransactions) {
-            onboardingTransactions.push(new ExternalPartyOnboardingTransaction({
-                transaction,
-                signatures: [
-                    await this.signExternalPartyPayloadAsync(request, transaction, "topology-transaction", generated.partyId, generated.publicKeyFingerprint),
-                ],
-            }));
-        }
         const multiHashSignature = await this.signExternalPartyPayloadAsync(request, generated.multiHash, "multi-hash", generated.partyId, generated.publicKeyFingerprint);
         return this.allocateExternalPartyAsync(AllocateExternalPartyRequest.create({
             synchronizer: request.synchronizer,
-            onboardingTransactions: onboardingTransactions.map((transaction) => ({
-                transaction: transaction.transaction,
-                signatures: transaction.signatures.map(toGeneratedSignature),
+            onboardingTransactions: generated.topologyTransactions.map((transaction) => ({
+                transaction,
+                signatures: [],
             })),
             multiHashSignatures: [toGeneratedSignature(multiHashSignature)],
             identityProviderId: request.identityProviderId,

package/node/.generated/start-local/additional-config.extra-participants.conf

@@ -70,75 +70,3 @@ canton.participants.extra-3 = $${_participant} {
   }
 }
 
-canton.participants.extra-1.ledger-api.auth-services = [
-  {
-    type = unsafe-jwt-hmac-256
-    target-audience = "https://canton.network.global"
-    secret = "unsafe"
-  },
-  {
-    type = jwt-es-256-crt
-    certificate = "/app/es256-certificate.pem"
-    target-audience = "https://canton.network.global/es256"
-  }
-]
-
-canton.participants.extra-2.ledger-api.auth-services = [
-  {
-    type = unsafe-jwt-hmac-256
-    target-audience = "https://canton.network.global"
-    secret = "unsafe"
-  },
-  {
-    type = jwt-es-256-crt
-    certificate = "/app/es256-certificate.pem"
-    target-audience = "https://canton.network.global/es256"
-  }
-]
-
-canton.participants.extra-3.ledger-api.auth-services = [
-  {
-    type = unsafe-jwt-hmac-256
-    target-audience = "https://canton.network.global"
-    secret = "unsafe"
-  },
-  {
-    type = jwt-es-256-crt
-    certificate = "/app/es256-certificate.pem"
-    target-audience = "https://canton.network.global/es256"
-  }
-]
-
-canton.participants.extra-1.ledger-api.tls {
-  cert-chain-file = "/app/localnet-tls/server.crt"
-  private-key-file = "/app/localnet-tls/server.key"
-  trust-collection-file = "/app/localnet-tls/ca.crt"
-}
-canton.participants.extra-1.admin-api.tls {
-  cert-chain-file = "/app/localnet-tls/server.crt"
-  private-key-file = "/app/localnet-tls/server.key"
-  trust-collection-file = "/app/localnet-tls/ca.crt"
-}
-
-canton.participants.extra-2.ledger-api.tls {
-  cert-chain-file = "/app/localnet-tls/server.crt"
-  private-key-file = "/app/localnet-tls/server.key"
-  trust-collection-file = "/app/localnet-tls/ca.crt"
-}
-canton.participants.extra-2.admin-api.tls {
-  cert-chain-file = "/app/localnet-tls/server.crt"
-  private-key-file = "/app/localnet-tls/server.key"
-  trust-collection-file = "/app/localnet-tls/ca.crt"
-}
-
-canton.participants.extra-3.ledger-api.tls {
-  cert-chain-file = "/app/localnet-tls/server.crt"
-  private-key-file = "/app/localnet-tls/server.key"
-  trust-collection-file = "/app/localnet-tls/ca.crt"
-}
-canton.participants.extra-3.admin-api.tls {
-  cert-chain-file = "/app/localnet-tls/server.crt"
-  private-key-file = "/app/localnet-tls/server.key"
-  trust-collection-file = "/app/localnet-tls/ca.crt"
-}
-

package/node/.generated/start-local/additional-config.extra-validators.conf

@@ -103,18 +103,3 @@ canton.validator-apps.extra-3-validator_backend = $${_validator_backend} {
 
 canton.sv-apps.sv.expected-validator-onboardings += { secret = "${EXTRA_VALIDATOR_3_ONBOARDING_SECRET}" }
 
-canton.validator-apps.extra-1-validator_backend.participant-client {
-  admin-api.tls.trust-collection-file = "/app/localnet-tls/ca.crt"
-  ledger-api.client-config.tls.trust-collection-file = "/app/localnet-tls/ca.crt"
-}
-
-canton.validator-apps.extra-2-validator_backend.participant-client {
-  admin-api.tls.trust-collection-file = "/app/localnet-tls/ca.crt"
-  ledger-api.client-config.tls.trust-collection-file = "/app/localnet-tls/ca.crt"
-}
-
-canton.validator-apps.extra-3-validator_backend.participant-client {
-  admin-api.tls.trust-collection-file = "/app/localnet-tls/ca.crt"
-  ledger-api.client-config.tls.trust-collection-file = "/app/localnet-tls/ca.crt"
-}
-

package/node/.generated/start-local/compose-extra-participants.yaml

@@ -84,78 +84,6 @@ services:
           }
         }
         
-        canton.participants.extra-1.ledger-api.auth-services = [
-          {
-            type = unsafe-jwt-hmac-256
-            target-audience = "https://canton.network.global"
-            secret = "unsafe"
-          },
-          {
-            type = jwt-es-256-crt
-            certificate = "/app/es256-certificate.pem"
-            target-audience = "https://canton.network.global/es256"
-          }
-        ]
-        
-        canton.participants.extra-2.ledger-api.auth-services = [
-          {
-            type = unsafe-jwt-hmac-256
-            target-audience = "https://canton.network.global"
-            secret = "unsafe"
-          },
-          {
-            type = jwt-es-256-crt
-            certificate = "/app/es256-certificate.pem"
-            target-audience = "https://canton.network.global/es256"
-          }
-        ]
-        
-        canton.participants.extra-3.ledger-api.auth-services = [
-          {
-            type = unsafe-jwt-hmac-256
-            target-audience = "https://canton.network.global"
-            secret = "unsafe"
-          },
-          {
-            type = jwt-es-256-crt
-            certificate = "/app/es256-certificate.pem"
-            target-audience = "https://canton.network.global/es256"
-          }
-        ]
-        
-        canton.participants.extra-1.ledger-api.tls {
-          cert-chain-file = "/app/localnet-tls/server.crt"
-          private-key-file = "/app/localnet-tls/server.key"
-          trust-collection-file = "/app/localnet-tls/ca.crt"
-        }
-        canton.participants.extra-1.admin-api.tls {
-          cert-chain-file = "/app/localnet-tls/server.crt"
-          private-key-file = "/app/localnet-tls/server.key"
-          trust-collection-file = "/app/localnet-tls/ca.crt"
-        }
-        
-        canton.participants.extra-2.ledger-api.tls {
-          cert-chain-file = "/app/localnet-tls/server.crt"
-          private-key-file = "/app/localnet-tls/server.key"
-          trust-collection-file = "/app/localnet-tls/ca.crt"
-        }
-        canton.participants.extra-2.admin-api.tls {
-          cert-chain-file = "/app/localnet-tls/server.crt"
-          private-key-file = "/app/localnet-tls/server.key"
-          trust-collection-file = "/app/localnet-tls/ca.crt"
-        }
-        
-        canton.participants.extra-3.ledger-api.tls {
-          cert-chain-file = "/app/localnet-tls/server.crt"
-          private-key-file = "/app/localnet-tls/server.key"
-          trust-collection-file = "/app/localnet-tls/ca.crt"
-        }
-        canton.participants.extra-3.admin-api.tls {
-          cert-chain-file = "/app/localnet-tls/server.crt"
-          private-key-file = "/app/localnet-tls/server.key"
-          trust-collection-file = "/app/localnet-tls/ca.crt"
-        }
-        
     ports:
       - "${EXTRA_PARTICIPANT_1_LEDGER_API_PUBLISHED_PORT}:${EXTRA_PARTICIPANT_1_LEDGER_API_PORT}"
       - "${EXTRA_PARTICIPANT_1_ADMIN_API_PUBLISHED_PORT}:${EXTRA_PARTICIPANT_1_ADMIN_API_PORT}"
@@ -276,21 +204,6 @@ services:
         
         canton.sv-apps.sv.expected-validator-onboardings += { secret = "${EXTRA_VALIDATOR_3_ONBOARDING_SECRET}" }
         
-        canton.validator-apps.extra-1-validator_backend.participant-client {
-          admin-api.tls.trust-collection-file = "/app/localnet-tls/ca.crt"
-          ledger-api.client-config.tls.trust-collection-file = "/app/localnet-tls/ca.crt"
-        }
-        
-        canton.validator-apps.extra-2-validator_backend.participant-client {
-          admin-api.tls.trust-collection-file = "/app/localnet-tls/ca.crt"
-          ledger-api.client-config.tls.trust-collection-file = "/app/localnet-tls/ca.crt"
-        }
-        
-        canton.validator-apps.extra-3-validator_backend.participant-client {
-          admin-api.tls.trust-collection-file = "/app/localnet-tls/ca.crt"
-          ledger-api.client-config.tls.trust-collection-file = "/app/localnet-tls/ca.crt"
-        }
-        
     ports:
       - "${EXTRA_VALIDATOR_1_ADMIN_API_PUBLISHED_PORT}:${EXTRA_VALIDATOR_1_ADMIN_API_PORT}"
       - "${EXTRA_VALIDATOR_2_ADMIN_API_PUBLISHED_PORT}:${EXTRA_VALIDATOR_2_ADMIN_API_PORT}"
@@ -333,10 +246,8 @@ services:
       SCRIBE_TARGET_POSTGRES_USERNAME: ${DB_USER}
       SCRIBE_TARGET_POSTGRES_PASSWORD: ${DB_PASSWORD}
       SCRIBE_CONFIG: /onboarding/extra-1-pqs.conf
-      SCRIBE_SOURCE_LEDGER_TLS_CAFILE: /app/localnet-tls/ca.crt
     volumes:
       - onboarding:/onboarding
-      - "/home/helena/env/daml/typescript-sdk/.generated/localnet-tls/ca.crt:/app/localnet-tls/ca.crt:ro"
     command:
       - pipeline
       - ledger
@@ -387,10 +298,8 @@ services:
       SCRIBE_TARGET_POSTGRES_USERNAME: ${DB_USER}
       SCRIBE_TARGET_POSTGRES_PASSWORD: ${DB_PASSWORD}
       SCRIBE_CONFIG: /onboarding/extra-2-pqs.conf
-      SCRIBE_SOURCE_LEDGER_TLS_CAFILE: /app/localnet-tls/ca.crt
     volumes:
       - onboarding:/onboarding
-      - "/home/helena/env/daml/typescript-sdk/.generated/localnet-tls/ca.crt:/app/localnet-tls/ca.crt:ro"
     command:
       - pipeline
       - ledger
@@ -441,10 +350,8 @@ services:
       SCRIBE_TARGET_POSTGRES_USERNAME: ${DB_USER}
       SCRIBE_TARGET_POSTGRES_PASSWORD: ${DB_PASSWORD}
       SCRIBE_CONFIG: /onboarding/extra-3-pqs.conf
-      SCRIBE_SOURCE_LEDGER_TLS_CAFILE: /app/localnet-tls/ca.crt
     volumes:
       - onboarding:/onboarding
-      - "/home/helena/env/daml/typescript-sdk/.generated/localnet-tls/ca.crt:/app/localnet-tls/ca.crt:ro"
     command:
       - pipeline
       - ledger

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
@@ -958,40 +958,88 @@ extra_pqs_services() {
   done
 }
 
-wait_for_container_health() {
+container_readiness_state() {
   local container="$1"
-  local attempts="${2:-30}"
-  local delay_seconds="${3:-2}"
-  local status
+  docker inspect --format '{{.State.Status}} {{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}' "$container" \
+    2>/dev/null | tail -n 1 || true
+}
 
-  for ((i = 1; i <= attempts; i++)); do
-    status="$(docker inspect --format '{{.State.Health.Status}}' "$container" 2>/dev/null | tail -n 1 || true)"
-    if [[ "$status" == "healthy" ]]; then
-      return 0
-    fi
-    sleep "$delay_seconds"
-  done
+container_health_is_ready() {
+  local _container="$1"
+  local _lifecycle_state="$2"
+  local health_status="$3"
+  [[ "$lifecycle_state" == "running" && "$health_status" == "healthy" ]]
+}
 
-  echo "$container did not become healthy after $((attempts * delay_seconds)) seconds." >&2
-  return 1
+canton_and_extras_are_ready() {
+  local _container="$1"
+  local _lifecycle_state="$2"
+  local health_status="$3"
+  local extra_participants="$4"
+  [[ "$lifecycle_state" == "running" && "$health_status" == "healthy" ]] \
+    && extra_participants_healthy "$extra_participants"
 }
 
-wait_for_canton_health() {
-  local extra_participants="${1:-0}"
-  local attempts=30
-  local delay_seconds=2
-  local status
+print_container_logs() {
+  local container="$1"
+  echo "Recent logs for $container:" >&2
+  docker logs --tail 40 "$container" >&2 || true
+}
+
+readiness_elapsed_seconds() {
+  if [[ -n "${START_LOCAL_TEST_READINESS_CLOCK_FILE:-}" ]]; then
+    cat "$START_LOCAL_TEST_READINESS_CLOCK_FILE"
+    return 0
+  fi
+  printf '%s\n' "$SECONDS"
+}
 
-  for ((i = 1; i <= attempts; i++)); do
-    status="$(docker inspect --format '{{.State.Health.Status}}' canton 2>/dev/null | tail -n 1 || true)"
-    if [[ "$status" == "healthy" ]] && extra_participants_healthy "$extra_participants"; then
+wait_for_container_readiness() {
+  local container="$1"
+  local readiness_predicate="$2"
+  shift 2
+
+  local last_readiness_state=""
+  local last_diagnostic_at
+  last_diagnostic_at="$(readiness_elapsed_seconds)"
+
+  while true; do
+    local lifecycle_state health_status readiness_state
+    read -r lifecycle_state health_status <<< "$(container_readiness_state "$container")"
+    lifecycle_state="${lifecycle_state:-missing}"
+    health_status="${health_status:-unknown}"
+
+    if [[ "$lifecycle_state" != "running" && "$lifecycle_state" != "restarting" ]]; then
+      echo "$container is not running (state: $lifecycle_state)." >&2
+      print_container_logs "$container"
+      return 1
+    fi
+
+    readiness_state="$lifecycle_state/$health_status"
+    if [[ "$readiness_state" != "$last_readiness_state" ]]; then
+      echo "$container readiness: $readiness_state"
+      last_readiness_state="$readiness_state"
+    fi
+
+    if "$readiness_predicate" "$container" "$lifecycle_state" "$health_status" "$@"; then
       return 0
     fi
-    sleep "$delay_seconds"
+
+    local now
+    now="$(readiness_elapsed_seconds)"
+    if (( now - last_diagnostic_at >= 30 )); then
+      echo "$container is still not ready (state: $lifecycle_state, health: $health_status)." >&2
+      print_container_logs "$container"
+      last_diagnostic_at="$now"
+    fi
+
+    sleep 2
   done
+}
 
-  echo "canton did not become healthy after $((attempts * delay_seconds)) seconds." >&2
-  return 1
+wait_for_canton_health() {
+  local extra_participants="${1:-0}"
+  wait_for_container_readiness canton canton_and_extras_are_ready "$extra_participants"
 }
 
 provision_extra_pqs() {
@@ -1190,8 +1238,8 @@ start_ledger_stack() {
   docker_compose "${compose_args[@]}" up -d --no-recreate "${followup_services[@]}"
 
   if (( extra_participants > 0 )); then
-    wait_for_container_health splice 60 2
-    wait_for_container_health splice-onboarding 60 2
+    wait_for_container_readiness splice container_health_is_ready
+    wait_for_container_readiness splice-onboarding container_health_is_ready
     if [[ "$auth_mode" == "shared-secret" ]]; then
       grant_localnet_validator_read_rights "$extra_participants"
     fi

package/node/test-start-local.sh

@@ -42,8 +42,9 @@ run_case() {
   local quickstart_root_dir="$tmpdir/cn-quickstart"
   local stubbin="$tmpdir/bin"
   local generated_dir="$tmpdir/generated"
+  local docker_state_dir="$tmpdir/docker-state"
 
-  rm -rf "$quickstart_dir" "$quickstart_root_dir" "$stubbin" "$generated_dir" "$tmpdir/tls"
+  rm -rf "$quickstart_dir" "$quickstart_root_dir" "$stubbin" "$generated_dir" "$docker_state_dir" "$tmpdir/tls"
   mkdir -p \
     "$quickstart_root_dir" \
     "$quickstart_dir/docker/modules/localnet/env" \
@@ -51,7 +52,9 @@ run_case() {
     "$quickstart_dir/docker/modules/splice-onboarding" \
     "$quickstart_dir/docker/modules/keycloak" \
     "$stubbin" \
-    "$generated_dir"
+    "$generated_dir" \
+    "$docker_state_dir"
+  printf '0\n' > "$docker_state_dir/readiness-seconds"
   ln -s "$quickstart_dir" "$quickstart_root_dir/quickstart"
   printf '%s\n' "$makefile_targets" > "$quickstart_dir/Makefile"
   printf '%s\n' \
@@ -132,11 +135,68 @@ printf 'stub env SV_PROFILE=%s\n' "${SV_PROFILE:-}"
 printf 'stub env PQS_SV_PROFILE=%s\n' "${PQS_SV_PROFILE:-}"
 printf 'stub env AUTH_MODE=%s\n' "${AUTH_MODE:-}"
 if [[ "${1:-}" == "inspect" ]]; then
-  printf 'healthy\n'
+  container="${!#}"
+  state_file="${START_LOCAL_TEST_DOCKER_STATE_DIR}/${docker_mode}-${container}.count"
+  count=0
+  if [[ -f "$state_file" ]]; then
+    count="$(<"$state_file")"
+  fi
+  count=$((count + 1))
+  printf '%s\n' "$count" > "$state_file"
+
+  lifecycle=running
+  health=healthy
+  case "$docker_mode:$container" in
+    slow-canton:canton)
+      if (( count <= 31 )); then health=starting; fi
+      ;;
+    slow-splice:splice)
+      if (( count <= 61 )); then health=starting; fi
+      ;;
+    restarting-canton:canton)
+      if (( count == 1 )); then
+        lifecycle=restarting
+        health=unhealthy
+      fi
+      ;;
+    restarting-healthy-canton:canton)
+      if (( count == 1 )); then
+        lifecycle=restarting
+        health=healthy
+      fi
+      ;;
+    exited-canton:canton)
+      lifecycle=exited
+      health=unhealthy
+      ;;
+  esac
+
+  if [[ "$*" == *'.State.Status'* ]]; then
+    printf '%s %s\n' "$lifecycle" "$health"
+  else
+    printf '%s\n' "$health"
+  fi
+  exit 0
+fi
+if [[ "${1:-}" == "logs" ]]; then
+  printf 'stub log tail for %s\n' "${!#}"
   exit 0
 fi
-  if [[ "${1:-}" == "exec" ]]; then
-    extra_pqs_config_file=""
+if [[ "${1:-}" == "exec" ]]; then
+  if [[ "$*" == *"http://localhost:"* ]]; then
+    printf '%s\n' "$*" > "${START_LOCAL_TEST_DOCKER_STATE_DIR}/extra-healthcheck-command"
+    healthcheck_state_file="${START_LOCAL_TEST_DOCKER_STATE_DIR}/${docker_mode}-extra-healthcheck.count"
+    healthcheck_count=0
+    if [[ -f "$healthcheck_state_file" ]]; then
+      healthcheck_count="$(<"$healthcheck_state_file")"
+    fi
+    healthcheck_count=$((healthcheck_count + 1))
+    printf '%s\n' "$healthcheck_count" > "$healthcheck_state_file"
+    if [[ "$docker_mode" == "slow-extra-health" && "$healthcheck_count" == "1" ]]; then
+      exit 1
+    fi
+  fi
+  extra_pqs_config_file=""
     while (( "$#" )); do
       if [[ "${1:-}" == "-e" && "${2:-}" == EXTRA_PQS_CONFIG_FILE=* ]]; then
         extra_pqs_config_file="${2#EXTRA_PQS_CONFIG_FILE=}"
@@ -160,6 +220,9 @@ if [[ "${1:-}" == "compose" && "${2:-}" == "version" ]]; then
   exit 0
 fi
 printf 'stub docker %s\n' "$*"
+if [[ "$*" == *" up -d --no-recreate pqs-extra-1"* ]]; then
+  printf 'stub extra pqs startup\n'
+fi
   if [[ "$docker_mode" == "staged-start" ]]; then
   if [[ "${1:-}" == "compose" && "$*" == *" down -v --remove-orphans"* ]]; then
     exit 0
@@ -189,6 +252,16 @@ EOF
   sed -i "s|__DOCKER_MODE__|$docker_mode|" "$stubbin/docker"
   chmod +x "$stubbin/docker"
 
+cat > "$stubbin/sleep" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+if [[ -n "${START_LOCAL_TEST_READINESS_CLOCK_FILE:-}" ]]; then
+  current="$(<"$START_LOCAL_TEST_READINESS_CLOCK_FILE")"
+  printf '%s\n' "$((current + ${1:-0}))" > "$START_LOCAL_TEST_READINESS_CLOCK_FILE"
+fi
+EOF
+  chmod +x "$stubbin/sleep"
+
   cat > "$stubbin/docker-compose" <<'EOF'
 #!/usr/bin/env bash
 set -euo pipefail
@@ -226,6 +299,8 @@ EOF
         LOCALNET_TLS_CERT_CHAIN_PATH="$tls_cert_chain_path" \
         LOCALNET_TLS_PRIVATE_KEY_PATH="$tls_private_key_path" \
         LOCALNET_TLS_CA_CERT_PATH="$tls_ca_cert_path" \
+        START_LOCAL_TEST_DOCKER_STATE_DIR="$docker_state_dir" \
+        START_LOCAL_TEST_READINESS_CLOCK_FILE="$docker_state_dir/readiness-seconds" \
         EXTRA_PARTICIPANTS="$extra_participants" \
         PATH="$stubbin:$PATH" \
         bash ./start-local.sh 2>&1
@@ -240,6 +315,8 @@ EOF
         LOCALNET_TLS_CERT_CHAIN_PATH="$tls_cert_chain_path" \
         LOCALNET_TLS_PRIVATE_KEY_PATH="$tls_private_key_path" \
         LOCALNET_TLS_CA_CERT_PATH="$tls_ca_cert_path" \
+        START_LOCAL_TEST_DOCKER_STATE_DIR="$docker_state_dir" \
+        START_LOCAL_TEST_READINESS_CLOCK_FILE="$docker_state_dir/readiness-seconds" \
         EXTRA_PARTICIPANTS="$extra_participants" \
         PATH="$stubbin:$PATH" \
         bash ./start-local.sh 2>&1
@@ -353,7 +430,11 @@ printf 'stub env SV_PROFILE=%s\n' "${SV_PROFILE:-}"
 printf 'stub env PQS_SV_PROFILE=%s\n' "${PQS_SV_PROFILE:-}"
 printf 'stub env AUTH_MODE=%s\n' "${AUTH_MODE:-}"
 if [[ "${1:-}" == "inspect" ]]; then
-  printf 'healthy\n'
+  if [[ "$*" == *'.State.Status'* ]]; then
+    printf 'running healthy\n'
+  else
+    printf 'healthy\n'
+  fi
   exit 0
 fi
 if [[ "${1:-}" == "exec" ]]; then
@@ -390,6 +471,15 @@ run_case $'.PHONY: start\nstart:\n' 'stub env APP_USER_PROFILE=off'
 run_case $'.PHONY: start\nstart:\n' 'stub env SV_PROFILE=on'
 run_case $'.PHONY: start\nstart:\n' 'stub env PQS_SV_PROFILE=on'
 run_case $'.PHONY: start\nstart:\n' 'stub env AUTH_MODE=oauth2' oauth2
+run_case $'.PHONY: start\nstart:\n' 'canton readiness: running/starting' shared-secret slow-canton
+run_case $'.PHONY: start\nstart:\n' 'canton is still not ready (state: running, health: starting).' shared-secret slow-canton
+run_case $'.PHONY: start\nstart:\n' 'stub log tail for canton' shared-secret slow-canton
+run_case $'.PHONY: start\nstart:\n' 'canton readiness: restarting/unhealthy' shared-secret restarting-canton
+run_case $'.PHONY: start\nstart:\n' 'canton readiness: running/healthy' shared-secret restarting-healthy-canton
+run_case $'.PHONY: start\nstart:\n' 'canton is not running (state: exited).' shared-secret exited-canton '' '' '' 0 0 '' '' '' 1
+run_case $'.PHONY: start\nstart:\n' 'stub log tail for canton' shared-secret exited-canton '' '' '' 0 0 '' '' '' 1
+run_case $'.PHONY: start\nstart:\n' 'splice readiness: running/starting' shared-secret slow-splice 1
+run_case $'.PHONY: start\nstart:\n' 'stub extra pqs startup' shared-secret slow-splice 1
 run_case $'.PHONY: start\nstart:\n' 'stub docker compose -f compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/localnet/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/splice-onboarding/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/pqs/compose.yaml --env-file .env --env-file .env.local --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/compose.env --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/env/common.env --env-file '"$tmpdir"'/quickstart/docker/modules/pqs/compose.env --profile app-provider --profile pqs-app-provider --profile pqs-sv down -v --remove-orphans'
 run_case $'.PHONY: start\nstart:\n' 'stub docker compose -f compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/localnet/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/splice-onboarding/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/pqs/compose.yaml --env-file .env --env-file .env.local --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/compose.env --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/env/common.env --env-file '"$tmpdir"'/quickstart/docker/modules/pqs/compose.env --profile app-provider --profile pqs-app-provider --profile pqs-sv up -d --no-recreate postgres canton'
 run_case $'.PHONY: start\nstart:\n' 'stub docker compose -f compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/localnet/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/splice-onboarding/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/pqs/compose.yaml --env-file .env --env-file .env.local --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/compose.env --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/env/common.env --env-file '"$tmpdir"'/quickstart/docker/modules/pqs/compose.env --profile app-provider --profile pqs-app-provider --profile pqs-sv -f '"$tmpdir"'/quickstart/docker/modules/keycloak/compose.yaml --env-file '"$tmpdir"'/quickstart/docker/modules/keycloak/compose.env --profile keycloak down -v --remove-orphans' oauth2
@@ -398,6 +488,9 @@ run_case $'.PHONY: start\nstart:\n' 'stub docker-compose -f compose.yaml -f '"$t
 run_case $'.PHONY: start\nstart:\n' 'stub docker compose -f compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/localnet/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/splice-onboarding/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/pqs/compose.yaml --env-file .env --env-file .env.local --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/compose.env --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/env/common.env --env-file '"$tmpdir"'/quickstart/docker/modules/pqs/compose.env --profile app-provider --profile pqs-app-provider --profile pqs-sv -f '"$tmpdir"'/generated/compose-extra-participants.yaml --env-file '"$tmpdir"'/generated/extra-participants.env down -v --remove-orphans' shared-secret default 3
 run_case $'.PHONY: start\nstart:\n' 'stub docker compose -f compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/localnet/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/splice-onboarding/compose.yaml -f '"$tmpdir"'/quickstart/docker/modules/pqs/compose.yaml --env-file .env --env-file .env.local --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/compose.env --env-file '"$tmpdir"'/quickstart/docker/modules/localnet/env/common.env --env-file '"$tmpdir"'/quickstart/docker/modules/pqs/compose.env --profile app-provider --profile pqs-app-provider --profile pqs-sv -f '"$tmpdir"'/generated/compose-extra-participants.yaml --env-file '"$tmpdir"'/generated/extra-participants.env up -d --no-recreate pqs-extra-1 pqs-extra-2 pqs-extra-3' shared-secret default 3
 run_case $'.PHONY: start\nstart:\n' 'ES256 bearer token written to '"$tmpdir"'/es256/ledger-api-user.token' shared-secret default 3 '' '' 1
+assert_file_contains_text "$tmpdir/docker-state/extra-healthcheck-command" 'wget -q --timeout=2 --tries=1 -O /dev/null http://localhost:5900/health'
+assert_file_contains_text "$tmpdir/docker-state/extra-healthcheck-command" 'wget -q --timeout=2 --tries=1 -O /dev/null http://localhost:6900/health'
+assert_file_contains_text "$tmpdir/docker-state/extra-healthcheck-command" 'wget -q --timeout=2 --tries=1 -O /dev/null http://localhost:7900/health'
 assert_file_contains "$tmpdir/es256/canton-es256.conf" 'canton.participants.app-provider.ledger-api.auth-services = ['
 assert_file_contains "$tmpdir/es256/canton-es256.conf" '    type = jwt-es-256-crt'
 assert_file_contains "$tmpdir/es256/canton-es256.conf" '    certificate = "/app/es256-certificate.pem"'
@@ -418,6 +511,8 @@ assert_file_contains "$tmpdir/generated/extra-participants.env" 'EXTRA_VALIDATOR
 assert_file_contains "$tmpdir/generated/extra-participants.env" 'EXTRA_VALIDATOR_1_WALLET_ADMIN_USER_NAME=extra-1'
 assert_file_contains "$tmpdir/generated/extra-participants.env" 'EXTRA_VALIDATOR_1_AUTH_AUDIENCE=https://canton.network.global'
 assert_file_contains "$tmpdir/generated/extra-participants.env" 'CREATE_DATABASE_EXTRA_PQS_1=pqs-extra-1'
+run_case $'.PHONY: start\nstart:\n' 'stub extra pqs startup' shared-secret slow-extra-health 3
+assert_file_contains "$tmpdir/docker-state/slow-extra-health-extra-healthcheck.count" '2'
 assert_file_contains "$tmpdir/generated/extra-participants.env" 'EXTRA_PQS_1_POSTGRES_PUBLISHED_PORT=5541'
 assert_file_contains "$tmpdir/generated/extra-participants.env" 'EXTRA_PQS_3_POSTGRES_PUBLISHED_PORT=5543'
 assert_file_contains "$tmpdir/generated/compose-extra-participants.yaml" '      ADDITIONAL_CONFIG_EXTRA_PARTICIPANTS: |'

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@distrohelena/canton-typescript-sdk",
-    "version": "0.1.30",
+    "version": "0.1.32",
     "license": "Apache-2.0",
     "type": "module",
     "main": "./dist/index.js",
@@ -79,6 +79,13 @@
         "build": "node ./scripts/clean-dist.mjs && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node ./scripts/write-cjs-package.mjs",
         "generate:daml-interface": "node ./dist/daml-interface/cli/daml-interface-cli-main.js",
         "generate:grpc": "node ./scripts/generate-grpc-bindings.mjs",
+        "examples:check": "npm run build && tsc -p tsconfig.examples.json --noEmit",
+        "example:init": "npm run build && node --loader ts-node/esm examples/01-client-initialization.ts",
+        "example:tls": "npm run build && node --loader ts-node/esm examples/02-tls-connection.ts",
+        "example:jwt": "npm run build && node --loader ts-node/esm examples/03-jwt-authentication.ts",
+        "example:party:hosted": "npm run build && node --loader ts-node/esm examples/10-hosted-party.ts",
+        "example:party:external": "npm run build && node --loader ts-node/esm examples/20-external-party-ed25519.ts",
+        "example:party:decentralized": "npm run build && node --loader ts-node/esm examples/30-decentralized-party-ed25519.ts",
         "lint": "eslint . --max-warnings=0",
         "lint:fix": "eslint . --fix --max-warnings=0",
         "start:local-ledger": "bash node/start-local.sh",