@qubic.org/registry 0.2.0

package/README.md

@@ -0,0 +1,321 @@
+# `@qubic.org/registry`
+
+ABI registry and binary payload codec for Qubic smart contracts.
+
+This package is the foundation of the Qubic TypeScript SDK's contract interaction layer. It stores per-epoch snapshots of every deployed smart contract's interface, so any call — historical or current — can be correctly encoded and decoded using the exact ABI that was active at that epoch. It also provides the binary codec that translates between typed TypeScript values and the little-endian binary format the Qubic network speaks.
+
+## Installation
+
+```sh
+bun add @qubic.org/registry
+```
+
+In a monorepo workspace, reference it as:
+
+```json
+{ "dependencies": { "@qubic.org/registry": "workspace:*" } }
+```
+
+## API Reference
+
+### Types
+
+```ts
+type FieldType =
+  | 'uint8' | 'uint16' | 'uint32' | 'uint64'
+  | 'sint8' | 'sint16' | 'sint32' | 'sint64'
+  | 'uint128' | 'id' | 'bytes' | 'array' | 'struct'
+
+interface BinaryField {
+  name: string
+  type: FieldType
+  offset: number        // byte offset from start of enclosing struct
+  byteLength: number    // total byte footprint, always authoritative
+  description?: string
+  arrayLength?: number
+  arrayItemType?: FieldType
+  arrayItemByteLength?: number
+  arrayItemStructRef?: string
+  structRef?: string
+}
+
+interface NamedStruct {
+  name: string
+  fields: BinaryField[]
+  byteLength: number
+}
+
+interface ContractCallBase {
+  kind: 'procedure' | 'function'
+  inputType: number       // declaration-order ordinal, starts at 1
+  name: string
+  description?: string
+  inputFields: BinaryField[]
+  outputFields: BinaryField[]
+  inputSize: number
+  outputSize: number
+  requiresAmount?: boolean
+  sourceRef?: string
+}
+
+interface ContractAbiVersion {
+  contractIndex: number
+  contractName: string
+  effectiveFromEpoch: number
+  effectiveToEpoch: number | null   // null = currently active
+  coreVersion?: string
+  coreCommit?: string
+  structs: Record<string, NamedStruct>
+  procedures: ContractCallBase[]
+  functions: ContractCallBase[]
+  changelog?: string
+  registeredAt: string
+  registeredBy?: string
+}
+
+interface ContractRegistry {
+  schemaVersion: 1
+  updatedAt: string
+  versions: ContractAbiVersion[]    // sorted contractIndex ASC, effectiveFromEpoch ASC
+}
+
+interface AbiLookupResult {
+  version: ContractAbiVersion
+  isCurrent: boolean
+  isRegistryPossiblyStale: boolean  // true when epoch > latest known and isCurrent=true
+}
+```
+
+### Registry functions
+
+```ts
+import {
+  getAbi,
+  getCurrentAbi,
+  getAbiHistory,
+  getProcedure,
+  getFunction,
+  findContractByIndex,
+  findContractByName,
+  validateRegistry,
+  AbiNotFoundError,
+} from '@qubic.org/registry'
+```
+
+| Function | Signature | Description |
+|---|---|---|
+| `getAbi` | `(registry, contractIndex, epoch) => AbiLookupResult` | Returns the ABI version active at the given epoch. Throws `AbiNotFoundError` if none covers it. |
+| `getCurrentAbi` | `(registry, contractIndex) => ContractAbiVersion` | Returns the version with `effectiveToEpoch === null`. Throws if none. |
+| `getAbiHistory` | `(registry, contractIndex) => ContractAbiVersion[]` | All versions sorted by `effectiveFromEpoch` ascending. |
+| `getProcedure` | `(version, inputType) => ContractCallBase` | Finds a procedure by its ordinal. Throws if not found. |
+| `getFunction` | `(version, inputType) => ContractCallBase` | Finds a function by its ordinal. Throws if not found. |
+| `findContractByIndex` | `(registry, contractIndex) => string` | Returns the contract name for an index. Throws if not registered. |
+| `findContractByName` | `(registry, name) => number` | Case-insensitive lookup of a contract index by name. Throws if not found. |
+| `validateRegistry` | `(registry) => void` | Checks for overlapping epoch ranges and field/size consistency. Throws with a descriptive message on any inconsistency. |
+
+### Payload codec
+
+```ts
+import {
+  buildPayload,
+  decodePayload,
+  buildPayloadManual,
+  PayloadBuildError,
+} from '@qubic.org/registry'
+
+type FieldValue = number | bigint | string | Uint8Array | FieldValue[] | DecodedStruct
+type DecodedStruct = Record<string, unknown>
+```
+
+**`buildPayload`**
+
+```ts
+function buildPayload(
+  fields: BinaryField[],
+  structs: Record<string, NamedStruct>,
+  input: Record<string, FieldValue | Uint8Array>,
+  identityToPublicKey: (identity: string) => Uint8Array,
+): Uint8Array
+```
+
+Encodes a record of named field values to binary. Encoding rules:
+
+- `uint8/16/32`, `sint8/16/32` — little-endian via `DataView`
+- `uint64` / `sint64` — `BigUint64` / `BigInt64` little-endian
+- `uint128` — two consecutive `uint64` LE (lo word first, hi second)
+- `id` — 32-byte public key via the injected `identityToPublicKey`
+- `bytes` — `Uint8Array` copied verbatim, zero-padded to `byteLength` if shorter
+- `struct` — recursive encoding using `structs[field.structRef].fields`
+- `array` — N items encoded sequentially
+
+Advanced: pass a `Uint8Array` whose length equals `field.byteLength` to bypass type coercion entirely.
+
+Throws `PayloadBuildError` on type mismatch, missing field, or length mismatch.
+
+**`decodePayload`**
+
+```ts
+function decodePayload(
+  data: Uint8Array,
+  fields: BinaryField[],
+  structs: Record<string, NamedStruct>,
+  publicKeyToIdentity: (pk: Uint8Array) => string,
+): DecodedStruct
+```
+
+Reverses `buildPayload`. All field types decode symmetrically.
+
+**`buildPayloadManual`**
+
+```ts
+function buildPayloadManual(
+  fields: ReadonlyArray<{ type: FieldType; value: FieldValue }>,
+): Uint8Array
+```
+
+Encodes ordered fields without field names. For unknown or custom contracts where you know the layout but have no registry entry.
+
+### Registry client
+
+```ts
+import { createRegistryClient } from '@qubic.org/registry'
+
+interface RegistryClientOptions {
+  url?: string                              // default: 'https://registry.qubic.ts/registry.json'
+  cache?: 'none' | 'session' | 'persistent' // default: 'session'
+  ttlMs?: number                            // default: 3_600_000 (1 hour)
+  fetch?: typeof globalThis.fetch
+}
+
+interface RegistryClient {
+  getAbi(contractIndex: number, epoch: number): Promise<AbiLookupResult>
+  getCurrentAbi(contractIndex: number): Promise<ContractAbiVersion>
+  getAbiHistory(contractIndex: number): Promise<ContractAbiVersion[]>
+  getRegistry(): Promise<ContractRegistry>
+}
+
+function createRegistryClient(options?: RegistryClientOptions): RegistryClient
+```
+
+Cache modes: `session` uses a module-level variable (server) or `sessionStorage` (browser); `persistent` uses `localStorage`; `none` fetches on every call.
+
+## Examples
+
+### Look up a contract ABI at a specific epoch
+
+```ts
+import { createRegistryClient, AbiNotFoundError } from '@qubic.org/registry'
+
+const client = createRegistryClient()
+
+const result = await client.getAbi(9, 212)
+console.log(result.version.contractName)       // 'Qearn'
+console.log(result.isCurrent)                  // false if epoch 212 is historical
+console.log(result.isRegistryPossiblyStale)    // true if epoch is ahead of the latest snapshot
+```
+
+### Encode a contract call input
+
+```ts
+import { createRegistryClient, buildPayload } from '@qubic.org/registry'
+import { identityToPublicKey } from '@qubic.org/crypto'
+
+const client = createRegistryClient()
+const abi = await client.getCurrentAbi(9)
+
+const lockProc = abi.procedures.find((p) => p.name === 'lock')!
+
+const payload = buildPayload(
+  lockProc.inputFields,
+  abi.structs,
+  { amount: 5_000_000n },
+  identityToPublicKey,
+)
+```
+
+### Decode a contract response
+
+```ts
+import { decodePayload } from '@qubic.org/registry'
+import { publicKeyToIdentity } from '@qubic.org/crypto'
+
+const decoded = decodePayload(responseBytes, fn.outputFields, abi.structs, publicKeyToIdentity)
+console.log(decoded.returnCode) // number
+```
+
+### Build a payload without a registry (manual mode)
+
+```ts
+import { buildPayloadManual } from '@qubic.org/registry'
+
+const payload = buildPayloadManual([
+  { type: 'uint64', value: 5_000_000n },
+  { type: 'uint32', value: 150 },
+])
+```
+
+### Walk a contract's version history
+
+```ts
+const history = await client.getAbiHistory(9)
+for (const v of history) {
+  console.log(`epoch ${v.effectiveFromEpoch}–${v.effectiveToEpoch ?? 'now'}: ${v.changelog}`)
+}
+```
+
+## Error handling
+
+```ts
+import { AbiNotFoundError, PayloadBuildError } from '@qubic.org/registry'
+
+try {
+  const result = await client.getAbi(9, 1)
+} catch (e) {
+  if (e instanceof AbiNotFoundError) {
+    console.error(`No ABI for contract ${e.contractIndex} at epoch ${e.epoch}`)
+  }
+}
+
+try {
+  buildPayload(fields, structs, { wrongField: 0 }, idToPk)
+} catch (e) {
+  if (e instanceof PayloadBuildError) {
+    console.error(e.message) // 'Missing field "amount"'
+  }
+}
+```
+
+## Data layout
+
+The compiled registry lives under `data/`:
+
+```
+data/
+  epochs/{epoch}/{ContractName}.json   # one ContractAbiVersion per file
+  epoch-refs.json                      # maps epoch numbers to git tags
+  registry.json                        # compiled ContractRegistry (version-range index)
+  schema.json                          # JSON Schema for validation
+```
+
+## Backfill scripts
+
+These scripts are not exported but maintain the data above.
+
+```sh
+# Parse a single contract ABI from local resources/core/
+bun scripts/extract-abi.ts
+
+# Backfill historical snapshots by scanning qubic/core git tags
+bun scripts/backfill.ts --from-epoch 104 [--to-epoch 220] [--contracts Qearn,Qx] [--token GH_TOKEN] [--dry-run]
+
+# Validate all epoch snapshot files against the JSON Schema
+bun scripts/validate.ts
+```
+
+## Design notes
+
+**Per-epoch snapshots** — Qubic contract ABIs change between epochs. Storing one `ContractAbiVersion` per epoch range means historical transactions from any epoch can be decoded against the correct struct layout, not the current one.
+
+**Injected identity converters** — `buildPayload` and `decodePayload` accept `identityToPublicKey` and `publicKeyToIdentity` as parameters rather than importing from `@qubic.org/crypto` directly. This keeps the codec tree-shakeable and testable without cryptographic dependencies, and lets server and browser environments supply different implementations.
+
+**`effectiveToEpoch: null`** — a sentinel value meaning "currently active." This avoids storing an arbitrary large epoch ceiling that would need updating with every new epoch.

package/data/epoch-refs.json

@@ -0,0 +1,131 @@
+{
+  "83": "v1.180.0",
+  "84": "v1.181.0",
+  "85": "v1.182.0",
+  "86": "v1.183.0",
+  "87": "v1.184.0",
+  "88": "v1.185.1",
+  "89": "v1.186.0",
+  "90": "v1.187.0",
+  "91": "v1.188.0",
+  "92": "v1.189.0",
+  "93": "v1.190.0",
+  "94": "v1.191.1",
+  "95": "v1.192.0",
+  "96": "v1.193.1",
+  "97": "v1.193.4",
+  "98": "v1.194.2",
+  "99": "v1.195.1",
+  "100": "v1.196.0",
+  "101": "v1.197.0",
+  "102": "v1.198.0",
+  "104": "v1.199.0",
+  "106": "v1.200.0",
+  "107": "v1.201.0",
+  "108": "v1.202.0",
+  "109": "v1.203.1",
+  "110": "v1.204.0",
+  "111": "v1.205.1",
+  "112": "v1.206.0",
+  "113": "v1.207.0",
+  "114": "v1.208.0",
+  "115": "v1.209.0",
+  "116": "v1.210.0",
+  "117": "v1.210.1",
+  "118": "v1.211.0",
+  "119": "v1.212.0",
+  "120": "v1.212.1",
+  "121": "v1.213.0",
+  "122": "v1.214.1",
+  "123": "v1.215.0",
+  "124": "v1.216.0",
+  "125": "v1.217.0",
+  "126": "v1.218.0",
+  "127": "v1.219.0",
+  "128": "v1.220.0",
+  "129": "v1.221.0",
+  "130": "v1.222.1",
+  "131": "v1.223.1",
+  "132": "v1.224.4",
+  "133": "v1.225.1",
+  "134": "v1.225.2",
+  "135": "v1.225.3",
+  "136": "v1.226.0",
+  "137": "v1.227.0",
+  "138": "v1.228.0",
+  "139": "v1.229.0",
+  "140": "v1.230.0",
+  "141": "v1.230.1",
+  "142": "v1.230.2",
+  "143": "v1.231.0",
+  "144": "v1.232.0",
+  "145": "v1.232.1",
+  "146": "v1.233.0",
+  "147": "v1.233.1",
+  "148": "v1.234.0",
+  "149": "v1.235.0",
+  "150": "v1.235.1",
+  "151": "v1.236.0",
+  "152": "v1.237.0",
+  "153": "v1.238.0",
+  "154": "v1.239.1",
+  "155": "v1.240.0",
+  "156": "v1.241.0",
+  "157": "v1.242.0",
+  "158": "v1.242.1",
+  "159": "v1.243.0",
+  "160": "v1.244.1",
+  "161": "v1.245.1",
+  "162": "v1.245.3",
+  "163": "v1.246.2",
+  "164": "v1.246.3",
+  "165": "v1.247.0",
+  "166": "v1.247.1",
+  "167": "v1.248.0",
+  "168": "v1.249.1",
+  "169": "v1.250.0",
+  "170": "v1.251.0",
+  "171": "v1.252.0",
+  "172": "v1.253.1",
+  "173": "v1.254.0",
+  "174": "v1.255.0",
+  "175": "v1.256.0",
+  "176": "v1.257.1",
+  "177": "v1.258.1",
+  "178": "v1.259.2",
+  "179": "v1.260.0",
+  "180": "v1.261.0",
+  "181": "v1.262.0",
+  "182": "v1.263.0",
+  "183": "v1.264.0",
+  "184": "v1.265.0",
+  "185": "v1.265.3",
+  "186": "v1.266.1",
+  "187": "v1.267.0",
+  "188": "v1.268.0",
+  "189": "v1.268.1",
+  "190": "v1.269.0",
+  "191": "v1.271.0",
+  "192": "v1.272.0",
+  "193": "v1.272.1",
+  "194": "v1.272.2",
+  "195": "v1.273.0",
+  "196": "v1.274.0",
+  "197": "v1.275.0",
+  "198": "v1.276.0",
+  "199": "v1.277.0",
+  "200": "v1.278.0",
+  "201": "v1.279.0",
+  "202": "v1.280.0",
+  "203": "v1.281.0",
+  "204": "v1.282.0",
+  "205": "v1.283.0",
+  "206": "v1.284.0",
+  "207": "v1.285.1",
+  "208": "v1.286.1",
+  "209": "v1.287.1",
+  "210": "v1.288.0",
+  "211": "v1.289.0",
+  "212": "v1.290.0",
+  "213": "v1.291.0"
+}

package/data/epochs/122/MyLastMatch.json

@@ -0,0 +1,9 @@
+{
+  "contractIndex": 5,
+  "contractName": "MyLastMatch",
+  "contractAddress": "FAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAYWJB",
+  "epoch": 122,
+  "structs": {},
+  "procedures": [],
+  "functions": []
+}