@qubic.ts/contracts 0.1.0

package/src/registry/io-layout.ts

@@ -0,0 +1,57 @@
+import type { ContractDefinition, ContractIoTypeDefinition } from "./types.js";
+
+export type CompilerIoTypeLayout = Readonly<{
+  contractName: string;
+  typeName: string;
+  byteSize: number;
+  byteAlign: number;
+}>;
+
+export function applyIoTypeLayouts(
+  contracts: readonly ContractDefinition[],
+  layouts: readonly CompilerIoTypeLayout[],
+): readonly ContractDefinition[] {
+  if (layouts.length === 0) return contracts;
+
+  const layoutByKey = new Map<string, CompilerIoTypeLayout>();
+  for (const layout of layouts) {
+    layoutByKey.set(makeLayoutKey(layout.contractName, layout.typeName), layout);
+  }
+
+  return contracts.map((contract) => {
+    if (!contract.ioTypes || contract.ioTypes.length === 0) return contract;
+
+    const ioTypes = contract.ioTypes.map((typeDef) => {
+      const layout = layoutByKey.get(makeLayoutKey(contract.name, typeDef.name));
+      if (!layout) return typeDef;
+      return {
+        ...typeDef,
+        byteSize: layout.byteSize,
+        byteAlign: layout.byteAlign,
+      } as ContractIoTypeDefinition;
+    });
+
+    const ioTypeByName = new Map(ioTypes.map((typeDef) => [typeDef.name, typeDef]));
+
+    const entries = contract.entries.map((entry) => {
+      const inputType = entry.inputTypeName ? ioTypeByName.get(entry.inputTypeName) : undefined;
+      const outputType = entry.outputTypeName ? ioTypeByName.get(entry.outputTypeName) : undefined;
+
+      return {
+        ...entry,
+        inputSize: entry.inputSize ?? inputType?.byteSize,
+        outputSize: entry.outputSize ?? outputType?.byteSize,
+      };
+    });
+
+    return {
+      ...contract,
+      entries,
+      ioTypes,
+    };
+  });
+}
+
+function makeLayoutKey(contractName: string, typeName: string): string {
+  return `${contractName}::${typeName}`;
+}

package/src/registry/normalize.ts

@@ -0,0 +1,61 @@
+import type {
+  ContractDefinition,
+  ContractEntry,
+  ContractIoTypeDefinition,
+  ContractsRegistry,
+  ContractsRegistryIndex,
+} from "./types.js";
+
+export function normalizeContractsRegistry(registry: ContractsRegistry): ContractsRegistry {
+  const contracts = [...registry.contracts].map(normalizeContract).sort(compareContracts);
+  return {
+    ...registry,
+    contracts,
+  };
+}
+
+export function createContractsRegistryIndex(registry: ContractsRegistry): ContractsRegistryIndex {
+  const byName = new Map<string, ContractDefinition>();
+  const byIndex = new Map<number, ContractDefinition>();
+  const byAddress = new Map<string, ContractDefinition>();
+
+  for (const contract of registry.contracts) {
+    byName.set(contract.name, contract);
+    byIndex.set(contract.contractIndex, contract);
+    byAddress.set(contract.address, contract);
+  }
+
+  return { byName, byIndex, byAddress };
+}
+
+function normalizeContract(contract: ContractDefinition): ContractDefinition {
+  return {
+    ...contract,
+    entries: [...contract.entries].sort(compareEntries),
+    ioTypes: contract.ioTypes ? [...contract.ioTypes].sort(compareIoTypes) : undefined,
+  };
+}
+
+function compareContracts(a: ContractDefinition, b: ContractDefinition): number {
+  if (a.contractIndex !== b.contractIndex) {
+    return a.contractIndex - b.contractIndex;
+  }
+  return a.name.localeCompare(b.name);
+}
+
+function compareEntries(a: ContractEntry, b: ContractEntry): number {
+  if (a.kind !== b.kind) {
+    return a.kind === "function" ? -1 : 1;
+  }
+  if (a.inputType !== b.inputType) {
+    return a.inputType - b.inputType;
+  }
+  return a.name.localeCompare(b.name);
+}
+
+function compareIoTypes(a: ContractIoTypeDefinition, b: ContractIoTypeDefinition): number {
+  if (a.kind !== b.kind) {
+    return a.kind === "struct" ? -1 : 1;
+  }
+  return a.name.localeCompare(b.name);
+}

package/src/registry/schema.fixture.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "bun:test";
+import {
+  createContractsRegistryIndex,
+  normalizeContractsRegistry,
+  validateContractsRegistry,
+} from "./index.js";
+
+describe("registry schema fixture", () => {
+  it("validates, normalizes, and indexes fixture registry", async () => {
+    const fixturePath = new URL("../../test/fixtures/registry.sample.json", import.meta.url);
+    const fixtureRaw = (await Bun.file(fixturePath).json()) as unknown;
+
+    const parsed = validateContractsRegistry(fixtureRaw);
+    const normalized = normalizeContractsRegistry(parsed);
+    const index = createContractsRegistryIndex(normalized);
+
+    expect(parsed.version).toBe(1);
+    expect(normalized.contracts[0]?.name).toBe("QUTIL");
+    expect(index.byIndex.get(10)?.name).toBe("QVAULT");
+  });
+});

package/src/registry/schema.ts

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import type {
+  ContractDefinition,
+  ContractEntry,
+  ContractIoField,
+  ContractIoTypeDefinition,
+  ContractsRegistry,
+  RegistrySource,
+} from "./types.js";
+
+const uint32Schema = z.number().int().nonnegative().max(0xffff_ffff);
+const nonEmptyStringSchema = z.string().trim().min(1);
+
+export const registrySourceSchema: z.ZodType<RegistrySource> = z
+  .object({
+    name: nonEmptyStringSchema,
+    revision: z.string().optional(),
+    hash: z.string().optional(),
+  })
+  .strict();
+
+export const contractEntrySchema: z.ZodType<ContractEntry> = z
+  .object({
+    kind: z.enum(["function", "procedure"]),
+    name: nonEmptyStringSchema,
+    displayName: z.string().optional(),
+    inputType: uint32Schema,
+    inputTypeName: nonEmptyStringSchema.optional(),
+    outputTypeName: nonEmptyStringSchema.optional(),
+    inputSize: uint32Schema.optional(),
+    outputSize: uint32Schema.optional(),
+  })
+  .strict();
+
+export const contractIoFieldSchema: z.ZodType<ContractIoField> = z
+  .object({
+    name: nonEmptyStringSchema,
+    type: nonEmptyStringSchema,
+    byteOffset: uint32Schema.optional(),
+  })
+  .strict();
+
+export const contractIoTypeDefinitionSchema: z.ZodType<ContractIoTypeDefinition> =
+  z.discriminatedUnion("kind", [
+    z
+      .object({
+        kind: z.literal("struct"),
+        name: nonEmptyStringSchema,
+        fields: z.array(contractIoFieldSchema),
+        byteSize: uint32Schema.optional(),
+        byteAlign: uint32Schema.optional(),
+      })
+      .strict(),
+    z
+      .object({
+        kind: z.literal("alias"),
+        name: nonEmptyStringSchema,
+        target: nonEmptyStringSchema,
+        byteSize: uint32Schema.optional(),
+        byteAlign: uint32Schema.optional(),
+      })
+      .strict(),
+  ]);
+
+export const contractDefinitionSchema: z.ZodType<ContractDefinition> = z
+  .object({
+    name: nonEmptyStringSchema,
+    contractIndex: uint32Schema,
+    address: nonEmptyStringSchema,
+    label: z.string().optional(),
+    filename: z.string().optional(),
+    githubUrl: z.string().optional(),
+    website: z.string().optional(),
+    proposalUrl: z.string().optional(),
+    entries: z.array(contractEntrySchema),
+    ioTypes: z.array(contractIoTypeDefinitionSchema).optional(),
+  })
+  .strict();
+
+export const contractsRegistrySchema: z.ZodType<ContractsRegistry> = z
+  .object({
+    version: z.literal(1),
+    metadata: z
+      .object({
+        generatedAt: z.string().refine((value) => !Number.isNaN(Date.parse(value)), {
+          message: "generatedAt must be an ISO date string",
+        }),
+        sources: z.array(registrySourceSchema),
+      })
+      .strict(),
+    contracts: z.array(contractDefinitionSchema),
+  })
+  .strict();
+
+export function validateContractsRegistry(value: unknown): ContractsRegistry {
+  return contractsRegistrySchema.parse(value);
+}

package/src/registry/types.ts

@@ -0,0 +1,98 @@
+export type ContractEntryKind = "function" | "procedure";
+
+export type ContractEntry = Readonly<{
+  kind: ContractEntryKind;
+  name: string;
+  displayName?: string;
+  inputType: number;
+  inputTypeName?: string;
+  outputTypeName?: string;
+  inputSize?: number;
+  outputSize?: number;
+}>;
+
+export type ContractIoField = Readonly<{
+  name: string;
+  type: string;
+  byteOffset?: number;
+}>;
+
+export type ContractIoTypeDefinition =
+  | Readonly<{
+      kind: "struct";
+      name: string;
+      fields: readonly ContractIoField[];
+      byteSize?: number;
+      byteAlign?: number;
+    }>
+  | Readonly<{
+      kind: "alias";
+      name: string;
+      target: string;
+      byteSize?: number;
+      byteAlign?: number;
+    }>;
+
+export type ContractDefinition = Readonly<{
+  name: string;
+  contractIndex: number;
+  address: string;
+  label?: string;
+  filename?: string;
+  githubUrl?: string;
+  website?: string;
+  proposalUrl?: string;
+  entries: readonly ContractEntry[];
+  ioTypes?: readonly ContractIoTypeDefinition[];
+}>;
+
+export type RegistrySource = Readonly<{
+  name: string;
+  revision?: string;
+  hash?: string;
+}>;
+
+export type ContractsRegistry = Readonly<{
+  version: 1;
+  metadata: Readonly<{
+    generatedAt: string;
+    sources: readonly RegistrySource[];
+  }>;
+  contracts: readonly ContractDefinition[];
+}>;
+
+export type ContractsRegistryIndex = Readonly<{
+  byName: ReadonlyMap<string, ContractDefinition>;
+  byIndex: ReadonlyMap<number, ContractDefinition>;
+  byAddress: ReadonlyMap<string, ContractDefinition>;
+}>;
+
+export type StaticProcedureEnrichment = Readonly<{
+  id: number;
+  name: string;
+}>;
+
+export type StaticContractEnrichment = Readonly<{
+  contractIndex?: number;
+  name?: string;
+  address?: string;
+  label?: string;
+  filename?: string;
+  githubUrl?: string;
+  website?: string;
+  proposalUrl?: string;
+  procedures?: readonly StaticProcedureEnrichment[];
+}>;
+
+export type ContractOverlay = Readonly<{
+  contractIndex: number;
+  patch?: Readonly<
+    Partial<
+      Pick<
+        ContractDefinition,
+        "name" | "address" | "label" | "filename" | "githubUrl" | "website" | "proposalUrl"
+      >
+    >
+  >;
+  entryDisplayNames?: Readonly<Record<number, string>>;
+}>;

package/test/fixtures/io-layout.contracts.json

@@ -0,0 +1,32 @@
+[
+  {
+    "name": "QUTIL",
+    "contractIndex": 4,
+    "address": "QUTIL",
+    "entries": [
+      {
+        "kind": "function",
+        "name": "GetFees",
+        "inputType": 7,
+        "inputTypeName": "GetFees_input",
+        "outputTypeName": "GetFees_output"
+      }
+    ],
+    "ioTypes": [
+      {
+        "kind": "struct",
+        "name": "GetFees_input",
+        "fields": [
+          { "name": "contractIndex", "type": "uint32" }
+        ]
+      },
+      {
+        "kind": "struct",
+        "name": "GetFees_output",
+        "fields": [
+          { "name": "fee", "type": "uint64" }
+        ]
+      }
+    ]
+  }
+]

package/test/fixtures/io-layout.layouts.json

@@ -0,0 +1,14 @@
+[
+  {
+    "contractName": "QUTIL",
+    "typeName": "GetFees_input",
+    "byteSize": 8,
+    "byteAlign": 8
+  },
+  {
+    "contractName": "QUTIL",
+    "typeName": "GetFees_output",
+    "byteSize": 16,
+    "byteAlign": 8
+  }
+]

package/test/fixtures/registry.sample.codecs.ts

@@ -0,0 +1,100 @@
+/* eslint-disable */
+/* This file is generated. Do not edit manually. */
+
+export interface ContractTypeMap {
+  QUTIL: {
+    readonly contractIndex: 4;
+    readonly functions: {
+      GetFees: {
+        readonly kind: "function";
+        readonly inputType: 1;
+        readonly inputTypeName: "GetFees_input";
+        readonly outputTypeName: "GetFees_output";
+        readonly input: unknown;
+        readonly output: unknown;
+      };
+    };
+    readonly procedures: {
+      BurnQubic: {
+        readonly kind: "procedure";
+        readonly inputType: 2;
+        readonly inputTypeName: "BurnQubic_input";
+        readonly outputTypeName: "BurnQubic_output";
+        readonly input: unknown;
+        readonly output: unknown;
+      };
+    };
+  };
+  QVAULT: {
+    readonly contractIndex: 10;
+    readonly functions: Record<never, never>;
+    readonly procedures: {
+      SubmitAuthAddress: {
+        readonly kind: "procedure";
+        readonly inputType: 7;
+        readonly inputTypeName: "SubmitAuthAddress_input";
+        readonly outputTypeName: "SubmitAuthAddress_output";
+        readonly input: unknown;
+        readonly output: unknown;
+      };
+    };
+  };
+}
+
+export type ContractName = keyof ContractTypeMap & string;
+export type FunctionName<C extends ContractName> = keyof ContractTypeMap[C]["functions"] & string;
+export type ProcedureName<C extends ContractName> = keyof ContractTypeMap[C]["procedures"] & string;
+
+export type FunctionInput<
+  C extends ContractName,
+  F extends FunctionName<C>,
+> = ContractTypeMap[C]["functions"][F]["input"];
+export type FunctionOutput<
+  C extends ContractName,
+  F extends FunctionName<C>,
+> = ContractTypeMap[C]["functions"][F]["output"];
+
+export type ProcedureInput<
+  C extends ContractName,
+  P extends ProcedureName<C>,
+> = ContractTypeMap[C]["procedures"][P]["input"];
+export type ProcedureOutput<
+  C extends ContractName,
+  P extends ProcedureName<C>,
+> = ContractTypeMap[C]["procedures"][P]["output"];
+
+export const contractCodecRegistry = {
+  QUTIL: {
+    contractIndex: 4,
+    functions: {
+      GetFees: {
+        kind: "function",
+        inputType: 1,
+        inputTypeName: "GetFees_input",
+        outputTypeName: "GetFees_output",
+      },
+    },
+    procedures: {
+      BurnQubic: {
+        kind: "procedure",
+        inputType: 2,
+        inputTypeName: "BurnQubic_input",
+        outputTypeName: "BurnQubic_output",
+      },
+    },
+  },
+  QVAULT: {
+    contractIndex: 10,
+    functions: {},
+    procedures: {
+      SubmitAuthAddress: {
+        kind: "procedure",
+        inputType: 7,
+        inputTypeName: "SubmitAuthAddress_input",
+        outputTypeName: "SubmitAuthAddress_output",
+      },
+    },
+  },
+} as const satisfies Readonly<Record<ContractName, unknown>>;
+
+export type RuntimeContractCodecRegistry = typeof contractCodecRegistry;

package/test/fixtures/registry.sample.json

@@ -0,0 +1,27 @@
+{
+  "version": 1,
+  "metadata": {
+    "generatedAt": "2026-02-18T00:00:00.000Z",
+    "sources": [
+      { "name": "qubic/core", "revision": "abc123" },
+      { "name": "static", "revision": "def456" }
+    ]
+  },
+  "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/test/fixtures/registry.sample.runtime.ts

@@ -0,0 +1,54 @@
+/* eslint-disable */
+/* This file is generated. Do not edit manually. */
+
+import type { ContractsRegistry } from "../registry/types.js";
+
+export const coreContractsRegistry = {
+  "version": 1,
+  "metadata": {
+    "generatedAt": "2026-02-18T00:00:00.000Z",
+    "sources": [
+      {
+        "name": "qubic/core",
+        "revision": "abc123"
+      },
+      {
+        "name": "static",
+        "revision": "def456"
+      }
+    ]
+  },
+  "contracts": [
+    {
+      "name": "QUTIL",
+      "contractIndex": 4,
+      "address": "EAAAA",
+      "entries": [
+        {
+          "kind": "function",
+          "name": "GetFees",
+          "inputType": 1
+        },
+        {
+          "kind": "procedure",
+          "name": "BurnQubic",
+          "inputType": 2
+        }
+      ]
+    },
+    {
+      "name": "QVAULT",
+      "contractIndex": 10,
+      "address": "KAAAA",
+      "entries": [
+        {
+          "kind": "procedure",
+          "name": "SubmitAuthAddress",
+          "inputType": 7
+        }
+      ]
+    }
+  ]
+} as const satisfies ContractsRegistry;
+
+export const coreContractDefinitions = coreContractsRegistry.contracts;

package/test/fixtures/registry.sample.types.ts

@@ -0,0 +1,16 @@
+/* eslint-disable */
+/* This file is generated. Do not edit manually. */
+
+export type ContractName = "QUTIL" | "QVAULT";
+
+export type FunctionName<C extends ContractName> = C extends "QUTIL"
+  ? "GetFees"
+  : C extends "QVAULT"
+    ? never
+    : never;
+
+export type ProcedureName<C extends ContractName> = C extends "QUTIL"
+  ? "BurnQubic"
+  : C extends "QVAULT"
+    ? "SubmitAuthAddress"
+    : never;