iCKB Stack

iCKB Stack Monorepo: all TS libs, web UI, bot, CLI and shared packages, built on top of CCC.

Status

This monorepo is developing the new generation of iCKB libraries, replacing the deprecated @ickb/lumos-utils and @ickb/v1-core (which were built on the now-deprecated Lumos framework).

New packages (under packages/, built on CCC):

Package	Purpose	Status
@ickb/utils	Blockchain primitives, transaction helpers, epoch arithmetic, UDT handling	Active development
@ickb/dao	Nervos DAO abstraction layer	Active development
@ickb/order	Limit order cell management	Active development
@ickb/core	iCKB core protocol logic (deposits, receipts, owned owner)	Active development
@ickb/sdk	High-level SDK composing all packages	Active development

Apps migration status:

App	Purpose	Stack
apps/faucet	Testnet CKB distribution	Migrated to new packages + CCC
apps/sampler	iCKB exchange rate sampling	Migrated to new packages + CCC
apps/bot	Automated order matching	Legacy (@ickb/v1-core + Lumos)
apps/tester	Order creation simulator	Legacy (@ickb/v1-core + Lumos)
apps/interface	React web UI	Legacy (@ickb/v1-core + Lumos)

Key upstream contributions: UDT and Epoch support were contributed to CCC upstream and have been merged. Some local utilities may overlap with features now available natively in CCC.

Dependencies

graph TD;
    B["@ickb/utils"] --> A["@ckb-ccc/core"];
    C["@ickb/dao"] --> A;
    C --> B;
    D["@ickb/core"] --> A;
    D --> B;
    D --> C;
    E["@ickb/order"] --> A;
    E --> B;
    F["@ickb/sdk"] --> A;
    F --> B;
    F --> C;
    F --> D;
    F --> E;

    click A "https://github.com/ckb-devrel/ccc/tree/master/packages/core" "Go to @ckb-ccc/core"
    click B "https://github.com/ickb/stack/tree/master/packages/utils" "Go to @ickb/utils"
    click C "https://github.com/ickb/stack/tree/master/packages/dao" "Go to @ickb/dao"
    click D "https://github.com/ickb/stack/tree/master/packages/core" "Go to @ickb/core"
    click E "https://github.com/ickb/stack/tree/master/packages/order" "Go to @ickb/order"
    click F "https://github.com/ickb/stack/tree/master/packages/sdk" "Go to @ickb/sdk"

Loading

Develop with Forks

When forks/.pin/<name>/manifest is committed, pnpm install automatically sets up the local fork development environment on first run (by replaying pinned merges via forks/forker/replay.sh). No manual setup step is needed — just clone and install:

git clone git@github.com:ickb/stack.git && cd stack && pnpm install

To redo the setup from scratch: bash forks/forker/clean-all.sh && pnpm install.

After pnpm install, see forks/forker/README.md for recording new pins, developing fork PRs, and the full workflow.

Developer Scripts

Command	Description
pnpm coworker	Launch an interactive AI Coworker session (full autonomy, opus model).
pnpm coworker:ask	One-shot AI query for scripting (sonnet model, stateless). Used by record.sh.
bash forks/forker/status.sh <name>	Check if fork clone matches pinned state. Exit 0 = safe to wipe.
bash forks/forker/record.sh <name>	Record fork pins (clone, merge refs, build). Guarded against pending work.
bash forks/forker/save.sh <name>	Capture local fork work as a patch in .pin/ (survives re-records and replays).
bash forks/forker/push.sh <name>	Cherry-pick commits from wip branch onto a PR branch for pushing to the fork.
bash forks/forker/clean.sh <name>	Remove fork clone, keep pins (guarded). Re-replay on next pnpm install.
bash forks/forker/reset.sh <name>	Remove fork clone and pins (guarded). Restores published packages.
pnpm check:full	Wipe derived state and validate from scratch. Skips wipe if forks have pending work.

Epoch Semantic Versioning

This repository follows Epoch Semantic Versioning. In short ESV aims to provide a more nuanced and effective way to communicate software changes, allowing for better user understanding and smoother upgrades.

Licensing

This source code, crafted with care by Phroi, is freely available on GitHub and it is released under the MIT License.