@ckb-ccc/spore 0.1.0-alpha.2

package/src/helper/index.ts

@@ -0,0 +1,68 @@
+import { ccc } from "@ckb-ccc/core";
+import { SporeScriptInfo, SporeScriptInfoLike } from "../predefined/index.js";
+
+export async function findSingletonCellByArgs(
+  client: ccc.Client,
+  args: ccc.HexLike,
+  scripts: (SporeScriptInfoLike | undefined)[],
+): Promise<
+  | {
+      cell: ccc.Cell;
+      scriptInfo: SporeScriptInfo;
+    }
+  | undefined
+> {
+  for (const scriptInfo of scripts) {
+    if (!scriptInfo) {
+      continue;
+    }
+
+    const cell = await client.findSingletonCellByType(
+      {
+        ...scriptInfo,
+        args,
+      },
+      true,
+    );
+
+    if (cell) {
+      return {
+        cell,
+        scriptInfo: SporeScriptInfo.from(scriptInfo),
+      };
+    }
+  }
+}
+
+export async function searchOneCellBySigner(
+  signer: ccc.Signer,
+): Promise<ccc.Cell | undefined> {
+  for await (const cell of signer.findCells(
+    {
+      scriptLenRange: [0, 1],
+      outputDataLenRange: [0, 1],
+    },
+    true,
+    undefined,
+    1,
+  )) {
+    return cell;
+  }
+}
+
+export async function injectOneCapacityCell(
+  signer: ccc.Signer,
+  tx: ccc.Transaction,
+): Promise<void> {
+  const liveCell = await searchOneCellBySigner(signer);
+  if (!liveCell) {
+    throw new Error("No live cell found");
+  }
+
+  tx.inputs.push(
+    ccc.CellInput.from({
+      previousOutput: liveCell.outPoint,
+      ...liveCell,
+    }),
+  );
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./cluster/index.js";
+export * as dob from "./dob/index.js";
+export * from "./predefined/index.js";
+export * from "./spore/index.js";

package/src/predefined/advanced.ts

@@ -0,0 +1,2 @@
+export * from "./mainnet.advanced.js";
+export * from "./testnet.advanced.js";

package/src/predefined/index.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./utils.js";

package/src/predefined/mainnet.advanced.ts

@@ -0,0 +1,76 @@
+import { SporeScriptInfoLike, SporeVersion } from "./types.js";
+
+export const SCRIPTS_SPORE_MAINNET: Record<
+  SporeVersion,
+  SporeScriptInfoLike | undefined
+> = Object.freeze({
+  [SporeVersion.DID]: {
+    codeHash:
+      "0xcfba73b58b6f30e70caed8a999748781b164ef9a1e218424a6fb55ebf641cb33",
+    hashType: "type",
+    cellDeps: [
+      {
+        cellDep: {
+          outPoint: {
+            txHash:
+              "0x37c80ba8124780920bc8fe06b49e3535b43ca339bb9a97fb462b16d575bfa9a6",
+            index: 0,
+          },
+          depType: "code",
+        },
+        type: {
+          codeHash:
+            "0x00000000000000000000000000000000000000000000000000545950455f4944",
+          hashType: "type",
+          args: "0x62312cd846659e188b05da11dc3f080b083c27371ea701d6026e11e713e0e3de",
+        },
+      },
+    ],
+    cobuild: true,
+  },
+  [SporeVersion.V2]: {
+    codeHash:
+      "0x4a4dce1df3dffff7f8b2cd7dff7303df3b6150c9788cb75dcf6747247132b9f5",
+    hashType: "data1",
+    cellDeps: [
+      {
+        cellDep: {
+          outPoint: {
+            txHash:
+              "0x96b198fb5ddbd1eed57ed667068f1f1e55d07907b4c0dbd38675a69ea1b69824",
+            index: 0,
+          },
+          depType: "code",
+        },
+      },
+    ],
+    cobuild: true,
+  },
+  [SporeVersion.V1]: undefined,
+});
+
+export const SCRIPTS_CLUSTER_MAINNET: Record<
+  SporeVersion,
+  SporeScriptInfoLike | undefined
+> = Object.freeze({
+  [SporeVersion.V2]: {
+    codeHash:
+      "0x7366a61534fa7c7e6225ecc0d828ea3b5366adec2b58206f2ee84995fe030075",
+    hashType: "data1",
+    cellDeps: [
+      {
+        cellDep: {
+          outPoint: {
+            txHash:
+              "0xe464b7fb9311c5e2820e61c99afc615d6b98bdefbe318c34868c010cbd0dc938",
+            index: 0,
+          },
+          depType: "code",
+        },
+      },
+    ],
+    cobuild: true,
+  },
+  [SporeVersion.V1]: undefined,
+  [SporeVersion.DID]: undefined,
+});

package/src/predefined/testnet.advanced.ts

@@ -0,0 +1,107 @@
+import { SporeScriptInfoLike, SporeVersion } from "./types.js";
+
+export const SCRIPTS_SPORE_TESTNET: Record<
+  SporeVersion,
+  SporeScriptInfoLike | undefined
+> = Object.freeze({
+  [SporeVersion.DID]: {
+    codeHash:
+      "0x0b1f412fbae26853ff7d082d422c2bdd9e2ff94ee8aaec11240a5b34cc6e890f",
+    hashType: "type",
+    cellDeps: [
+      {
+        cellDep: {
+          outPoint: {
+            txHash:
+              "0x306961e0eb04ed972c60cb89a0aed1b0ef065d96d2fc0000c62db5275e32dc6f",
+            index: 0,
+          },
+          depType: "code",
+        },
+        type: {
+          codeHash:
+            "0x00000000000000000000000000000000000000000000000000545950455f4944",
+          hashType: "type",
+          args: "0x80f0d4bf6b3951911aa6b98cc609d477a8a10b903b35cfd528d098e95c36f680",
+        },
+      },
+    ],
+  },
+  [SporeVersion.V2]: {
+    codeHash:
+      "0x685a60219309029d01310311dba953d67029170ca4848a4ff638e57002130a0d",
+    hashType: "data1",
+    cellDeps: [
+      {
+        cellDep: {
+          outPoint: {
+            txHash:
+              "0x5e8d2a517d50fd4bb4d01737a7952a1f1d35c8afc77240695bb569cd7d9d5a1f",
+            index: 0,
+          },
+          depType: "code",
+        },
+      },
+    ],
+    cobuild: true,
+  },
+  [SporeVersion.V1]: {
+    codeHash:
+      "0xbbad126377d45f90a8ee120da988a2d7332c78ba8fd679aab478a19d6c133494",
+    hashType: "data1",
+    cellDeps: [
+      {
+        cellDep: {
+          outPoint: {
+            txHash:
+              "0xfd694382e621f175ddf81ce91ce2ecf8bfc027d53d7d31b8438f7d26fc37fd19",
+            index: 0,
+          },
+          depType: "code",
+        },
+      },
+    ],
+  },
+});
+
+export const SCRIPTS_CLUSTER_TESTNET: Record<
+  SporeVersion,
+  SporeScriptInfoLike | undefined
+> = Object.freeze({
+  [SporeVersion.V2]: {
+    codeHash:
+      "0x0bbe768b519d8ea7b96d58f1182eb7e6ef96c541fbd9526975077ee09f049058",
+    hashType: "data1",
+    cellDeps: [
+      {
+        cellDep: {
+          outPoint: {
+            txHash:
+              "0xcebb174d6e300e26074aea2f5dbd7f694bb4fe3de52b6dfe205e54f90164510a",
+            index: 0,
+          },
+          depType: "code",
+        },
+      },
+    ],
+    cobuild: true,
+  },
+  [SporeVersion.V1]: {
+    codeHash:
+      "0x598d793defef36e2eeba54a9b45130e4ca92822e1d193671f490950c3b856080",
+    hashType: "data1",
+    cellDeps: [
+      {
+        cellDep: {
+          outPoint: {
+            txHash:
+              "0x49551a20dfe39231e7db49431d26c9c08ceec96a29024eef3acc936deeb2ca76",
+            index: 0,
+          },
+          depType: "code",
+        },
+      },
+    ],
+  },
+  [SporeVersion.DID]: undefined,
+});

package/src/predefined/types.ts

@@ -0,0 +1,37 @@
+import { ccc } from "@ckb-ccc/core";
+
+export const DEFAULT_COBUILD_INFO_HASH = ccc.hashCkb(
+  ccc.bytesFrom("CCC_DEFAULT_COBUILD_INFO", "utf8"),
+);
+
+export enum SporeVersion {
+  V1 = "V1",
+  V2 = "V2",
+  DID = "DID",
+}
+
+export const SPORE_VERSION_DEFAULT = SporeVersion.V2;
+
+export type SporeScriptInfoLike = ccc.ScriptInfoLike & {
+  cobuild?: boolean;
+};
+
+export class SporeScriptInfo extends ccc.ScriptInfo {
+  constructor(
+    codeHash: ccc.Hex,
+    hashType: ccc.HashType,
+    cellDeps: ccc.CellDepInfo[],
+    public cobuild?: boolean,
+  ) {
+    super(codeHash, hashType, cellDeps);
+  }
+
+  static from(scriptInfoLike: SporeScriptInfoLike): SporeScriptInfo {
+    return new SporeScriptInfo(
+      ccc.hexFrom(scriptInfoLike.codeHash),
+      ccc.hashTypeFrom(scriptInfoLike.hashType),
+      scriptInfoLike.cellDeps.map((c) => ccc.CellDepInfo.from(c)),
+      scriptInfoLike.cobuild,
+    );
+  }
+}

package/src/predefined/utils.ts

@@ -0,0 +1,56 @@
+import { ccc } from "@ckb-ccc/core";
+import {
+  SCRIPTS_CLUSTER_MAINNET,
+  SCRIPTS_CLUSTER_TESTNET,
+  SCRIPTS_SPORE_MAINNET,
+  SCRIPTS_SPORE_TESTNET,
+} from "./advanced.js";
+import {
+  SPORE_VERSION_DEFAULT,
+  SporeScriptInfo,
+  SporeVersion,
+} from "./types.js";
+
+export function getSporeScriptInfos(client: ccc.Client) {
+  return client.addressPrefix === "ckb"
+    ? SCRIPTS_SPORE_MAINNET
+    : SCRIPTS_SPORE_TESTNET;
+}
+
+export function getClusterScriptInfos(client: ccc.Client) {
+  return client.addressPrefix === "ckb"
+    ? SCRIPTS_CLUSTER_MAINNET
+    : SCRIPTS_CLUSTER_TESTNET;
+}
+
+export function getSporeScriptInfo(
+  client: ccc.Client,
+  version?: SporeVersion,
+): SporeScriptInfo {
+  const scriptInfo =
+    getSporeScriptInfos(client)[version ?? SPORE_VERSION_DEFAULT];
+
+  if (!scriptInfo) {
+    throw new Error(
+      `Spore script info not found of for version ${version} on ${client.addressPrefix}`,
+    );
+  }
+
+  return SporeScriptInfo.from(scriptInfo);
+}
+
+export function getClusterScriptInfo(
+  client: ccc.Client,
+  version?: SporeVersion,
+): SporeScriptInfo {
+  const scriptInfo =
+    getClusterScriptInfos(client)[version ?? SPORE_VERSION_DEFAULT];
+
+  if (!scriptInfo) {
+    throw new Error(
+      `Cluster script info not found of for version ${version} on ${client.addressPrefix}`,
+    );
+  }
+
+  return SporeScriptInfo.from(scriptInfo);
+}

package/src/spore/advanced.ts

@@ -0,0 +1,88 @@
+import { ccc } from "@ckb-ccc/core";
+import { UnpackResult } from "@ckb-lumos/codec";
+import { assembleTransferClusterAction } from "../advanced.js";
+import { assertCluster } from "../cluster/index.js";
+import { Action, SporeData } from "../codec/index.js";
+import { searchOneCellBySigner } from "../helper/index.js";
+
+export async function prepareCluster(
+  signer: ccc.Signer,
+  tx: ccc.Transaction,
+  data: SporeData,
+  clusterMode?: "lockProxy" | "clusterCell" | "skip",
+  scriptInfoHash?: ccc.HexLike,
+): Promise<UnpackResult<typeof Action> | undefined> {
+  // skip if the spore is not belong to a cluster
+  if (!data.clusterId || clusterMode === "skip") {
+    return;
+  }
+
+  if (!clusterMode) {
+    throw Error("clusterMode is undefined but the spore has a cluster");
+  }
+
+  const { cell: cluster, scriptInfo } = await assertCluster(
+    signer.client,
+    data.clusterId,
+  );
+
+  // If this cluster has been processed, nothing will happen to the tx
+  switch (clusterMode) {
+    case "lockProxy": {
+      const lock = cluster.cellOutput.lock;
+
+      if (!(await tx.findInputIndexByLock(lock, signer.client))) {
+        // note: We can only search proxy of signer, if any custom logic is in need, developer should get
+        // the proxy filled in transaction before invoking `createSpore`
+        const proxy = await searchOneCellBySigner(signer);
+        if (!proxy) {
+          throw new Error("Cluster lock proxy cell not found");
+        }
+        tx.inputs.push(
+          ccc.CellInput.from({
+            previousOutput: proxy.outPoint,
+            ...proxy,
+          }),
+        );
+      }
+      if (tx.outputs.every((output) => output.lock !== lock)) {
+        tx.addOutput({
+          lock,
+        });
+      }
+      tx.addCellDeps({
+        outPoint: cluster.outPoint,
+        depType: "code",
+      });
+      return;
+    }
+    case "clusterCell": {
+      if (tx.inputs.some((i) => i.previousOutput.eq(cluster.outPoint))) {
+        return;
+      }
+
+      tx.inputs.push(
+        ccc.CellInput.from({
+          previousOutput: cluster.outPoint,
+          ...cluster,
+        }),
+      );
+      tx.addOutput(cluster.cellOutput, cluster.outputData);
+      await tx.addCellDepInfos(signer.client, scriptInfo.cellDeps);
+      // note: add cluster as cellDep, which will be used in Spore contract
+      tx.addCellDeps({
+        outPoint: cluster.outPoint,
+        depType: "code",
+      });
+
+      if (scriptInfo.cobuild) {
+        return assembleTransferClusterAction(
+          cluster.cellOutput,
+          cluster.cellOutput,
+          scriptInfoHash,
+        );
+      }
+      return;
+    }
+  }
+}

package/src/spore/index.ts

@@ -0,0 +1,236 @@
+import { ccc } from "@ckb-ccc/core";
+import {
+  assembleCreateSporeAction,
+  assembleMeltSporeAction,
+  assembleTransferSporeAction,
+  prepareSporeTransaction,
+} from "../advanced.js";
+import { SporeData, packRawSporeData } from "../codec/index.js";
+import {
+  findSingletonCellByArgs,
+  injectOneCapacityCell,
+} from "../helper/index.js";
+import {
+  SporeScriptInfo,
+  SporeScriptInfoLike,
+  getSporeScriptInfo,
+  getSporeScriptInfos,
+} from "../predefined/index.js";
+import { prepareCluster } from "./advanced.js";
+
+export async function findSpore(
+  client: ccc.Client,
+  args: ccc.HexLike,
+  scripts?: SporeScriptInfoLike[],
+): Promise<
+  | {
+      cell: ccc.Cell;
+      scriptInfo: SporeScriptInfo;
+    }
+  | undefined
+> {
+  return findSingletonCellByArgs(
+    client,
+    args,
+    scripts ?? Object.values(getSporeScriptInfos(client)),
+  );
+}
+
+export async function assertSpore(
+  client: ccc.Client,
+  args: ccc.HexLike,
+  scripts?: SporeScriptInfoLike[],
+): Promise<{
+  cell: ccc.Cell;
+  scriptInfo: SporeScriptInfo;
+}> {
+  const res = await findSpore(client, args, scripts);
+
+  if (!res) {
+    throw new Error(`Spore ${ccc.hexFrom(args)} not found`);
+  }
+
+  return res;
+}
+
+/**
+ * Create one Spore cell with the specified Spore data.
+ *
+ * @param signer who takes the responsibility to balance and sign the transaction
+ * @param data specific format of data required by Spore protocol
+ * @param to owner of new spore cell, signer if no provided
+ * @param clusterMode how to process cluster cell **(if clusterId is not provided in SporeData, this parameter will be ignored)**
+ *   - undefined: error if the spore has a cluster but the clusterMode is not set
+ *   - lockProxy: put a cell that uses the same lock from Cluster cell in both Inputs and Outputs
+ *   - clusterCell: directly put Cluster cell in Inputs and Outputs
+ *   - skip: don't handle the cluster logic
+ * @param tx the transaction skeleton, if not provided, a new one will be created
+ * @param scriptInfo the script info of Spore cell, if not provided, the default script info will be used
+ * @param scriptInfoHash the script info hash used in cobuild
+ * @returns
+ *  - **tx**: a new transaction that contains created Spore cells
+ *  - **id**: the sporeId of created Spore cell
+ */
+export async function createSpore(params: {
+  signer: ccc.Signer;
+  data: SporeData;
+  to?: ccc.ScriptLike;
+  clusterMode?: "lockProxy" | "clusterCell" | "skip";
+  tx?: ccc.TransactionLike;
+  scriptInfo?: SporeScriptInfoLike;
+  scriptInfoHash?: ccc.HexLike;
+}): Promise<{
+  tx: ccc.Transaction;
+  id: ccc.Hex;
+}> {
+  const { signer, data, to, clusterMode, scriptInfoHash } = params;
+  const scriptInfo = params.scriptInfo ?? getSporeScriptInfo(signer.client);
+
+  // prepare transaction
+  const actions = [];
+  const ids: ccc.Hex[] = [];
+  const tx = ccc.Transaction.from(params.tx ?? {});
+  if (tx.inputs.length === 0) {
+    await injectOneCapacityCell(signer, tx);
+  }
+
+  const { script: lock } = await signer.getRecommendedAddressObj();
+
+  // build spore cell
+  const id = ccc.hashTypeId(tx.inputs[0], tx.outputs.length);
+  ids.push(id);
+
+  const packedData = packRawSporeData(data);
+  tx.addOutput(
+    {
+      lock: to ?? lock,
+      type: {
+        ...scriptInfo,
+        args: id,
+      },
+    },
+    packedData,
+  );
+
+  // create spore action
+  if (scriptInfo.cobuild) {
+    const output = tx.outputs[tx.outputs.length - 1];
+    const createAction = assembleCreateSporeAction(
+      output,
+      packedData,
+      scriptInfoHash,
+    );
+    actions.push(createAction);
+  }
+
+  // complete cellDeps
+  await tx.addCellDepInfos(signer.client, scriptInfo.cellDeps);
+
+  const action = await prepareCluster(signer, tx, data, clusterMode);
+  if (action) {
+    actions.push(action);
+  }
+
+  return {
+    tx: await prepareSporeTransaction(signer, tx, actions),
+    id,
+  };
+}
+
+/**
+ * Transfer one Spore cell
+ *
+ * @param signer who takes the responsibility to balance and sign the transaction
+ * @param id sporeId
+ * @param to Spore's new owner
+ * @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 Spore cells
+ */
+export async function transferSpore(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 ?? {});
+
+  const { cell: sporeCell, scriptInfo } = await assertSpore(signer.client, id);
+  await tx.addCellDepInfos(signer.client, scriptInfo.cellDeps);
+  tx.inputs.push(
+    ccc.CellInput.from({
+      previousOutput: sporeCell.outPoint,
+      ...sporeCell,
+    }),
+  );
+  tx.addOutput(
+    {
+      lock: to,
+      type: sporeCell.cellOutput.type,
+    },
+    sporeCell.outputData,
+  );
+
+  const actions = scriptInfo.cobuild
+    ? [
+        assembleTransferSporeAction(
+          sporeCell.cellOutput,
+          tx.outputs[tx.outputs.length - 1],
+          scriptInfoHash,
+        ),
+      ]
+    : [];
+
+  return {
+    tx: await prepareSporeTransaction(signer, tx, actions),
+  };
+}
+
+/**
+ * Melt one Spore cell
+ *
+ * @param signer who takes the responsibility to balance and sign the transaction
+ * @param id sporeId to be melted
+ * @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 melted Spore cell
+ */
+export async function meltSpore(params: {
+  signer: ccc.Signer;
+  id: ccc.HexLike;
+  tx?: ccc.TransactionLike;
+  scriptInfoHash?: ccc.HexLike;
+}): Promise<{
+  tx: ccc.Transaction;
+}> {
+  const { signer, id, scriptInfoHash } = params;
+
+  // prepare transaction
+  const tx = ccc.Transaction.from(params.tx ?? {});
+
+  // build spore cell
+  const { cell: sporeCell, scriptInfo } = await assertSpore(signer.client, id);
+  await tx.addCellDepInfos(signer.client, scriptInfo.cellDeps);
+  tx.inputs.push(
+    ccc.CellInput.from({
+      previousOutput: sporeCell.outPoint,
+      ...sporeCell,
+    }),
+  );
+
+  const actions = scriptInfo.cobuild
+    ? [assembleMeltSporeAction(sporeCell.cellOutput, scriptInfoHash)]
+    : [];
+
+  return {
+    tx: await prepareSporeTransaction(signer, tx, actions),
+  };
+}

package/typedoc.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["./src/index.ts", "./src/advanced.ts"],
+  "extends": ["../../typedoc.base.json"],
+  "name": "@ckb-ccc spore"
+}