refactor: replace local utility functions with CCC equivalents

.changeset/remove-local-utility-functions.md

@@ -0,0 +1,14 @@
+---
+"@ickb/utils": major
+"@ickb/order": patch
+"@ickb/sdk": patch
+---
+
+Remove local max, min, gcd, hexFrom, isHex utility functions -- replaced by CCC equivalents
+
+- Delete `max`, `min`, `gcd`, `hexFrom`, `isHex` from `@ickb/utils` public API
+- Replace `max()` call sites with `Math.max()` in `@ickb/order` and `@ickb/sdk`
+- Replace `gcd()` call site with `ccc.gcd()` in `@ickb/order`
+- Replace `hexFrom(entity)` call sites with `entity.toHex()` in `@ickb/order` and `@ickb/sdk`
+- Replace `hexFrom(bytes)` call site with `ccc.hexFrom()` in faucet app
+- Update `unique()` internal implementation to use `entity.toHex()` instead of local `hexFrom()`

.planning/REQUIREMENTS.md

@@ -22,11 +22,11 @@ Requirements for initial milestone. Each maps to roadmap phases.
 
 ### CCC Utility Deduplication
 
-- [ ] **DEDUP-01**: Local `max()` / `min()` replaced with `ccc.numMax()` / `ccc.numMin()` across all packages
-- [ ] **DEDUP-02**: Local `gcd()` replaced with `ccc.gcd()` across all packages
-- [ ] **DEDUP-03**: Local `isHex()` replaced with `ccc.isHex()` in `@ickb/utils`
-- [ ] **DEDUP-04**: Local `hexFrom()` refactored to explicit calls -- CCC's `hexFrom()` only handles `HexLike` (not `bigint | Entity`), so call sites should use `ccc.numToHex()` for bigint and `ccc.hexFrom(entity.toBytes())` for entities (per STACK.md evaluation)
-- [ ] **DEDUP-05**: iCKB-unique utilities (`binarySearch`, `asyncBinarySearch`, `shuffle`, `unique`, `collect`, `BufferedGenerator`, `MinHeap`) are preserved unchanged
+- [x] **DEDUP-01**: Local `max()` / `min()` replaced across all packages -- `Math.max()`/`Math.min()` for number-typed contexts (avoids unnecessary `number→bigint→number` round-trips via `ccc.numMax()`)
+- [x] **DEDUP-02**: Local `gcd()` replaced with `ccc.gcd()` across all packages
+- [x] **DEDUP-03**: Local `isHex()` replaced with `ccc.isHex()` in `@ickb/utils`
+- [x] **DEDUP-04**: Local `hexFrom()` refactored to explicit calls -- CCC's `hexFrom()` only handles `HexLike` (not `bigint | Entity`), so call sites should use `ccc.numToHex()` for bigint and `ccc.hexFrom(entity.toBytes())` for entities (per STACK.md evaluation)
+- [x] **DEDUP-05**: iCKB-unique utilities (`binarySearch`, `asyncBinarySearch`, `shuffle`, `unique`, `collect`, `BufferedGenerator`, `MinHeap`) are preserved unchanged
 
 ### CCC Udt Integration
 
@@ -91,11 +91,11 @@ Which phases cover which requirements. Updated during roadmap creation.
 | SMTX-08 | Phase 6 | Pending | |
 | SMTX-09 | Phase 7 | Pending | |
 | SMTX-10 | Phase 4, 5 | Pending | Deprecated calls in dao/order (Phase 4) and core (Phase 5) |
-| DEDUP-01 | Phase 2 | Pending | |
-| DEDUP-02 | Phase 2 | Pending | |
-| DEDUP-03 | Phase 2 | Pending | |
-| DEDUP-04 | Phase 2 | Pending | |
-| DEDUP-05 | Phase 2 | Pending | |
+| DEDUP-01 | Phase 2 | Complete | max()/min() replaced with Math.max()/Math.min() for number-typed contexts, local deleted (02-01) |
+| DEDUP-02 | Phase 2 | Complete | gcd() replaced with ccc.gcd(), local deleted (02-01) |
+| DEDUP-03 | Phase 2 | Complete | isHex() deleted, only used internally by deleted hexFrom() (02-01) |
+| DEDUP-04 | Phase 2 | Complete | hexFrom() call sites use entity.toHex() or ccc.hexFrom(), local deleted (02-01) |
+| DEDUP-05 | Phase 2 | Complete | All 8 iCKB-unique utilities preserved unchanged (02-01) |
 | UDT-01 | Phase 3 | Pending | |
 | UDT-02 | Phase 3 | Pending | |
 | UDT-03 | Phase 3 | Pending | |
@@ -109,4 +109,4 @@ Which phases cover which requirements. Updated during roadmap creation.
 
 ---
 *Requirements defined: 2026-02-21*
-*Last updated: 2026-02-22 after 01-03 execution (SMTX-01, SMTX-02, SMTX-05 completed; Phase 1 complete)*
+*Last updated: 2026-02-23 after 02-01 execution (DEDUP-01 through DEDUP-05 completed; Phase 2 complete)*

.planning/ROADMAP.md

@@ -13,7 +13,7 @@ This roadmap delivers the v1 milestone: removing the abandoned SmartTransaction
 Decimal phases appear between their surrounding integers in numeric order.
 
 - [x] **Phase 1: SmartTransaction Removal (feature-slice)** - Delete SmartTransaction class and infrastructure across all packages; contribute 64-output DAO limit check to CCC core; migrate all method signatures to ccc.TransactionLike
-- [ ] **Phase 2: CCC Utility Adoption** - Replace local utility functions that duplicate CCC equivalents across all packages; preserve iCKB-unique utilities
+- [x] **Phase 2: CCC Utility Adoption** - Replace local utility functions that duplicate CCC equivalents across all packages; preserve iCKB-unique utilities
 - [ ] **Phase 3: CCC Udt Integration Investigation** - Assess feasibility of subclassing CCC's Udt class for iCKB's multi-representation value; design header access pattern; document decision
 - [ ] **Phase 4: Deprecated CCC API Replacement** - Replace deprecated CCC API calls (`udtBalanceFrom`, etc.) with `@ckb-ccc/udt` equivalents in dao and order packages; finalize UDT handler replacement pattern based on Phase 3 findings
 - [ ] **Phase 5: @ickb/core UDT Refactor** - Implement IckbUdt class or refactor IckbUdtManager based on Phase 3 findings; preserve iCKB conservation law; replace deprecated CCC API calls in core
@@ -45,16 +45,15 @@ Plans:
 **Depends on**: Phase 1
 **Requirements**: DEDUP-01, DEDUP-02, DEDUP-03, DEDUP-04, DEDUP-05
 **Success Criteria** (what must be TRUE):
-  1. All call sites using local `max()`/`min()` now use `ccc.numMax()`/`ccc.numMin()` and the local implementations are deleted
+  1. All call sites using local `max()`/`min()` now use `Math.max()`/`Math.min()` (number-typed contexts) and the local implementations are deleted
   2. All call sites using local `gcd()` now use `ccc.gcd()` and the local implementation is deleted
   3. Local `isHex()` in `@ickb/utils` is replaced with `ccc.isHex()`
   4. Local `hexFrom()` call sites are refactored to explicit calls: `ccc.numToHex()` for bigint and `ccc.hexFrom(entity.toBytes())` for entities (CCC's `hexFrom()` only handles `HexLike`, not `bigint | Entity`)
   5. iCKB-unique utilities (`binarySearch`, `asyncBinarySearch`, `shuffle`, `unique`, `collect`, `BufferedGenerator`, `MinHeap`) remain in `@ickb/utils` unchanged
-**Plans**: TBD
+**Plans**: 1 plan
 
 Plans:
-- [ ] 02-01: TBD
-- [ ] 02-02: TBD
+- [x] 02-01-PLAN.md — Replace local max/min/gcd/hexFrom/isHex with CCC equivalents, delete local implementations, preserve iCKB-unique utilities
 
 ### Phase 3: CCC Udt Integration Investigation
 **Goal**: Clear, documented decision on whether IckbUdt should extend CCC's `udt.Udt` class for iCKB's multi-representation value (xUDT + receipts + deposits), with the header access pattern designed. This decision determines the replacement for UdtHandler/UdtManager (which remain in `@ickb/utils` with updated signatures after Phase 1).
@@ -139,7 +138,7 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7
 | Phase | Plans Complete | Status | Completed |
 |-------|----------------|--------|-----------|
 | 1. SmartTransaction Removal (feature-slice) | 3/3 | Complete    | 2026-02-22 |
-| 2. CCC Utility Adoption | 0/2 | Not started | - |
+| 2. CCC Utility Adoption | 1/1 | Complete    | 2026-02-23 |
 | 3. CCC Udt Integration Investigation | 0/2 | Not started | - |
 | 4. Deprecated CCC API Replacement | 0/2 | Not started | - |
 | 5. @ickb/core UDT Refactor | 0/3 | Not started | - |

.planning/STATE.md

@@ -5,32 +5,33 @@
 See: .planning/PROJECT.md (updated 2026-02-20)
 
 **Core value:** Clean, CCC-aligned library packages published to npm that frontends can depend on to interact with iCKB contracts -- no Lumos, no abandoned abstractions, no duplicated functionality with CCC.
-**Current focus:** Phase 1: SmartTransaction Removal (feature-slice)
+**Current focus:** Phase 2: CCC Utility Adoption
 
 ## Current Position
 
-Phase: 1 of 7 (SmartTransaction Removal -- feature-slice)
-Plan: 3 of 3 in current phase (phase complete)
-Status: Phase 01 complete, ready for phase 02
-Last activity: 2026-02-22 -- Plan 01-03 executed (SmartTransaction/CapacityManager deletion)
+Phase: 2 of 7 (CCC Utility Adoption)
+Plan: 1 of 1 in current phase (phase complete)
+Status: Phase 02 complete, ready for phase 03
+Last activity: 2026-02-23 -- Plan 02-01 executed (local utility functions replaced with CCC equivalents)
 
-Progress: [██░░░░░░░░] 15%
+Progress: [███░░░░░░░] 25%
 
 ## Performance Metrics
 
 **Velocity:**
-- Total plans completed: 3
-- Average duration: ~17min
-- Total execution time: 0.9 hours
+- Total plans completed: 4
+- Average duration: ~15min
+- Total execution time: 1.0 hours
 
 **By Phase:**
 
 | Phase | Plans | Total | Avg/Plan |
 |-------|-------|-------|----------|
 | 01 | 3/3 | 52min | 17min |
+| 02 | 1/1 | 7min | 7min |
 
 **Recent Trend:**
-- Last 5 plans: 01-01 (~30min), 01-02 (~6min), 01-03 (~16min)
+- Last 5 plans: 01-01 (~30min), 01-02 (~6min), 01-03 (~16min), 02-01 (~7min)
 - Trend: accelerating
 
 *Updated after each plan completion*
@@ -58,6 +59,8 @@ Recent decisions affecting current work:
 - [01-03]: Replaced addUdtHandlers with tx.addCellDeps(this.udtHandler.cellDeps) across all packages
 - [01-03]: SmartTransaction class and CapacityManager class fully deleted from @ickb/utils
 - [01-03]: SDK getCkb() uses direct client.findCellsOnChain instead of CapacityManager
+- [02-01]: Used Math.max() over Number(ccc.numMax()) for number-typed contexts to avoid unnecessary number→bigint→number round-trips
+- [02-01]: Used entity.toHex() for Entity args, ccc.hexFrom() for BytesLike args -- matching CCC's type-safe separation
 
 ### Pending Todos
 
@@ -70,6 +73,6 @@ None yet.
 
 ## Session Continuity
 
-Last session: 2026-02-22
-Stopped at: Completed 01-03-PLAN.md (Phase 01 complete)
-Resume file: .planning/phases/01-ickb-utils-smarttransaction-removal/01-03-SUMMARY.md
+Last session: 2026-02-23
+Stopped at: Completed 02-01-PLAN.md (Phase 02 complete)
+Resume file: .planning/phases/02-ccc-utility-adoption/02-01-SUMMARY.md

.planning/phases/02-ccc-utility-adoption/02-01-PLAN.md

@@ -0,0 +1,186 @@
+---
+phase: 02-ccc-utility-adoption
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - packages/utils/src/utils.ts
+  - packages/order/src/entities.ts
+  - packages/sdk/src/codec.ts
+  - packages/order/src/order.ts
+  - packages/sdk/src/sdk.ts
+  - apps/faucet/src/main.ts
+autonomous: true
+requirements:
+  - DEDUP-01
+  - DEDUP-02
+  - DEDUP-03
+  - DEDUP-04
+  - DEDUP-05
+
+must_haves:
+  truths:
+    - "All call sites using local max()/min() now use Math.max()/Math.min() (number-typed contexts) and the local implementations are deleted"
+    - "The single gcd() call site uses ccc.gcd() and the local implementation is deleted"
+    - "Local isHex() and hexFrom() are deleted from @ickb/utils"
+    - "All hexFrom() call sites use entity.toHex() for Entity args and ccc.hexFrom() for BytesLike args"
+    - "iCKB-unique utilities (binarySearch, asyncBinarySearch, shuffle, unique, collect, BufferedGenerator, MinHeap, sum) remain in @ickb/utils unchanged in signature"
+    - "unique() internal implementation updated from hexFrom(i) to i.toHex()"
+    - "pnpm check:full passes with zero errors"
+  artifacts:
+    - path: "packages/utils/src/utils.ts"
+      provides: "Utility module with local max/min/gcd/hexFrom/isHex deleted, unique() updated"
+      contains: "i.toHex()"
+    - path: "packages/order/src/entities.ts"
+      provides: "Order entities with CCC utility calls"
+      contains: "ccc.gcd"
+    - path: "packages/sdk/src/codec.ts"
+      provides: "SDK codec with Math.max replacing local max"
+      contains: "Math.max"
+  key_links:
+    - from: "packages/order/src/entities.ts"
+      to: "@ckb-ccc/core"
+      via: "ccc.gcd() call; Math.max() for number-typed max"
+      pattern: "ccc\\.gcd|Math\\.max"
+    - from: "packages/sdk/src/codec.ts"
+      to: "@ckb-ccc/core"
+      via: "Math.max() replacing local max (number-typed context)"
+      pattern: "Math\\.max"
+    - from: "packages/utils/src/utils.ts"
+      to: "@ckb-ccc/core"
+      via: "unique() uses entity.toHex() instead of deleted hexFrom()"
+      pattern: "i\\.toHex\\(\\)"
+---
+
+<objective>
+Replace five local utility functions (max, min, gcd, hexFrom, isHex) in @ickb/utils with their CCC equivalents at all call sites, update the unique() internal implementation, delete the local function definitions, and verify iCKB-unique utilities remain intact.
+
+Purpose: Eliminate duplicated functionality with CCC core -- local copies diverge over time and create maintenance burden.
+Output: All packages and apps compile cleanly with CCC utility calls instead of local wrappers.
+</objective>
+
+<execution_context>
+@/home/node/.claude/get-shit-done/workflows/execute-plan.md
+@/home/node/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/02-ccc-utility-adoption/02-RESEARCH.md
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Replace all external call sites with CCC equivalents</name>
+  <files>
+    packages/order/src/entities.ts
+    packages/sdk/src/codec.ts
+    packages/order/src/order.ts
+    packages/sdk/src/sdk.ts
+    apps/faucet/src/main.ts
+  </files>
+  <action>
+Replace every external call site of the five local utility functions with CCC equivalents. The exact replacements are:
+
+**max() -- 2 call sites (DEDUP-01):**
+1. `packages/order/src/entities.ts` line ~172: `max(aScale.toString(2).length, bScale.toString(2).length)` becomes `Math.max(aScale.toString(2).length, bScale.toString(2).length)`. Remove `max` from the `@ickb/utils` import.
+2. `packages/sdk/src/codec.ts` line ~80: `max(1, ...bins)` becomes `Math.max(1, ...bins)`. Remove `max` from the `@ickb/utils` import (this may make the import empty or removable).
+
+**gcd() -- 1 call site (DEDUP-02):**
+1. `packages/order/src/entities.ts` line ~167: `gcd(aScale, bScale)` becomes `ccc.gcd(aScale, bScale)`. Remove `gcd` from the `@ickb/utils` import. Note: CCC's gcd returns `Num` (bigint), same type as current usage -- direct drop-in.
+
+**hexFrom() -- 5 external call sites (DEDUP-04):**
+1. `packages/sdk/src/sdk.ts` line ~393: `hexFrom(cell.cellOutput.lock)` becomes `cell.cellOutput.lock.toHex()`. Remove `hexFrom` from the `@ickb/utils` import.
+2. `packages/sdk/src/sdk.ts` line ~423: `hexFrom(wr.owner.cell.cellOutput.lock)` becomes `wr.owner.cell.cellOutput.lock.toHex()`. (Same import fix as above.)
+3. `packages/order/src/order.ts` line ~560: `hexFrom(master.cell.outPoint)` becomes `master.cell.outPoint.toHex()`. Remove `hexFrom` from the `@ickb/utils` import.
+4. `packages/order/src/order.ts` line ~572: `hexFrom(master)` becomes `master.toHex()`. (Same import fix as above.)
+5. `apps/faucet/src/main.ts` line ~20: `hexFrom(getRandomValues(new Uint8Array(32)))` becomes `ccc.hexFrom(getRandomValues(new Uint8Array(32)))`. Remove `hexFrom` from the `@ickb/utils` import. Add `import { ccc } from "@ckb-ccc/core";` if not already present.
+
+After all replacements, clean up imports: remove `max`, `min`, `gcd`, `hexFrom`, `isHex` from all `@ickb/utils` import statements. If an import statement becomes empty, delete it entirely. If it still has other symbols (e.g., `CheckedInt32LE`, `unique`, `sum`), keep only those.
+
+IMPORTANT: Use `import type` for type-only imports per `verbatimModuleSyntax`. All functions must have explicit return type annotations per ESLint rules.
+  </action>
+  <verify>
+Run `pnpm -r --filter './packages/**' --filter './apps/faucet' exec tsc --noEmit` to verify all modified packages compile. No import errors for removed symbols.
+  </verify>
+  <done>
+All 8 external call sites (2 max, 1 gcd, 5 hexFrom) replaced with CCC equivalents. Zero references to local max/min/gcd/hexFrom/isHex remain in any file outside packages/utils/src/utils.ts.
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Update unique() internals, delete local functions, generate changeset, and verify</name>
+  <files>
+    packages/utils/src/utils.ts
+  </files>
+  <action>
+**Step 1: Update `unique()` internal call (DEDUP-05 preservation):**
+In `packages/utils/src/utils.ts`, inside the `unique()` function (line ~349), change:
+```typescript
+const key = hexFrom(i);
+```
+to:
+```typescript
+const key = i.toHex();
+```
+The function signature, JSDoc, and external behavior remain identical -- only the internal implementation detail changes. Update the JSDoc to mention `toHex()` instead of `hexFrom` in the description ("based on their hex representation" or similar).
+
+**Step 2: Delete local function definitions (DEDUP-01, DEDUP-02, DEDUP-03, DEDUP-04):**
+Delete these functions and their JSDoc from `packages/utils/src/utils.ts`:
+- `max<T>(res: T, ...rest: T[]): T` (starts at line ~227, ~20 lines including JSDoc)
+- `min<T>(res: T, ...rest: T[]): T` (starts at line ~250, ~20 lines including JSDoc)
+- `gcd(res: bigint, ...rest: bigint[]): bigint` (starts at line ~314, ~18 lines including JSDoc)
+- `hexFrom(v: bigint | ccc.Entity | ccc.BytesLike): ccc.Hex` (starts at line ~357, ~38 lines including JSDoc)
+- `isHex(s: string): s is ccc.Hex` (starts at line ~396, ~30 lines including JSDoc)
+
+Preserve ALL other functions in utils.ts: `binarySearch`, `asyncBinarySearch`, `shuffle`, `unique`, `collect`, `BufferedGenerator`, `MinHeap`, `sum`, and any others. These are iCKB-unique utilities with no CCC equivalents.
+
+**Step 3: Generate changeset:**
+Run `pnpm changeset` non-interactively or create the changeset file manually in `.changeset/`. The changeset should:
+- Mark `@ickb/utils` as a minor change (removing public exports is breaking but project uses Epoch SemVer)
+- Summary: "Remove local max, min, gcd, hexFrom, isHex utility functions -- replaced by CCC equivalents (ccc.numMax, ccc.numMin, ccc.gcd, ccc.hexFrom, ccc.isHex, entity.toHex())"
+
+**Step 4: Full verification:**
+Run `pnpm check:full` to verify the entire build pipeline passes. This wipes derived state and regenerates from scratch, confirming no broken references.
+
+IMPORTANT: Do NOT delete `sum()`. It has no CCC equivalent and must be preserved. Same for all utilities listed in DEDUP-05.
+  </action>
+  <verify>
+1. `grep -rn "export function max\|export function min\|export function gcd\|export function hexFrom\|export function isHex" packages/utils/src/utils.ts` returns zero matches (all five deleted).
+2. `grep -n "export function unique\|export function sum\|export function binarySearch\|export function shuffle\|export function collect\|export class BufferedGenerator\|export class MinHeap" packages/utils/src/utils.ts` returns 7+ matches (all preserved).
+3. `grep -n "i.toHex()" packages/utils/src/utils.ts` returns a match inside `unique()`.
+4. `pnpm check:full` passes with zero errors.
+5. A changeset file exists in `.changeset/` documenting the removal.
+  </verify>
+  <done>
+Local max, min, gcd, hexFrom, isHex are deleted from @ickb/utils. unique() uses entity.toHex() internally. All iCKB-unique utilities preserved. Changeset generated. pnpm check:full passes.
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+1. No references to local `max`, `min`, `gcd`, `hexFrom`, or `isHex` exist as imports from `@ickb/utils` in any file across the repo
+2. All call sites use CCC equivalents or native JS: `Math.max`/`Math.min` (number contexts), `ccc.gcd`, `ccc.hexFrom`, `entity.toHex()`, `ccc.numToHex`, `ccc.isHex`
+3. The five function definitions are deleted from `packages/utils/src/utils.ts`
+4. `unique()` in `packages/utils/src/utils.ts` uses `i.toHex()` internally
+5. All iCKB-unique utilities remain exported from `@ickb/utils`
+6. `pnpm check:full` passes
+7. A changeset entry exists for the breaking API change
+</verification>
+
+<success_criteria>
+- Zero type errors across all 5 library packages and all apps
+- Zero imports of max/min/gcd/hexFrom/isHex from @ickb/utils anywhere in the codebase
+- All 8 external call sites replaced with CCC equivalents per the research inventory
+- iCKB-unique utilities compile and export correctly
+- Changeset generated documenting the removal
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/02-ccc-utility-adoption/02-01-SUMMARY.md`
+</output>