@ckb-ccc/spore 0.1.0-alpha.2

package/src/codec/cobuild/sporeAction.ts

@@ -0,0 +1,153 @@
+import { blockchain } from "@ckb-lumos/base";
+import { molecule } from "@ckb-lumos/codec";
+
+const Hash = blockchain.Byte32;
+
+export const Address = molecule.union(
+  {
+    Script: blockchain.Script,
+  },
+  ["Script"],
+);
+
+/**
+ * Spore
+ */
+export const CreateSpore = molecule.table(
+  {
+    sporeId: Hash,
+    to: Address,
+    dataHash: Hash,
+  },
+  ["sporeId", "to", "dataHash"],
+);
+export const TransferSpore = molecule.table(
+  {
+    sporeId: Hash,
+    from: Address,
+    to: Address,
+  },
+  ["sporeId", "from", "to"],
+);
+export const MeltSpore = molecule.table(
+  {
+    sporeId: Hash,
+    from: Address,
+  },
+  ["sporeId", "from"],
+);
+
+/**
+ * Cluster
+ */
+export const CreateCluster = molecule.table(
+  {
+    clusterId: Hash,
+    to: Address,
+    dataHash: Hash,
+  },
+  ["clusterId", "to", "dataHash"],
+);
+export const TransferCluster = molecule.table(
+  {
+    clusterId: Hash,
+    from: Address,
+    to: Address,
+  },
+  ["clusterId", "from", "to"],
+);
+
+/**
+ * ClusterProxy
+ */
+export const CreateClusterProxy = molecule.table(
+  {
+    clusterId: Hash,
+    clusterProxyId: Hash,
+    to: Address,
+  },
+  ["clusterId", "clusterProxyId", "to"],
+);
+export const TransferClusterProxy = molecule.table(
+  {
+    clusterId: Hash,
+    clusterProxyId: Hash,
+    from: Address,
+    to: Address,
+  },
+  ["clusterId", "clusterProxyId", "from", "to"],
+);
+export const MeltClusterProxy = molecule.table(
+  {
+    clusterId: Hash,
+    clusterProxyId: Hash,
+    from: Address,
+  },
+  ["clusterId", "clusterProxyId", "from"],
+);
+
+/**
+ * ClusterAgent
+ */
+export const CreateClusterAgent = molecule.table(
+  {
+    clusterId: Hash,
+    clusterProxyId: Hash,
+    to: Address,
+  },
+  ["clusterId", "clusterProxyId", "to"],
+);
+export const TransferClusterAgent = molecule.table(
+  {
+    clusterId: Hash,
+    from: Address,
+    to: Address,
+  },
+  ["clusterId", "from", "to"],
+);
+export const MeltClusterAgent = molecule.table(
+  {
+    clusterId: Hash,
+    from: Address,
+  },
+  ["clusterId", "from"],
+);
+
+/**
+ * Spore ScriptInfo Actions
+ */
+export const SporeAction = molecule.union(
+  {
+    // Spore
+    CreateSpore,
+    TransferSpore,
+    MeltSpore,
+
+    // Cluster
+    CreateCluster,
+    TransferCluster,
+
+    // ClusterProxy
+    CreateClusterProxy,
+    TransferClusterProxy,
+    MeltClusterProxy,
+
+    // ClusterAgent
+    CreateClusterAgent,
+    TransferClusterAgent,
+    MeltClusterAgent,
+  },
+  [
+    "CreateSpore",
+    "TransferSpore",
+    "MeltSpore",
+    "CreateCluster",
+    "TransferCluster",
+    "CreateClusterProxy",
+    "TransferClusterProxy",
+    "MeltClusterProxy",
+    "CreateClusterAgent",
+    "TransferClusterAgent",
+    "MeltClusterAgent",
+  ],
+);

package/src/codec/cobuild/witnessLayout.ts

@@ -0,0 +1,40 @@
+import { blockchain } from "@ckb-lumos/base";
+import { molecule } from "@ckb-lumos/codec";
+import { Message } from "./buildingPacket.js";
+
+export const SighashAll = molecule.table(
+  {
+    seal: blockchain.Bytes,
+    message: Message,
+  },
+  ["seal", "message"],
+);
+export const SighashAllOnly = molecule.table(
+  {
+    seal: blockchain.Bytes,
+  },
+  ["seal"],
+);
+
+/**
+ * Otx related are not implemented yet, so just placeholders.
+ */
+export const Otx = molecule.table({}, []);
+export const OtxStart = molecule.table({}, []);
+
+export const WitnessLayoutFieldTags = {
+  SighashAll: 4278190081,
+  SighashAllOnly: 4278190082,
+  Otx: 4278190083,
+  OtxStart: 4278190084,
+} as const;
+
+export const WitnessLayout = molecule.union(
+  {
+    SighashAll,
+    SighashAllOnly,
+    Otx,
+    OtxStart,
+  },
+  WitnessLayoutFieldTags,
+);

package/src/codec/index.ts

@@ -0,0 +1,3 @@
+export * from "./cluster.js";
+export * from "./cobuild/index.js";
+export * from "./spore.js";

package/src/codec/spore.ts

@@ -0,0 +1,36 @@
+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 MolSporeData = molecule.table(
+  {
+    contentType: RawString,
+    content: blockchain.Bytes,
+    clusterId: blockchain.BytesOpt,
+  },
+  ["contentType", "content", "clusterId"],
+);
+
+export interface SporeData {
+  contentType: string;
+  content: ccc.BytesLike;
+  clusterId?: ccc.HexLike;
+}
+
+export function packRawSporeData(packable: SporeData): Uint8Array {
+  return MolSporeData.pack({
+    contentType: packable.contentType,
+    content: packable.content,
+    clusterId: packable.clusterId,
+  });
+}
+
+export function unpackToRawSporeData(unpackable: ccc.BytesLike): SporeData {
+  const unpacked = MolSporeData.unpack(unpackable);
+  return {
+    contentType: unpacked.contentType,
+    content: unpacked.content,
+    clusterId: ccc.apply(ccc.hexFrom, unpacked.clusterId),
+  };
+}

package/src/dob/api/decode.ts

@@ -0,0 +1,61 @@
+import { ccc } from "@ckb-ccc/core";
+import { Axios } from "axios";
+import { getErrorByCode } from "../helper/error.js";
+import { RenderOutput } from "../helper/object.js";
+
+export async function decodeDobBySporeId(
+  sporeId: ccc.HexLike,
+  dobServerUrl: string,
+): Promise<RenderOutput> {
+  const axios = new Axios({
+    baseURL: dobServerUrl,
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+  });
+  const result = await axios.post(
+    "/",
+    JSON.stringify({
+      id: 0,
+      jsonrpc: "2.0",
+      method: "dob_decode",
+      params: [ccc.hexFrom(sporeId).replace(/^0x/, "")],
+    }),
+  );
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-argument
+  const decoderResult = JSON.parse(result.data);
+  if ("error" in decoderResult) {
+    const serverError = getErrorByCode(decoderResult.error.code as number);
+    throw new Error(`Decode DOB failed: ${serverError}`);
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-argument
+  const renderResult = JSON.parse(decoderResult.result);
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-argument
+  const renderOutput = JSON.parse(renderResult.render_output);
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+  return renderOutput;
+}
+
+export async function decodeDobBySporeCell(
+  sporeOutput: ccc.CellOutputLike,
+  dobServerUrl: string,
+): Promise<RenderOutput> {
+  const sporeId = sporeOutput.type?.args;
+  if (sporeId === undefined) {
+    throw new Error("Invalid spore cell: missing spore id");
+  }
+  return decodeDobBySporeId(ccc.hexFrom(sporeId), dobServerUrl);
+}
+
+export async function decodeDobBySporeOutpoint(
+  client: ccc.Client,
+  sporeOutpoint: ccc.OutPointLike,
+  dobServerUrl: string,
+): Promise<RenderOutput> {
+  const liveCell = await client.getCell(sporeOutpoint);
+  if (!liveCell) {
+    throw new Error("Invalid spore outpoint: missing spore cell");
+  }
+  return decodeDobBySporeCell(liveCell.cellOutput, dobServerUrl);
+}

package/src/dob/api/encode.ts

@@ -0,0 +1,84 @@
+import {
+  checkDecoder,
+  checkPatternDob0,
+  checkPatternDob1,
+  DNA,
+  Dob0,
+  Dob1,
+} from "../helper/index.js";
+
+export function encodeDna(dna: DNA): ArrayBuffer {
+  const encoder = new TextEncoder();
+  return encoder.encode(JSON.stringify(dna));
+}
+
+export function encodeClusterDescriptionForDob0(dob0: Dob0): string {
+  checkDecoder(dob0.dob.decoder);
+  dob0.dob.pattern.forEach((v) => {
+    checkPatternDob0(v);
+    v.toJSON = function () {
+      if (v.traitArgs) {
+        return [
+          v.traitName,
+          v.dobType,
+          v.dnaOffset,
+          v.dnaLength,
+          v.patternType,
+          v.traitArgs,
+        ];
+      } else {
+        return [
+          v.traitName,
+          v.dobType,
+          v.dnaOffset,
+          v.dnaLength,
+          v.patternType,
+        ];
+      }
+    };
+  });
+  return JSON.stringify(dob0);
+}
+
+export function encodeClusterDescriptionForDob1(dob1: Dob1): string {
+  dob1.dob.decoders.forEach((value) => {
+    checkDecoder(value.decoder);
+    value.pattern.forEach((v) => {
+      if ("dnaOffset" in v) {
+        checkPatternDob0(v);
+        v.toJSON = function () {
+          if (v.traitArgs) {
+            return [
+              v.traitName,
+              v.dobType,
+              v.dnaOffset,
+              v.dnaLength,
+              v.patternType,
+              v.traitArgs,
+            ];
+          } else {
+            return [
+              v.traitName,
+              v.dobType,
+              v.dnaOffset,
+              v.dnaLength,
+              v.patternType,
+            ];
+          }
+        };
+      } else {
+        checkPatternDob1(v);
+        v.toJSON = () => {
+          return [
+            v.imageName,
+            v.svgFields,
+            v.traitName,
+            v.patternType,
+            v.traitArgs,
+          ];
+        };
+      }
+    });
+  });
+  return JSON.stringify(dob1);
+}

package/src/dob/api/index.ts

@@ -0,0 +1,2 @@
+export * from "./decode.js";
+export * from "./encode.js";

package/src/dob/config/index.ts

@@ -0,0 +1 @@
+export * from "./predefined.js";

package/src/dob/config/predefined.ts

@@ -0,0 +1,71 @@
+import { ccc } from "@ckb-ccc/core";
+import { Decoder } from "../helper/index.js";
+
+export type DobType = "dob0" | "dob1";
+export type DobScriptInfo = Record<DobType, Decoder>;
+
+export const DOB_TESTNET_DECODERS: DobScriptInfo = Object.freeze({
+  ["dob0"]: {
+    type: "code_hash",
+    hash: "0x13cac78ad8482202f18f9df4ea707611c35f994375fa03ae79121312dda9925c",
+  },
+  // another avaliable options:
+  // {
+  //   type: "type_id",
+  //   hash: "0x784e32cef202b9d4759ea96e80d806f94051e8069fd34d761f452553700138d7",
+  // }
+  // or
+  // {
+  //   type: "type_script",
+  //   script: {
+  //     code_hash:
+  //       "0x00000000000000000000000000000000000000000000000000545950455f4944",
+  //     hash_type: "type",
+  //     args: "0x784e32cef202b9d4759ea96e80d806f94051e8069fd34d761f452553700138d7",
+  //   }
+  // }
+  ["dob1"]: {
+    type: "code_hash",
+    hash: "0xda3525549b72970b4c95f5b5749357f20d1293d335710b674f09c32f7d54b6dc",
+  },
+});
+
+export const DOB_MAINNET_DECODERS: DobScriptInfo = Object.freeze({
+  ["dob0"]: {
+    type: "code_hash",
+    hash: "0x13cac78ad8482202f18f9df4ea707611c35f994375fa03ae79121312dda9925c",
+  },
+  // another avaliable options:
+  // {
+  //   type: "type_id",
+  //   hash: "0x8892bea4405a1f077921799bc0f4516e0ebaef7aea0dfc6614a8898fb47d5372",
+  // },
+  // or
+  // {
+  //   type: "type_script",
+  //   script: {
+  //     code_hash:
+  //       "0x00000000000000000000000000000000000000000000000000545950455f4944",
+  //     hash_type: "type",
+  //     args: "0x8892bea4405a1f077921799bc0f4516e0ebaef7aea0dfc6614a8898fb47d5372",
+  //   }
+  // }
+  ["dob1"]: {
+    type: "code_hash",
+    hash: "0xda3525549b72970b4c95f5b5749357f20d1293d335710b674f09c32f7d54b6dc",
+  },
+});
+
+export function getDecoder(
+  client: ccc.Client,
+  dobType: DobType,
+  dobScriptInfo?: DobScriptInfo,
+): Decoder {
+  if (dobScriptInfo) {
+    return dobScriptInfo[dobType];
+  }
+  if (client.addressPrefix === "ckb") {
+    return DOB_MAINNET_DECODERS[dobType];
+  }
+  return DOB_TESTNET_DECODERS[dobType];
+}

package/src/dob/helper/check.ts

@@ -0,0 +1,107 @@
+import { Decoder, PatternElementDob0, PatternElementDob1 } from "./object.js";
+
+export function checkDecoder(decoder: Decoder) {
+  if (decoder.type === "code_hash" || decoder.type === "type_id") {
+    if (decoder.hash === undefined) {
+      throw new Error(
+        "Invalid decoder: 'hash' is required for 'code_hash' and 'type_id'",
+      );
+    }
+  }
+  if (decoder.type === "type_script" && decoder.script === undefined) {
+    throw new Error("Invalid decoder: 'script' is required for 'type_script'");
+  }
+}
+
+export function checkPatternDob0(value: PatternElementDob0) {
+  switch (value.patternType) {
+    case "options": {
+      if (value.traitArgs === undefined) {
+        throw new Error(
+          "Invalid pattern: 'traitArgs' is required for 'options'",
+        );
+      }
+      if (value.traitArgs.length === 0) {
+        throw new Error(
+          "Invalid pattern: 'traitArgs' should not be empty for 'options'",
+        );
+      }
+      break;
+    }
+    case "range": {
+      if (value.traitArgs === undefined) {
+        throw new Error("Invalid pattern: 'traitArgs' is required for 'range'");
+      }
+      if (
+        value.traitArgs.length !== 2 ||
+        value.traitArgs.filter((v) => typeof v === "number").length !== 2
+      ) {
+        throw new Error(
+          "Invalid pattern: 'traitArgs' should contain exactly 2 numbers for 'range'",
+        );
+      }
+      break;
+    }
+  }
+  if (value.dnaLength === 0) {
+    throw new Error("Invalid pattern: 'dnaLength' should be greater than 0");
+  }
+}
+
+export function checkPatternDob1(value: PatternElementDob1) {
+  switch (value.patternType) {
+    case "options": {
+      if (!Array.isArray(value.traitArgs)) {
+        throw new Error(
+          "Invalid pattern: 'traitArgs' should be an array for 'options'",
+        );
+      }
+      for (const args of value.traitArgs) {
+        if (args.length !== 2) {
+          throw new Error(
+            "Invalid pattern: 'traitArgs' should contain exactly 2 elements for 'options'",
+          );
+        }
+        if (typeof args[0] !== "string") {
+          if (!Array.isArray(args[0])) {
+            throw new Error(
+              "Invalid pattern: 'traitArgs[0]' should be a string or an array that contains only 2 numbers or the '*' for 'options'",
+            );
+          }
+          if (args[0].length === 1 && args[0][0] !== "*") {
+            throw new Error(
+              "Invalid pattern: 'traitArgs[0]' should be a string or an array that contains only 2 numbers or the '*' for 'options'",
+            );
+          }
+          if (
+            args[0].length === 2 &&
+            (typeof args[0][0] !== "number" || typeof args[0][1] !== "number")
+          ) {
+            throw new Error(
+              "Invalid pattern: 'traitArgs[0]' should be a string or an array that contains only 2 numbers or the '*' for 'options'",
+            );
+          }
+          if (args[0].length === 0 || args[0].length > 2) {
+            throw new Error(
+              "Invalid pattern: 'traitArgs[0]' should be a string or an array that contains only 2 numbers or the '*' for 'options'",
+            );
+          }
+        }
+        if (typeof args[1] !== "string") {
+          throw new Error(
+            "Invalid pattern: 'traitArgs[1]' should be a string for 'options'",
+          );
+        }
+      }
+      break;
+    }
+    case "raw": {
+      if (value.traitName !== "" || typeof value.traitArgs !== "string") {
+        throw new Error(
+          "Invalid pattern: 'traitName' should be empty and 'traitArgs' should be a string for 'raw'",
+        );
+      }
+      break;
+    }
+  }
+}

package/src/dob/helper/error.ts

@@ -0,0 +1,41 @@
+const errors = {
+  1001: "DnaLengthNotMatch",
+  1002: "SporeIdLengthInvalid",
+  1003: "NativeDecoderNotFound",
+  1004: "SporeIdNotFound",
+  1005: "SporeDataUncompatible",
+  1006: "SporeDataContentTypeUncompatible",
+  1007: "DOBVersionUnexpected",
+  1008: "ClusterIdNotSet",
+  1009: "ClusterIdNotFound",
+  1010: "ClusterDataUncompatible",
+  1011: "DecoderIdNotFound",
+  1012: "DecoderOutputInvalid",
+  1013: "HexedDNAParseError",
+  1014: "HexedSporeIdParseError",
+  1015: "DecoderBinaryPathInvalid",
+  1016: "DecoderExecutionError",
+  1017: "DecoderExecutionInternalError",
+  1018: "FetchLiveCellsError",
+  1019: "FetchTransactionError",
+  1020: "NoOutputCellInTransaction",
+  1021: "DOBContentUnexpected",
+  1022: "DOBMetadataUnexpected",
+  1023: "DOBRenderCacheNotFound",
+  1024: "DOBRenderCacheModified",
+  1025: "DecoderBinaryHashInvalid",
+  1026: "DecoderBinaryNotFoundInCell",
+  1027: "JsonRpcRequestError",
+  1028: "SystemTimeError",
+  1029: "DecoderHashNotFound",
+  1030: "DecoderScriptNotFound",
+  1031: "DecoderChainIsEmpty",
+};
+
+export function getErrorByCode(code: number): string {
+  const errorIndex = Object.keys(errors).indexOf(code.toString());
+  if (errorIndex < 0) {
+    throw new Error(`Error code ${code} not found`);
+  }
+  return Object.values(errors)[errorIndex];
+}

package/src/dob/helper/index.ts

@@ -0,0 +1,2 @@
+export * from "./check.js";
+export * from "./object.js";

package/src/dob/helper/object.ts

@@ -0,0 +1,66 @@
+export type DNA = string | { dna: string } | string[];
+
+export interface Decoder {
+  type: "code_hash" | "type_id" | "type_script";
+  hash?: string; // required if `type` is `code_hash` or `type_id`
+  script?: {
+    code_hash: string;
+    hash_type: string;
+    args: string;
+  }; // required if `type` is `type_script`
+}
+
+export interface PatternElementDob0 {
+  traitName: string;
+  dobType: string; // String | Number
+  dnaOffset: number;
+  dnaLength: number;
+  patternType: "options" | "range" | "rawNumber" | "rawString" | "utf8";
+  traitArgs?: string[] | number[]; // can only be `undefined` in case that `patternType` is `rawNumber` or `rawString`
+  toJSON?: () => unknown;
+}
+
+export interface PatternDob0 {
+  ver: 0;
+  decoder: Decoder;
+  pattern: PatternElementDob0[];
+}
+
+export interface Dob0 {
+  description: string;
+  dob: PatternDob0;
+}
+
+export type Dob1PatternArgs = string | number[] | ["*"];
+
+export interface PatternElementDob1 {
+  imageName: string;
+  svgFields: "attributes" | "elements";
+  traitName: string; // can only be empty in case that `patternType` is `raw`
+  patternType: "options" | "raw";
+  traitArgs: Dob1PatternArgs[][] | string; // can only be `string` in case that `patternType` is `raw`
+  toJSON?: () => unknown;
+}
+
+export interface PatternDob1 {
+  ver: 1;
+  decoders: {
+    decoder: Decoder;
+    pattern: PatternElementDob0[] | PatternElementDob1[];
+  }[];
+}
+
+export interface Dob1 {
+  description: string;
+  dob: PatternDob1;
+}
+
+export interface DecodeElement {
+  name: string;
+  traits: {
+    type: string;
+    value: number | string;
+  }[];
+}
+
+export type RenderOutput = DecodeElement[];

package/src/dob/index.ts

@@ -0,0 +1,3 @@
+export * from "./api/index.js";
+export * from "./config/index.js";
+export * from "./helper/index.js";