@qubic.org/registry 0.2.0

package/data/schema.json

@@ -0,0 +1,197 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ContractRegistry",
+  "type": "object",
+  "required": ["schemaVersion", "updatedAt", "versions"],
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "versions": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/ContractAbiVersion"
+      }
+    }
+  },
+  "definitions": {
+    "FieldType": {
+      "type": "string",
+      "enum": [
+        "uint8",
+        "uint16",
+        "uint32",
+        "uint64",
+        "sint64",
+        "uint128",
+        "id",
+        "bytes",
+        "array",
+        "struct"
+      ]
+    },
+    "BinaryField": {
+      "type": "object",
+      "required": ["name", "type", "offset", "byteLength"],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "type": {
+          "$ref": "#/definitions/FieldType"
+        },
+        "offset": {
+          "type": "integer"
+        },
+        "byteLength": {
+          "type": "integer"
+        },
+        "description": {
+          "type": "string"
+        },
+        "arrayLength": {
+          "type": "integer"
+        },
+        "arrayItemType": {
+          "$ref": "#/definitions/FieldType"
+        },
+        "arrayItemByteLength": {
+          "type": "integer"
+        },
+        "arrayItemStructRef": {
+          "type": "string"
+        },
+        "structRef": {
+          "type": "string"
+        }
+      }
+    },
+    "NamedStruct": {
+      "type": "object",
+      "required": ["name", "fields", "byteLength"],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "fields": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/BinaryField"
+          }
+        },
+        "byteLength": {
+          "type": "integer"
+        }
+      }
+    },
+    "ContractCallBase": {
+      "type": "object",
+      "required": [
+        "kind",
+        "inputType",
+        "name",
+        "inputFields",
+        "outputFields",
+        "inputSize",
+        "outputSize"
+      ],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": ["procedure", "function"]
+        },
+        "inputType": {
+          "type": "integer"
+        },
+        "name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "inputFields": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/BinaryField"
+          }
+        },
+        "outputFields": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/BinaryField"
+          }
+        },
+        "inputSize": {
+          "type": "integer"
+        },
+        "outputSize": {
+          "type": "integer"
+        },
+        "requiresAmount": {
+          "type": "boolean"
+        },
+        "sourceRef": {
+          "type": "string"
+        }
+      }
+    },
+    "ContractAbiVersion": {
+      "type": "object",
+      "required": [
+        "contractIndex",
+        "contractName",
+        "effectiveFromEpoch",
+        "effectiveToEpoch",
+        "structs",
+        "procedures",
+        "functions"
+      ],
+      "properties": {
+        "contractIndex": {
+          "type": "integer"
+        },
+        "contractName": {
+          "type": "string"
+        },
+        "effectiveFromEpoch": {
+          "type": "integer"
+        },
+        "effectiveToEpoch": {
+          "type": ["integer", "null"]
+        },
+        "coreVersion": {
+          "type": "string"
+        },
+        "coreCommit": {
+          "type": "string"
+        },
+        "structs": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/NamedStruct"
+          }
+        },
+        "procedures": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ContractCallBase"
+          }
+        },
+        "functions": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ContractCallBase"
+          }
+        },
+        "changelog": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/dist/client.d.ts

@@ -0,0 +1,28 @@
+import type { AbiLookupResult, ContractAbiVersion, ContractRegistry } from './types.js';
+export interface RegistryClientOptions {
+    /** Remote registry.json URL. Default: 'https://registry.qubic.ts/registry.json' */
+    url?: string;
+    /** Caching strategy. Default: 'session' */
+    cache?: 'none' | 'session' | 'persistent';
+    /** TTL in ms for cached registry. Default: 3_600_000 (1 hour) */
+    ttlMs?: number;
+    /** Custom fetch implementation (for testing or proxying). */
+    fetch?: typeof globalThis.fetch;
+}
+export interface RegistryClient {
+    getAbi(contractIndex: number, epoch: number): Promise<AbiLookupResult>;
+    getCurrentAbi(contractIndex: number): Promise<ContractAbiVersion>;
+    getAbiHistory(contractIndex: number): Promise<ContractAbiVersion[]>;
+    /** Returns the full raw registry for custom use. */
+    getRegistry(): Promise<ContractRegistry>;
+}
+/**
+ * Creates a client that fetches registry.json from a remote URL and caches it.
+ *
+ * Cache modes:
+ *   'session':    module-level variable (server) or sessionStorage (browser)
+ *   'persistent': localStorage (browser) or Bun.file cache (server)
+ *   'none':       always fetch fresh
+ */
+export declare function createRegistryClient(options?: RegistryClientOptions): RegistryClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAEvF,MAAM,WAAW,qBAAqB;IACpC,mFAAmF;IACnF,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,CAAA;IACzC,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,6DAA6D;IAC7D,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IACtE,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;IACjE,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAA;IACnE,oDAAoD;IACpD,WAAW,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAA;CACzC;AAQD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAsFxF"}

package/dist/client.js

@@ -0,0 +1,102 @@
+import { getAbi, getAbiHistory, getCurrentAbi } from './registry.js';
+const DEFAULT_URL = 'https://registry.qubic.ts/registry.json';
+const DEFAULT_TTL = 3_600_000;
+/** Module-level session cache shared across all clients in the same process. */
+let sessionCache;
+/**
+ * Creates a client that fetches registry.json from a remote URL and caches it.
+ *
+ * Cache modes:
+ *   'session':    module-level variable (server) or sessionStorage (browser)
+ *   'persistent': localStorage (browser) or Bun.file cache (server)
+ *   'none':       always fetch fresh
+ */
+export function createRegistryClient(options = {}) {
+    const url = options.url ?? DEFAULT_URL;
+    const cacheMode = options.cache ?? 'session';
+    const ttlMs = options.ttlMs ?? DEFAULT_TTL;
+    const fetchFn = options.fetch ?? globalThis.fetch;
+    const STORAGE_KEY = `@qubic.org/registry:${url}`;
+    async function fetchRegistry() {
+        const res = await fetchFn(url);
+        if (!res.ok)
+            throw new Error(`Failed to fetch registry: HTTP ${res.status}`);
+        return (await res.json());
+    }
+    async function load() {
+        const now = Date.now();
+        if (cacheMode === 'session') {
+            if (sessionCache && now < sessionCache.expiresAt)
+                return sessionCache.registry;
+            if (typeof globalThis.sessionStorage !== 'undefined') {
+                try {
+                    const raw = globalThis.sessionStorage.getItem(STORAGE_KEY);
+                    if (raw) {
+                        const cached = JSON.parse(raw);
+                        if (now < cached.expiresAt) {
+                            sessionCache = cached;
+                            return cached.registry;
+                        }
+                    }
+                }
+                catch {
+                    /* ignore storage errors */
+                }
+            }
+        }
+        else if (cacheMode === 'persistent') {
+            if (typeof globalThis.localStorage !== 'undefined') {
+                try {
+                    const raw = globalThis.localStorage.getItem(STORAGE_KEY);
+                    if (raw) {
+                        const cached = JSON.parse(raw);
+                        if (now < cached.expiresAt)
+                            return cached.registry;
+                    }
+                }
+                catch {
+                    /* ignore storage errors */
+                }
+            }
+        }
+        const registry = await fetchRegistry();
+        const entry = { registry, expiresAt: now + ttlMs };
+        if (cacheMode === 'session') {
+            sessionCache = entry;
+            if (typeof globalThis.sessionStorage !== 'undefined') {
+                try {
+                    globalThis.sessionStorage.setItem(STORAGE_KEY, JSON.stringify(entry));
+                }
+                catch {
+                    /* ignore quota errors */
+                }
+            }
+        }
+        else if (cacheMode === 'persistent') {
+            if (typeof globalThis.localStorage !== 'undefined') {
+                try {
+                    globalThis.localStorage.setItem(STORAGE_KEY, JSON.stringify(entry));
+                }
+                catch {
+                    /* ignore quota errors */
+                }
+            }
+        }
+        return registry;
+    }
+    return {
+        async getAbi(contractIndex, epoch) {
+            return getAbi(await load(), contractIndex, epoch);
+        },
+        async getCurrentAbi(contractIndex) {
+            return getCurrentAbi(await load(), contractIndex);
+        },
+        async getAbiHistory(contractIndex) {
+            return getAbiHistory(await load(), contractIndex);
+        },
+        async getRegistry() {
+            return load();
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAsBpE,MAAM,WAAW,GAAG,yCAAyC,CAAA;AAC7D,MAAM,WAAW,GAAG,SAAS,CAAA;AAE7B,gFAAgF;AAChF,IAAI,YAA2E,CAAA;AAE/E;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAAiC,EAAE;IACtE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,WAAW,CAAA;IACtC,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,IAAI,SAAS,CAAA;IAC5C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,WAAW,CAAA;IAC1C,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAA;IAEjD,MAAM,WAAW,GAAG,uBAAuB,GAAG,EAAE,CAAA;IAEhD,KAAK,UAAU,aAAa;QAC1B,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAA;QAC9B,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAA;QAC5E,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAqB,CAAA;IAC/C,CAAC;IAED,KAAK,UAAU,IAAI;QACjB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QAEtB,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,IAAI,YAAY,IAAI,GAAG,GAAG,YAAY,CAAC,SAAS;gBAAE,OAAO,YAAY,CAAC,QAAQ,CAAA;YAC9E,IAAI,OAAO,UAAU,CAAC,cAAc,KAAK,WAAW,EAAE,CAAC;gBACrD,IAAI,CAAC;oBACH,MAAM,GAAG,GAAG,UAAU,CAAC,cAAc,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;oBAC1D,IAAI,GAAG,EAAE,CAAC;wBACR,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAsD,CAAA;wBACnF,IAAI,GAAG,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;4BAC3B,YAAY,GAAG,MAAM,CAAA;4BACrB,OAAO,MAAM,CAAC,QAAQ,CAAA;wBACxB,CAAC;oBACH,CAAC;gBACH,CAAC;gBAAC,MAAM,CAAC;oBACP,2BAA2B;gBAC7B,CAAC;YACH,CAAC;QACH,CAAC;aAAM,IAAI,SAAS,KAAK,YAAY,EAAE,CAAC;YACtC,IAAI,OAAO,UAAU,CAAC,YAAY,KAAK,WAAW,EAAE,CAAC;gBACnD,IAAI,CAAC;oBACH,MAAM,GAAG,GAAG,UAAU,CAAC,YAAY,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;oBACxD,IAAI,GAAG,EAAE,CAAC;wBACR,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAsD,CAAA;wBACnF,IAAI,GAAG,GAAG,MAAM,CAAC,SAAS;4BAAE,OAAO,MAAM,CAAC,QAAQ,CAAA;oBACpD,CAAC;gBACH,CAAC;gBAAC,MAAM,CAAC;oBACP,2BAA2B;gBAC7B,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,aAAa,EAAE,CAAA;QACtC,MAAM,KAAK,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,GAAG,KAAK,EAAE,CAAA;QAElD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,YAAY,GAAG,KAAK,CAAA;YACpB,IAAI,OAAO,UAAU,CAAC,cAAc,KAAK,WAAW,EAAE,CAAC;gBACrD,IAAI,CAAC;oBACH,UAAU,CAAC,cAAc,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAA;gBACvE,CAAC;gBAAC,MAAM,CAAC;oBACP,yBAAyB;gBAC3B,CAAC;YACH,CAAC;QACH,CAAC;aAAM,IAAI,SAAS,KAAK,YAAY,EAAE,CAAC;YACtC,IAAI,OAAO,UAAU,CAAC,YAAY,KAAK,WAAW,EAAE,CAAC;gBACnD,IAAI,CAAC;oBACH,UAAU,CAAC,YAAY,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAA;gBACrE,CAAC;gBAAC,MAAM,CAAC;oBACP,yBAAyB;gBAC3B,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,QAAQ,CAAA;IACjB,CAAC;IAED,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,aAAa,EAAE,KAAK;YAC/B,OAAO,MAAM,CAAC,MAAM,IAAI,EAAE,EAAE,aAAa,EAAE,KAAK,CAAC,CAAA;QACnD,CAAC;QACD,KAAK,CAAC,aAAa,CAAC,aAAa;YAC/B,OAAO,aAAa,CAAC,MAAM,IAAI,EAAE,EAAE,aAAa,CAAC,CAAA;QACnD,CAAC;QACD,KAAK,CAAC,aAAa,CAAC,aAAa;YAC/B,OAAO,aAAa,CAAC,MAAM,IAAI,EAAE,EAAE,aAAa,CAAC,CAAA;QACnD,CAAC;QACD,KAAK,CAAC,WAAW;YACf,OAAO,IAAI,EAAE,CAAA;QACf,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './registry.js';
+export * from './payload.js';
+export { contractIndexToIdentity } from '@qubic.org/crypto';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './registry.js';
+export * from './payload.js';
+export { contractIndexToIdentity } from '@qubic.org/crypto';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/payload.d.ts

@@ -0,0 +1,46 @@
+import type { BinaryField, FieldType, NamedStruct } from './types.js';
+export type DecodedStruct = Record<string, unknown>;
+export type FieldValue = number | bigint | string | Uint8Array | FieldValue[] | DecodedStruct;
+export declare class PayloadBuildError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Encodes a contract call input into binary using registry field descriptors.
+ *
+ * Field encoding rules:
+ *   uint8/16/32    → DataView.setUintN (little-endian)
+ *   uint64/sint64  → DataView.setBigUint64 / setBigInt64 (little-endian)
+ *   uint128        → two consecutive uint64 LE (lo word first, hi word second)
+ *   id             → 32-byte public key via injected identityToPublicKey
+ *   bytes          → Uint8Array copied verbatim (must be exactly field.byteLength)
+ *   struct         → recursively encoded using structs[field.structRef].fields
+ *   array          → N items encoded sequentially
+ *
+ * Advanced mode: pass a Uint8Array as the value for any field. Its length must
+ * equal field.byteLength — it is copied verbatim without type coercion.
+ *
+ * @throws {PayloadBuildError} on type mismatch, out-of-range value, or length mismatch
+ */
+export declare function buildPayload(fields: BinaryField[], structs: Record<string, NamedStruct>, input: Record<string, FieldValue | Uint8Array>, identityToPublicKey: (identity: string) => Uint8Array): Uint8Array;
+/**
+ * Decodes binary payload bytes into a typed record using registry field descriptors.
+ * Mirror of buildPayload — same field dispatch logic, reversed direction.
+ */
+export declare function decodePayload(data: Uint8Array, fields: BinaryField[], structs: Record<string, NamedStruct>, publicKeyToIdentity: (pk: Uint8Array) => string): DecodedStruct;
+/**
+ * Builds a payload from an ordered list of typed fields — no registry, no field names.
+ * For use with unknown or custom contracts.
+ *
+ * @example
+ * const payload = buildPayloadManual([
+ *   { type: 'uint64', value: 5_000_000n },
+ *   { type: 'uint32', value: 150 },
+ * ])
+ */
+export declare function buildPayloadManual(fields: ReadonlyArray<{
+    type: FieldType;
+    value: FieldValue;
+}>): Uint8Array;
+//# sourceMappingURL=payload.d.ts.map

package/dist/payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../src/payload.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAGrE,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AACnD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,EAAE,GAAG,aAAa,CAAA;AAE7F,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,WAAW,EAAE,EACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACpC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC,EAC9C,mBAAmB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,UAAU,GACpD,UAAU,CA0BZ;AAiND;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,WAAW,EAAE,EACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACpC,mBAAmB,EAAE,CAAC,EAAE,EAAE,UAAU,KAAK,MAAM,GAC9C,aAAa,CAOf;AA8ED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC,GAC5D,UAAU,CA+BZ"}