feat(coin): new coin package

.changeset/early-oranges-lick.md

@@ -0,0 +1,7 @@
+---
+"@ckb-ccc/shell": minor
+"@ckb-ccc/coin": minor
+---
+
+feat(coin): new coin package
+

packages/coin/.npmignore

@@ -0,0 +1,21 @@
+node_modules/
+misc/
+
+*test.js
+*test.ts
+*test.d.ts
+*test.d.ts.map
+*spec.js
+*spec.ts
+*spec.d.ts
+*spec.d.ts.map
+
+tsconfig.json
+tsconfig.*.json
+eslint.config.mjs
+.prettierrc
+.prettierignore
+
+tsconfig.tsbuildinfo
+tsconfig.*.tsbuildinfo
+.github/

packages/coin/.prettierignore

@@ -0,0 +1,15 @@
+node_modules/
+
+dist/
+dist.commonjs/
+
+.npmignore
+.prettierrc
+tsconfig.json
+eslint.config.mjs
+prettier.config.*
+
+tsconfig.tsbuildinfo
+.github/
+
+CHANGELOG.md

packages/coin/README.md

@@ -0,0 +1,142 @@
+<p align="center">
+  <a href="https://app.ckbccc.com/">
+    <img alt="Logo" src="https://raw.githubusercontent.com/ckb-devrel/ccc/master/assets/logoAndText.svg" style="height: 8rem; max-width: 90%; padding: 0.5rem 0;" />
+  </a>
+</p>
+
+<h1 align="center" style="font-size: 48px;">
+  CCC's Support for Coin
+</h1>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@ckb-ccc/coin"><img
+    alt="NPM Version" src="https://img.shields.io/npm/v/%40ckb-ccc%2Fcoin"
+  /></a>
+  <img alt="GitHub commit activity" src="https://img.shields.io/github/commit-activity/m/ckb-devrel/ccc" />
+  <img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/ckb-devrel/ccc/master" />
+  <img alt="GitHub branch check runs" src="https://img.shields.io/github/check-runs/ckb-devrel/ccc/master" />
+  <a href="https://live.ckbccc.com/"><img
+    alt="Playground" src="https://img.shields.io/website?url=https%3A%2F%2Flive.ckbccc.com%2F&label=Playground"
+  /></a>
+  <a href="https://app.ckbccc.com/"><img
+    alt="App" src="https://img.shields.io/website?url=https%3A%2F%2Fapp.ckbccc.com%2F&label=App"
+  /></a>
+  <a href="https://docs.ckbccc.com/"><img
+    alt="Docs" src="https://img.shields.io/website?url=https%3A%2F%2Fdocs.ckbccc.com%2F&label=Docs"
+  /></a>
+</p>
+
+<p align="center">
+  CCC - CKBers' Codebase is a one-stop solution for your CKB JS/TS ecosystem development.
+  <br />
+  Empower yourself with CCC to discover the unlimited potential of CKB.
+  <br />
+  Interoperate with wallets from different chain ecosystems.
+  <br />
+  Fully enabling CKB's Turing completeness and cryptographic freedom power.
+</p>
+
+## Quick Start
+
+`Coin` from `@ckb-ccc/coin` is a generic helper for on-chain fungible tokens identified by a CKB type script.
+
+### Instantiate
+
+```ts
+import { Coin } from "@ckb-ccc/coin";
+import { ccc } from "@ckb-ccc/core";
+
+// Classic instantiation with explicit script and cellDeps
+const coin = await Coin.new({
+  script: {
+    codeHash: "0x...",
+    hashType: "type",
+    args: "0x...",
+  },
+  client,
+  cellDeps: [{ outPoint: codeOutPoint, depType: "code" }],
+});
+
+// Instantiation via knownScript (e.g., sUDT)
+const sUdt = await Coin.new({
+  knownScript: ccc.KnownScript.SUdt,
+  script: {
+    args: ownerLock.hash(),
+  },
+  client,
+});
+
+// Instantiation of xUDT via CoinXUdt with structured args
+import { CoinXUdt } from "@ckb-ccc/coin";
+
+const xUdt = await CoinXUdt.new({
+  xUdtArgs: {
+    ownerScriptHash: ownerLock.hash(),
+    ownerModeOutputType: true,
+  },
+  client,
+});
+```
+
+### Query balance
+
+```ts
+// Total balance across all cells of the signer
+const balance = await coin.calculateBalance(signer);
+console.log(`Balance: ${balance}`);
+
+// Full info: Balance + CKB capacity + cell count
+const info = await coin.calculateInfo(signer);
+console.log(`Balance: ${info.amount}, Cells: ${info.count}`);
+```
+
+### Send
+
+Build the transaction manually, then use `completeBy` to add Coin inputs and a change output:
+
+```ts
+const coin = await Coin.new({
+  knownScript: ccc.KnownScript.SUdt,
+  script: {
+    args: ownerLock.hash(),
+  },
+  client,
+});
+
+const { script: to } = await signer.getRecommendedAddressObj();
+
+// Build outputs
+const tx = await coin.transfer([{ to, amount: 1000n }]);
+
+// Add Coin inputs + change (change goes back to signer)
+const completedTx = await coin.completeBy(signer, tx);
+
+// Cover CKB capacity and fee
+await completedTx.completeInputsByCapacity(signer);
+await completedTx.completeFeeBy(signer);
+
+const txHash = await signer.sendTransaction(completedTx);
+```
+
+### Change to a specific address
+
+```ts
+const { script: changeLock } = await signer.getRecommendedAddressObj();
+const completedTx = await coin.completeChangeToLock(signer, changeLock, tx);
+```
+
+## Extensible UDT (xUDT) Support
+
+`CoinXUdt` extends `Coin` to provide specialized support for RFC 52 extensible UDT (xUDT).
+
+- **Args Encoding/Decoding**: Provides `CoinXUdtArgs` to correctly build and parse xUDT type script arguments, supporting owner-mode flags.
+- **Default Known Script**: When `knownScript` is omitted, `CoinXUdt` uses `ccc.KnownScript.XUdt`. A complete `script` with `codeHash` and `hashType` takes priority over this shorthand. Pass `script.args` to use existing xUDT args, or pass `xUdtArgs` to build args from `ownerScriptHash` and `flags`.
+- **Underlying Coin Compatibility**: Inherits all query, transfer, and transaction completion methods of the generic `Coin` class.
+
+## Learn More?
+
+Check the [package documentation](https://docs.ckbccc.com/docs/packages/protocol-sdks/coin) and [API reference](https://api.ckbccc.com/classes/_ckb-ccc_coin.coin) for more details.
+
+<h3 align="center">
+  Read more about CCC on <a href="https://docs.ckbccc.com">our website</a> or <a href="https://github.com/ckb-devrel/ccc">GitHub Repo</a>.
+</h3>

packages/coin/eslint.config.mjs

@@ -0,0 +1,62 @@
+// @ts-check
+
+import eslint from "@eslint/js";
+import eslintPluginPrettierRecommended from "eslint-plugin-prettier/recommended";
+import tseslint from "typescript-eslint";
+
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+
+export default [
+  ...tseslint.config({
+    files: ["**/*.ts"],
+    extends: [
+      eslint.configs.recommended,
+      ...tseslint.configs.recommendedTypeChecked,
+    ],
+    rules: {
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          args: "all",
+          argsIgnorePattern: "^_",
+          caughtErrors: "all",
+          caughtErrorsIgnorePattern: "^_",
+          destructuredArrayIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+          ignoreRestSiblings: true,
+        },
+      ],
+      "@typescript-eslint/unbound-method": ["error", { ignoreStatic: true }],
+      "@typescript-eslint/no-unsafe-member-access": "off",
+      "@typescript-eslint/require-await": "off",
+      "@typescript-eslint/only-throw-error": [
+        "error",
+        {
+          allowThrowingAny: true,
+          allowThrowingUnknown: true,
+          allowRethrowing: true,
+        },
+      ],
+      "@typescript-eslint/prefer-promise-reject-errors": [
+        "error",
+        {
+          allowThrowingAny: true,
+          allowThrowingUnknown: true,
+        },
+      ],
+      "no-empty": "off",
+      "prefer-const": [
+        "error",
+        { ignoreReadBeforeAssign: true, destructuring: "all" },
+      ],
+    },
+    languageOptions: {
+      parserOptions: {
+        project: true,
+        tsconfigRootDir: dirname(fileURLToPath(import.meta.url)),
+      },
+    },
+  }),
+  eslintPluginPrettierRecommended,
+];

packages/coin/misc/basedirs/dist.commonjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

packages/coin/misc/basedirs/dist/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

packages/coin/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@ckb-ccc/coin",
+  "version": "0.0.0",
+  "description": "Coin",
+  "author": "Hanssen <0@hanssen0.com>",
+  "license": "MIT",
+  "private": false,
+  "homepage": "https://github.com/ckb-devrel/ccc",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/ckb-devrel/ccc.git"
+  },
+  "sideEffects": false,
+  "main": "./dist.commonjs/index.js",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist.commonjs/index.js"
+    },
+    "./barrel": {
+      "import": "./dist/barrel.mjs",
+      "require": "./dist.commonjs/barrel.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "vitest",
+    "test:ci": "vitest run",
+    "build": "tsdown",
+    "lint": "tsc --noEmit && eslint ./src",
+    "format": "prettier --write . && eslint --fix ./src"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.0.0",
+    "eslint": "^10.5.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.6",
+    "prettier": "^3.8.4",
+    "prettier-plugin-organize-imports": "^4.3.0",
+    "tsdown": "^0.22.3",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.61.1",
+    "vitest": "^4.1.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ckb-ccc/co-build": "workspace:*",
+    "@ckb-ccc/core": "workspace:*"
+  },
+  "packageManager": "pnpm@11.8.0",
+  "types": "./dist.commonjs/index.d.ts"
+}

packages/coin/prettier.config.cjs

@@ -0,0 +1,11 @@
+/**
+ * @see https://prettier.io/docs/configuration
+ * @type {import("prettier").Config}
+ */
+const config = {
+  singleQuote: false,
+  trailingComma: "all",
+  plugins: [require.resolve("prettier-plugin-organize-imports")],
+};
+
+module.exports = config;

packages/coin/src/barrel.ts

@@ -0,0 +1,3 @@
+export * from "./coBuild.js";
+export * from "./coin/index.js";
+export * from "./xUdt/index.js";