feat(zhtlc): estimate activation percentage based on block height

[takenagain]

Summary by CodeRabbit

• New Features

  • Rich, phase-based progress for ZHTLC activation with clearer step counts and percentage estimates.
  • Dedicated messages for missing Zcash parameters and other terminal states.
  • Actionable error messages and signals when user action is required (e.g., hardware wallet prompts).

• Improvements

  • More consistent, real-time activation updates driven by a unified progress estimator.
  • Faster, more reliable completion detection and streamlined status handling.
  • Improved guidance for hardware wallet flows (e.g., Trezor).

• Bug Fixes

  • Reduced spurious failures during activation monitoring and improved error handling.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly follows conventional commit style by indicating a new feature for ZHTLC and clearly communicates the primary change of estimating activation progress based on block height, which aligns with the pull request’s core objective of introducing a progress estimator driven by blockchain height. It is concise, specific to the scope, and directly reflects the main functionality added without extraneous information.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🧪 Early access (Sonnet 4.5): enabled

We are currently testing the Sonnet 4.5 model, which is expected to improve code review quality. However, this model may lead to increased noise levels in the review comments. Please disable the early access features if the noise level causes any inconvenience.

Note:

• Public repositories are always opted into early access features.
• You can enable or disable early access features from the CodeRabbit UI or by updating the CodeRabbit configuration file.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[takenagain]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[Copilot]

Pull Request Overview

This PR refactors the ZHTLC activation strategy to use a new progress estimation system based on block height tracking rather than hardcoded progress percentages. The changes introduce a dedicated progress estimator that can calculate activation percentage based on the current scanned block versus the latest known block height.

Key changes:

• Introduces a new progress estimation system with block height-based percentage calculations
• Replaces hardcoded progress updates with a configurable estimator class
• Adds structured progress reporting with better error handling and user action signals

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
zhtlc_activation_strategy.dart	Refactored to use the new progress estimator instead of inline progress calculations
zhtlc_activation_progress_estimator.dart	New class that estimates activation progress based on block heights and task phases
zhtlc_activation_progress.dart	New convenience wrapper for creating standardized ZHTLC progress snapshots

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[github-actions]

Visit the preview URL for this PR (updated for commit 04c4ca5):

https://kdf-sdk--pr230-feat-zhtlc-activatio-ndlutfl8.web.app

_{(expires Tue, 07 Oct 2025 00:07:16 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: 9c1b6e6c010cf0b965c455ba7a69c4aedafa8a1d}

[github-actions]

Visit the preview URL for this PR (updated for commit 04c4ca5):

https://komodo-playground--pr230-feat-zhtlc-activatio-rgbyec5v.web.app

_{(expires Tue, 07 Oct 2025 00:07:45 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: 2bfedd77fdea45b25ba7c784416e81f177aa5c47}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (5)

packages/komodo_defi_sdk/lib/src/activation/protocol_strategies/zhtlc_activation_progress_estimator.dart (1)

181-206: OK + error detail precedence (minor).

If status.status == 'Ok' but details embeds {"error":...}, we emit a terminal failure. That’s safer, but please confirm the daemon never embeds "error" in a success payload (e.g., warning). If it can, gate on a stronger signal (e.g., error.level == 'fatal') or prefer the phase (completed) over the presence of error.

Also applies to: 208-225

packages/komodo_defi_sdk/lib/src/activation/protocol_strategies/zhtlc_activation_progress.dart (2)

52-53: Deduplicate the error code constant.

Avoid hardcoding 'ZHTLC_ACTIVATION_ERROR' in multiple files. Expose a single constant and reuse it.

 class ZhtlcActivationProgress extends ActivationProgress {
+  static const errorCode = 'ZHTLC_ACTIVATION_ERROR';
@@
-        errorCode: 'ZHTLC_ACTIVATION_ERROR',
+        errorCode: ZhtlcActivationProgress.errorCode,

Optionally import and use this in the estimator to replace its private _kZhtlcErrorCode.

---

56-58: Use UTC timestamps for diagnostics.

DateTime.now().toIso8601String() is local time and ambiguous. Prefer UTC for logs/telemetry.

-          'timestamp': DateTime.now().toIso8601String(),
+          'timestamp': DateTime.now().toUtc().toIso8601String(),

packages/komodo_defi_sdk/lib/src/activation/protocol_strategies/zhtlc_activation_strategy.dart (2)

63-67: Avoid lossy as casts when copying typed config (minor).

If these fields are already strongly typed in userConfig, the as int?/String? casts add risk (throw on unexpected num/String). Pass them directly.

-          .copyWith(
-            scanBlocksPerIteration: userConfig.scanBlocksPerIteration as int?,
-            scanIntervalMs: userConfig.scanIntervalMs as int?,
-            zcashParamsPath: userConfig.zcashParamsPath as String?,
-            privKeyPolicy: privKeyPolicy,
-          );
+          .copyWith(
+            scanBlocksPerIteration: userConfig.scanBlocksPerIteration,
+            scanIntervalMs: userConfig.scanIntervalMs,
+            zcashParamsPath: userConfig.zcashParamsPath,
+            privKeyPolicy: privKeyPolicy,
+          );

---

93-95: Make polling interval configurable (optional).

500ms is fine for UX but can be heavy on mobile networks. Consider sourcing from config or backing off after N steady states.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e6e924c and 0c1f9c2.

📒 Files selected for processing (3)

• packages/komodo_defi_sdk/lib/src/activation/protocol_strategies/zhtlc_activation_progress.dart (1 hunks)
• packages/komodo_defi_sdk/lib/src/activation/protocol_strategies/zhtlc_activation_progress_estimator.dart (1 hunks)
• packages/komodo_defi_sdk/lib/src/activation/protocol_strategies/zhtlc_activation_strategy.dart (4 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: build_and_preview_playground_preview
• GitHub Check: build_and_preview_sdk_example_preview
• GitHub Check: Flutter tests (all packages)

🔇 Additional comments (1)

packages/komodo_defi_sdk/lib/src/activation/protocol_strategies/zhtlc_activation_progress_estimator.dart (1)

259-283: Confirm completed heuristic keys appear only in final ZHTLC status
Couldn’t find any example fixtures for enableZhtlcStatus; manually verify that wallet_balance, current_block, and ticker only occur in the terminal “completed” payload (zhtlc_activation_progress_estimator.dart L259–283).