@qubic.ts/contracts 0.1.0

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@qubic.ts/contracts",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "scripts": {
+    "build": "echo \"qubic-ts-contracts build pending\"",
+    "generate": "bun run ./scripts/generate-artifacts.ts",
+    "generate:check": "bun run ./scripts/generate-artifacts.ts --check",
+    "check": "bun run generate:check && bun test ./src/**/*.test.ts",
+    "test": "bun test ./src/**/*.test.ts"
+  }
+}

package/scripts/generate-artifacts.ts

@@ -0,0 +1,178 @@
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import {
+  generateContractCodecs,
+  type GeneratedPerContractFile,
+  generatePerContractFiles,
+  generateRegistryRuntime,
+  generateRegistryTypes,
+} from "../src/generator/index.js";
+import { validateContractsRegistry } from "../src/registry/schema.js";
+
+type CliOptions = Readonly<{
+  check: boolean;
+  registryInput: string;
+  runtimeOutput: string;
+  typesOutput: string;
+  codecsOutput: string;
+  perContractDir: string;
+}>;
+
+const options = parseArgs(process.argv.slice(2));
+
+const sourceRaw = (await Bun.file(options.registryInput).json()) as unknown;
+const registry = validateContractsRegistry(sourceRaw);
+
+const runtimeOutput = generateRegistryRuntime(registry);
+const typesOutput = generateRegistryTypes(registry);
+const codecsOutput = generateContractCodecs(registry);
+const perContractFiles = generatePerContractFiles(registry);
+
+if (options.check) {
+  await assertFileEquals(options.runtimeOutput, runtimeOutput, "runtime registry");
+  await assertFileEquals(options.typesOutput, typesOutput, "registry types");
+  await assertFileEquals(options.codecsOutput, codecsOutput, "contract codecs");
+  await assertPerContractFilesUpToDate(options.perContractDir, perContractFiles);
+  console.log("Generated contracts artifacts are up to date.");
+  process.exit(0);
+}
+
+await writeTextFile(options.runtimeOutput, runtimeOutput);
+await writeTextFile(options.typesOutput, typesOutput);
+await writeTextFile(options.codecsOutput, codecsOutput);
+await writePerContractFiles(options.perContractDir, perContractFiles);
+
+console.log("Generated contracts artifacts:");
+console.log(`- ${options.runtimeOutput}`);
+console.log(`- ${options.typesOutput}`);
+console.log(`- ${options.codecsOutput}`);
+console.log(`- ${options.perContractDir} (${perContractFiles.length * 2} files)`);
+
+function parseArgs(argv: readonly string[]): CliOptions {
+  let check = false;
+  let registryInput = "./src/generated/core-registry.source.json";
+  let runtimeOutput = "./src/generated/core-registry.ts";
+  let typesOutput = "./src/generated/core-registry.types.ts";
+  let codecsOutput = "./src/generated/core-registry.codecs.ts";
+  let perContractDir = "./src/generated/contracts";
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--check") {
+      check = true;
+      continue;
+    }
+    if (arg === "--registry-input") {
+      registryInput = argv[i + 1] ?? registryInput;
+      i++;
+      continue;
+    }
+    if (arg === "--runtime-output") {
+      runtimeOutput = argv[i + 1] ?? runtimeOutput;
+      i++;
+      continue;
+    }
+    if (arg === "--types-output") {
+      typesOutput = argv[i + 1] ?? typesOutput;
+      i++;
+      continue;
+    }
+    if (arg === "--codecs-output") {
+      codecsOutput = argv[i + 1] ?? codecsOutput;
+      i++;
+      continue;
+    }
+    if (arg === "--per-contract-dir") {
+      perContractDir = argv[i + 1] ?? perContractDir;
+      i++;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return {
+    check,
+    registryInput,
+    runtimeOutput,
+    typesOutput,
+    codecsOutput,
+    perContractDir,
+  };
+}
+
+async function writeTextFile(path: string, content: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, content, "utf8");
+}
+
+async function writePerContractFiles(
+  outputDir: string,
+  files: readonly GeneratedPerContractFile[],
+): Promise<void> {
+  await mkdir(outputDir, { recursive: true });
+  await clearExistingGeneratedFiles(outputDir);
+
+  for (const file of files) {
+    await writeFile(join(outputDir, `${file.fileStem}.registry.json`), file.registryJson, "utf8");
+    await writeFile(join(outputDir, `${file.fileStem}.types.ts`), file.typesTs, "utf8");
+  }
+}
+
+async function assertFileEquals(path: string, expected: string, label: string): Promise<void> {
+  const actual = await readFile(path, "utf8").catch(() => null);
+  if (actual === null) {
+    throw new Error(`Missing generated ${label} file: ${path}`);
+  }
+  if (actual !== expected) {
+    throw new Error(`Generated ${label} is out of date: ${path}`);
+  }
+}
+
+async function assertPerContractFilesUpToDate(
+  outputDir: string,
+  files: readonly GeneratedPerContractFile[],
+): Promise<void> {
+  const expected = new Map<string, string>();
+  for (const file of files) {
+    expected.set(`${file.fileStem}.registry.json`, file.registryJson);
+    expected.set(`${file.fileStem}.types.ts`, file.typesTs);
+  }
+
+  const entries = await readdir(outputDir, { withFileTypes: true }).catch(() => []);
+  const existingNames = entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+    .filter((name) => isGeneratedContractFileName(name));
+
+  for (const name of existingNames) {
+    if (!expected.has(name)) {
+      throw new Error(`Unexpected generated file: ${join(outputDir, name)}`);
+    }
+  }
+
+  for (const [name, expectedContent] of expected) {
+    const path = join(outputDir, name);
+    const actual = await readFile(path, "utf8").catch(() => null);
+    if (actual === null) {
+      throw new Error(`Missing generated file: ${path}`);
+    }
+    if (actual !== expectedContent) {
+      throw new Error(`Generated file is out of date: ${path}`);
+    }
+  }
+}
+
+async function clearExistingGeneratedFiles(outputDir: string): Promise<void> {
+  const entries = await readdir(outputDir, { withFileTypes: true }).catch(() => []);
+  await Promise.all(
+    entries
+      .filter((entry) => entry.isFile())
+      .filter((entry) => isGeneratedContractFileName(entry.name))
+      .map((entry) => rm(join(outputDir, entry.name))),
+  );
+}
+
+function isGeneratedContractFileName(name: string): boolean {
+  return name.endsWith(".registry.json") || name.endsWith(".types.ts");
+}

package/src/codec/entry-input.test.ts

@@ -0,0 +1,198 @@
+import { describe, expect, it } from "bun:test";
+import { decodeContractEntryInputData, encodeContractEntryInputData } from "./entry-input.js";
+
+describe("encodeContractEntryInputData", () => {
+  it("encodes and decodes a struct input using castxml offsets", () => {
+    const encoded = encodeContractEntryInputData({
+      registry: makeContracts(),
+      contractName: "QTEST",
+      entryName: "SetConfig",
+      value: {
+        enabled: true,
+        threshold: 500,
+      },
+    });
+
+    expect(encoded.inputType).toBe(7);
+    expect([...encoded.bytes]).toEqual([1, 0, 0, 0, 244, 1, 0, 0]);
+
+    const decoded = decodeContractEntryInputData({
+      registry: makeContracts(),
+      contractName: "QTEST",
+      entryName: "SetConfig",
+      bytes: encoded.bytes,
+    });
+
+    expect(decoded.value).toEqual({
+      enabled: true,
+      threshold: 500,
+    });
+  });
+
+  it("encodes alias types as raw bytes when target type is unknown but byteSize exists", () => {
+    const encoded = encodeContractEntryInputData({
+      registry: makeContracts(),
+      contractName: "QTEST",
+      entryName: "SetRawBlob",
+      value: Uint8Array.of(1, 2, 3, 4),
+    });
+    expect([...encoded.bytes]).toEqual([1, 2, 3, 4]);
+
+    const decoded = decodeContractEntryInputData({
+      registry: makeContracts(),
+      contractName: "QTEST",
+      entryName: "SetRawBlob",
+      bytes: Uint8Array.of(9, 8, 7, 6),
+    });
+    expect(decoded.value).toEqual(Uint8Array.of(9, 8, 7, 6));
+  });
+
+  it("requires layout metadata unless sequential mode is enabled", () => {
+    expect(() =>
+      encodeContractEntryInputData({
+        registry: makeContracts(),
+        contractName: "QTEST",
+        entryName: "SetSequential",
+        value: { first: 1, second: 2 },
+      }),
+    ).toThrow("Missing byteOffset metadata");
+
+    const encoded = encodeContractEntryInputData({
+      registry: makeContracts(),
+      contractName: "QTEST",
+      entryName: "SetSequential",
+      value: { first: 1, second: 2 },
+      allowSequentialLayout: true,
+    });
+    expect([...encoded.bytes]).toEqual([1, 0, 2, 0]);
+  });
+
+  it("resolves namespaced nested type names inside Array declarations", () => {
+    const encoded = encodeContractEntryInputData({
+      registry: makeContracts(),
+      contractName: "QTEST",
+      entryName: "SetOrders",
+      value: {
+        orders: [{ value: 10 }, { value: 20 }],
+      },
+    });
+    expect([...encoded.bytes]).toEqual([10, 0, 20, 0]);
+
+    const decoded = decodeContractEntryInputData({
+      registry: makeContracts(),
+      contractName: "QTEST",
+      entryName: "SetOrders",
+      bytes: encoded.bytes,
+    });
+    expect(decoded.value).toEqual({
+      orders: [{ value: 10 }, { value: 20 }],
+    });
+  });
+});
+
+function makeContracts() {
+  return [
+    {
+      name: "QTEST",
+      contractIndex: 99,
+      address: "QTEST",
+      entries: [
+        {
+          kind: "procedure" as const,
+          name: "SetConfig",
+          inputType: 7,
+          inputTypeName: "SetConfig_input",
+          outputTypeName: "SetConfig_output",
+        },
+        {
+          kind: "procedure" as const,
+          name: "SetRawBlob",
+          inputType: 8,
+          inputTypeName: "SetRawBlob_input",
+          outputTypeName: "SetRawBlob_output",
+        },
+        {
+          kind: "procedure" as const,
+          name: "SetSequential",
+          inputType: 9,
+          inputTypeName: "SetSequential_input",
+          outputTypeName: "SetSequential_output",
+        },
+        {
+          kind: "procedure" as const,
+          name: "SetOrders",
+          inputType: 10,
+          inputTypeName: "SetOrders_input",
+          outputTypeName: "SetOrders_output",
+        },
+      ],
+      ioTypes: [
+        {
+          kind: "struct" as const,
+          name: "SetConfig_input",
+          byteSize: 8,
+          fields: [
+            { name: "enabled", type: "bit", byteOffset: 0 },
+            { name: "threshold", type: "uint32", byteOffset: 4 },
+          ],
+        },
+        {
+          kind: "alias" as const,
+          name: "SetConfig_output",
+          target: "NoData",
+          byteSize: 1,
+        },
+        {
+          kind: "alias" as const,
+          name: "SetRawBlob_input",
+          target: "ExternalBlobType",
+          byteSize: 4,
+        },
+        {
+          kind: "alias" as const,
+          name: "SetRawBlob_output",
+          target: "NoData",
+          byteSize: 1,
+        },
+        {
+          kind: "struct" as const,
+          name: "SetSequential_input",
+          fields: [
+            { name: "first", type: "uint16" },
+            { name: "second", type: "uint16" },
+          ],
+        },
+        {
+          kind: "alias" as const,
+          name: "SetSequential_output",
+          target: "NoData",
+          byteSize: 1,
+        },
+        {
+          kind: "struct" as const,
+          name: "Order",
+          byteSize: 2,
+          fields: [{ name: "value", type: "uint16", byteOffset: 0 }],
+        },
+        {
+          kind: "struct" as const,
+          name: "SetOrders_input",
+          byteSize: 4,
+          fields: [
+            {
+              name: "orders",
+              type: "Array<QTEST::SetOrders_input::Order, 2>",
+              byteOffset: 0,
+            },
+          ],
+        },
+        {
+          kind: "alias" as const,
+          name: "SetOrders_output",
+          target: "NoData",
+          byteSize: 1,
+        },
+      ],
+    },
+  ];
+}