Skip to content

Adopt CCC udt.Udt as IckbUdt base class#23

Merged
phroi merged 5 commits intomasterfrom
refactor/adopt-ccc-udt
Feb 26, 2026
Merged

Adopt CCC udt.Udt as IckbUdt base class#23
phroi merged 5 commits intomasterfrom
refactor/adopt-ccc-udt

Conversation

@phroi
Copy link
Member

@phroi phroi commented Feb 26, 2026

Why

Replace the homegrown UDT infrastructure (UdtHandler, UdtManager) with CCC's udt.Udt base class. This aligns iCKB with the upstream CCC token abstraction, reducing maintenance surface and enabling CCC's built-in UDT balance completion.

Changes

  • @ickb/core: Rewrite IckbUdtManager as IckbUdt extending udt.Udt, accepting code OutPoints instead of CellDep arrays. Override infoFrom() to value xUDT, receipt, and deposit cells. Remove udtHandler from LogicManager and OwnedOwnerManager.
  • @ickb/dao: Widen DaoManager.isDeposit() to accept CellAny.
  • @ickb/order: Replace UdtHandler with plain udtScript in OrderManager.
  • @ickb/utils: Delete UdtHandler, UdtManager, UdtCell, ErrorTransactionInsufficientCoin.
  • @ickb/sdk: Wire getConfig() to construct IckbUdt with code OutPoints, computing the UDT type script dynamically.

@gemini-code-assist
Copy link

Summary of Changes

Hello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request undertakes a significant refactoring of the User Defined Token (UDT) handling within the iCKB project. The primary goal is to transition from a custom, homegrown UDT infrastructure to leveraging the robust and standardized udt.Udt base class provided by the CCC framework. This strategic shift aims to streamline UDT management, reduce maintenance overhead, and enable the use of CCC's built-in UDT balance completion mechanisms. The core of this change involves creating a specialized IckbUdt class by subclassing udt.Udt, which is then tailored to accurately account for iCKB's unique multi-representation value across xUDT, receipt, and deposit cells. Concurrently, all legacy custom UDT handlers and related utility functions have been removed, and various managers and the SDK have been updated to seamlessly integrate with this new, CCC-aligned UDT abstraction.

Highlights

  • UDT Infrastructure Migration: Replaced the custom UDT infrastructure (UdtHandler, UdtManager) with CCC's udt.Udt base class, aligning iCKB with upstream CCC token abstraction.
  • IckbUdt Implementation: Rewrote IckbUdtManager as IckbUdt extending udt.Udt, which now accepts code OutPoints and overrides infoFrom() to correctly value xUDT, receipt, and deposit cells for multi-representation balance.
  • Manager Refactoring: Removed udtHandler parameters and associated cellDeps additions from LogicManager and OwnedOwnerManager, and replaced UdtHandler with a plain udtScript in OrderManager, centralizing UDT cellDeps management at the SDK level.
  • Old UDT Utilities Deletion: Deleted UdtHandler, UdtManager, UdtCell, and ErrorTransactionInsufficientCoin from @ickb/utils, eliminating ~400 lines of duplicated code.
  • SDK Integration: Updated the SDK to construct IckbUdt with code OutPoints, dynamically computing the UDT type script, and removed ickbUdt arguments from manager constructions.
Changelog
  • .changeset/adopt-ccc-udt.md
    • Added a new changeset file detailing the adoption of CCC's UDT base class and related refactorings.
  • .planning/PROJECT.md
    • Updated the project roadmap to reflect decisions and progress on CCC UDT handling and related refactorings.
  • .planning/REQUIREMENTS.md
    • Marked several UDT-related requirements as completed and updated their descriptions to reflect the implementation details.
  • .planning/ROADMAP.md
    • Updated the roadmap to reflect the completion of Phase 4 and detailed the scope and goals for Phase 5.
  • .planning/STATE.md
    • Updated the project's current state, progress, and performance metrics to reflect the completion of Phase 5.
  • .planning/phases/03-ccc-udt-integration-investigation/03-DECISION.md
    • Updated the implementation guidance for Phases 4 and 5, clarifying manager parameter changes and UDT cellDeps handling.
  • .planning/phases/04-deprecated-ccc-api-replacement/04-01-PLAN.md
    • Added a plan document outlining the replacement of UdtHandler with ccc.Script in OrderManager and removal of UDT cellDeps.
  • .planning/phases/04-deprecated-ccc-api-replacement/04-01-SUMMARY.md
    • Added a summary report for the completion of Phase 4 Plan 01, detailing accomplishments and decisions.
  • .planning/phases/04-deprecated-ccc-api-replacement/04-CONTEXT.md
    • Added a context document for Phase 4, detailing implementation decisions for OrderManager refactoring.
  • .planning/phases/04-deprecated-ccc-api-replacement/04-RESEARCH.md
    • Added a research document for Phase 4, analyzing architecture patterns, pitfalls, and providing code examples.
  • .planning/phases/04-deprecated-ccc-api-replacement/04-VERIFICATION.md
    • Added a verification report for Phase 4, confirming the successful completion of the plan.
  • .planning/phases/05-ickb-core-udt-refactor/05-01-PLAN.md
    • Added a plan document outlining the implementation of IckbUdt and removal of udtHandler from LogicManager and OwnedOwnerManager.
  • .planning/phases/05-ickb-core-udt-refactor/05-01-SUMMARY.md
    • Added a summary report for the completion of Phase 5 Plan 01, detailing accomplishments and decisions.
  • .planning/phases/05-ickb-core-udt-refactor/05-02-PLAN.md
    • Added a plan document outlining the deletion of UDT infrastructure from @ickb/utils and SDK updates.
  • .planning/phases/05-ickb-core-udt-refactor/05-02-SUMMARY.md
    • Added a summary report for the completion of Phase 5 Plan 02, detailing accomplishments and decisions.
  • .planning/phases/05-ickb-core-udt-refactor/05-CONTEXT.md
    • Added a context document for Phase 5, detailing implementation decisions for IckbUdt and UDT infrastructure deletion.
  • .planning/phases/05-ickb-core-udt-refactor/05-RESEARCH.md
    • Added a research document for Phase 5, analyzing architecture patterns, pitfalls, and providing code examples.
  • .planning/phases/05-ickb-core-udt-refactor/05-VERIFICATION.md
    • Added a verification report for Phase 5, confirming the successful completion of the plan.
  • package.json
    • Updated the pnpm package manager version.
  • packages/core/package.json
    • Added @ckb-ccc/udt as a dependency.
  • packages/core/src/logic.ts
    • Refactored LogicManager by removing the udtHandler parameter and associated cellDeps additions, and updated JSDoc.
  • packages/core/src/owned_owner.ts
    • Refactored OwnedOwnerManager by removing the udtHandler parameter and associated cellDeps additions, and updated JSDoc.
  • packages/core/src/udt.ts
    • Rewrote the UDT management class from IckbUdtManager to IckbUdt, extending udt.Udt and implementing custom infoFrom, addCellDeps, and typeScriptFrom methods.
  • packages/dao/src/dao.ts
    • Widened the isDeposit method's parameter type to accept ccc.CellAny.
  • packages/order/src/order.ts
    • Refactored OrderManager by replacing UdtHandler with a plain ccc.Script for UDT identification, removed UDT cellDeps additions, and updated JSDoc.
  • packages/sdk/src/constants.ts
    • Updated the SDK's configuration to use the new IckbUdt class, incorporating code OutPoint constants and removing ickbUdt arguments from manager constructions.
  • packages/utils/src/index.ts
    • Removed the export statement for the deleted udt.js file.
  • packages/utils/src/udt.ts
    • Deleted the file containing the old UdtHandler interface, UdtManager class, and related UDT utilities.
  • pnpm-lock.yaml
    • Updated various dependency versions to reflect changes in the project.
  • pnpm-workspace.yaml
    • Added @ckb-ccc/udt to the catalog.
Activity
  • The pull request involved a significant refactoring effort, meticulously documented across multiple planning and summary files for Phases 4 and 5.
  • Phase 4, which focused on replacing the custom UdtHandler in @ickb/order with a more streamlined approach, has been successfully completed and verified.
  • Phase 5, encompassing the implementation of the new IckbUdt class and the complete deletion of the old UDT infrastructure, has also been completed and verified.
  • Detailed plans, research, context, and verification reports were generated for each step, demonstrating a thorough and structured approach to the refactoring process.
  • The pnpm-lock.yaml and package.json files were updated to reflect new dependencies and package manager versions, ensuring project consistency.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

Copy link

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request is a significant and well-executed refactoring that replaces the homegrown UDT infrastructure with CCC's udt.Udt base class. This aligns iCKB with the upstream CCC token abstraction, reducing maintenance and enabling built-in balance completion. The changes are consistent across all packages, from deleting old utilities to updating the SDK to construct the new IckbUdt class. I've provided suggestions to improve readability and reduce code duplication, along with a note on a documentation inconsistency that should be updated to reflect the actual implementation, in line with repository guidelines.

Comment on lines 63 to 79
const ickbUdt = new IckbUdt(
// xUDT code cell OutPoint: use known constants for mainnet/testnet,
// fall back to first cellDep's outPoint for devnet.
network
? (network === "mainnet" ? MAINNET_XUDT_CODE : TESTNET_XUDT_CODE)
: d.udt.cellDeps[0]?.outPoint ?? ((): never => { throw new Error("devnet config missing xUDT code cell outPoint in udt.cellDeps"); })(),
IckbUdt.typeScriptFrom(
ccc.Script.from(d.udt.script),
ccc.Script.from(d.logic.script),
),
// iCKB Logic code cell OutPoint: same pattern as above.
network
? (network === "mainnet" ? MAINNET_LOGIC_CODE : TESTNET_LOGIC_CODE)
: d.logic.cellDeps[0]?.outPoint ?? ((): never => { throw new Error("devnet config missing Logic code cell outPoint in logic.cellDeps"); })(),
d.logic.script,
d.logic.cellDeps,
dao,
ickbUdt,
);

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

While this pattern of using a nullish coalescing operator with an immediately-invoked function expression that throws an error is functionally correct, it can be a bit dense and hard to read for some developers. Consider refactoring this to a more traditional if check for clarity. This would make the intent of throwing an error on missing configuration more explicit and easier to understand at a glance.

  const xudtCode = network
    ? network === "mainnet"
      ? MAINNET_XUDT_CODE
      : TESTNET_XUDT_CODE
    : d.udt.cellDeps[0]?.outPoint;
  if (!xudtCode) {
    throw new Error(
      'devnet config missing xUDT code cell outPoint in udt.cellDeps',
    );
  }

  const logicCode = network
    ? network === "mainnet"
      ? MAINNET_LOGIC_CODE
      : TESTNET_LOGIC_CODE
    : d.logic.cellDeps[0]?.outPoint;
  if (!logicCode) {
    throw new Error(
      'devnet config missing Logic code cell outPoint in logic.cellDeps',
    );
  }

  const ickbUdt = new IckbUdt(
    xudtCode,
    IckbUdt.typeScriptFrom(
      ccc.Script.from(d.udt.script),
      ccc.Script.from(d.logic.script),
    ),
    logicCode,
    d.logic.script,
    dao,
  );

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@gemini-code-assist Already refactored — the latest push uses separate xudtCode/logicCode variables with explicit if (!...) checks, exactly as suggested.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The refactoring looks good. It significantly improves readability and maintainability by making the error-handling logic explicit. This aligns well with best practices for clear and robust code.

Add phase 04 (CCC UDT investigation) and phase 05 (iCKB core UDT
refactor) planning documents including research, context, plans,
execution summaries, and verification reports.

Update PROJECT.md, REQUIREMENTS.md, ROADMAP.md, and STATE.md to
reflect the new milestone scope and phase progression.
Add @ckb-ccc/udt as a catalog dependency and wire it into @ickb/core.
This provides the udt.Udt base class that IckbUdt will extend.
Rewrite IckbUdtManager as IckbUdt, extending the CCC udt.Udt base class
instead of the homegrown UdtManager. The new class:

- Accepts code OutPoints (xUDT, Logic) instead of pre-built CellDep arrays
- Overrides infoFrom() to value iCKB's three cell representations
  (xUDT cells, receipt cells, deposit cells)
- Overrides addCellDeps() to add individual code deps
- Exposes typeScriptFrom() static for computing the UDT type script

Also widen DaoManager.isDeposit() to accept CellAny (needed by
IckbUdt.infoFrom which works with CellAny, not just Cell).
- Remove udtHandler parameter from LogicManager and OwnedOwnerManager
  constructors; callers now manage UDT cellDeps via IckbUdt.addCellDeps()
- Replace UdtHandler with plain udtScript in OrderManager
- Wire getConfig() to construct IckbUdt with code OutPoints,
  computing the UDT type script dynamically via IckbUdt.typeScriptFrom()
- Delete UDT infrastructure from @ickb/utils (UdtHandler, UdtManager,
  UdtCell, ErrorTransactionInsufficientCoin) — all superseded by CCC
@phroi phroi force-pushed the refactor/adopt-ccc-udt branch from 7b3b168 to 0ee8e2a Compare February 26, 2026 22:38
@phroi
Copy link
Member Author

phroi commented Feb 26, 2026

/gemini review

Copy link

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This is a major and well-executed refactoring that replaces the homegrown UDT infrastructure with CCC's udt.Udt base class. The changes are comprehensive, touching multiple packages and aligning iCKB with the upstream CCC token abstraction. The code is cleaner and more maintainable. I've found one opportunity for a performance improvement in the infoFrom method by parallelizing network requests.

@phroi
Copy link
Member Author

phroi commented Feb 26, 2026

LGTM

Phroi %219

@phroi phroi merged commit 382b36b into master Feb 26, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant