@qubic.org/registry 0.2.6 → 1.0.0

package/src/payload.ts

@@ -0,0 +1,433 @@
+import type { BinaryField, FieldType, NamedStruct } from './types.js'
+
+// DecodedStruct uses unknown to avoid circular type constraint issues.
+export type DecodedStruct = Record<string, unknown>
+export type FieldValue = number | bigint | string | Uint8Array | FieldValue[] | DecodedStruct
+
+export class PayloadBuildError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, { cause: options?.cause })
+    this.name = 'PayloadBuildError'
+  }
+}
+
+/**
+ * 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 function buildPayload(
+  fields: BinaryField[],
+  structs: Record<string, NamedStruct>,
+  input: Record<string, FieldValue | Uint8Array>,
+  identityToPublicKey: (identity: string) => Uint8Array,
+): Uint8Array {
+  const totalSize = fields.reduce((s, f) => s + f.byteLength, 0)
+  const buf = new Uint8Array(totalSize)
+  const view = new DataView(buf.buffer)
+
+  for (const field of fields) {
+    const raw = input[field.name]
+    if (raw === undefined) {
+      throw new PayloadBuildError(`Missing field "${field.name}"`)
+    }
+
+    // Advanced mode: Uint8Array verbatim copy
+    if (raw instanceof Uint8Array) {
+      if (raw.byteLength !== field.byteLength) {
+        throw new PayloadBuildError(
+          `Field "${field.name}": Uint8Array length ${raw.byteLength} !== expected ${field.byteLength}`,
+        )
+      }
+      buf.set(raw, field.offset)
+      continue
+    }
+
+    encodeField(field, raw as FieldValue, buf, view, field.offset, structs, identityToPublicKey)
+  }
+
+  return buf
+}
+
+// ── Shared scalar encoder ─────────────────────────────────────────────────────
+
+function writeScalar(
+  type: FieldType,
+  fieldName: string,
+  value: FieldValue,
+  buf: Uint8Array,
+  view: DataView,
+  offset: number,
+  identityToPublicKey: (identity: string) => Uint8Array,
+): void {
+  switch (type) {
+    case 'uint8':
+      if (typeof value !== 'number')
+        throw new PayloadBuildError(`Field "${fieldName}": expected number`)
+      view.setUint8(offset, value)
+      break
+    case 'sint8':
+      if (typeof value !== 'number')
+        throw new PayloadBuildError(`Field "${fieldName}": expected number`)
+      view.setInt8(offset, value)
+      break
+    case 'uint16':
+      if (typeof value !== 'number')
+        throw new PayloadBuildError(`Field "${fieldName}": expected number`)
+      view.setUint16(offset, value, true)
+      break
+    case 'sint16':
+      if (typeof value !== 'number')
+        throw new PayloadBuildError(`Field "${fieldName}": expected number`)
+      view.setInt16(offset, value, true)
+      break
+    case 'uint32':
+      if (typeof value !== 'number')
+        throw new PayloadBuildError(`Field "${fieldName}": expected number`)
+      view.setUint32(offset, value, true)
+      break
+    case 'sint32':
+      if (typeof value !== 'number')
+        throw new PayloadBuildError(`Field "${fieldName}": expected number`)
+      view.setInt32(offset, value, true)
+      break
+    case 'uint64':
+      if (typeof value !== 'bigint')
+        throw new PayloadBuildError(`Field "${fieldName}": expected bigint`)
+      view.setBigUint64(offset, value, true)
+      break
+    case 'sint64':
+      if (typeof value !== 'bigint')
+        throw new PayloadBuildError(`Field "${fieldName}": expected bigint`)
+      view.setBigInt64(offset, value, true)
+      break
+    case 'uint128': {
+      if (typeof value !== 'bigint')
+        throw new PayloadBuildError(`Field "${fieldName}": expected bigint`)
+      view.setBigUint64(offset, value & 0xffffffffffffffffn, true)
+      view.setBigUint64(offset + 8, value >> 64n, true)
+      break
+    }
+    case 'id': {
+      if (typeof value !== 'string')
+        throw new PayloadBuildError(`Field "${fieldName}": expected Identity string`)
+      buf.set(identityToPublicKey(value).subarray(0, 32), offset)
+      break
+    }
+    default:
+      throw new PayloadBuildError(`Scalar encoding not supported for type "${type}"`)
+  }
+}
+
+// ── Shared scalar decoder ─────────────────────────────────────────────────────
+
+function readScalar(
+  type: FieldType,
+  data: Uint8Array,
+  view: DataView,
+  offset: number,
+  publicKeyToIdentity: (pk: Uint8Array) => string,
+): FieldValue {
+  switch (type) {
+    case 'uint8':
+      return view.getUint8(offset)
+    case 'sint8':
+      return view.getInt8(offset)
+    case 'uint16':
+      return view.getUint16(offset, true)
+    case 'sint16':
+      return view.getInt16(offset, true)
+    case 'uint32':
+      return view.getUint32(offset, true)
+    case 'sint32':
+      return view.getInt32(offset, true)
+    case 'uint64':
+      return view.getBigUint64(offset, true)
+    case 'sint64':
+      return view.getBigInt64(offset, true)
+    case 'uint128': {
+      const lo = view.getBigUint64(offset, true)
+      const hi = view.getBigUint64(offset + 8, true)
+      return lo + hi * 2n ** 64n
+    }
+    case 'id':
+      return publicKeyToIdentity(data.subarray(offset, offset + 32))
+    default:
+      throw new PayloadBuildError(`Scalar decoding not supported for type "${type}"`)
+  }
+}
+
+// ── Field encoder ─────────────────────────────────────────────────────────────
+
+function encodeField(
+  field: BinaryField,
+  value: FieldValue,
+  buf: Uint8Array,
+  view: DataView,
+  offset: number,
+  structs: Record<string, NamedStruct>,
+  identityToPublicKey: (identity: string) => Uint8Array,
+): void {
+  switch (field.type) {
+    case 'uint8':
+    case 'sint8':
+    case 'uint16':
+    case 'sint16':
+    case 'uint32':
+    case 'sint32':
+    case 'uint64':
+    case 'sint64':
+    case 'uint128':
+    case 'id':
+      writeScalar(field.type, field.name, value, buf, view, offset, identityToPublicKey)
+      break
+    case 'bytes': {
+      if (!(value instanceof Uint8Array))
+        throw new PayloadBuildError(`Field "${field.name}": expected Uint8Array`)
+      if (value.byteLength !== field.byteLength)
+        throw new PayloadBuildError(
+          `Field "${field.name}": Uint8Array length ${value.byteLength} !== expected ${field.byteLength}`,
+        )
+      buf.set(value, offset)
+      break
+    }
+    case 'struct': {
+      if (field.structRef === undefined)
+        throw new PayloadBuildError(`Field "${field.name}": missing structRef`)
+      const namedStruct = structs[field.structRef]
+      if (!namedStruct)
+        throw new PayloadBuildError(`Field "${field.name}": struct "${field.structRef}" not found`)
+      if (
+        typeof value !== 'object' ||
+        value === null ||
+        Array.isArray(value) ||
+        value instanceof Uint8Array
+      )
+        throw new PayloadBuildError(`Field "${field.name}": expected object for struct`)
+      const nested = value as DecodedStruct
+      for (const sf of namedStruct.fields) {
+        const sv = nested[sf.name]
+        if (sv === undefined) throw new PayloadBuildError(`Struct field "${sf.name}" missing`)
+        encodeField(
+          sf,
+          sv as FieldValue,
+          buf,
+          view,
+          offset + sf.offset,
+          structs,
+          identityToPublicKey,
+        )
+      }
+      break
+    }
+    case 'array': {
+      if (!Array.isArray(value))
+        throw new PayloadBuildError(`Field "${field.name}": expected array`)
+      if (field.arrayItemByteLength === undefined)
+        throw new PayloadBuildError(`Field "${field.name}": missing arrayItemByteLength`)
+      const itemLen = field.arrayItemByteLength
+      const itemType = field.arrayItemType ?? 'uint8'
+      for (let i = 0; i < value.length; i++) {
+        const itemOffset = offset + i * itemLen
+        if (field.arrayItemStructRef !== undefined) {
+          const namedStruct = structs[field.arrayItemStructRef]
+          if (!namedStruct)
+            throw new PayloadBuildError(
+              `Field "${field.name}": struct item "${field.arrayItemStructRef}" not found`,
+            )
+          const itemVal = value[i] as DecodedStruct
+          for (const sf of namedStruct.fields) {
+            const sv = itemVal[sf.name]
+            if (sv === undefined)
+              throw new PayloadBuildError(`Array struct field "${sf.name}" missing`)
+            encodeField(
+              sf,
+              sv as FieldValue,
+              buf,
+              view,
+              itemOffset + sf.offset,
+              structs,
+              identityToPublicKey,
+            )
+          }
+        } else {
+          writeScalar(
+            itemType,
+            field.name,
+            value[i] as FieldValue,
+            buf,
+            view,
+            itemOffset,
+            identityToPublicKey,
+          )
+        }
+      }
+      break
+    }
+    default:
+      throw new PayloadBuildError(`Unknown field type: ${field.type}`)
+  }
+}
+
+// ── Field decoder ─────────────────────────────────────────────────────────────
+
+/**
+ * Decodes binary payload bytes into a typed record using registry field descriptors.
+ * Mirror of buildPayload — same field dispatch logic, reversed direction.
+ */
+export function decodePayload(
+  data: Uint8Array,
+  fields: BinaryField[],
+  structs: Record<string, NamedStruct>,
+  publicKeyToIdentity: (pk: Uint8Array) => string,
+): DecodedStruct {
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength)
+  const result: DecodedStruct = {}
+  for (const field of fields) {
+    result[field.name] = decodeField(field, data, view, field.offset, structs, publicKeyToIdentity)
+  }
+  return result
+}
+
+function decodeField(
+  field: BinaryField,
+  data: Uint8Array,
+  view: DataView,
+  offset: number,
+  structs: Record<string, NamedStruct>,
+  publicKeyToIdentity: (pk: Uint8Array) => string,
+): FieldValue {
+  switch (field.type) {
+    case 'uint8':
+    case 'sint8':
+    case 'uint16':
+    case 'sint16':
+    case 'uint32':
+    case 'sint32':
+    case 'uint64':
+    case 'sint64':
+    case 'uint128':
+    case 'id':
+      return readScalar(field.type, data, view, offset, publicKeyToIdentity)
+    case 'bytes':
+      return data.slice(offset, offset + field.byteLength)
+    case 'struct': {
+      if (field.structRef === undefined)
+        throw new PayloadBuildError(`Field "${field.name}": missing structRef`)
+      const namedStruct = structs[field.structRef]
+      if (!namedStruct)
+        throw new PayloadBuildError(`Field "${field.name}": struct "${field.structRef}" not found`)
+      const nested: DecodedStruct = {}
+      for (const sf of namedStruct.fields) {
+        nested[sf.name] = decodeField(
+          sf,
+          data,
+          view,
+          offset + sf.offset,
+          structs,
+          publicKeyToIdentity,
+        )
+      }
+      return nested
+    }
+    case 'array': {
+      if (field.arrayLength === undefined)
+        throw new PayloadBuildError(`Field "${field.name}": missing arrayLength`)
+      const items: FieldValue[] = []
+      const itemLen = field.arrayItemByteLength ?? 0
+      const itemType = field.arrayItemType ?? 'uint8'
+      for (let i = 0; i < field.arrayLength; i++) {
+        const itemOffset = offset + i * itemLen
+        if (field.arrayItemStructRef !== undefined) {
+          const namedStruct = structs[field.arrayItemStructRef]
+          if (namedStruct) {
+            const nested: DecodedStruct = {}
+            for (const sf of namedStruct.fields) {
+              nested[sf.name] = decodeField(
+                sf,
+                data,
+                view,
+                itemOffset + sf.offset,
+                structs,
+                publicKeyToIdentity,
+              )
+            }
+            items.push(nested)
+          }
+        } else {
+          items.push(readScalar(itemType, data, view, itemOffset, publicKeyToIdentity))
+        }
+      }
+      return items
+    }
+    default:
+      throw new PayloadBuildError(`Unknown field type: ${field.type}`)
+  }
+}
+
+/**
+ * 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 function buildPayloadManual(
+  fields: ReadonlyArray<{ type: FieldType; value: FieldValue }>,
+): Uint8Array {
+  const sizes: Record<string, number> = {
+    uint8: 1,
+    sint8: 1,
+    uint16: 2,
+    sint16: 2,
+    uint32: 4,
+    sint32: 4,
+    uint64: 8,
+    sint64: 8,
+    uint128: 16,
+    id: 32,
+  }
+  let totalSize = 0
+  for (const f of fields) {
+    if (f.type === 'struct' || f.type === 'array') {
+      throw new PayloadBuildError(
+        `buildPayloadManual does not support '${f.type}' fields — use buildPayload with a full BinaryField descriptor instead`,
+      )
+    }
+    if (f.type === 'id') {
+      throw new PayloadBuildError(
+        `buildPayloadManual does not support 'id' fields — use buildPayload with an identityToPublicKey parameter instead`,
+      )
+    }
+    totalSize += f.value instanceof Uint8Array ? f.value.byteLength : (sizes[f.type] ?? 0)
+  }
+  const buf = new Uint8Array(totalSize)
+  const view = new DataView(buf.buffer)
+  let offset = 0
+  for (const f of fields) {
+    if (f.value instanceof Uint8Array) {
+      buf.set(f.value, offset)
+      offset += f.value.byteLength
+    } else {
+      const size = sizes[f.type] ?? 0
+      writeScalar(f.type, '', f.value, buf, view, offset, () => new Uint8Array(32))
+      offset += size
+    }
+  }
+  return buf
+}

package/src/registry.ts

@@ -0,0 +1,204 @@
+import type {
+  AbiLookupResult,
+  ContractAbiVersion,
+  ContractCallBase,
+  ContractRegistry,
+} from './types.js'
+
+export class AbiNotFoundError extends Error {
+  constructor(
+    readonly contractIndex: number,
+    readonly epoch: number,
+    options?: { cause?: unknown },
+  ) {
+    super(`No ABI found for contract ${contractIndex} at epoch ${epoch}`, {
+      cause: options?.cause,
+    })
+    this.name = 'AbiNotFoundError'
+  }
+}
+
+export class EntryNotFoundError extends AbiNotFoundError {
+  constructor(
+    readonly kind: 'procedure' | 'function',
+    readonly contractName: string,
+    readonly inputType: number,
+  ) {
+    super(-1, -1)
+    this.message = `${kind} inputType ${inputType} not found in contract ${contractName}`
+    this.name = 'EntryNotFoundError'
+  }
+}
+
+/**
+ * Returns the ABI version active at the given epoch for the given contract.
+ * @throws {AbiNotFoundError} if no version covers the epoch.
+ */
+export function getAbi(
+  registry: ContractRegistry,
+  contractIndex: number,
+  epoch: number,
+): AbiLookupResult {
+  const versions = registry.versions.filter((v) => v.contractIndex === contractIndex)
+  const version = versions.find(
+    (v) =>
+      v.effectiveFromEpoch <= epoch && epoch <= (v.effectiveToEpoch ?? Number.POSITIVE_INFINITY),
+  )
+  if (!version) throw new AbiNotFoundError(contractIndex, epoch)
+  const maxFrom = versions.reduce((m, v) => Math.max(m, v.effectiveFromEpoch), 0)
+  const isCurrent = version.effectiveToEpoch === null
+  return {
+    version,
+    isCurrent,
+    isRegistryPossiblyStale: isCurrent && epoch > maxFrom,
+  }
+}
+
+/**
+ * Returns all ABI versions for a contract, sorted by effectiveFromEpoch ASC.
+ */
+export function getAbiHistory(
+  registry: ContractRegistry,
+  contractIndex: number,
+): ContractAbiVersion[] {
+  return registry.versions
+    .filter((v) => v.contractIndex === contractIndex)
+    .sort((a, b) => a.effectiveFromEpoch - b.effectiveFromEpoch)
+}
+
+/**
+ * Returns the currently-active ABI version (effectiveToEpoch === null).
+ * @throws {AbiNotFoundError} if none exists.
+ */
+export function getCurrentAbi(
+  registry: ContractRegistry,
+  contractIndex: number,
+): ContractAbiVersion {
+  const version = registry.versions.find(
+    (v) => v.contractIndex === contractIndex && v.effectiveToEpoch === null,
+  )
+  if (!version) throw new AbiNotFoundError(contractIndex, -1)
+  return version
+}
+
+/**
+ * Finds a procedure by inputType ordinal.
+ * @throws if not found.
+ */
+export function getProcedure(version: ContractAbiVersion, inputType: number): ContractCallBase {
+  const proc = version.procedures.find((p) => p.inputType === inputType)
+  if (!proc) throw new EntryNotFoundError('procedure', version.contractName, inputType)
+  return proc
+}
+
+/**
+ * Finds a function by inputType ordinal.
+ * @throws {EntryNotFoundError} if not found.
+ */
+export function getFunction(version: ContractAbiVersion, inputType: number): ContractCallBase {
+  const fn = version.functions.find((f) => f.inputType === inputType)
+  if (!fn) throw new EntryNotFoundError('function', version.contractName, inputType)
+  return fn
+}
+
+/**
+ * Returns the contract name for a given index.
+ * @throws if the index is not registered.
+ */
+export function findContractByIndex(registry: ContractRegistry, contractIndex: number): string {
+  const version = registry.versions.find((v) => v.contractIndex === contractIndex)
+  if (!version) throw new Error(`Contract index ${contractIndex} not found in registry`)
+  return version.contractName
+}
+
+/**
+ * Returns the contract index for a given name (case-insensitive).
+ * @throws if not found.
+ */
+export function findContractByName(registry: ContractRegistry, name: string): number {
+  const lower = name.toLowerCase()
+  const version = registry.versions.find((v) => v.contractName.toLowerCase() === lower)
+  if (!version) throw new Error(`Contract name "${name}" not found in registry`)
+  return version.contractIndex
+}
+
+/**
+ * Validates the registry for structural correctness.
+ * @throws with a descriptive message on any inconsistency.
+ */
+export function validateRegistry(registry: ContractRegistry): void {
+  const byContract = new Map<number, ContractAbiVersion[]>()
+  for (const v of registry.versions) {
+    const list = byContract.get(v.contractIndex) ?? []
+    list.push(v)
+    byContract.set(v.contractIndex, list)
+  }
+
+  for (const [contractIndex, versions] of byContract) {
+    const currentVersions = versions.filter((v) => v.effectiveToEpoch === null)
+    if (currentVersions.length > 1) {
+      throw new Error(
+        `Contract ${contractIndex} has multiple current versions (effectiveToEpoch === null)`,
+      )
+    }
+
+    const sorted = [...versions].sort((a, b) => a.effectiveFromEpoch - b.effectiveFromEpoch)
+    for (let i = 0; i < sorted.length - 1; i++) {
+      const a = sorted[i]
+      const b = sorted[i + 1]
+      if (a === undefined || b === undefined) continue
+      const aEnd = a.effectiveToEpoch ?? Number.POSITIVE_INFINITY
+      if (aEnd >= b.effectiveFromEpoch) {
+        throw new Error(
+          `Contract ${contractIndex} has overlapping epoch ranges: [${a.effectiveFromEpoch}, ${a.effectiveToEpoch}] and [${b.effectiveFromEpoch}, ${b.effectiveToEpoch}]`,
+        )
+      }
+    }
+
+    for (const v of versions) {
+      validateVersion(v)
+    }
+  }
+}
+
+function validateVersion(v: ContractAbiVersion): void {
+  for (const call of [...v.procedures, ...v.functions]) {
+    const inputSum = call.inputFields.reduce((s, f) => s + f.byteLength, 0)
+    if (inputSum !== call.inputSize) {
+      throw new Error(
+        `Contract ${v.contractName} ${call.kind} "${call.name}": inputSize ${call.inputSize} !== sum of inputField byteLengths ${inputSum}`,
+      )
+    }
+    const outputSum = call.outputFields.reduce((s, f) => s + f.byteLength, 0)
+    if (outputSum !== call.outputSize) {
+      throw new Error(
+        `Contract ${v.contractName} ${call.kind} "${call.name}": outputSize ${call.outputSize} !== sum of outputField byteLengths ${outputSum}`,
+      )
+    }
+    for (const field of [...call.inputFields, ...call.outputFields]) {
+      validateField(field, v)
+    }
+  }
+}
+
+function validateField(field: import('./types.js').BinaryField, v: ContractAbiVersion): void {
+  if (field.type === 'array') {
+    const len = field.arrayLength ?? 0
+    const itemLen = field.arrayItemByteLength ?? 0
+    if (len * itemLen !== field.byteLength) {
+      throw new Error(
+        `Contract ${v.contractName} field "${field.name}": arrayLength × arrayItemByteLength !== byteLength`,
+      )
+    }
+    if (field.arrayItemStructRef !== undefined && !(field.arrayItemStructRef in v.structs)) {
+      throw new Error(
+        `Contract ${v.contractName} field "${field.name}": arrayItemStructRef "${field.arrayItemStructRef}" not found in structs`,
+      )
+    }
+  }
+  if (field.type === 'struct' && field.structRef !== undefined && !(field.structRef in v.structs)) {
+    throw new Error(
+      `Contract ${v.contractName} field "${field.name}": structRef "${field.structRef}" not found in structs`,
+    )
+  }
+}