@distrohelena/canton-typescript-sdk 0.1.30 → 0.1.31

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/start-local.sh

@@ -958,40 +958,87 @@ 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"
+  [[ "$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"
+  [[ "$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" ]]; 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 +1237,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,7 +135,39 @@ 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
+      ;;
+    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
@@ -160,6 +195,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 +227,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 +274,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 +290,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 +405,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 +446,13 @@ 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 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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@distrohelena/canton-typescript-sdk",
-    "version": "0.1.30",
+    "version": "0.1.31",
     "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",