zklicensing 0.1.0-beta.2 → 0.1.0-beta.21

package/src/chainHead.ts

@@ -0,0 +1,106 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * chainHead.ts — reads a zkApp's first state field (its tree root) and the
+ * chain's current slot from a Mina node over GraphQL, in one query, without
+ * o1js and without touching o1js's global Mina instance.
+ */
+
+import { DEFAULT_MINA_GRAPHQL_URLS } from './onChainRoot.js';
+
+/** `state`: the account's whole app state (decimal strings). */
+export type ChainHead = { root: string; slot: number; state: string[] };
+
+export async function readChainHead(args: {
+  address: string;
+  network: 'devnet' | 'mainnet';
+  graphqlUrl?: string;
+  fetcher?: typeof fetch;
+}): Promise<ChainHead> {
+  const url = args.graphqlUrl ?? DEFAULT_MINA_GRAPHQL_URLS[args.network];
+  const { account, slot } = await readZkappHead({ address: args.address, graphqlUrl: url, fetcher: args.fetcher });
+  const root = account.appState?.[0];
+  if (!root) throw new Error(`${args.address} is not a zkApp on ${args.network}`);
+  if (slot === undefined) throw new MinaNodeError(`Mina node ${url} did not report the current slot`, 0);
+  return { root, slot, state: account.appState! };
+}
+
+/** Permission names as a Mina node reports them: 'Proof', 'Signature', 'Either', 'None', 'Impossible'. */
+export type ZkappAccount = {
+  found: boolean;
+  zkappUri?: string;
+  vkHash?: string;
+  appState?: string[];
+  permissions?: {
+    editState?: string; send?: string; setZkappUri?: string; setPermissions?: string;
+    setDelegate?: string; setTiming?: string;
+    setVerificationKey?: { auth?: string; txnVersion?: number };
+  };
+};
+
+/** A Mina node that couldn't be reached or answered with an error; `status` 0 when there was no HTTP answer. */
+export class MinaNodeError extends Error {
+  constructor(message: string, readonly status: number) { super(message); }
+}
+
+/**
+ * Reads a zkApp account (state, verification-key hash, URI, permissions)
+ * from a Mina node over GraphQL — the fields o1js's fetchAccount reads,
+ * without o1js and its global Mina instance. `found: false` when the node
+ * has no such account.
+ */
+export async function readZkappAccount(args: { address: string; graphqlUrl: string; fetcher?: typeof fetch }): Promise<ZkappAccount> {
+  return (await readZkappHead(args)).account;
+}
+
+/**
+ * The one GraphQL read behind readZkappAccount and readChainHead: the
+ * account and the chain's current slot (`undefined` when the node didn't
+ * report it) in one query. Throws MinaNodeError.
+ */
+export async function readZkappHead(args: { address: string; graphqlUrl: string; fetcher?: typeof fetch }): Promise<{ account: ZkappAccount; slot?: number }> {
+  const query = `query($pk: PublicKey!) {
+    account(publicKey: $pk) {
+      zkappUri
+      zkappState
+      verificationKey { hash }
+      permissions { editState send setZkappUri setPermissions setDelegate setTiming setVerificationKey { auth txnVersion } }
+    }
+    bestChain(maxLength: 1) { protocolState { consensusState { slotSinceGenesis } } }
+  }`;
+  let resp: Response;
+  try {
+    resp = await (args.fetcher ?? fetch)(args.graphqlUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ query, variables: { pk: args.address } }),
+    });
+  } catch (e: any) {
+    throw new MinaNodeError(`Mina node ${args.graphqlUrl}: ${e?.message ?? e}`, 0);
+  }
+  const body = await resp.json().catch(() => null) as { data?: { account?: any; bestChain?: any[] }; errors?: Array<{ message?: string }> } | null;
+  if (!resp.ok || !body?.data) {
+    throw new MinaNodeError(`Mina node ${args.graphqlUrl}: ${body?.errors?.map(e => e.message).join('; ') || `HTTP ${resp.status}`}`, resp.status);
+  }
+  const rawSlot = body.data.bestChain?.[0]?.protocolState?.consensusState?.slotSinceGenesis;
+  const slot = rawSlot === undefined || rawSlot === null || !Number.isFinite(Number(rawSlot)) ? undefined : Number(rawSlot);
+  const a = body.data.account;
+  if (!a) return { account: { found: false }, slot };
+  const p = a.permissions ?? {};
+  const txn = p.setVerificationKey?.txnVersion;
+  return {
+    slot,
+    account: {
+      found: true,
+      zkappUri: a.zkappUri ?? undefined,
+      vkHash: a.verificationKey?.hash != null ? String(a.verificationKey.hash) : undefined,
+      appState: Array.isArray(a.zkappState) ? a.zkappState.map(String) : undefined,
+      permissions: {
+        editState: p.editState, send: p.send, setZkappUri: p.setZkappUri, setPermissions: p.setPermissions,
+        setDelegate: p.setDelegate, setTiming: p.setTiming,
+        setVerificationKey: p.setVerificationKey ? { auth: p.setVerificationKey.auth, txnVersion: txn === undefined || txn === null ? undefined : Number(txn) } : undefined,
+      },
+    },
+  };
+}

package/src/compactMerkleMap.ts

@@ -0,0 +1,222 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * compactMerkleMap.ts
+ *
+ * A drop-in for o1js's MerkleMap (height 256: set, getRoot, getWitness — same
+ * positions, hashes and witnesses) that stores only what the tree can't
+ * compute cheaply: the leaves, and the values of the two children of every
+ * node where two leaves' paths split ("split children", 2(N − 1) of them).
+ * Every other node a witness needs is an empty subtree, a known constant.
+ *
+ * So it can be saved and loaded without re-hashing (toCompact / fromCompact):
+ * a MerkleMap would have to be rebuilt, one 256-hash path per leaf. Changes
+ * (setMany) re-hash only the paths above the changed leaves.
+ */
+
+import { Bool, Field, MerkleMap, MerkleMapWitness, Poseidon } from 'o1js';
+
+export const TREE_HEIGHT = 256;
+
+let zeroCache: bigint[] | null = null;
+/** zeros()[l]: the value of an empty subtree whose top is at level l. */
+export function zeros(): bigint[] {
+  if (!zeroCache) {
+    const z = [0n];
+    for (let i = 1; i < TREE_HEIGHT; i++) z.push(Poseidon.hash([Field(z[i - 1]), Field(z[i - 1])]).toBigInt());
+    zeroCache = z;
+  }
+  return zeroCache;
+}
+const H = (a: bigint, b: bigint) => Poseidon.hash([Field(a), Field(b)]).toBigInt();
+
+const keyMap = new MerkleMap();
+/** A key's leaf position, as MerkleMap places it. */
+export function keyIndex(key: Field | string | bigint): bigint {
+  return (keyMap as any)._keyToIndex(Field(key)) as bigint;
+}
+
+function bitLength(x: bigint): number { let n = 0; while (x > 0n) { x >>= 1n; n++; } return n; }
+
+/** The split-children positions [level, index], in canonical order, for sorted leaf positions. */
+export function splitChildren(sorted: bigint[]): Array<[number, bigint]> {
+  const out: Array<[number, bigint]> = [];
+  for (let i = 0; i + 1 < sorted.length; i++) {
+    const a = sorted[i], b = sorted[i + 1];
+    const l = bitLength(a ^ b) - 1; // the children's level; they meet at l + 1
+    out.push([l, a >> BigInt(l)], [l, b >> BigInt(l)]);
+  }
+  return out;
+}
+
+/** Field values as 32-byte big-endian words, base64. */
+export function encodeFields(values: bigint[]): string {
+  const bytes = new Uint8Array(values.length * 32);
+  values.forEach((v, i) => { for (let k = 31; k >= 0; k--) { bytes[i * 32 + k] = Number(v & 0xffn); v >>= 8n; } });
+  let bin = '';
+  for (let i = 0; i < bytes.length; i += 0x8000) bin += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  return btoa(bin);
+}
+export function decodeFields(b64: string): bigint[] {
+  const bin = atob(b64);
+  if (bin.length % 32) throw new Error('compact data is not a whole number of fields');
+  const out: bigint[] = [];
+  for (let i = 0; i < bin.length; i += 32) {
+    let v = 0n;
+    for (let k = 0; k < 32; k++) v = (v << 8n) | BigInt(bin.charCodeAt(i + k));
+    out.push(v);
+  }
+  return out;
+}
+
+const nodeKey = (l: number, j: bigint) => `${l}:${j}`;
+const cmp = (a: bigint, b: bigint) => (a < b ? -1 : a > b ? 1 : 0);
+/** First position >= x in a sorted array. */
+function lower(arr: bigint[], x: bigint): number {
+  let lo = 0, hi = arr.length;
+  while (lo < hi) { const m = (lo + hi) >> 1; if (arr[m] < x) lo = m + 1; else hi = m; }
+  return lo;
+}
+
+export type CompactMapData = {
+  /** Leaf positions, sorted. */
+  indices: bigint[];
+  /** Leaf values, in the same order. */
+  leaves: bigint[];
+  /** Split-children values, in splitChildren order. */
+  splits: bigint[];
+};
+
+export class CompactMerkleMap {
+  private idx: bigint[] = [];
+  private leaves = new Map<bigint, bigint>();
+  private split = new Map<string, bigint>();
+  private root: bigint = zeros()[TREE_HEIGHT - 1];
+
+  /** Number of non-empty leaves. */
+  get size(): number { return this.idx.length; }
+
+  getRoot(): Field { return Field(this.root); }
+
+  set(key: Field, value: Field): void { this.setMany([[key, value]]); }
+
+  /** Sets several leaves, re-hashing only above them. */
+  setMany(entries: Iterable<[Field | string, Field | bigint]>): void {
+    const changed: bigint[] = [];
+    for (const [k, v] of entries) {
+      const i = keyIndex(k);
+      const val = typeof v === 'bigint' ? v : v.toBigInt();
+      if (!this.leaves.has(i)) this.idx.splice(lower(this.idx, i), 0, i);
+      this.leaves.set(i, val);
+      changed.push(i);
+    }
+    if (changed.length === 0) return;
+    changed.sort(cmp);
+    this.recompute(changed);
+  }
+
+  /** A MerkleMapWitness for `key`, as MerkleMap.getWitness gives it. */
+  getWitness(key: Field): MerkleMapWitness {
+    const { isLefts, siblings } = this.witnessValues(keyIndex(key));
+    return new MerkleMapWitness(isLefts.map(b => Bool(b)), siblings.map(s => Field(s)));
+  }
+
+  witnessValues(s: bigint): { isLefts: boolean[]; siblings: bigint[] } {
+    const isLefts: boolean[] = [];
+    const siblings: bigint[] = [];
+    const memo = new Map<string, bigint>();
+    for (let l = 0; l < TREE_HEIGHT - 1; l++) {
+      const at = s >> BigInt(l);
+      isLefts.push((at & 1n) === 0n);
+      // A split child, or empty — except for a key not in the map, whose
+      // path meets one non-empty subtree that isn't a split child: computed.
+      siblings.push(this.split.get(nodeKey(l, at ^ 1n)) ?? this.valueOf(l, at ^ 1n, [], memo));
+    }
+    return { isLefts, siblings };
+  }
+
+  /** A node's value, when it is a leaf, a split child, or empty; otherwise undefined. */
+  getNode(level: number, index: bigint): bigint | undefined {
+    if (level === 0 && this.leaves.has(index)) return this.leaves.get(index);
+    const v = this.split.get(nodeKey(level, index));
+    if (v !== undefined) return v;
+    const lo = index << BigInt(level), hi = ((index + 1n) << BigInt(level)) - 1n;
+    return lower(this.idx, lo) === lower(this.idx, hi + 1n) ? zeros()[level] : undefined;
+  }
+
+  /** The split-children values in canonical order (for compact copies). */
+  splitValues(): bigint[] {
+    return splitChildren(this.idx).map(([l, j]) => this.split.get(nodeKey(l, j))!);
+  }
+
+  toCompact(): CompactMapData {
+    return { indices: [...this.idx], leaves: this.idx.map(i => this.leaves.get(i)!), splits: this.splitValues() };
+  }
+
+  /**
+   * Loads a saved copy without re-hashing the tree: only the path from the
+   * root down to the first split. Throws if the data is inconsistent, or if
+   * `expectedRoot` is given and the copy doesn't fold to it. Values deeper
+   * down aren't re-checked (that would cost the full rebuild): protect a
+   * stored copy with a checksum.
+   */
+  static fromCompact(d: CompactMapData, expectedRoot?: string): CompactMerkleMap {
+    const m = new CompactMerkleMap();
+    for (let i = 1; i < d.indices.length; i++) if (d.indices[i] <= d.indices[i - 1]) throw new Error('compact map: positions are not sorted');
+    if (d.leaves.length !== d.indices.length) throw new Error('compact map: one value per leaf expected');
+    const positions = splitChildren(d.indices);
+    if (d.splits.length !== positions.length) throw new Error(`compact map: expected ${positions.length} split values, got ${d.splits.length}`);
+    m.idx = [...d.indices];
+    d.indices.forEach((i, k) => m.leaves.set(i, d.leaves[k]));
+    positions.forEach(([l, j], k) => m.split.set(nodeKey(l, j), d.splits[k]));
+    m.root = m.computeRoot([]);
+    if (expectedRoot !== undefined && m.root.toString() !== expectedRoot) throw new Error('compact map: the saved copy does not fold to its root');
+    return m;
+  }
+
+  /** Recomputes split values above the changed positions (sorted), and the root. */
+  private recompute(changed: bigint[]): void {
+    this.root = this.computeRoot(changed);
+  }
+
+  private computeRoot(changed: bigint[]): bigint {
+    const memo = new Map<string, bigint>();
+    const next = new Map<string, bigint>();
+    for (const [l, j] of splitChildren(this.idx)) next.set(nodeKey(l, j), this.valueOf(l, j, changed, memo));
+    const root = this.valueOf(TREE_HEIGHT - 1, 0n, changed, memo);
+    this.split = next;
+    return root;
+  }
+
+  /**
+   * A node's value: empty, a leaf, a split child kept from before when no
+   * changed leaf is below it, one leaf's path, or the hash of its children.
+   */
+  private valueOf(l: number, j: bigint, changed: bigint[], memo: Map<string, bigint>): bigint {
+    const k = nodeKey(l, j);
+    const m = memo.get(k);
+    if (m !== undefined) return m;
+    const z = zeros();
+    const idx = this.idx;
+    const lo = j << BigInt(l), hi = ((j + 1n) << BigInt(l)) - 1n;
+    const a = lower(idx, lo), b = lower(idx, hi + 1n);
+    let v: bigint;
+    if (a === b) v = z[l];
+    else if (l === 0) v = this.leaves.get(j)!;
+    else {
+      const touched = lower(changed, lo) !== lower(changed, hi + 1n);
+      const kept = touched ? undefined : this.split.get(k);
+      if (kept !== undefined) v = kept;
+      else if (b - a === 1) {
+        // One leaf below: its path up to here, beside empty subtrees.
+        const pos = idx[a];
+        let h = this.leaves.get(pos)!;
+        for (let t = 0; t < l; t++) h = ((pos >> BigInt(t)) & 1n) === 0n ? H(h, z[t]) : H(z[t], h);
+        v = h;
+      } else v = H(this.valueOf(l - 1, 2n * j, changed, memo), this.valueOf(l - 1, 2n * j + 1n, changed, memo));
+    }
+    memo.set(k, v);
+    return v;
+  }
+}