feat: codegen for molecule

.changeset/many-years-tap.md

@@ -0,0 +1,5 @@
+---
+"@ckb-lumos/molecule": minor
+---
+
+feat: cli for generating code from mol files

.changeset/soft-guests-camp.md

@@ -0,0 +1,6 @@
+---
+"@ckb-lumos/codec": patch
+"@ckb-lumos/lumos": patch
+---
+
+feat: export mol layout definition to ensure tsc can infer types

examples/molecule-codegen/README.md

@@ -0,0 +1,32 @@
+# Codegen from Molecule Schema
+
+This example demonstrates how to use the `lumos-molecule-codegen` from the `@ckb-lumos/molecule` package to generate TypeScript code from a Molecule schema.
+
+The [`blockchain.mol`](blockchain.mol) is a revised version from the original one in the nervosnetwork/ckb repository. It has been modified to make the unpacked `HashType` and `DepType` fields human-readable.
+
+The difference is shown below:
+
+```diff
++array HashType [byte;1];
+
+table Script {
+  code_hash: Bytes32;
+- hash_type: byte;
++ hash_type: HashType;
+  args: Bytes;
+}
+```
+
+And we can provide a [`custmoized.ts`](customized.ts) file to override the original `HashType` and `DepType` fields.
+
+To generate the [`blockchain.ts`](blockchain.ts) file from the `blockchain.mol` schema, run the following command:
+
+```sh
+npx lumos-molecule-codegen > blockchain.ts
+```
+
+To test whether the generated code works, run the following command:
+
+```sh
+ts-node main.ts
+```

examples/molecule-codegen/blockchain.mol

@@ -0,0 +1,122 @@
+/* Basic Types */
+
+// The `UintN` is used to store a `N` bits unsigned integer
+// as a byte array in little endian.
+array Uint32 [byte; 4];
+array Uint64 [byte; 8];
+array Uint128 [byte; 16];
+array Byte32 [byte; 32];
+array Uint256 [byte; 32];
+
+vector Bytes <byte>;
+option BytesOpt (Bytes);
+vector BytesOptVec <BytesOpt>;
+vector BytesVec <Bytes>;
+vector Byte32Vec <Byte32>;
+
+/* Types for Chain */
+
+option ScriptOpt (Script);
+
+array ProposalShortId [byte; 10];
+
+vector UncleBlockVec <UncleBlock>;
+vector TransactionVec <Transaction>;
+vector ProposalShortIdVec <ProposalShortId>;
+vector CellDepVec <CellDep>;
+vector CellInputVec <CellInput>;
+vector CellOutputVec <CellOutput>;
+
+array HashType [byte; 1];
+
+table Script {
+    code_hash:      Byte32,
+    hash_type:      HashType,
+    args:           Bytes,
+}
+
+struct OutPoint {
+    tx_hash:        Byte32,
+    index:          Uint32,
+}
+
+struct CellInput {
+    since:           Uint64,
+    previous_output: OutPoint,
+}
+
+table CellOutput {
+    capacity:       Uint64,
+    lock:           Script,
+    type_:          ScriptOpt,
+}
+
+array DepType [byte; 1];
+
+struct CellDep {
+    out_point:      OutPoint,
+    dep_type:       DepType,
+}
+
+table RawTransaction {
+    version:        Uint32,
+    cell_deps:      CellDepVec,
+    header_deps:    Byte32Vec,
+    inputs:         CellInputVec,
+    outputs:        CellOutputVec,
+    outputs_data:   BytesVec,
+}
+
+table Transaction {
+    raw:            RawTransaction,
+    witnesses:      BytesVec,
+}
+
+struct RawHeader {
+    version:                Uint32,
+    compact_target:         Uint32,
+    timestamp:              Uint64,
+    number:                 Uint64,
+    epoch:                  Uint64,
+    parent_hash:            Byte32,
+    transactions_root:      Byte32,
+    proposals_hash:         Byte32,
+    extra_hash:             Byte32,
+    dao:                    Byte32,
+}
+
+struct Header {
+    raw:                    RawHeader,
+    nonce:                  Uint128,
+}
+
+table UncleBlock {
+    header:                 Header,
+    proposals:              ProposalShortIdVec,
+}
+
+table Block {
+    header:                 Header,
+    uncles:                 UncleBlockVec,
+    transactions:           TransactionVec,
+    proposals:              ProposalShortIdVec,
+}
+
+table BlockV1 {
+    header:                 Header,
+    uncles:                 UncleBlockVec,
+    transactions:           TransactionVec,
+    proposals:              ProposalShortIdVec,
+    extension:              Bytes,
+}
+
+table CellbaseWitness {
+    lock:    Script,
+    message: Bytes,
+}
+
+table WitnessArgs {
+    lock:                   BytesOpt,          // Lock args
+    input_type:             BytesOpt,          // Type args for input
+    output_type:            BytesOpt,          // Type args for output
+}

examples/molecule-codegen/blockchain.ts

@@ -0,0 +1,142 @@
+// This file is generated by @ckb-lumos/molecule, please do not modify it manually.
+/* eslint-disable */
+
+import { bytes, createBytesCodec, createFixedBytesCodec, molecule } from "@ckb-lumos/codec";
+import { Uint32, Uint64, Uint128, DepType, HashType } from './customized'
+
+const { array, vector, union, option, struct, table } = molecule;
+
+const fallbackBytesCodec = createBytesCodec({
+  pack: bytes.bytify,
+  unpack: bytes.hexify,
+});
+
+function createFallbackFixedBytesCodec(byteLength: number) {
+  return createFixedBytesCodec({
+    pack: bytes.bytify,
+    unpack: bytes.hexify,
+    byteLength,
+  });
+}
+
+const byte = createFallbackFixedBytesCodec(1);
+
+export const Byte32 = createFallbackFixedBytesCodec(32);
+
+export const Uint256 = createFallbackFixedBytesCodec(32);
+
+export const Bytes = fallbackBytesCodec;
+
+export const BytesOpt = option(Bytes);
+
+export const BytesOptVec = vector(BytesOpt);
+
+export const BytesVec = vector(Bytes);
+
+export const Byte32Vec = vector(Byte32);
+
+export const ProposalShortId = createFallbackFixedBytesCodec(10);
+
+export const ProposalShortIdVec = vector(ProposalShortId);
+
+export const Script = table({
+  codeHash: Byte32,
+  hashType: HashType,
+  args: Bytes
+}, ['codeHash', 'hashType', 'args']);
+
+export const OutPoint = struct({
+  txHash: Byte32,
+  index: Uint32
+}, ['txHash', 'index']);
+
+export const CellInput = struct({
+  since: Uint64,
+  previousOutput: OutPoint
+}, ['since', 'previousOutput']);
+
+export const CellDep = struct({
+  outPoint: OutPoint,
+  depType: DepType
+}, ['outPoint', 'depType']);
+
+export const RawHeader = struct({
+  version: Uint32,
+  compactTarget: Uint32,
+  timestamp: Uint64,
+  number: Uint64,
+  epoch: Uint64,
+  parentHash: Byte32,
+  transactionsRoot: Byte32,
+  proposalsHash: Byte32,
+  extraHash: Byte32,
+  dao: Byte32
+}, ['version', 'compactTarget', 'timestamp', 'number', 'epoch', 'parentHash', 'transactionsRoot', 'proposalsHash', 'extraHash', 'dao']);
+
+export const Header = struct({
+  raw: RawHeader,
+  nonce: Uint128
+}, ['raw', 'nonce']);
+
+export const UncleBlock = table({
+  header: Header,
+  proposals: ProposalShortIdVec
+}, ['header', 'proposals']);
+
+export const CellbaseWitness = table({
+  lock: Script,
+  message: Bytes
+}, ['lock', 'message']);
+
+export const WitnessArgs = table({
+  lock: BytesOpt,
+  inputType: BytesOpt,
+  outputType: BytesOpt
+}, ['lock', 'inputType', 'outputType']);
+
+export const ScriptOpt = option(Script);
+
+export const UncleBlockVec = vector(UncleBlock);
+
+export const CellDepVec = vector(CellDep);
+
+export const CellInputVec = vector(CellInput);
+
+export const CellOutput = table({
+  capacity: Uint64,
+  lock: Script,
+  type_: ScriptOpt
+}, ['capacity', 'lock', 'type_']);
+
+export const CellOutputVec = vector(CellOutput);
+
+export const RawTransaction = table({
+  version: Uint32,
+  cellDeps: CellDepVec,
+  headerDeps: Byte32Vec,
+  inputs: CellInputVec,
+  outputs: CellOutputVec,
+  outputsData: BytesVec
+}, ['version', 'cellDeps', 'headerDeps', 'inputs', 'outputs', 'outputsData']);
+
+export const Transaction = table({
+  raw: RawTransaction,
+  witnesses: BytesVec
+}, ['raw', 'witnesses']);
+
+export const TransactionVec = vector(Transaction);
+
+export const Block = table({
+  header: Header,
+  uncles: UncleBlockVec,
+  transactions: TransactionVec,
+  proposals: ProposalShortIdVec
+}, ['header', 'uncles', 'transactions', 'proposals']);
+
+export const BlockV1 = table({
+  header: Header,
+  uncles: UncleBlockVec,
+  transactions: TransactionVec,
+  proposals: ProposalShortIdVec,
+  extension: Bytes
+}, ['header', 'uncles', 'transactions', 'proposals', 'extension']);

examples/molecule-codegen/customized.ts

@@ -0,0 +1,55 @@
+import { createFixedBytesCodec, number } from "@ckb-lumos/codec";
+
+const { Uint32, Uint64, Uint128 } = number;
+
+/**
+ * <pre>
+ *  0b0000000 0
+ *    ───┬─── │
+ *       │    ▼
+ *       │   type - the last bit indicates locating contract(script) via type hash and runs in the latest version of the CKB-VM
+ *       │
+ *       ▼
+ * data* - the first 7 bits indicate locating contract(script) via code hash and runs in the specified version of the CKB-VM
+ * </pre>
+ *
+ */
+const HashType = createFixedBytesCodec<"data" | "type" | "data1" | "data2">({
+  byteLength: 1,
+  // prettier-ignore
+  pack: (hashType) => {
+    if (hashType === "type")  return new Uint8Array([0b0000000_1]);
+    if (hashType === "data")  return new Uint8Array([0b0000000_0]);
+    if (hashType === "data1") return new Uint8Array([0b0000001_0]);
+    if (hashType === "data2") return new Uint8Array([0b0000010_0]);
+
+    throw new Error('Unknown hash type')
+  },
+  unpack: (byte) => {
+    if (byte[0] === 0b0000000_1) return "type";
+    if (byte[0] === 0b0000000_0) return "data";
+    if (byte[0] === 0b0000001_0) return "data1";
+    if (byte[0] === 0b0000010_0) return "data2";
+
+    throw new Error("Unknown hash type");
+  },
+});
+
+const DepType = createFixedBytesCodec<"code" | "depGroup">({
+  byteLength: 1,
+  // prettier-ignore
+  pack: (depType) => {
+    if (depType === "code")     return new Uint8Array([0]);
+    if (depType === "depGroup") return new Uint8Array([1]);
+
+    throw new Error("Unknown dep type");
+  },
+  unpack: (byte) => {
+    if (byte[0] === 0) return "code";
+    if (byte[0] === 1) return "depGroup";
+
+    throw new Error("Unknown dep type");
+  },
+});
+
+export { Uint32, Uint64, Uint128, DepType, HashType };

examples/molecule-codegen/lumos-molecule-codegen.json

@@ -0,0 +1,5 @@
+{
+  "objectKeyFormat": "camelcase",
+  "prepend": "import { Uint32, Uint64, Uint128, DepType, HashType } from './customized'",
+  "schemaFile": "blockchain.mol"
+}

examples/molecule-codegen/main.ts

@@ -0,0 +1,7 @@
+import { Script } from "./blockchain";
+
+const packed = Script.pack({ codeHash: new Uint8Array(32), hashType: "type", args: "0xdeadbeef" });
+const unpacked = Script.unpack(packed);
+
+console.log("packed script", packed);
+console.log("unpacked script", unpacked);

examples/molecule-codegen/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@lumos-example/misc",
+  "private": true,
+  "version": "1.0.0",
+  "license": "MIT",
+  "dependencies": {
+    "@ckb-lumos/codec": "canary"
+  },
+  "devDependencies": {
+    "@ckb-lumos/molecule": "canary"
+  }
+}