@ckb-ccc/spore 0.1.0-alpha.2

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@ckb-ccc/spore",
+  "version": "0.1.0-alpha.2",
+  "description": "CCC - CKBer's Codebase. Common Chains Connector's support for Spore protocol",
+  "author": "ashuralyk <ashuralyk@live.com>",
+  "license": "MIT",
+  "private": false,
+  "homepage": "https://github.com/ckb-ecofund/ccc",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/ckb-ecofund/ccc.git"
+  },
+  "main": "dist.commonjs/index.js",
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "default": "./dist.commonjs/index.js"
+    },
+    "./advanced": {
+      "import": "./dist/advanced.js",
+      "default": "./dist.commonjs/advanced.js"
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.1.1",
+    "copyfiles": "^2.4.1",
+    "eslint": "^9.1.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "prettier": "^3.2.5",
+    "prettier-plugin-organize-imports": "^3.2.4",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.4.5",
+    "typescript-eslint": "^7.7.0",
+    "dotenv": "^16.4.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ckb-lumos/base": "^0.24.0-next.1",
+    "@ckb-lumos/codec": "^0.24.0-next.1",
+    "axios": "^1.7.7",
+    "@ckb-ccc/core": "0.1.0-alpha.4"
+  },
+  "scripts": {
+    "build": "rimraf ./dist && rimraf ./dist.commonjs && tsc && tsc --project tsconfig.commonjs.json && copyfiles -u 2 misc/basedirs/**/* .",
+    "lint": "eslint ./src",
+    "format": "prettier --write . && eslint --fix ./src"
+  }
+}

package/src/advanced.ts

@@ -0,0 +1,4 @@
+export * from "./cobuild/index.js";
+export * from "./codec/index.js";
+export * from "./predefined/advanced.js";
+export * from "./spore/advanced.js";

package/src/cluster/index.ts

@@ -0,0 +1,180 @@
+import { ccc } from "@ckb-ccc/core";
+import {
+  assembleCreateClusterAction,
+  assembleTransferClusterAction,
+  prepareSporeTransaction,
+} from "../advanced.js";
+import { ClusterData, packRawClusterData } from "../codec/index.js";
+import {
+  findSingletonCellByArgs,
+  injectOneCapacityCell,
+} from "../helper/index.js";
+import {
+  SporeScriptInfo,
+  SporeScriptInfoLike,
+  getClusterScriptInfo,
+  getClusterScriptInfos,
+} from "../predefined/index.js";
+
+export async function findCluster(
+  client: ccc.Client,
+  args: ccc.HexLike,
+  scripts?: SporeScriptInfoLike[],
+): Promise<
+  | {
+      cell: ccc.Cell;
+      scriptInfo: SporeScriptInfo;
+    }
+  | undefined
+> {
+  return findSingletonCellByArgs(
+    client,
+    args,
+    scripts ?? Object.values(getClusterScriptInfos(client)),
+  );
+}
+
+export async function assertCluster(
+  client: ccc.Client,
+  args: ccc.HexLike,
+  scripts?: SporeScriptInfoLike[],
+): Promise<{
+  cell: ccc.Cell;
+  scriptInfo: SporeScriptInfo;
+}> {
+  const res = await findCluster(client, args, scripts);
+
+  if (!res) {
+    throw new Error(`Cluster ${ccc.hexFrom(args)} not found`);
+  }
+
+  return res;
+}
+
+/**
+ * Create a new Cluster cell
+ *
+ * @param signer who takes the responsibility to balance and sign the transaction
+ * @param data specific format of data required by Cluster protocol
+ * @param to the owner of the Cluster cell, which will be replaced with signer if not provided
+ * @param tx the transaction skeleton, if not provided, a new one will be created
+ * @param scriptInfo the script info of new cluster, default spore version if undefined
+ * @param scriptInfoHash the script info hash used in cobuild
+ * @returns
+ *  - **tx**: a new transaction that contains created Cluster cell
+ *  - **id**: the id of the created Cluster cell
+ */
+export async function createSporeCluster(params: {
+  signer: ccc.Signer;
+  data: ClusterData;
+  to?: ccc.ScriptLike;
+  tx?: ccc.TransactionLike;
+  scriptInfo?: SporeScriptInfoLike;
+  scriptInfoHash?: ccc.HexLike;
+}): Promise<{
+  tx: ccc.Transaction;
+  id: ccc.Hex;
+}> {
+  const { signer, data, to, scriptInfoHash } = params;
+  const scriptInfo = params.scriptInfo ?? getClusterScriptInfo(signer.client);
+
+  // prepare transaction
+  const tx = ccc.Transaction.from(params.tx ?? {});
+  if (tx.inputs.length === 0) {
+    await injectOneCapacityCell(signer, tx);
+  }
+
+  // build cluster cell
+  const id = ccc.hashTypeId(tx.inputs[0], tx.outputs.length);
+  const packedClusterData = packRawClusterData(data);
+  tx.addOutput(
+    {
+      lock: to ?? (await signer.getRecommendedAddressObj()).script,
+      type: {
+        ...scriptInfo,
+        args: id,
+      },
+    },
+    packedClusterData,
+  );
+
+  // complete cellDeps
+  await tx.addCellDepInfos(signer.client, scriptInfo.cellDeps);
+
+  // generate cobuild action
+  const actions = scriptInfo.cobuild
+    ? [
+        assembleCreateClusterAction(
+          tx.outputs[tx.outputs.length - 1],
+          packedClusterData,
+          scriptInfoHash,
+        ),
+      ]
+    : [];
+
+  return {
+    tx: await prepareSporeTransaction(signer, tx, actions),
+    id,
+  };
+}
+
+/**
+ * Transfer a Cluster cell
+ *
+ * @param signer who takes the responsibility to balance and sign the transaction
+ * @param id the id of the Cluster cell to be transferred
+ * @param to the new owner of the Cluster cell
+ * @param tx the transaction skeleton, if not provided, a new one will be created
+ * @param scriptInfoHash the script info hash used in cobuild
+ * @returns
+ *  - **tx**: a new transaction that contains transferred Cluster cell
+ */
+export async function transferSporeCluster(params: {
+  signer: ccc.Signer;
+  id: ccc.HexLike;
+  to: ccc.ScriptLike;
+  tx?: ccc.TransactionLike;
+  scriptInfoHash?: ccc.HexLike;
+}): Promise<{
+  tx: ccc.Transaction;
+}> {
+  const { signer, id, to, scriptInfoHash } = params;
+
+  // prepare transaction
+  const tx = ccc.Transaction.from(params.tx ?? {});
+
+  // build cluster cell
+  const { cell: cluster, scriptInfo } = await assertCluster(signer.client, id);
+
+  tx.inputs.push(
+    ccc.CellInput.from({
+      previousOutput: cluster.outPoint,
+      ...cluster,
+    }),
+  );
+  tx.addOutput(
+    {
+      lock: to,
+      type: cluster.cellOutput.type,
+    },
+    cluster.outputData,
+  );
+
+  // complete cellDeps
+  await tx.addCellDepInfos(signer.client, scriptInfo.cellDeps);
+
+  // generate cobuild action
+  const actions = scriptInfo.cobuild
+    ? [
+        assembleTransferClusterAction(
+          cluster.cellOutput,
+          tx.outputs[tx.outputs.length - 1],
+          scriptInfoHash,
+        ),
+      ]
+    : [];
+
+  return {
+    tx: await prepareSporeTransaction(signer, tx, actions),
+  };
+}

package/src/cobuild/index.ts

@@ -0,0 +1,220 @@
+import { ccc } from "@ckb-ccc/core";
+import { UnpackResult } from "@ckb-lumos/codec";
+import {
+  Action,
+  ActionVec,
+  SporeAction,
+  WitnessLayout,
+} from "../codec/index.js";
+import { DEFAULT_COBUILD_INFO_HASH } from "../predefined/index.js";
+
+export function assembleCreateSporeAction(
+  sporeOutput: ccc.CellOutputLike,
+  sporeData: ccc.BytesLike,
+  scriptInfoHash: ccc.HexLike = DEFAULT_COBUILD_INFO_HASH,
+): UnpackResult<typeof Action> {
+  if (!sporeOutput.type) {
+    throw new Error("Spore cell must have a type script");
+  }
+  const sporeType = ccc.Script.from(sporeOutput.type);
+  const sporeTypeHash = sporeType.hash();
+  const actionData = SporeAction.pack({
+    type: "CreateSpore",
+    value: {
+      sporeId: sporeType.args,
+      dataHash: ccc.hashCkb(sporeData),
+      to: {
+        type: "Script",
+        value: ccc.Script.from(sporeOutput.lock),
+      },
+    },
+  });
+  return {
+    scriptInfoHash: ccc.hexFrom(scriptInfoHash),
+    scriptHash: sporeTypeHash,
+    data: ccc.hexFrom(actionData),
+  };
+}
+
+export function assembleTransferSporeAction(
+  sporeInput: ccc.CellOutputLike,
+  sporeOutput: ccc.CellOutputLike,
+  scriptInfoHash: ccc.HexLike = DEFAULT_COBUILD_INFO_HASH,
+): UnpackResult<typeof Action> {
+  if (!sporeInput.type || !sporeOutput.type) {
+    throw new Error("Spore cell must have a type script");
+  }
+
+  const sporeType = ccc.Script.from(sporeOutput.type);
+  const sporeTypeHash = sporeType.hash();
+  const actionData = SporeAction.pack({
+    type: "TransferSpore",
+    value: {
+      sporeId: sporeType.args,
+      from: {
+        type: "Script",
+        value: ccc.Script.from(sporeInput.lock),
+      },
+      to: {
+        type: "Script",
+        value: ccc.Script.from(sporeOutput.lock),
+      },
+    },
+  });
+  return {
+    scriptInfoHash: ccc.hexFrom(scriptInfoHash),
+    scriptHash: sporeTypeHash,
+    data: ccc.hexFrom(actionData),
+  };
+}
+
+export function assembleMeltSporeAction(
+  sporeInput: ccc.CellOutputLike,
+  scriptInfoHash: ccc.HexLike = DEFAULT_COBUILD_INFO_HASH,
+): UnpackResult<typeof Action> {
+  if (!sporeInput.type) {
+    throw new Error("Spore cell must have a type script");
+  }
+  const sporeType = ccc.Script.from(sporeInput.type);
+  const sporeTypeHash = sporeType.hash();
+  const actionData = SporeAction.pack({
+    type: "MeltSpore",
+    value: {
+      sporeId: sporeType.args,
+      from: {
+        type: "Script",
+        value: ccc.Script.from(sporeInput.lock),
+      },
+    },
+  });
+  return {
+    scriptInfoHash: ccc.hexFrom(scriptInfoHash),
+    scriptHash: sporeTypeHash,
+    data: ccc.hexFrom(actionData),
+  };
+}
+
+export function assembleCreateClusterAction(
+  clusterOutput: ccc.CellOutputLike,
+  clusterData: ccc.BytesLike,
+  scriptInfoHash: ccc.HexLike = DEFAULT_COBUILD_INFO_HASH,
+): UnpackResult<typeof Action> {
+  if (!clusterOutput.type) {
+    throw new Error("Cluster cell must have a type script");
+  }
+  const clusterType = ccc.Script.from(clusterOutput.type);
+  const clusterTypeHash = clusterType.hash();
+  const actionData = SporeAction.pack({
+    type: "CreateCluster",
+    value: {
+      clusterId: clusterType.args,
+      dataHash: ccc.hashCkb(clusterData),
+      to: {
+        type: "Script",
+        value: ccc.Script.from(clusterOutput.lock),
+      },
+    },
+  });
+  return {
+    scriptInfoHash: ccc.hexFrom(scriptInfoHash),
+    scriptHash: clusterTypeHash,
+    data: ccc.hexFrom(actionData),
+  };
+}
+
+export function assembleTransferClusterAction(
+  clusterInput: ccc.CellOutputLike,
+  clusterOutput: ccc.CellOutputLike,
+  scriptInfoHash: ccc.HexLike = DEFAULT_COBUILD_INFO_HASH,
+): UnpackResult<typeof Action> {
+  if (!clusterInput.type || !clusterOutput.type) {
+    throw new Error("Cluster cell must have a type script");
+  }
+  const clusterType = ccc.Script.from(clusterOutput.type);
+  const clusterTypeHash = clusterType.hash();
+  const actionData = SporeAction.pack({
+    type: "TransferCluster",
+    value: {
+      clusterId: clusterType.args,
+      from: {
+        type: "Script",
+        value: ccc.Script.from(clusterInput.lock),
+      },
+      to: {
+        type: "Script",
+        value: ccc.Script.from(clusterOutput.lock),
+      },
+    },
+  });
+  return {
+    scriptInfoHash: ccc.hexFrom(scriptInfoHash),
+    scriptHash: clusterTypeHash,
+    data: ccc.hexFrom(actionData),
+  };
+}
+
+export async function prepareSporeTransaction(
+  signer: ccc.Signer,
+  txLike: ccc.TransactionLike,
+  actions: UnpackResult<typeof ActionVec>,
+): Promise<ccc.Transaction> {
+  let tx = ccc.Transaction.from(txLike);
+
+  if (actions.length === 0) {
+    return signer.prepareTransaction(tx);
+  }
+
+  const existedActions = extractCobuildActionsFromTx(tx);
+  tx = await signer.prepareTransaction(tx);
+  injectCobuild(tx, [...existedActions, ...actions]);
+  return tx;
+}
+
+export function unpackCommonCobuildProof(
+  data: ccc.HexLike,
+): UnpackResult<typeof WitnessLayout> | undefined {
+  try {
+    return WitnessLayout.unpack(ccc.bytesFrom(data));
+  } catch {
+    return;
+  }
+}
+
+export function extractCobuildActionsFromTx(
+  tx: ccc.Transaction,
+): UnpackResult<typeof ActionVec> {
+  if (tx.witnesses.length === 0) {
+    return [];
+  }
+  const witnessLayout = unpackCommonCobuildProof(
+    tx.witnesses[tx.witnesses.length - 1],
+  );
+  if (!witnessLayout) {
+    return [];
+  }
+  if (witnessLayout.type !== "SighashAll") {
+    throw new Error("Invalid cobuild proof type: " + witnessLayout.type);
+  }
+
+  // Remove existed cobuild witness
+  tx.witnesses.pop();
+  return witnessLayout.value.message.actions;
+}
+
+export function injectCobuild(
+  tx: ccc.Transaction,
+  actions: UnpackResult<typeof ActionVec>,
+): void {
+  const witnessLayout = ccc.hexFrom(
+    WitnessLayout.pack({
+      type: "SighashAll",
+      value: {
+        seal: "0x",
+        message: {
+          actions,
+        },
+      },
+    }),
+  );
+  tx.witnesses.push(ccc.hexFrom(witnessLayout));
+}

package/src/codec/base.ts

@@ -0,0 +1,11 @@
+import { ccc } from "@ckb-ccc/core";
+import { molecule } from "@ckb-lumos/codec";
+
+/**
+ * The codec for packing/unpacking UTF-8 raw strings.
+ * Should be packed like so: String.pack('something')
+ */
+export const RawString = molecule.byteVecOf({
+  pack: (packable: string) => ccc.bytesFrom(packable, "utf8"),
+  unpack: (unpackable: ccc.BytesLike) => ccc.bytesTo(unpackable, "utf8"),
+});

package/src/codec/cluster.ts

@@ -0,0 +1,133 @@
+import { ccc } from "@ckb-ccc/core";
+import { blockchain } from "@ckb-lumos/base";
+import { molecule } from "@ckb-lumos/codec";
+import { RawString } from "./base.js";
+
+export const MolClusterDataV1 = molecule.table(
+  {
+    name: RawString,
+    description: RawString,
+  },
+  ["name", "description"],
+);
+export const MolClusterDataV2 = molecule.table(
+  {
+    name: RawString,
+    description: RawString,
+    mutantId: blockchain.BytesOpt,
+  },
+  ["name", "description", "mutantId"],
+);
+
+export interface ClusterDataV1 {
+  name: string;
+  description: string;
+}
+export interface ClusterDataV2 {
+  name: string;
+  description: string;
+  mutantId?: ccc.HexLike;
+}
+export type ClusterData = ClusterDataV2;
+
+export type ClusterDataVersion = "v1" | "v2";
+
+/**
+ * Pack RawClusterData to Uint8Array.
+ * Pass an optional "version" field to select a specific packing version.
+ */
+export function packRawClusterData(packable: ClusterData): Uint8Array;
+export function packRawClusterData(
+  packable: ClusterDataV1,
+  version: "v1",
+): Uint8Array;
+export function packRawClusterData(
+  packable: ClusterDataV2,
+  version: "v2",
+): Uint8Array;
+export function packRawClusterData(
+  packable: ClusterDataV1 | ClusterDataV2,
+  version?: ClusterDataVersion,
+): Uint8Array {
+  if (!version) {
+    return packRawClusterDataV2(packable);
+  }
+
+  switch (version) {
+    case "v1":
+      return packRawClusterDataV1(packable);
+    case "v2":
+      return packRawClusterDataV2(packable);
+  }
+}
+export function packRawClusterDataV1(packable: ClusterDataV1): Uint8Array {
+  return MolClusterDataV1.pack({
+    name: packable.name,
+    description: packable.description,
+  });
+}
+export function packRawClusterDataV2(packable: ClusterDataV2): Uint8Array {
+  return MolClusterDataV2.pack({
+    name: packable.name,
+    description: packable.description,
+    mutantId: packable.mutantId,
+  });
+}
+
+/**
+ * Unpack Hex/Bytes to RawClusterData.
+ * Pass an optional "version" field to select a specific unpacking version.
+ */
+export function unpackToRawClusterData(unpackable: ccc.BytesLike): ClusterData;
+export function unpackToRawClusterData(
+  unpackable: ccc.BytesLike,
+  version: "v1",
+): ClusterDataV1;
+export function unpackToRawClusterData(
+  unpackable: ccc.BytesLike,
+  version: "v2",
+): ClusterDataV2;
+export function unpackToRawClusterData(
+  unpackable: ccc.BytesLike,
+  version?: ClusterDataVersion,
+): unknown {
+  if (version) {
+    switch (version) {
+      case "v1":
+        return unpackToRawClusterDataV1(unpackable);
+      case "v2":
+        return unpackToRawClusterDataV2(unpackable);
+    }
+  }
+
+  try {
+    return unpackToRawClusterDataV2(unpackable);
+  } catch {
+    try {
+      return unpackToRawClusterDataV1(unpackable);
+    } catch {
+      throw new Error(
+        `Cannot unpack ClusterData, no matching molecule: ${ccc.hexFrom(unpackable)}`,
+      );
+    }
+  }
+}
+export function unpackToRawClusterDataV1(
+  unpackable: ccc.BytesLike,
+): ClusterDataV1 {
+  const decoded = MolClusterDataV1.unpack(unpackable);
+  return {
+    name: decoded.name,
+    description: decoded.description,
+  };
+}
+export function unpackToRawClusterDataV2(
+  unpackable: ccc.BytesLike,
+): ClusterDataV2 {
+  const decoded = MolClusterDataV2.unpack(unpackable);
+  return {
+    name: decoded.name,
+    description: decoded.description,
+    mutantId: ccc.apply(ccc.hexFrom, decoded.mutantId),
+  };
+}

package/src/codec/cobuild/buildingPacket.ts

@@ -0,0 +1,72 @@
+import { blockchain } from "@ckb-lumos/base";
+import { molecule, number } from "@ckb-lumos/codec";
+import { RawString } from "../base.js";
+
+const Uint32Opt = molecule.option(number.Uint32LE);
+
+const Hash = blockchain.Byte32;
+
+export const Action = molecule.table(
+  {
+    scriptInfoHash: Hash,
+    scriptHash: Hash,
+    data: blockchain.Bytes,
+  },
+  ["scriptInfoHash", "scriptHash", "data"],
+);
+
+export const ActionVec = molecule.vector(Action);
+
+export const Message = molecule.table(
+  {
+    actions: ActionVec,
+  },
+  ["actions"],
+);
+
+export const ResolvedInputs = molecule.table(
+  {
+    outputs: blockchain.CellOutputVec,
+    outputsData: blockchain.BytesVec,
+  },
+  ["outputs", "outputsData"],
+);
+
+export const ScriptInfo = molecule.table(
+  {
+    name: RawString,
+    url: RawString,
+    scriptHash: Hash,
+    schema: RawString,
+    messageType: RawString,
+  },
+  ["name", "url", "scriptHash", "schema", "messageType"],
+);
+
+export const ScriptInfoVec = molecule.vector(ScriptInfo);
+
+export const BuildingPacketV1 = molecule.table(
+  {
+    message: Message,
+    payload: blockchain.Transaction,
+    resolvedInputs: ResolvedInputs,
+    changeOutput: Uint32Opt,
+    scriptInfos: ScriptInfoVec,
+    lockActions: ActionVec,
+  },
+  [
+    "message",
+    "payload",
+    "resolvedInputs",
+    "changeOutput",
+    "scriptInfos",
+    "lockActions",
+  ],
+);
+
+export const BuildingPacket = molecule.union(
+  {
+    BuildingPacketV1,
+  },
+  ["BuildingPacketV1"],
+);

package/src/codec/cobuild/index.ts

@@ -0,0 +1,3 @@
+export * from "./buildingPacket.js";
+export * from "./sporeAction.js";
+export * from "./witnessLayout.js";