fix(zhtlc): align orderbook RPC with KDF schema, and add id pagination support

[takenagain]

Summary by CodeRabbit

• New Features
  • Enhanced orderbook parsing to support structured prices, volumes (including aggregated), addresses, and confirmation settings.
  • Added paging metadata to transaction history responses, supporting both page-number and from-id modes.
  • Broadened ZHTLC transaction history to handle multiple pagination types.
• Refactor
  • Strategy factory now accepts optional custom strategies, with improved selection logic.
  • More robust JSON handling for numeric and string conversions.
• Style
  • Adjusted loading text color in the withdraw source address field for better theme consistency.
• Tests
  • Added comprehensive fixtures and tests for orderbook parsing and strategy selection.

[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.

Walkthrough

Introduces new orderbook structures (OrderAddress, updated OrderInfo) with nested numeric parsing, adds NumericValue type, enhances pagination deserialization and propagates paging options through transaction history responses and strategies (including ZHTLC support for transaction-based pagination). Updates JSON utils for int→String conversion, adds tests/fixtures, and tweaks a UI text color.

Changes

Cohort / File(s)	Summary
Orderbook structures packages/komodo_defi_rpc_methods/lib/src/common_structures/orderbook/order_address.dart, .../order_info.dart, .../primitive/numeric_value.dart	Adds OrderAddress and OrderAddressType; rewrites OrderInfo to v2 schema with nested NumericValue and optional fields; implements NumericValue with decimal/fraction/rational parsing, tryParse, and JSON (de)serialization.
Pagination and JSON utils packages/komodo_defi_rpc_methods/lib/src/common_structures/pagination/pagination.dart, packages/komodo_defi_types/lib/src/utils/json_type_utils.dart	Adds Pagination.fromJson supporting multiple key variants and type coercions; updates JSON traversal to convert int to String for String targets.
Transaction history strategies and response packages/komodo_defi_rpc_methods/lib/src/rpc_methods/transaction_history/my_tx_history.dart, packages/komodo_defi_sdk/lib/src/transaction_history/strategies/etherscan_transaction_history_strategy.dart, .../zhtlc_transaction_strategy.dart, .../transaction_history_strategies.dart, packages/komodo_defi_types/lib/src/transactions/transaction_history_strategy.dart	MyTxHistoryResponse gains pagingOptions; Etherscan strategy populates pagingOptions; ZHTLC strategy supports transaction-based pagination and refactors request param handling; factory allows injecting strategies; removes a legacy pagination helper in types.
Tests and fixtures packages/komodo_defi_rpc_methods/test/fixtures/orderbook/orderbook_response.json, .../test/src/common_structures/orderbook/order_info_test.dart, packages/komodo_defi_sdk/test/transaction_history/transaction_history_strategies_test.dart	Adds comprehensive orderbook fixture; tests OrderInfo parsing/round-trip; tests strategy selection prioritizing ZHTLC and order independence.
UI tweak packages/komodo_ui/lib/src/defi/withdraw/source_address_field.dart	Changes loading text color source from colorScheme.onSurface to textTheme.bodyMedium?.color with same alpha application.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor UI
  participant Factory as TransactionHistoryStrategyFactory
  participant Strategy as Strategy (V2/Legacy/Etherscan/ZHTLC)
  participant RPC as RPC / Provider

  UI->>Factory: forAsset(asset, auth, pubkeyManager)
  Factory-->>UI: Strategy instance

  UI->>Strategy: fetchTransactionHistory(pagination, limit)
  alt Page-based
    Strategy->>RPC: getHistory(limit, page=pageNumber)
    RPC-->>Strategy: txs
    Strategy-->>UI: MyTxHistoryResponse(txs, pagingOptions: {page_number})
  else Transaction-based
    Strategy->>RPC: getHistory(limit, from_id)
    RPC-->>Strategy: txs
    Strategy-->>UI: MyTxHistoryResponse(txs, pagingOptions: {from_id})
  else Unsupported
    Strategy-->>UI: throw UnsupportedError
  end

Loading

sequenceDiagram
  autonumber
  participant Net as RPC Orderbook JSON
  participant Parser as OrderInfo.fromJson
  participant Sub as NumericValue / OrderAddress / ConfSettings

  Net-->>Parser: order entry JSON (v2 schema)
  Parser->>Sub: parse price/base_*/rel_* as NumericValue
  Parser->>Sub: parse address as OrderAddress(address_type, address_data)
  Parser->>Sub: parse conf_settings
  Sub-->>Parser: typed objects
  Parser-->>Caller: OrderInfo(fields nullable, nested values)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• feat(rpc): trading-related RPCs/types #191 — Also refactors orderbook models and JSON (de)serialization, including numeric/fraction/rational handling, aligning closely with these changes.

Suggested reviewers

• smk762
• CharlVS

Poem

I nibbled the bytes and parsed the grain,
New orders bloom on the data plain.
Pages turn with a gentle hop,
From IDs to numbers—no need to stop.
With whiskered wit and structured cheer,
I ship these changes—spring is here! 🐇✨

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 accurately captures the primary objectives of the pull request by stating the alignment of the orderbook RPC with the KDF schema and the addition of ID-based pagination support, and it uses a clear conventional prefix without extraneous detail. It is concise, specific to the main changes described in the diff summaries, and would be immediately understandable to team members reviewing the commit history.
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

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

[github-actions]

Visit the preview URL for this PR (updated for commit 0b84aab):

https://kdf-sdk--pr229-bugfix-orderbook-rpc-1ins2quq.web.app

_{(expires Sun, 05 Oct 2025 22:53:40 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: 9c1b6e6c010cf0b965c455ba7a69c4aedafa8a1d}

[github-actions]

Visit the preview URL for this PR (updated for commit 0b84aab):

https://komodo-playground--pr229-bugfix-orderbook-rpc-3w3w1ml8.web.app

_{(expires Sun, 05 Oct 2025 22:53:25 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: 2bfedd77fdea45b25ba7c784416e81f177aa5c47}

[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 aligns the ZHTLC orderbook RPC implementation with the KDF schema and adds support for ID-based pagination. The changes include:

• Enhanced pagination support for ZHTLC transactions with ID-based pagination
• Updated orderbook schema to match KDF format with structured address and numeric value types
• Improved JSON type conversion utilities and added comprehensive test coverage

Reviewed Changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
source_address_field.dart	UI color theme fix for text styling
json_type_utils.dart	Added safe int-to-string conversion for JSON parsing
transaction_history_strategy.dart	Removed unused legacy pagination helper method
transaction_history_strategies_test.dart	Added comprehensive test coverage for ZHTLC strategy selection
transaction_history_strategies.dart	Added configurable strategy injection and improved error message formatting
zhtlc_transaction_strategy.dart	Enhanced pagination support with ID-based pagination for ZHTLC
etherscan_transaction_history_strategy.dart	Added pagination options field to response structure
order_info_test.dart	Added comprehensive tests for orderbook schema parsing
orderbook_response.json	Added test fixture for orderbook API responses
my_tx_history.dart	Added pagination options field to transaction history response
numeric_value.dart	Implemented complete numeric value structure for KDF schema alignment
pagination.dart	Added JSON parsing support for pagination parameters
order_info.dart	Complete rewrite to match KDF orderbook schema
order_address.dart	Added structured address type for orderbook entries

---

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

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

packages/komodo_defi_sdk/lib/src/transaction_history/transaction_history_strategies.dart (1)

13-20: Freeze the strategy list to avoid aliasing surprises.

Right now _strategies holds a directly passed-in list, so anyone keeping that reference can mutate the factory’s internals after construction. Wrapping the source in List.unmodifiable(...) would lock the roster down while still allowing custom injection.

Consider:

-  }) : _strategies =
-           strategies ??
-           [
-             EtherscanTransactionStrategy(pubkeyManager: pubkeyManager),
-             V2TransactionStrategy(auth),
-             const LegacyTransactionStrategy(),
-             const ZhtlcTransactionStrategy(),
-           ];
+  }) : _strategies = List.unmodifiable(
+          strategies ??
+              [
+                EtherscanTransactionStrategy(pubkeyManager: pubkeyManager),
+                V2TransactionStrategy(auth),
+                const LegacyTransactionStrategy(),
+                const ZhtlcTransactionStrategy(),
+              ],
+        );

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8626160 and a353d06.

📒 Files selected for processing (14)

• packages/komodo_defi_rpc_methods/lib/src/common_structures/orderbook/order_address.dart (1 hunks)
• packages/komodo_defi_rpc_methods/lib/src/common_structures/orderbook/order_info.dart (1 hunks)
• packages/komodo_defi_rpc_methods/lib/src/common_structures/pagination/pagination.dart (1 hunks)
• packages/komodo_defi_rpc_methods/lib/src/common_structures/primitive/numeric_value.dart (1 hunks)
• packages/komodo_defi_rpc_methods/lib/src/rpc_methods/transaction_history/my_tx_history.dart (5 hunks)
• packages/komodo_defi_rpc_methods/test/fixtures/orderbook/orderbook_response.json (1 hunks)
• packages/komodo_defi_rpc_methods/test/src/common_structures/orderbook/order_info_test.dart (1 hunks)
• packages/komodo_defi_sdk/lib/src/transaction_history/strategies/etherscan_transaction_history_strategy.dart (1 hunks)
• packages/komodo_defi_sdk/lib/src/transaction_history/strategies/zhtlc_transaction_strategy.dart (2 hunks)
• packages/komodo_defi_sdk/lib/src/transaction_history/transaction_history_strategies.dart (6 hunks)
• packages/komodo_defi_sdk/test/transaction_history/transaction_history_strategies_test.dart (1 hunks)
• packages/komodo_defi_types/lib/src/transactions/transaction_history_strategy.dart (0 hunks)
• packages/komodo_defi_types/lib/src/utils/json_type_utils.dart (1 hunks)
• packages/komodo_ui/lib/src/defi/withdraw/source_address_field.dart (1 hunks)

💤 Files with no reviewable changes (1)

• packages/komodo_defi_types/lib/src/transactions/transaction_history_strategy.dart

🔇 Additional comments (4)

packages/komodo_defi_types/lib/src/utils/json_type_utils.dart (1)

129-134: Solid int-to-string handling

Thanks for adding the exact int→String path; it removes the need for lossy casting while keeping the behavior deterministic.

packages/komodo_defi_sdk/lib/src/transaction_history/strategies/etherscan_transaction_history_strategy.dart (1)

113-117: Paging metadata mirrors incoming request cleanly.

Good call echoing the active pagination mode back through pagingOptions; it keeps the response aligned with the new schema without disturbing the existing sorting/paging flow.

packages/komodo_defi_sdk/lib/src/transaction_history/strategies/zhtlc_transaction_strategy.dart (1)

21-34: Unified pagination handling reads well.

The record-based switch keeps both page- and id-based flows compact and makes the downstream RPC call much clearer.

packages/komodo_defi_rpc_methods/lib/src/common_structures/orderbook/order_info.dart (1)

125-139: Confirm SDK constraint for null-aware map entries.

These map literals rely on the Dart 3.8+ null-aware element syntax ('key': ?value). Please double-check that the package’s environment.sdk constraint (and any package-level language version overrides) already guarantee Dart ≥3.8 so this compiles everywhere we publish or consume it. If not, we should bump the constraint in the relevant pubspecs before merging.