docs: refresh codebase docs for post-phase-1 state

- Update all SmartTransaction/CapacityManager references to note
  deletion in Phase 1 (ARCHITECTURE, CONCERNS, CONVENTIONS)
- Update fork-scripts paths from ccc-fork/*.sh to fork-scripts/*.sh
  (PROJECT, CONCERNS, CONVENTIONS, STACK, STRUCTURE)
- Add fork-scripts/ directory tree and @generated markers (STRUCTURE)
- Mark resolved concerns as RESOLVED (CONCERNS)
- Update code examples to current APIs: findUdts, isUdt, collect
  (CONVENTIONS)
- Update 64-output DAO limit references to CCC core (CONCERNS)

Author: phroi

.planning/PROJECT.md

@@ -56,7 +56,7 @@ Clean, CCC-aligned library packages published to npm that frontends can depend o
 
 **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.
+**Local CCC dev build:** `ccc-fork/` supports using local CCC builds for testing. `.pnpmfile.cjs` transparently rewires `@ckb-ccc/*` to local packages. `fork-scripts/patch.sh` rewrites exports to `.ts` source. This enables testing upstream changes before they're published.
 
 ## Constraints
 

.planning/codebase/ARCHITECTURE.md

@@ -11,7 +11,7 @@
 - Manager-based pattern encapsulating script operations with uniform `ScriptDeps` interface
 - Async-first cell discovery via generator functions with lazy evaluation
 - TypeScript ESM modules with strict null checks and type safety
-- SmartTransaction builder for automatic fee/change calculation
+- CCC-native transaction building with TransactionLike pattern (SmartTransaction deleted in Phase 1)
 - Cell wrapper abstractions extending raw blockchain data with domain logic
 
 **Migration Status:**
@@ -21,7 +21,7 @@
 - Apps split: `faucet` and `sampler` already use new packages; `bot`, `tester`, `interface` still on legacy Lumos
 - CCC PRs for UDT and Epoch support have been MERGED upstream -- local Epoch class has been deleted (replaced by `ccc.Epoch`); some local UDT handling may still overlap with CCC's `@ckb-ccc/udt`
 - Custom `mol.union` codec and deprecated `mol.*` APIs have been replaced with CCC's `mol.union`, `ccc.Entity.Base`, and `@ccc.codec` decorator
-- SmartTransaction was ABANDONED as an ecosystem-wide concept (no adoption), but the class itself remains used locally; headers are now cached in CCC Client Cache
+- SmartTransaction was DELETED in Phase 1; all managers now accept `ccc.TransactionLike` and return `ccc.Transaction` directly; headers cached by CCC Client Cache
 
 ## Protocol Design (from whitepaper)
 
@@ -70,21 +70,22 @@ Receipts convert to UDT; deposits stay as deposits or convert to UDT. No iCKB ca
 
 **Foundation: CCC Framework**
 - Purpose: Provide blockchain primitives and client interface
-- Location: `@ckb-ccc/core` (npm or local `ccc-dev/ccc/`)
+- Location: `@ckb-ccc/core` (npm or local `ccc-fork/ccc/`)
 - Contains: CKB RPC clients, transaction builders, signers, Molecule codec, UDT support, Epoch handling
 - Used by: All packages and applications
 - Note: CCC now includes UDT and Epoch features contributed by this project's maintainer
 
 **Utilities Layer (`packages/utils/src/`)**
-- Purpose: Reusable blockchain primitives and transaction helpers
-- Key exports: `SmartTransaction`, `CapacityManager`, codec/heap utilities, UDT handlers
+- Purpose: Reusable blockchain primitives and UDT handlers
+- Key exports: `UdtManager`, `UdtHandler`, codec/heap utilities
 - Key files:
-  - `transaction.ts` (517 lines): SmartTransaction builder with fee completion and UDT balancing
-  - `capacity.ts` (221 lines): CapacityManager for cell discovery and collection
-  - `udt.ts` (393 lines): UDT token value calculations and handlers
-  - `utils.ts` (458 lines): General utilities (binary search, collectors, script helpers)
+  - `udt.ts` (407 lines): UDT token value calculations and handlers
+  - `utils.ts` (292 lines): General utilities (binary search, collectors, helpers)
+  - `codec.ts` (21 lines): CheckedInt32LE codec
+  - `heap.ts` (175 lines): MinHeap implementation
 - Depends on: `@ckb-ccc/core`
 - Used by: All domain packages
+- Note: `SmartTransaction`, `CapacityManager`, `transaction.ts`, `capacity.ts` were deleted in Phase 1
 
 **Domain Layer - DAO (`packages/dao/src/`)**
 - Purpose: Abstract Nervos DAO operations (deposit, withdraw, requestWithdrawal)
@@ -154,7 +155,7 @@ Receipts convert to UDT; deposits stay as deposits or convert to UDT. No iCKB ca
   - Location: `apps/faucet/src/main.ts` (88 lines), entry via `apps/faucet/src/index.ts`
   - Entry: `main()` async function
   - Pattern: Infinite loop with 2-minute poll interval
-  - Uses: CCC client, CapacityManager, SmartTransaction
+  - Uses: CCC client, ccc.Transaction
   - Flow: Discover faucet funds → transfer to user account → log JSON results
 
   **Sampler (Migrated to CCC):**
@@ -198,7 +199,7 @@ Receipts convert to UDT; deposits stay as deposits or convert to UDT. No iCKB ca
 
 1. User calls `IckbSdk.request(tx, user, info, amounts)` via app
 2. `OrderManager.mint()` creates order cell with `Info` metadata (ratio, direction, fee info)
-3. `SmartTransaction` adds cell deps, outputs, UDT handlers
+3. Transaction adds cell deps, outputs via `tx.addCellDeps()` / `tx.addOutput()`
 4. User signs and broadcasts transaction
 
 **Order Discovery and Matching (Bot Flow):**
@@ -213,7 +214,7 @@ Receipts convert to UDT; deposits stay as deposits or convert to UDT. No iCKB ca
 8. Bot identifies orders where CKB/UDT supply exists for matching
 9. Calls `OrderManager.satisfy()` to process matched orders
 10. Builds transaction with satisfied order cells and input/output witnesses
-11. Completes fees via `SmartTransaction.completeFeeChangeToLock()`
+11. Completes fees via `tx.completeFeeChangeToLock()`
 12. Signs and broadcasts
 
 **Maturity Estimation (Supporting Calculation):**
@@ -241,13 +242,13 @@ Receipts convert to UDT; deposits stay as deposits or convert to UDT. No iCKB ca
 2. Receipt cell minted containing deposit metadata
 3. Bot fetches deposits via `LogicManager.findDeposits()`
 4. After maturity, bot calls `LogicManager.withdraw()` to extract funds
-5. Change cells automatically added by SmartTransaction
+5. Change cells added via CCC fee completion pipeline
 
 **State Management:**
 
 - L1 state: Immutable snapshots fetched per query with configurable refresh intervals
-- Transaction state: Built incrementally via `SmartTransaction.add*` methods
-- UDT balances: Tracked per UDT handler in `SmartTransaction.udtHandlers` map
+- Transaction state: Built incrementally via `ccc.Transaction` methods (`addInput`, `addOutput`, `addCellDeps`)
+- UDT balances: Tracked via `UdtHandler` interface implementations
 - Maturing CKB: Cumulative array sorted by maturity timestamp
 
 ## Key Abstractions
@@ -260,7 +261,7 @@ Receipts convert to UDT; deposits stay as deposits or convert to UDT. No iCKB ca
 
 **Manager Classes (Pattern):**
 - Purpose: Encapsulate entity-specific operations
-- Pattern: Stateless managers with methods that operate on SmartTransaction
+- Pattern: Stateless managers with methods that accept `ccc.TransactionLike` and return `ccc.Transaction`
 - Examples:
   - `DaoManager.deposit(tx, capacities, lock)`: Add DAO deposit cells
   - `OrderManager.mint(tx, user, info, amounts)`: Create order cell
@@ -277,16 +278,12 @@ Receipts convert to UDT; deposits stay as deposits or convert to UDT. No iCKB ca
   - `WithdrawalGroup`: Pairs owned (withdrawal request) + owner cell with value aggregation
 - Construction: Async factories via `daoCellFrom()`, `ickbDepositCellFrom()`, `receiptCellFrom()`
 
-**SmartTransaction (Builder):**
-- Purpose: Extends ccc.Transaction with UDT-aware balancing
-- Pattern: Incremental builder with state accumulation
-- Key state: `inputs`, `outputs`, `outputsData`, `cellDeps`, `headerDeps`, `witnesses`, `udtHandlers` map
-- Automatic operations:
-  - `completeFeeChangeToLock()`: Calculate and add change cells for CKB
-  - `addUdtChange()`: Add change cells for each tracked UDT
-  - `addCellDeps()`: Deduplicate and append cell dependencies
-- Used by: All managers to build transactions atomically
-- Note: The "SmartTransaction" ecosystem concept was ABANDONED (no CKB ecosystem adoption). However, this class is still actively used throughout all new packages. The name is a vestige. Header caching has moved to CCC's Client Cache.
+**Transaction Building (ccc.Transaction):**
+- Purpose: All managers use plain `ccc.Transaction` (SmartTransaction was deleted in Phase 1)
+- Pattern: Managers accept `ccc.TransactionLike` and return `ccc.Transaction` (TransactionLike pattern)
+- Key operations: `tx.addCellDeps()`, `tx.addInput()`, `tx.addOutput()`, `tx.headerDeps.push()`
+- Fee completion: CCC-native `completeFeeBy()` / `completeFeeChangeToLock()` with DAO-aware 64-output limit check (contributed to CCC core)
+- Header caching: Transparently handled by CCC Client Cache (no explicit header map)
 
 **Value Types (Domain Models):**
 - `ValueComponents`: `{ ckbValue: ccc.FixedPoint; udtValue: ccc.FixedPoint }`
@@ -371,14 +368,14 @@ Receipts convert to UDT; deposits stay as deposits or convert to UDT. No iCKB ca
 - Pattern: CCC signers abstract wallet implementation
 
 **Capacity & Fee Management:**
-- `CapacityManager`: Discovers and collects cells for capacity
-- `SmartTransaction`: Auto-calculates fees from transaction size
-- Pattern: Add-then-complete flow (add inputs/outputs, then complete fee)
+- CCC-native: `tx.completeFeeBy()` / `tx.completeFeeChangeToLock()` with DAO-aware 64-output limit
+- Pattern: Add-then-complete flow (add inputs/outputs, then complete fee via CCC pipeline)
+- Note: `CapacityManager` was deleted in Phase 1; capacity discovery uses `client.findCellsOnChain()` directly
 
 **UDT Handling:**
-- `UdtHandler`: Encapsulates token script + type script pair
-- Pattern: Managers create handlers; SmartTransaction tracks per-UDT changes
-- Automatic change: `SmartTransaction.addUdtChange()` for balancing
+- `UdtHandler`: Interface encapsulating token script + cell deps
+- `UdtManager`: Base implementation with `isUdt()`, `findUdts()`, `completeInputsByUdt()`
+- Pattern: Managers hold `UdtHandler` reference; cell deps added via `tx.addCellDeps(udtHandler.cellDeps)`
 
 ---
 

.planning/codebase/CONCERNS.md

@@ -38,27 +38,28 @@
 
 ### Local UDT Handling May Overlap CCC Upstream (Medium)
 
-- Issue: CCC now has a dedicated `@ckb-ccc/udt` package (at `ccc-dev/ccc/packages/udt/`). The local `packages/utils/src/udt.ts` and `packages/core/src/udt.ts` implement custom UDT handling (`UdtHandler` interface, `IckbUdtManager` class). While the local UDT handling is iCKB-specific (custom balance calculation accounting for DAO deposits), the generic UDT operations like `ccc.udtBalanceFrom()` are still being used from CCC upstream in `packages/utils/src/udt.ts` (4 locations).
+- Issue: CCC now has a dedicated `@ckb-ccc/udt` package (at `ccc-fork/ccc/packages/udt/`). The local `packages/utils/src/udt.ts` and `packages/core/src/udt.ts` implement custom UDT handling (`UdtHandler` interface, `IckbUdtManager` class). While the local UDT handling is iCKB-specific (custom balance calculation accounting for DAO deposits), the generic UDT operations like `ccc.udtBalanceFrom()` are still being used from CCC upstream in `packages/utils/src/udt.ts` (4 locations).
 - Files:
   - `packages/utils/src/udt.ts` - `UdtHandler` interface, `UdtManager` class (~370 lines)
   - `packages/core/src/udt.ts` - `IckbUdtManager` extending UDT handling for iCKB-specific logic
-  - `ccc-dev/ccc/packages/udt/src/` - CCC upstream UDT package
+  - `ccc-fork/ccc/packages/udt/src/` - CCC upstream UDT package
   - Usage of `ccc.udtBalanceFrom()`: `packages/utils/src/udt.ts` lines 169, 197, 323, 368
 - Impact: There may be duplicated utility code for standard UDT operations (finding cells, calculating balances). The iCKB-specific extensions (e.g., `IckbUdtManager` which modifies balance calculations based on DAO deposit/withdrawal state) are domain-specific and unlikely to be in CCC.
 - Fix approach: Audit the CCC `@ckb-ccc/udt` package to identify which local utilities can be replaced. Keep iCKB-specific extensions but delegate standard UDT operations (cell finding, basic balance) to CCC where possible.
 
 ### Fragile CCC Local Override Mechanism (Medium)
 
-- Issue: The `.pnpmfile.cjs` hook and `ccc-dev/record.sh` script create a fragile mechanism for overriding published CCC packages with local builds. The `.pnpmfile.cjs` `readPackage` hook intercepts pnpm's dependency resolution to redirect `@ckb-ccc/*` packages to local paths under `ccc-dev/ccc/packages/*/`.
+- Issue: The `.pnpmfile.cjs` hook and `fork-scripts/record.sh` script create a fragile mechanism for overriding published CCC packages with local builds. The `.pnpmfile.cjs` `readPackage` hook intercepts pnpm's dependency resolution to redirect `@ckb-ccc/*` packages to local paths under `ccc-fork/ccc/packages/*/`.
 - Files:
   - `.pnpmfile.cjs` - pnpm hook that overrides `@ckb-ccc/*` package resolutions
-  - `ccc-dev/record.sh` - clones CCC repo, merges refs, and builds it locally
-  - `pnpm-workspace.yaml` - includes `ccc-dev/ccc/packages/*` in workspace
-  - `ccc-dev/ccc/` - local CCC checkout (when present)
+  - `fork-scripts/record.sh` - generic fork record script (clones repo, merges refs, builds locally)
+  - `ccc-fork/config.json` - CCC fork configuration (upstream URL, refs, workspace config)
+  - `pnpm-workspace.yaml` - includes `ccc-fork/ccc/packages/*` in workspace (auto-generated section)
+  - `ccc-fork/ccc/` - local CCC checkout (when present)
 - Impact: Multiple fragility points:
-  1. The local CCC repo at `ccc-dev/ccc/` must be manually cloned and kept in sync with a specific branch/commit.
+  1. The local CCC repo at `ccc-fork/ccc/` must be manually cloned and kept in sync with a specific branch/commit.
   2. The `readPackage` hook modifies `dependencies` objects at install time, which can silently break if CCC reorganizes its packages.
-  3. CI/CD (`ccc-dev/replay.sh`) must run this setup before `pnpm install`, creating an ordering dependency.
+  3. CI/CD (`fork-scripts/replay.sh`) must run this setup before `pnpm install`, creating an ordering dependency.
   4. The override mechanism is invisible to developers who don't read `.pnpmfile.cjs`, leading to confusion when packages resolve differently than expected from `package.json`.
 - Fix approach: Now that UDT and Epoch PRs have been merged into CCC upstream, evaluate whether the local overrides are still needed. If CCC publishes releases containing the merged features, switch to published versions and remove the override mechanism.
 
@@ -107,7 +108,7 @@
   - `packages/dao/src/dao.ts`, lines 326-334 (called in async generator loop)
   - `packages/core/src/owned_owner.ts`, lines 229-234 (same pattern)
 - Cause: Each `daoCellFrom()` call makes 1-2 RPC calls that cannot be parallelized within a single cell construction.
-- Improvement path: The `SmartTransaction.headers` cache in `packages/utils/src/transaction.ts` partially mitigates this by caching fetched headers. For batch operations, consider prefetching all needed headers in parallel before constructing DAO cells.
+- Improvement path: CCC's Client Cache transparently caches fetched headers (SmartTransaction's header cache was deleted in Phase 1). For batch operations, consider prefetching all needed headers in parallel before constructing DAO cells.
 
 ### Duplicated RPC Batching Code in Legacy Apps
 
@@ -128,12 +129,9 @@
 
 ## Fragile Areas
 
-### SmartTransaction Class Extending ccc.Transaction
+### SmartTransaction Class Extending ccc.Transaction (RESOLVED)
 
-- Files: `packages/utils/src/transaction.ts` (517 lines)
-- Why fragile: `SmartTransaction` extends `ccc.Transaction` and overrides 8 methods: `completeFee`, `getInputsUdtBalance`, `getOutputsUdtBalance`, `getInputsCapacity`, `clone`, `copy`, `from`, `default`, and `fromLumosSkeleton`. Changes to `ccc.Transaction`'s interface or behavior upstream can silently break `SmartTransaction`.
-- Safe modification: When updating CCC dependency, review `ccc.Transaction` changelog for breaking changes to overridden methods. The `completeFee` override (lines 63-98) is particularly fragile as it calls `super.completeFee()` and also queries the client for the NervosDAO script to check the 64-output limit.
-- Test coverage: No tests for `SmartTransaction`.
+- Status: **Resolved in Phase 1** — SmartTransaction class and CapacityManager were fully deleted from `@ickb/utils`. All manager methods now accept `ccc.TransactionLike` and return `ccc.Transaction` directly. Header caching is handled by CCC Client Cache. The 64-output DAO limit check was contributed to CCC core.
 
 ### Bot Order Matching Algorithm
 
@@ -154,11 +152,11 @@
 ### 64 Output Cell Limit for NervosDAO Transactions
 
 - Current capacity: Maximum 64 output cells per transaction containing NervosDAO operations.
-- Limit: Enforced by the NervosDAO script itself. Checked in 6 locations throughout the codebase.
+- Limit: Enforced by the NervosDAO script itself. Consolidated into CCC core in Phase 1.
 - Files:
-  - `packages/dao/src/dao.ts`, lines 99-103, 174-177, 244-248
-  - `packages/core/src/owned_owner.ts`, lines 102-106, 144-148
-  - `packages/utils/src/transaction.ts`, lines 85-95
+  - `ccc-fork/ccc/packages/core/src/ckb/transaction.ts` — `assertDaoOutputLimit` utility + `completeFee` safety net (contributed to CCC core in Phase 1)
+  - `packages/dao/src/dao.ts` — calls `assertDaoOutputLimit`
+  - `packages/core/src/owned_owner.ts` — calls `assertDaoOutputLimit`
   - `apps/bot/src/index.ts`, line 414 (limits to 58 outputs to reserve 6 for change)
 - Scaling path: Protocol-level constraint. The bot works around it by limiting deposit/withdrawal operations per transaction. Future NervosDAO script updates may relax this.
 
@@ -242,19 +240,13 @@
 
 ## Dead Code
 
-### `fromLumosSkeleton` in SmartTransaction
+### `fromLumosSkeleton` in SmartTransaction (RESOLVED)
 
-- Issue: `SmartTransaction.fromLumosSkeleton()` at `packages/utils/src/transaction.ts` line 432 provides Lumos interoperability. Since the new packages do not use Lumos, this method is only needed if external code passes Lumos skeletons to the new packages.
-- Files: `packages/utils/src/transaction.ts`, lines 432-436
-- Impact: Low. The method is a thin wrapper delegating to the superclass.
-- Fix approach: Remove after all apps are migrated away from Lumos.
+- Status: **Resolved in Phase 1** — SmartTransaction class was fully deleted, including `fromLumosSkeleton()`.
 
-### SmartTransaction Name is Misleading (Not Dead)
+### SmartTransaction Name is Misleading (RESOLVED)
 
-- Issue: Despite the original "SmartTransaction" concept being abandoned ecosystem-wide, the `SmartTransaction` class in `packages/utils/src/transaction.ts` is actively used throughout the new packages. It extends `ccc.Transaction` with UDT handler management and header caching (which is what replaced the abandoned SmartTransaction headers concept). The name is a vestige but the code is alive and critical.
-- Files: `packages/utils/src/transaction.ts` - definition (517 lines). Used in: `packages/sdk/src/sdk.ts`, `packages/order/src/order.ts`, `packages/dao/src/dao.ts`, `packages/core/src/owned_owner.ts`, `packages/core/src/logic.ts`, `apps/faucet/src/main.ts`
-- Impact: The name `SmartTransaction` may confuse developers familiar with the abandoned ecosystem concept.
-- Fix approach: Consider renaming to `IckbTransaction` or `EnhancedTransaction`. Low priority since the class is internal to the monorepo.
+- Status: **Resolved in Phase 1** — SmartTransaction class was fully deleted from `@ickb/utils`. All manager methods now accept `ccc.TransactionLike` directly.
 
 ---