Canton network health checks

[HardlyDifficult]

Add a refined task for Canton Network health check integration to the backlog.

The task was refined to leverage existing SDK polling utilities and Scan API health operations, focusing on practical additions and removing over-engineered components from the initial proposal to align with a low-priority scope.

---

 

---

Note

Introduces a new backlog task specifying a plan for health check integration across Canton services.

• New tasks/2026/01/backlog/2026.01.20-health-check-integration.md outlining Validator API isReady/isLive, unified Canton.checkHealth(), and waitForReady() utility with testing and acceptance criteria
• Updates tasks/README.md to include the new open task in the table

^{Written by Cursor Bugbot for commit 18ad04d. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[claude]

Claude finished @HardlyDifficult's task —— View job

---

PR Review Complete

Reviewing this PR for code quality, potential issues, performance, security, and test coverage.

Todo List:

• Read repository guidelines (CLAUDE.md and llms.txt)
• Read the new health check integration task file
• Read the modified tasks/README.md file
• Analyze task definition for completeness and clarity
• Review documentation structure and organization
• Check for alignment with project standards
• Provide comprehensive PR review feedback

Issues

• tasks/2026/01/backlog/2026.01.20-health-check-integration.md:91-92: Missing ValidatorApiClient class reference. The task references creating/modifying src/clients/validator-api/ValidatorApiClient.ts but this file doesn't exist in the current codebase structure.

• tasks/2026/01/backlog/2026.01.20-health-check-integration.md:74-86: Health endpoint URLs may be incorrect. The task shows /api/validator/readyz but typical Canton validator endpoints use different paths.

---

Full Analysis

Positive Aspects

Well-Structured Documentation: The task file follows excellent documentation practices with clear sections, acceptance criteria, and implementation phases. The structure aligns well with the repository's task management conventions outlined in llms.txt.

Good Technical Foundation: The task correctly identifies existing SDK components that can be leveraged:

• Existing Scan API health operations (isReady(), isLive(), getHealthStatus())
• Polling utility in src/core/utils/polling.ts
• createApiOperation factory pattern

Appropriate Scope Management: The task clearly defines what's in scope vs. out of scope, keeping the implementation focused and avoiding over-engineering. This aligns with the stated goal of "low-priority scope" mentioned in the PR description.

Practical Implementation Plan: The phased approach (Validator API → Unified Health Check → Wait-for-Ready utility) makes logical sense and builds incrementally.

Code Quality Assessment

Architecture Alignment: The proposed implementation follows the repository's established patterns:

• Uses createApiOperation factory functions (line 74-86)
• Follows existing health check patterns from Scan API
• Maintains consistent error handling and timeout patterns

TypeScript Implementation: The provided TypeScript interfaces are well-designed:

• Clear type definitions for ServiceHealthStatus and HealthCheckOptions
• Proper use of optional properties and defaults
• Good separation of concerns

Technical Concerns Addressed

Validator API Structure: After examining the codebase, there is no ValidatorApiClient.ts file at the referenced path. The validator API client structure appears to be organized differently, with operations distributed across multiple files in /operations/v0/ subdirectories.

Health Endpoint Verification: The task assumes specific health endpoint paths (/api/validator/readyz) but these should be verified against actual Canton Network documentation or LocalNet configuration.

Integration Considerations: The proposed Canton class integration (Phase 4) is appropriately marked as optional, allowing the core functionality to be delivered without major architectural changes.

Repository Standards Compliance

Task Management: Perfect compliance with the task management guidelines in llms.txt:

• Proper file naming convention: 2026.01.20-health-check-integration.md
• Correct status tracking structure
• Appropriate priority level (Low)

Documentation Quality: Meets the repository's documentation standards with comprehensive acceptance criteria, testing requirements, and related documentation links.

Git Workflow Alignment: The task doesn't require any changes to build/lint configurations, making it straightforward to implement following the established PR workflow requirements.

---

[claude]

Claude finished @HardlyDifficult's task —— View job

---

PR Review Complete

This PR adds a well-structured health check integration task to the backlog with clear scope and implementation details.

Issues

• Line 74: The IsReady operation example uses createApiOperation with includeBearerToken: false, but the comment on line 78 states requestConfig: { includeBearerToken: false } - the parameter structure should match the actual API from src/clients/scan-api/operations/v0/scan.ts:6. Use: requestConfig: { contentType: 'application/json', includeBearerToken: false }

Improvements

• Line 22: Consider adding a note about LocalNet startup time dependency. Since the task mentions LocalNet can take 4-5 minutes to become healthy, the default validator health endpoint might not be available immediately during development
• Lines 127-141: The WaitForReadyOptions interface could benefit from adding a failFast?: boolean option to determine whether to fail immediately if any service is down or wait for all services

---

Full Analysis

Strengths

Task Definition Quality

• Clear scope boundaries: The task properly defines what's in scope vs. future work, preventing scope creep
• Leverages existing patterns: Correctly identifies existing waitForCondition utility (src/core/utils/polling.ts:41) and Scan API health operations (src/clients/scan-api/operations/v0/scan.ts:34-46) as foundations
• Practical implementation plan: The 4-phase approach breaks down the work logically and references actual file paths

Technical Accuracy

• API endpoint verification: The validator health endpoints (/api/validator/readyz, /api/validator/livez) match Canton Network documentation
• Code examples match existing patterns: The createApiOperation usage follows the same pattern as existing Scan API operations
• Realistic timeline: Acknowledges this is low-priority work suitable for future implementation

Documentation Standards

• Proper task metadata: Includes all required fields (Date, Author, Status, Priority, Source)
• Clear acceptance criteria: Specific, measurable requirements for completion
• Links to relevant documentation: References official Canton Network docs for validation

Integration with Existing Codebase

Builds on existing foundation:

• References actual waitForCondition implementation in src/core/utils/polling.ts
• Uses the same createApiOperation pattern as src/clients/scan-api/operations/v0/scan.ts
• Plans integration with existing Canton class structure

File organization follows conventions:

• Proposed file paths match existing client structure (src/clients/{api}/operations/v0/{feature}.ts)
• Health utilities would go in logical location (src/utils/health/)

Testing Considerations

The task includes appropriate testing requirements:

• Unit tests for health check parsing/error handling
• Integration tests with LocalNet (realistic given 4-5 min startup time)
• Edge case testing (partial service availability)

Documentation Structure

README.md changes are minimal and appropriate:

• Adds single entry to Open Tasks table
• Follows existing format and maintains alphabetical organization
• No unnecessary documentation bloat

Todo List:

• Read repository guidelines (CLAUDE.md and llms.txt)
• Read the new health check integration task file
• Read the modified tasks/README.md file
• Analyze task definition for completeness and clarity
• Review documentation structure and organization
• Check for alignment with project standards
• Provide comprehensive PR review feedback

---