@qubic.ts/contracts 0.1.0

package/src/generator/per-contract-files.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "bun:test";
+import type { ContractsRegistry } from "../registry/types.js";
+import { generatePerContractFiles } from "./per-contract-files.js";
+
+describe("generatePerContractFiles", () => {
+  it("generates one registry json and one typings file per contract", () => {
+    const output = generatePerContractFiles(makeFixture(), {
+      banner: "// generated",
+    });
+
+    expect(output).toHaveLength(2);
+
+    const qutil = output.find((item) => item.contractName === "QUTIL");
+    const qvault = output.find((item) => item.contractName === "QVAULT");
+    expect(qutil).toBeDefined();
+    expect(qvault).toBeDefined();
+
+    expect(qutil?.fileStem).toBe("QUTIL");
+    expect(qutil?.registryJson).toContain('"contractName": "QUTIL"');
+    expect(qutil?.registryJson).toContain('"contractIndex": 4');
+    expect(qutil?.typesTs).toContain("export interface ContractTypeMap {");
+    expect(qutil?.typesTs).toContain("QUTIL: {");
+    expect(qutil?.typesTs).toContain("// generated");
+    expect(qvault?.registryJson).toContain('"contractName": "QVAULT"');
+  });
+
+  it("is deterministic for equivalent input", () => {
+    const first = generatePerContractFiles(makeFixture());
+    const second = generatePerContractFiles(makeFixture());
+    expect(first).toEqual(second);
+  });
+
+  it("throws when contract address is not a valid identity", () => {
+    const fixture = makeFixture();
+    const broken: ContractsRegistry = {
+      ...fixture,
+      contracts: fixture.contracts.map((contract) =>
+        contract.name === "QUTIL" ? { ...contract, address: "QUTIL" } : contract,
+      ),
+    };
+    expect(() => generatePerContractFiles(broken)).toThrow("invalid address");
+  });
+});
+
+function makeFixture(): ContractsRegistry {
+  return {
+    version: 1,
+    metadata: {
+      generatedAt: "2026-02-18T00:00:00.000Z",
+      sources: [{ name: "qubic/core" }],
+    },
+    contracts: [
+      {
+        name: "QVAULT",
+        contractIndex: 10,
+        address: "KAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAHFSW",
+        entries: [{ kind: "procedure", name: "SubmitAuthAddress", inputType: 7 }],
+      },
+      {
+        name: "QUTIL",
+        contractIndex: 4,
+        address: "EAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAVWRF",
+        entries: [
+          { kind: "procedure", name: "BurnQubic", inputType: 2 },
+          { kind: "function", name: "GetFees", inputType: 1 },
+        ],
+      },
+    ],
+  };
+}

package/src/generator/per-contract-files.ts

@@ -0,0 +1,122 @@
+import { normalizeContractsRegistry } from "../registry/normalize.js";
+import type {
+  ContractDefinition,
+  ContractEntry,
+  ContractIoTypeDefinition,
+  ContractsRegistry,
+} from "../registry/types.js";
+import { generateContractCodecs } from "./contract-codecs.js";
+
+export type GeneratePerContractFilesOptions = Readonly<{
+  banner?: string;
+}>;
+
+export type GeneratedPerContractFile = Readonly<{
+  contractName: string;
+  fileStem: string;
+  registryJson: string;
+  typesTs: string;
+}>;
+
+export type PerContractRegistryEntry = Readonly<{
+  kind: ContractEntry["kind"];
+  name: string;
+  inputType: number;
+  inputTypeName?: string;
+  outputTypeName?: string;
+  inputSize?: number;
+  outputSize?: number;
+}>;
+
+export type PerContractRegistry = Readonly<{
+  contractName: string;
+  contractIndex: number;
+  filename?: string;
+  address: string;
+  entries: readonly PerContractRegistryEntry[];
+  ioTypes?: readonly ContractIoTypeDefinition[];
+}>;
+
+export function generatePerContractFiles(
+  registry: ContractsRegistry,
+  options: GeneratePerContractFilesOptions = {},
+): readonly GeneratedPerContractFile[] {
+  const normalized = normalizeContractsRegistry(registry);
+  const usedStems = new Set<string>();
+
+  return normalized.contracts.map((contract) => {
+    const fileStem = uniqueStem(toFileStem(contract.name), usedStems);
+    const singleContractRegistry = makeSingleContractRegistry(normalized, contract);
+    const perContractRegistry = makePerContractRegistry(contract);
+
+    return {
+      contractName: contract.name,
+      fileStem,
+      registryJson: `${JSON.stringify(perContractRegistry, null, 2)}\n`,
+      typesTs: generateContractCodecs(singleContractRegistry, {
+        ...(options.banner ? { banner: options.banner } : {}),
+      }),
+    };
+  });
+}
+
+function makeSingleContractRegistry(
+  registry: ContractsRegistry,
+  contract: ContractDefinition,
+): ContractsRegistry {
+  return {
+    version: 1,
+    metadata: registry.metadata,
+    contracts: [contract],
+  };
+}
+
+function makePerContractRegistry(contract: ContractDefinition): PerContractRegistry {
+  if (!isLikelyIdentityAddress(contract.address)) {
+    throw new Error(
+      `Contract ${contract.name} has invalid address "${contract.address}". Use static-enriched contract data for per-contract export.`,
+    );
+  }
+
+  return {
+    contractName: contract.name,
+    contractIndex: contract.contractIndex,
+    filename: contract.filename,
+    address: contract.address,
+    entries: contract.entries.map((entry) => ({
+      kind: entry.kind,
+      name: entry.name,
+      inputType: entry.inputType,
+      inputTypeName: entry.inputTypeName,
+      outputTypeName: entry.outputTypeName,
+      inputSize: entry.inputSize,
+      outputSize: entry.outputSize,
+    })),
+    ioTypes: contract.ioTypes,
+  };
+}
+
+function isLikelyIdentityAddress(value: string): boolean {
+  return /^[A-Z]{60}$/.test(value);
+}
+
+function toFileStem(value: string): string {
+  const cleaned = value
+    .trim()
+    .replace(/[^A-Za-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return cleaned.length > 0 ? cleaned : "contract";
+}
+
+function uniqueStem(base: string, usedStems: Set<string>): string {
+  if (!usedStems.has(base)) {
+    usedStems.add(base);
+    return base;
+  }
+
+  let suffix = 2;
+  while (usedStems.has(`${base}-${suffix}`)) suffix += 1;
+  const resolved = `${base}-${suffix}`;
+  usedStems.add(resolved);
+  return resolved;
+}

package/src/generator/registry-runtime.fixture.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "bun:test";
+import { validateContractsRegistry } from "../registry/index.js";
+import { generateRegistryRuntime } from "./registry-runtime.js";
+
+describe("generateRegistryRuntime fixture", () => {
+  it("matches the expected generated file", async () => {
+    const fixturePath = new URL("../../test/fixtures/registry.sample.json", import.meta.url);
+    const expectedPath = new URL("../../test/fixtures/registry.sample.runtime.ts", import.meta.url);
+
+    const fixtureRaw = (await Bun.file(fixturePath).json()) as unknown;
+    const expected = await Bun.file(expectedPath).text();
+    const registry = validateContractsRegistry(fixtureRaw);
+    const generated = generateRegistryRuntime(registry);
+
+    expect(generated).toBe(expected);
+  });
+});

package/src/generator/registry-runtime.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "bun:test";
+import type { ContractsRegistry } from "../registry/types.js";
+import { generateRegistryRuntime } from "./registry-runtime.js";
+
+describe("generateRegistryRuntime", () => {
+  it("renders a typed runtime registry export", () => {
+    const output = generateRegistryRuntime(makeFixture(), {
+      banner: "/* test */",
+      exportName: "testRegistry",
+    });
+
+    expect(output).toContain('import type { ContractsRegistry } from "../registry/types.js";');
+    expect(output).toContain("export const testRegistry = {");
+    expect(output).toContain("satisfies ContractsRegistry;");
+    expect(output).toContain("export const coreContractDefinitions = testRegistry.contracts;");
+  });
+
+  it("is deterministic for equivalent input", () => {
+    const first = generateRegistryRuntime(makeFixture());
+    const second = generateRegistryRuntime(makeFixture());
+    expect(first).toBe(second);
+  });
+});
+
+function makeFixture(): ContractsRegistry {
+  return {
+    version: 1,
+    metadata: {
+      generatedAt: "2026-01-01T00:00:00.000Z",
+      sources: [{ name: "core" }],
+    },
+    contracts: [
+      {
+        name: "QX",
+        contractIndex: 2,
+        address: "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
+        entries: [
+          {
+            kind: "function",
+            name: "GetBalance",
+            inputType: 1,
+            inputTypeName: "GetBalance_input",
+            outputTypeName: "GetBalance_output",
+          },
+        ],
+      },
+      {
+        name: "QUTIL",
+        contractIndex: 1,
+        address: "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+        entries: [],
+      },
+    ],
+  };
+}

package/src/generator/registry-runtime.ts

@@ -0,0 +1,28 @@
+import { normalizeContractsRegistry } from "../registry/normalize.js";
+import type { ContractsRegistry } from "../registry/types.js";
+
+export type GenerateRegistryRuntimeOptions = Readonly<{
+  banner?: string;
+  exportName?: string;
+}>;
+
+export function generateRegistryRuntime(
+  registry: ContractsRegistry,
+  options: GenerateRegistryRuntimeOptions = {},
+): string {
+  const normalized = normalizeContractsRegistry(registry);
+  const exportName = options.exportName ?? "coreContractsRegistry";
+  const banner =
+    options.banner ?? "/* eslint-disable */\n/* This file is generated. Do not edit manually. */";
+
+  return [
+    banner,
+    "",
+    'import type { ContractsRegistry } from "../registry/types.js";',
+    "",
+    `export const ${exportName} = ${JSON.stringify(normalized, null, 2)} as const satisfies ContractsRegistry;`,
+    "",
+    `export const coreContractDefinitions = ${exportName}.contracts;`,
+    "",
+  ].join("\n");
+}

package/src/generator/registry-types.fixture.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "bun:test";
+import { validateContractsRegistry } from "../registry/index.js";
+import { generateRegistryTypes } from "./registry-types.js";
+
+describe("generateRegistryTypes fixture", () => {
+  it("matches the expected generated file", async () => {
+    const fixturePath = new URL("../../test/fixtures/registry.sample.json", import.meta.url);
+    const expectedPath = new URL("../../test/fixtures/registry.sample.types.ts", import.meta.url);
+
+    const fixtureRaw = (await Bun.file(fixturePath).json()) as unknown;
+    const expected = await Bun.file(expectedPath).text();
+    const registry = validateContractsRegistry(fixtureRaw);
+    const generated = generateRegistryTypes(registry);
+
+    expect(generated).toBe(expected);
+  });
+});

package/src/generator/registry-types.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "bun:test";
+import type { ContractsRegistry } from "../registry/types.js";
+import { generateRegistryTypes } from "./registry-types.js";
+
+describe("generateRegistryTypes", () => {
+  it("generates contract/function/procedure unions", () => {
+    const output = generateRegistryTypes(makeFixture(), {
+      banner: "// generated",
+    });
+
+    expect(output).toContain('export type ContractName = "QUTIL" | "QVAULT";');
+    expect(output).toContain(
+      'export type FunctionName<C extends ContractName> = C extends "QUTIL"',
+    );
+    expect(output).toContain('? "GetFees"');
+    expect(output).toContain(
+      'export type ProcedureName<C extends ContractName> = C extends "QUTIL"',
+    );
+    expect(output).toContain('C extends "QVAULT"');
+    expect(output).toContain("// generated");
+  });
+
+  it("is deterministic", () => {
+    const first = generateRegistryTypes(makeFixture());
+    const second = generateRegistryTypes(makeFixture());
+    expect(first).toBe(second);
+  });
+});
+
+function makeFixture(): ContractsRegistry {
+  return {
+    version: 1,
+    metadata: {
+      generatedAt: "2026-02-18T00:00:00.000Z",
+      sources: [{ name: "qubic/core" }],
+    },
+    contracts: [
+      {
+        name: "QVAULT",
+        contractIndex: 10,
+        address: "KAAAA",
+        entries: [{ kind: "procedure", name: "SubmitAuthAddress", inputType: 7 }],
+      },
+      {
+        name: "QUTIL",
+        contractIndex: 4,
+        address: "EAAAA",
+        entries: [
+          { kind: "procedure", name: "BurnQubic", inputType: 2 },
+          { kind: "function", name: "GetFees", inputType: 1 },
+        ],
+      },
+    ],
+  };
+}

package/src/generator/registry-types.ts

@@ -0,0 +1,75 @@
+import { normalizeContractsRegistry } from "../registry/normalize.js";
+import type { ContractDefinition, ContractsRegistry } from "../registry/types.js";
+
+export type GenerateRegistryTypesOptions = Readonly<{
+  banner?: string;
+}>;
+
+export function generateRegistryTypes(
+  registry: ContractsRegistry,
+  options: GenerateRegistryTypesOptions = {},
+): string {
+  const normalized = normalizeContractsRegistry(registry);
+  const contracts = normalized.contracts;
+
+  const contractNameUnion = makeUnion(contracts.map((c) => c.name));
+  const functionType = makeConditionalType(contracts, "function");
+  const procedureType = makeConditionalType(contracts, "procedure");
+
+  const banner =
+    options.banner ?? "/* eslint-disable */\n/* This file is generated. Do not edit manually. */";
+
+  return [
+    banner,
+    "",
+    `export type ContractName = ${contractNameUnion};`,
+    "",
+    `export type FunctionName<C extends ContractName> = ${functionType};`,
+    "",
+    `export type ProcedureName<C extends ContractName> = ${procedureType};`,
+    "",
+  ].join("\n");
+}
+
+function makeConditionalType(
+  contracts: readonly ContractDefinition[],
+  kind: "function" | "procedure",
+  depth = 0,
+): string {
+  if (contracts.length === 0) return "never";
+  const [head, ...tail] = contracts;
+  if (!head) return "never";
+
+  const indent = "  ".repeat(depth);
+  const nestedIndent = "  ".repeat(depth + 1);
+  const union = makeUnion(
+    head.entries
+      .filter((entry) => entry.kind === kind)
+      .map((entry) => entry.name)
+      .sort((a, b) => a.localeCompare(b)),
+  );
+
+  if (tail.length === 0) {
+    return `${indent}C extends ${quote(head.name)}\n${nestedIndent}? ${union}\n${nestedIndent}: never`;
+  }
+
+  const next = makeConditionalType(tail, kind, depth + 1);
+  const [first = "never", ...rest] = next.split("\n");
+  const firstWithoutIndent = first.slice((depth + 1) * 2);
+  return [
+    `${indent}C extends ${quote(head.name)}`,
+    `${nestedIndent}? ${union}`,
+    `${nestedIndent}: ${firstWithoutIndent}`,
+    ...rest,
+  ].join("\n");
+}
+
+function makeUnion(values: readonly string[]): string {
+  if (values.length === 0) return "never";
+  const unique = [...new Set(values)].sort((a, b) => a.localeCompare(b));
+  return unique.map((item) => quote(item)).join(" | ");
+}
+
+function quote(value: string): string {
+  return JSON.stringify(value);
+}

package/src/index.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "bun:test";
+import {
+  bytesFromBase64,
+  bytesToBase64,
+  coreContractsRegistry,
+  createContractsRegistryIndex,
+  validateContractsRegistry,
+} from "./index.js";
+
+describe("base64 helpers", () => {
+  it("round trips bytes", () => {
+    const input = new Uint8Array([1, 2, 3, 4, 5, 250]);
+    const encoded = bytesToBase64(input);
+    const decoded = bytesFromBase64(encoded);
+    expect(Array.from(decoded)).toEqual(Array.from(input));
+  });
+});
+
+describe("bundled core registry", () => {
+  it("exports and validates a non-empty contracts registry", () => {
+    const parsed = validateContractsRegistry(coreContractsRegistry);
+    expect(parsed.version).toBe(1);
+    expect(parsed.contracts.length).toBeGreaterThan(0);
+
+    const index = createContractsRegistryIndex(parsed);
+    expect(index.byName.size).toBeGreaterThan(0);
+    expect(index.byIndex.size).toBeGreaterThan(0);
+  });
+});

package/src/index.ts

@@ -0,0 +1,49 @@
+export type DecodeMode = "typed" | "named" | "raw";
+
+export type DecodedInputData<T = unknown> =
+  | Readonly<{ mode: "typed"; value: T; rawBytes: Uint8Array }>
+  | Readonly<{ mode: "named"; name: string; rawBytes: Uint8Array }>
+  | Readonly<{ mode: "raw"; rawBytes: Uint8Array }>;
+
+export function bytesFromBase64(value: string): Uint8Array {
+  if (typeof atob !== "function") {
+    throw new Error("Base64 decoding is not available in this runtime");
+  }
+  const bin = atob(value);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+export function bytesToBase64(bytes: Uint8Array): string {
+  if (typeof btoa !== "function") {
+    throw new Error("Base64 encoding is not available in this runtime");
+  }
+  let bin = "";
+  for (const byte of bytes) bin += String.fromCharCode(byte);
+  return btoa(bin);
+}
+
+export * from "./codec/index.js";
+export * from "./generator/index.js";
+export { coreContractDefinitions, coreContractsRegistry } from "./generated/core-registry.js";
+export {
+  applyIoTypeLayouts,
+  createContractsRegistryIndex,
+  normalizeContractsRegistry,
+  validateContractsRegistry,
+} from "./registry/index.js";
+export type {
+  CompilerIoTypeLayout,
+  ContractDefinition,
+  ContractEntry,
+  ContractEntryKind,
+  ContractIoField,
+  ContractIoTypeDefinition,
+  ContractOverlay,
+  ContractsRegistry,
+  ContractsRegistryIndex,
+  RegistrySource,
+  StaticContractEnrichment,
+  StaticProcedureEnrichment,
+} from "./registry/types.js";

package/src/registry/index.ts

@@ -0,0 +1,17 @@
+export { applyIoTypeLayouts } from "./io-layout.js";
+export type { CompilerIoTypeLayout } from "./io-layout.js";
+export { createContractsRegistryIndex, normalizeContractsRegistry } from "./normalize.js";
+export { validateContractsRegistry } from "./schema.js";
+export type {
+  ContractDefinition,
+  ContractEntry,
+  ContractEntryKind,
+  ContractIoField,
+  ContractIoTypeDefinition,
+  ContractOverlay,
+  ContractsRegistry,
+  ContractsRegistryIndex,
+  RegistrySource,
+  StaticContractEnrichment,
+  StaticProcedureEnrichment,
+} from "./types.js";

package/src/registry/io-layout.fixture.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "bun:test";
+import { applyIoTypeLayouts } from "./io-layout.js";
+import type { CompilerIoTypeLayout } from "./io-layout.js";
+import type { ContractDefinition } from "./types.js";
+
+describe("io layout fixture", () => {
+  it("applies byte size and alignment metadata to io types and entries", async () => {
+    const contractsPath = new URL("../../test/fixtures/io-layout.contracts.json", import.meta.url);
+    const layoutsPath = new URL("../../test/fixtures/io-layout.layouts.json", import.meta.url);
+
+    const contracts = (await Bun.file(contractsPath).json()) as readonly ContractDefinition[];
+    const layouts = (await Bun.file(layoutsPath).json()) as readonly CompilerIoTypeLayout[];
+
+    const enriched = applyIoTypeLayouts(contracts, layouts);
+    const qutil = enriched[0];
+    expect(qutil?.entries[0]?.inputSize).toBe(8);
+    expect(qutil?.entries[0]?.outputSize).toBe(16);
+
+    const inputType = qutil?.ioTypes?.find((value) => value.name === "GetFees_input");
+    const outputType = qutil?.ioTypes?.find((value) => value.name === "GetFees_output");
+    expect(inputType).toMatchObject({ byteSize: 8, byteAlign: 8 });
+    expect(outputType).toMatchObject({ byteSize: 16, byteAlign: 8 });
+  });
+});

package/src/registry/io-layout.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "bun:test";
+import { applyIoTypeLayouts } from "./io-layout.js";
+import type { ContractDefinition } from "./types.js";
+
+describe("applyIoTypeLayouts", () => {
+  it("applies compiler layout metadata to io types and entry input/output sizes", () => {
+    const contracts = makeContracts();
+
+    const enriched = applyIoTypeLayouts(contracts, [
+      {
+        contractName: "QUTIL",
+        typeName: "GetFees_input",
+        byteSize: 8,
+        byteAlign: 8,
+      },
+      {
+        contractName: "QUTIL",
+        typeName: "GetFees_output",
+        byteSize: 16,
+        byteAlign: 8,
+      },
+    ]);
+
+    const qutil = enriched[0];
+    expect(qutil).toBeDefined();
+    expect(qutil?.entries[0]?.inputSize).toBe(8);
+    expect(qutil?.entries[0]?.outputSize).toBe(16);
+
+    const inputType = qutil?.ioTypes?.find((typeDef) => typeDef.name === "GetFees_input");
+    expect(inputType).toMatchObject({ byteSize: 8, byteAlign: 8 });
+
+    const outputType = qutil?.ioTypes?.find((typeDef) => typeDef.name === "GetFees_output");
+    expect(outputType).toMatchObject({ byteSize: 16, byteAlign: 8 });
+  });
+
+  it("keeps existing entry sizes when they are already defined", () => {
+    const contracts = makeContracts({ presetSizes: true });
+
+    const enriched = applyIoTypeLayouts(contracts, [
+      {
+        contractName: "QUTIL",
+        typeName: "GetFees_input",
+        byteSize: 8,
+        byteAlign: 8,
+      },
+      {
+        contractName: "QUTIL",
+        typeName: "GetFees_output",
+        byteSize: 16,
+        byteAlign: 8,
+      },
+    ]);
+
+    const entry = enriched[0]?.entries[0];
+    expect(entry?.inputSize).toBe(9);
+    expect(entry?.outputSize).toBe(17);
+  });
+});
+
+function makeContracts(
+  options?: Readonly<{ presetSizes?: boolean }>,
+): readonly ContractDefinition[] {
+  const entry = {
+    kind: "function" as const,
+    name: "GetFees",
+    inputType: 7,
+    inputTypeName: "GetFees_input",
+    outputTypeName: "GetFees_output",
+    inputSize: options?.presetSizes ? 9 : undefined,
+    outputSize: options?.presetSizes ? 17 : undefined,
+  };
+
+  return [
+    {
+      name: "QUTIL",
+      contractIndex: 4,
+      address: "QUTIL",
+      entries: [entry],
+      ioTypes: [
+        {
+          kind: "struct" as const,
+          name: "GetFees_input",
+          fields: [{ name: "contractIndex", type: "uint32" }],
+        },
+        {
+          kind: "struct" as const,
+          name: "GetFees_output",
+          fields: [{ name: "fee", type: "uint64" }],
+        },
+      ],
+    },
+  ];
+}