ickb · phroi · Feb 22, 2026 · Feb 20, 2026 · Feb 20, 2026 · Feb 21, 2026
diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml
@@ -24,7 +24,7 @@ jobs:
       - uses: pnpm/action-setup@v4
 
       - name: Install dependencies
-        run: pnpm build:prepare
+        run: pnpm install
       - name: Build
         run: pnpm build
 

diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md
@@ -0,0 +1,82 @@
+# iCKB Stack v2
+
+## What This Is
+
+A CCC-based TypeScript library suite and reference apps for interacting with the on-chain iCKB protocol (NervosDAO liquidity via pooled deposits and iCKB xUDT tokens). The library packages (`@ickb/utils`, `@ickb/dao`, `@ickb/order`, `@ickb/core`, `@ickb/sdk`) provide the building blocks; the apps (`bot`, `interface`, `faucet`, `sampler`, `tester`) demonstrate usage and run protocol operations.
+
+## 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.
+
+## Requirements
+
+### Validated
+
+<!-- Shipped and confirmed valuable. -->
+
+- ✓ CCC-based package structure (`@ickb/utils`, `@ickb/dao`, `@ickb/order`, `@ickb/core`, `@ickb/sdk`) — existing
+- ✓ Manager pattern with `ScriptDeps` interface for composability — existing
+- ✓ Async generator cell discovery with lazy evaluation — existing
+- ✓ Molecule codec integration with CCC's `mol.union`, `ccc.Entity.Base`, `@ccc.codec` — existing
+- ✓ Epoch class adopted from CCC (local Epoch deleted) — existing
+- ✓ Faucet and sampler apps migrated to CCC — existing
+
+### Active
+
+- [ ] Remove SmartTransaction — replace with `ccc.Transaction` + utility functions
+- [ ] Adopt CCC UDT handling — investigate subclassing `Udt` for iCKB's multi-representation value (xUDT + receipts + deposits)
+- [ ] Systematic CCC alignment audit — replace local utilities with CCC equivalents from merged upstream PRs
+- [ ] Migrate bot app from Lumos to CCC + new packages
+- [ ] Migrate interface app from Lumos to CCC + new packages (straight swap, same UI)
+- [ ] Migrate tester app from Lumos to CCC + new packages
+- [ ] Remove all Lumos dependencies (`@ckb-lumos/*`, `@ickb/lumos-utils`, `@ickb/v1-core`)
+- [ ] Clean APIs suitable for npm publication
+- [ ] Identify reusable patterns that could become CCC upstream PRs
+- [ ] Track CCC PR #328 (FeePayer) — potential CCC-native replacement for SmartTransaction's fee/balancing role
+
+### Out of Scope
+
+- UI/UX redesign for interface app — straight migration only
+- New reference/example apps — existing apps serve as reference
+- On-chain contract changes — contracts are immutable and non-upgradable
+- Mobile app — web-first
+- CCC framework changes — we adopt CCC, not fork it (PRs go upstream)
+
+## Context
+
+**Protocol:** iCKB tokenizes NervosDAO deposits. CKB deposited into NervosDAO is locked for ~30 days. iCKB represents that locked value as a liquid xUDT token. Key invariant: `Input UDT + Input Receipts = Output UDT + Input Deposits`. All contracts are deployed with zero-args locks (immutable, trustless).
+
+**iCKB UDT particularity:** iCKB value has three on-chain representations: (1) xUDT tokens (standard UDT), (2) receipt cells (pending conversion), (3) DAO deposit cells (locked CKB). CCC's `Udt` class only understands form (1). The relationship between all three forms is governed by the conservation law enforced by the `ickb_logic` type script. This makes CCC UDT adoption non-trivial — subclassing `Udt` to account for all three representations is a key design investigation.
+
+**SmartTransaction history:** `SmartTransaction` extends `ccc.Transaction` with UDT handler management and fee/change completion. The concept was proposed as an ecosystem-wide pattern but abandoned due to no adoption from CCC maintainers or other projects. The class itself still works and is used by all 5 library packages. Replacement: utility functions operating on plain `ccc.Transaction`.
+
+**CCC upstream contributions:** 12 PRs authored by this project's maintainer have been merged into CCC, covering: `shouldAddInputs` for completeFee (#225), `findCellsOnChain` (#258), auto capacity completion (#259), optimized completeFee (#260), UDT balance utilities (#228), multiple scripts for SignerCkbScriptReadonly (#265), `CellAny` type (#262), `reduce`/`reduceAsync` (#267), fixed-size mol union (#174), Epoch class (#314), UDT info querying (#261), `bytesLen`/`bytesLenUnsafe` (#353). PR #328 (FeePayer abstraction) is still open.
+
+**Local utility overlap with CCC core:** Several local utilities now have CCC equivalents that should be adopted: `gcd()`, `isHex()`, `hexFrom()`, `max()`/`min()` (use `numMax`/`numMin`). Utilities unique to iCKB (no CCC equivalent): `binarySearch()`, `asyncBinarySearch()`, `shuffle()`, `unique()`, `collect()`, `BufferedGenerator`, `MinHeap`.
+
+**Migration status:** Library packages are on CCC. Apps split: faucet/sampler already migrated; bot/interface/tester still on legacy Lumos (`@ckb-lumos/*`, `@ickb/lumos-utils@1.4.2`, `@ickb/v1-core@1.4.2`).
+
+**Local CCC dev build:** `ccc-dev/` supports using local CCC builds for testing. `.pnpmfile.cjs` transparently rewires `@ckb-ccc/*` to local packages. `ccc-dev/patch.sh` rewrites exports to `.ts` source. This enables testing upstream changes before they're published.
+
+## Constraints
+
+- **On-chain contracts**: Immutable — library must match existing contract behavior exactly
+- **CCC compatibility**: Must work with `@ckb-ccc/core ^1.12.2` (catalog-pinned)
+- **Node.js**: >= 24 (enforced via engines)
+- **Package manager**: pnpm 10.30.1 (pinned with SHA-512)
+- **TypeScript**: Strict mode with `noUncheckedIndexedAccess`, `verbatimModuleSyntax`, `noImplicitOverride`
+- **Versioning**: All packages use `1001.0.0` (Epoch Semantic Versioning), managed by changesets
+- **Publishing**: npm with `access: public` and `provenance: true`
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Remove SmartTransaction, use ccc.Transaction directly | SmartTransaction concept abandoned by ecosystem, no adoption from CCC maintainers | — Pending |
+| Investigate CCC Udt subclassing for iCKB | iCKB value is multi-representation (xUDT + receipts + deposits); need to determine if CCC's Udt can be extended | — Pending |
+| Library refactor before app migration | Clean packages first, then migrate apps on stable foundation | — Pending |
+| Interface app: straight migration only | No UI/UX redesign — swap Lumos internals for CCC packages | — Pending |
+| Track CCC PR #328 (FeePayer) | Could become CCC-native solution for what SmartTransaction does for fee completion | — Pending |
+
+---
+*Last updated: 2026-02-20 after initialization*
diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md
@@ -0,0 +1,112 @@
+# Requirements: iCKB Stack v2
+
+**Defined:** 2026-02-21
+**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.
+
+## v1 Requirements
+
+Requirements for initial milestone. Each maps to roadmap phases.
+
+### SmartTransaction Removal
+
+- [ ] **SMTX-01**: All manager methods (`DaoManager`, `OrderManager`, `LogicManager`, `OwnedOwnerManager`, `CapacityManager`, `UdtManager`, `IckbUdtManager`) accept `ccc.Transaction` instead of `SmartTransaction`
+- [ ] **SMTX-02**: `SmartTransaction` class and its `completeFee()` override are deleted from `@ickb/utils`
+- [ ] **SMTX-03**: Fee completion uses CCC-native `ccc.Transaction.completeFeeBy()` or `completeFeeChangeToLock()` with DAO-aware capacity calculation
+- [ ] **SMTX-04**: Header caching delegates to `ccc.Client.cache` instead of `SmartTransaction.headers` map
+- [ ] **SMTX-05**: UDT handler registration (`addUdtHandlers()`) is replaced by direct `Udt` instance usage or standalone utility functions
+- [ ] **SMTX-06**: 64-output NervosDAO limit check is consolidated into a single utility function (currently scattered across 6 locations)
+- [ ] **SMTX-07**: `IckbUdtManager` multi-representation UDT balance logic (xUDT + receipts + deposits) survives removal intact -- conservation law `Input UDT + Input Receipts = Output UDT + Input Deposits` is preserved
+- [ ] **SMTX-08**: `IckbSdk.estimate()` and `IckbSdk.maturity()` continue working after SmartTransaction removal
+- [ ] **SMTX-09**: All 5 library packages (`@ickb/utils`, `@ickb/dao`, `@ickb/order`, `@ickb/core`, `@ickb/sdk`) compile and pass type checking after removal
+- [ ] **SMTX-10**: Deprecated CCC API calls (`udtBalanceFrom`, `getInputsUdtBalance`, `getOutputsUdtBalance`, `completeInputsByUdt`) are replaced with `@ckb-ccc/udt` equivalents
+
+### 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
+
+### CCC Udt Integration
+
+- [ ] **UDT-01**: Feasibility assessment completed: can `IckbUdt extends udt.Udt` override `infoFrom()` or `getInputsInfo()`/`getOutputsInfo()` to account for receipt cells and deposit cells alongside xUDT cells
+- [ ] **UDT-02**: Header access pattern for receipt value calculation is designed -- determine whether `client.getCellWithHeader()`, `client.getHeaderByTxHash()`, or the existing `getHeader()` pattern is used within the Udt override
+- [ ] **UDT-03**: Decision documented: subclass CCC `Udt` vs. keep custom `UdtHandler` interface vs. hybrid approach
+- [ ] **UDT-04**: If subclassing is viable, `IckbUdt` class is implemented in `@ickb/core` with multi-representation balance calculation
+- [ ] **UDT-05**: If subclassing is not viable, `IckbUdtManager` is refactored to work with plain `ccc.Transaction` (no SmartTransaction dependency) while maintaining a compatible interface
+
+## v2 Requirements
+
+Deferred to next milestone. Tracked but not in current roadmap.
+
+### API & Publication
+
+- **API-01**: Clean public API surface -- audit all `export *` barrel files, mark internal symbols with `@internal`
+- **API-02**: npm publication with provenance -- publish updated packages after API audit
+- **API-03**: Type export audit -- ensure `.d.ts` correctness, no `any` leaks in public API
+
+### App Migration
+
+- **APP-01**: Bot app migrated from Lumos to CCC + new library packages
+- **APP-02**: Interface app migrated from Lumos to CCC + new library packages (straight swap, same UI)
+- **APP-03**: Tester app migrated from Lumos to CCC + new library packages
+
+### Ecosystem Cleanup
+
+- **CLEAN-01**: Complete Lumos removal -- remove all `@ckb-lumos/*`, `@ickb/lumos-utils`, `@ickb/v1-core` dependencies
+- **CLEAN-02**: Upstream CCC contribution -- identify reusable patterns for CCC PRs
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep.
+
+| Feature | Reason |
+|---------|--------|
+| UI/UX redesign for interface app | Straight migration only -- conflates concerns, delays migration |
+| New reference/example apps | Existing 5 apps already demonstrate all library capabilities |
+| On-chain contract changes | All contracts deployed with zero-args locks (immutable, non-upgradable) |
+| Mobile app | Web-first, web-only for now |
+| CCC framework fork | We adopt CCC, not fork it -- PRs go upstream |
+| Custom Molecule codec library | CCC already provides `mol.*` -- custom codecs duplicate effort |
+| Custom blockchain indexer | CCC's `findCells`/`findCellsOnChain` covers all current needs |
+| Multi-chain / L2 token bridging | Separate concern requiring different architecture |
+| Embedded wallet/signer management | CCC provides comprehensive signer abstraction |
+| Database/state persistence layer | All state is on-chain -- database creates stale-state problems |
+| SmartTransaction as ecosystem standard | Abandoned by CCC maintainers and broader ecosystem |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| SMTX-01 | Phase 5 | Pending |
+| SMTX-02 | Phase 1 | Pending |
+| SMTX-03 | Phase 6 | Pending |
+| SMTX-04 | Phase 1 | Pending |
+| SMTX-05 | Phase 4 | Pending |
+| SMTX-06 | Phase 1 | Pending |
+| SMTX-07 | Phase 5 | Pending |
+| SMTX-08 | Phase 6 | Pending |
+| SMTX-09 | Phase 7 | Pending |
+| SMTX-10 | Phase 4 | Pending |
+| 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 |
+| UDT-01 | Phase 3 | Pending |
+| UDT-02 | Phase 3 | Pending |
+| UDT-03 | Phase 3 | Pending |
+| UDT-04 | Phase 5 | Pending |
+| UDT-05 | Phase 5 | Pending |
+
+**Coverage:**
+- v1 requirements: 20 total
+- Mapped to phases: 20
+- Unmapped: 0
+
+---
+*Requirements defined: 2026-02-21*
+*Last updated: 2026-02-21 after roadmap creation*