@zkthunder_/sdk 0.1.0

package/README.md

@@ -0,0 +1,112 @@
+# @zkthunder_/sdk
+
+Zero-knowledge proofs for Robinhood Chain, generated locally with no
+dependencies, plus a tiny read-only client for the deployed zkThunder
+contracts. Everything the zkthunder.net labs do, as library calls.
+
+- Pedersen commitments on secp256k1: perfectly hiding, binding under discrete log.
+- Lineage bundles: two hidden values, proofs they are well formed, and a proof they link.
+- Range proofs: a hidden value is at least a public threshold (32 bit range).
+- Bound bundles for the trustless lineage: commitments that provably open to public roots.
+- Calldata encoders for every deployed contract, and a client that verifies on chain
+  over plain JSON-RPC.
+
+Secrets never leave your process. The outputs are commitments, proofs and booleans.
+
+## Install
+
+    npm install @zkthunder_/sdk
+
+Node 18 or newer (uses `fetch` and `BigInt`). No other dependencies.
+
+## Private eligibility with PrivateGate
+
+A user proves that a hidden balance is at least a threshold, for a named
+purpose, bound to the gate contract and to their own address. The gate stores
+the threshold; any contract can then ask `isEligible` without the balance ever
+appearing on chain.
+
+```js
+const zk = require("@zkthunder_/sdk");
+
+const GATE = "0x...";                       // a deployed PrivateGate
+const user = "0xYourAddress";
+const ctx = zk.gateContext(GATE, user, "tier-1 access");   // keccak256(abi.encode(gate, user, purpose))
+
+const { proof, commitment } = zk.proveRange({ value: 1250n, threshold: 1000n, ctx });
+// send from `user`: to = GATE, data = zk.encodeGateProve("tier-1 access", proof)
+// afterwards, from anywhere:
+const chain = new zk.Chain();
+await chain.isEligible(GATE, user, "tier-1 access", 1000n);   // true, and the 1250 was never revealed
+```
+
+The proof is useless anywhere else: another address, another gate or another
+purpose changes the context, and the verifier folds the context into every
+challenge.
+
+## Verify a range proof against the deployed verifier
+
+```js
+const ctx = zk.context("my-app", "proof-of-reserves", "2026-09");
+const rg = zk.proveRange({ value: 5_000_000n, threshold: 1_000_000n, ctx });
+await new zk.Chain().verifyRange(rg.proof, ctx);   // true: the RangeVerifier on mainnet accepts it
+```
+
+To publish a public receipt from your own address, send
+`zk.encodeAttest(rg.proof, ctx)` to `zk.MAINNET.rangeVerifier`; it emits
+`RangeVerified(by, ctx, threshold, commitmentDigest)`.
+
+## Read and audit the trustless lineage
+
+```js
+const chain = new zk.Chain();
+const head = await chain.lineage();       // { lastSeq, lastEndBlock, lastRoot, latestBlock }
+const audit = await chain.auditAnchor();  // re-reads the end block from the node and compares
+console.log(audit.ok, audit.rootMatchesBlock, audit.linksToPrevious);
+```
+
+Every root in the lineage was extracted by the contract from a block header it
+checked against the chain's own block hash. No caller ever supplies a root.
+
+## Lineage bundles and the public registry
+
+```js
+const ctx = zk.context("my-app/lineage", String(Date.now()));
+const lin = zk.proveLineage("previous state", "new state", ctx);
+await new zk.Chain().verifyLineage(lin.proof, ctx);                 // LineageVerifier says yes
+// record it: send zk.encodeSubmit(lin.proof, ctx) to zk.MAINNET.publicProofs
+```
+
+## API
+
+| Function | Purpose |
+| --- | --- |
+| `commit(value, blinding?)` | Pedersen commitment to a 32 byte value (text is hashed) |
+| `proveLineage(prev, out, ctx)` / `verifyLineage(proof, ctx)` | 23 word bundle for LineageVerifier |
+| `proveRange({ value, threshold, ctx, blinding? })` / `verifyRange(proof, ctx)` | range proof for RangeVerifier |
+| `proveTrustless(prev, out, ctx)` / `verifyTrustless(proof, ctx, prev, out)` | 37 word bound bundle for TrustlessAnchor |
+| `context(...parts)`, `purposeId(name)`, `gateContext(gate, user, purpose)` | context words that bind proofs to their use |
+| `encodeVerify`, `encodeVerifyBound`, `encodeSubmit`, `encodeAttest`, `encodeGateProve`, `encodeIsEligible` | calldata for the deployed contracts |
+| `new Chain({ rpcUrl?, addresses? })` | `verifyLineage`, `verifyRange`, `verifyTrustless`, `isEligible`, `lineage`, `record`, `auditAnchor` |
+| `MAINNET` | deployed addresses on chain 4663 |
+
+Sending transactions is left to whatever wallet library you already use: the
+encoders return calldata, and `MAINNET` has the addresses.
+
+## Limits, stated plainly
+
+- Range proofs cover a 32 bit difference between value and threshold and cost
+  about 1.9 million gas to verify on chain. Zero is not a valid threshold.
+- The on-chain verifiers compare 160 bit point addresses (the ecrecover trick);
+  a full coordinate check is on the roadmap.
+- These proofs establish commitment structure and lineage linkage. They do not
+  prove a state transition was computed correctly; that is the zkVM tier.
+
+## Test
+
+    node test.js
+
+Runs the local checks, then verifies fresh proofs against the mainnet contracts
+when the RPC is reachable.
+
+Apache-2.0.

package/index.d.ts

@@ -0,0 +1,48 @@
+export type Bytes32Like = string | Uint8Array;
+export interface Point { x: string; y: string }
+export interface Addresses {
+  chainId: number; rpcUrl: string; explorer: string;
+  proofAnchor: string; lineageVerifier: string; publicProofs: string; rangeVerifier: string; boundVerifier: string; trustlessAnchor: string;
+  /** empty until PrivateGate is deployed */
+  privateGate: string;
+}
+export const MAINNET: Readonly<Addresses>;
+export const NBITS: number;
+
+export function commit(value: Bytes32Like, blinding?: bigint | string | number): { commitment: Point; blinding: string };
+export function proveLineage(prevRoot: Bytes32Like, outRoot: Bytes32Like, ctx: Bytes32Like): { proof: string; words: bigint[]; ctx: string; commitments: { in: Point; out: Point }; verified: boolean };
+export function verifyLineage(proof: string | Uint8Array | bigint[], ctx: Bytes32Like): boolean;
+export function proveRange(args: { value: bigint | number | string; threshold: bigint | number | string; ctx: Bytes32Like; blinding?: bigint | string }): { proof: string; words: bigint[]; ctx: string; commitment: Point; blinding: string; threshold: string; bits: number; verified: boolean };
+export function verifyRange(proof: string | Uint8Array | bigint[], ctx: Bytes32Like): boolean;
+export function proveTrustless(prevRoot: Bytes32Like, outRoot: Bytes32Like, ctx: Bytes32Like): { proof: string; words: bigint[]; ctx: string; commitments: { in: Point; out: Point }; verified: boolean };
+export function verifyTrustless(proof: string | Uint8Array | bigint[], ctx: Bytes32Like, prevRoot: Bytes32Like, outRoot: Bytes32Like): boolean;
+
+export function context(...parts: Array<string | Uint8Array>): Uint8Array;
+export function purposeId(name: string): Uint8Array;
+export function gateContext(gate: string, user: string, purpose: string): Uint8Array;
+export function toBytes32(v: Bytes32Like): Uint8Array;
+export function keccak256(bytes: Uint8Array): Uint8Array;
+export function hex(bytes: Uint8Array): string;
+export function fromHex(hex: string): Uint8Array;
+
+export function encodeVerify(proof: string | Uint8Array | bigint[], ctx: Bytes32Like): string;
+export function encodeVerifyBound(proof: string | Uint8Array | bigint[], ctx: Bytes32Like, prevRoot: Bytes32Like, outRoot: Bytes32Like): string;
+export function encodeSubmit(proof: string | Uint8Array | bigint[], ctx: Bytes32Like, tag?: Bytes32Like): string;
+export function encodeAttest(proof: string | Uint8Array | bigint[], ctx: Bytes32Like): string;
+export function encodeGateProve(purpose: string, proof: string | Uint8Array | bigint[]): string;
+export function encodeIsEligible(user: string, purpose: string, minThreshold: bigint | number | string, maxAge?: bigint | number): string;
+
+export interface TrustlessRecord { seq: number; stateRootPrev: string; stateRootOut: string; cInDigest: string; cOutDigest: string; startBlock: number; endBlock: number; timestamp: number; prover: string }
+export class Chain {
+  constructor(opts?: { rpcUrl?: string; addresses?: Partial<Addresses> });
+  rpcUrl: string; addresses: Addresses;
+  rpc(method: string, params: unknown[]): Promise<any>;
+  call(to: string, data: string): Promise<string>;
+  verifyLineage(proof: string | Uint8Array | bigint[], ctx: Bytes32Like): Promise<boolean>;
+  verifyRange(proof: string | Uint8Array | bigint[], ctx: Bytes32Like): Promise<boolean>;
+  verifyTrustless(proof: string | Uint8Array | bigint[], ctx: Bytes32Like, prevRoot: Bytes32Like, outRoot: Bytes32Like): Promise<boolean>;
+  isEligible(gate: string, user: string, purpose: string, minThreshold: bigint | number | string, maxAge?: number): Promise<boolean>;
+  lineage(): Promise<{ contract: string; lastSeq: number; lastEndBlock: number; lastRoot: string; latestBlock: number }>;
+  record(seq: number): Promise<TrustlessRecord>;
+  auditAnchor(seq?: number): Promise<TrustlessRecord & { blockStateRoot: string; rootMatchesBlock: boolean; linksToPrevious: boolean | "genesis"; ok: boolean }>;
+}

package/index.js

@@ -0,0 +1,185 @@
+// zkThunder SDK: build and check zero-knowledge proofs for Robinhood Chain.
+//
+// No dependencies. Proofs are generated in this process; only commitments,
+// proofs and verification results leave it. Chain access uses plain
+// JSON-RPC over fetch (Node 18+), so no wallet library is required to read
+// the lineage or to ask a verifier contract its opinion.
+"use strict";
+const S = require("./lib/sigma.js");
+const { proveBundle, verifyBundleJS } = require("./lib/prove.js");
+const R = require("./lib/range.js");
+const T = require("./lib/trustless.js");
+
+/** Deployed addresses on Robinhood Chain mainnet (chain id 4663), all with verified source. */
+const MAINNET = Object.freeze({
+  chainId: 4663,
+  rpcUrl: "https://rpc.mainnet.chain.robinhood.com",
+  explorer: "https://robinhoodchain.blockscout.com",
+  proofAnchor: "0x54fE3b5A866190BF733104AB1c45d15405F27B16",
+  lineageVerifier: "0xDF3dD7eee2E2FD5e36900b882aa9473E72d56320",
+  publicProofs: "0x537819C42002691fD62e00bc251055587F51F502",
+  rangeVerifier: "0x003f80FF939dA662759ed7047D1a988e5a0E79A2",
+  boundVerifier: "0x9207ecf9ef5749ab39e17b610b1af974a03bd422",
+  trustlessAnchor: "0x6DF5BcE4799EdF35C98b5727aa25a7F2b67479a4",
+  /** PrivateGate permissioning contract (deployed 2026-09-13); pass your own gate via new Chain({ addresses: { privateGate } }) */
+  privateGate: "0xEc773A186532aC6080C258Edf883B726b13e2638",
+});
+
+/* ------------------------------------------------------------ bytes */
+const hex = (u8) => "0x" + S.hex(u8);
+const strip = (h) => (h.startsWith("0x") ? h.slice(2) : h);
+const isHex = (s) => typeof s === "string" && /^0x[0-9a-fA-F]*$/.test(s) && s.length % 2 === 0;
+const fromHex = (h) => Uint8Array.from((strip(h).match(/../g) || []).map((x) => parseInt(x, 16)));
+const pad32 = (v) => BigInt(v).toString(16).padStart(64, "0");
+const big = (v) => (typeof v === "bigint" ? v : BigInt(v));
+const wordsToBytes = (words) => { const b = new Uint8Array(words.length * 32); words.forEach((w, i) => b.set(S.bigTo32(big(w)), i * 32)); return b; };
+const bytesToWords = (u8) => { const out = []; for (let i = 0; i + 32 <= u8.length; i += 32) out.push(S.bytesToBig(u8.slice(i, i + 32))); return out; };
+const point = (P) => ({ x: "0x" + P.x.toString(16).padStart(64, "0"), y: "0x" + P.y.toString(16).padStart(64, "0") });
+const proofBytes = (proof) => (typeof proof === "string" ? fromHex(proof) : proof instanceof Uint8Array ? proof : wordsToBytes(proof));
+const proofWords = (proof) => (Array.isArray(proof) ? proof.map(big) : bytesToWords(proofBytes(proof)));
+
+/** Any value to 32 bytes: a 0x hex of 64 chars or a 32 byte array is used as-is; anything else is keccak256 of its UTF-8. */
+function toBytes32(v) {
+  if (v instanceof Uint8Array && v.length === 32) return v;
+  if (typeof v === "string" && /^0x[0-9a-fA-F]{64}$/.test(v)) return fromHex(v);
+  return S.keccak256(S.utf8(String(v)));
+}
+
+/** A context word from any parts (strings, hex, bytes): keccak256 of their concatenation. Bind every proof to the place it is used. */
+function context(...parts) {
+  const bufs = parts.map((p) => (p instanceof Uint8Array ? p : isHex(String(p)) ? fromHex(String(p)) : S.utf8(String(p))));
+  const all = new Uint8Array(bufs.reduce((n, b) => n + b.length, 0));
+  let o = 0; for (const b of bufs) { all.set(b, o); o += b.length; }
+  return S.keccak256(all);
+}
+
+/** keccak256("purpose name"): the bytes32 label PrivateGate and its consumers use. */
+const purposeId = (name) => S.keccak256(S.utf8(name));
+
+/** keccak256(abi.encode(gate, user, purpose)): exactly what PrivateGate.contextFor returns. `purpose` may be a name or a bytes32 hex. */
+function gateContext(gate, user, purpose) {
+  const p = /^0x[0-9a-fA-F]{64}$/.test(String(purpose)) ? strip(purpose) : S.hex(purposeId(String(purpose)));
+  return S.keccak256(fromHex(pad32(gate) + pad32(user) + p));
+}
+
+/* ------------------------------------------------------------ proofs */
+
+/** Pedersen commitment C = value*G + r*H to a 32 byte value (or a text, hashed). Perfectly hiding. */
+function commit(value, blinding) {
+  const c = S.commit(toBytes32(value), blinding === undefined ? undefined : big(blinding));
+  return { commitment: point(c.C), blinding: "0x" + c.r.toString(16).padStart(64, "0") };
+}
+
+/** Lineage bundle (23 words, 736 bytes): commitments to two hidden values, openings for both, and an equality link. */
+function proveLineage(prevRoot, outRoot, ctx) {
+  const c = toBytes32(ctx);
+  const b = proveBundle(toBytes32(prevRoot), toBytes32(outRoot), c);
+  return { proof: b.hex, words: b.words, ctx: hex(c), commitments: { in: point(b.commitments.C_in), out: point(b.commitments.C_out) }, verified: verifyBundleJS(b.words, c) };
+}
+/** Exact mirror of LineageVerifier.verify. */
+const verifyLineage = (proof, ctx) => verifyBundleJS(proofWords(proof), toBytes32(ctx));
+
+/** Range proof: a hidden `value` is at least the public `threshold`. The value never appears in the output. */
+function proveRange({ value, threshold, ctx, blinding }) {
+  const v = big(value), x = big(threshold);
+  if (v < 0n || x < 0n) throw new Error("value and threshold must be non-negative");
+  if (x === 0n) throw new Error("threshold must be at least 1: every number is at least 0, so there is nothing to prove");
+  if (v < x) throw new Error("value is below the threshold: no valid proof exists");
+  if (v - x >= 1n << BigInt(R.NBITS)) throw new Error(`value minus threshold must fit in ${R.NBITS} bits`);
+  const r = blinding === undefined ? S.randScalar() : big(blinding);
+  const C = S.ecAdd(S.ecMul(v, S.G), S.ecMul(r, S.H));
+  const c = toBytes32(ctx);
+  const p = R.proveRange(C, v, r, x, c);
+  return { proof: hex(wordsToBytes(p.words)), words: p.words, ctx: hex(c), commitment: point(C), blinding: "0x" + r.toString(16).padStart(64, "0"), threshold: x.toString(), bits: R.NBITS, verified: R.verifyRangeJS(p.words, c) };
+}
+/** Exact mirror of RangeVerifier.verify. */
+const verifyRange = (proof, ctx) => R.verifyRangeJS(proofWords(proof), toBytes32(ctx));
+
+/** Bound bundle (37 words) for TrustlessAnchor: a lineage bundle whose commitments provably open to two public roots. */
+function proveTrustless(prevRoot, outRoot, ctx) {
+  const c = toBytes32(ctx), a = toBytes32(prevRoot), b = toBytes32(outRoot);
+  const t = T.proveTrustlessFull(a, b, c);
+  return { proof: t.hex, words: t.words, ctx: hex(c), commitments: { in: point(t.commitments.C_in), out: point(t.commitments.C_out) }, verified: T.verifyTrustlessJS(t.words, c, a, b) };
+}
+/** Exact mirror of BoundLineageVerifier.verifyBound. */
+const verifyTrustless = (proof, ctx, prevRoot, outRoot) => T.verifyTrustlessJS(proofWords(proof), toBytes32(ctx), toBytes32(prevRoot), toBytes32(outRoot));
+
+/* ------------------------------------------------------------ calldata */
+const sel = (sig) => S.hex(S.keccak256(S.utf8(sig))).slice(0, 8);
+const dyn = (u8) => { const padded = Math.ceil(u8.length / 32) * 32; const b = new Uint8Array(padded); b.set(u8); return pad32(u8.length) + S.hex(b); };
+
+/** verify(bytes proof, bytes32 ctx): LineageVerifier, RangeVerifier and BoundLineageVerifier all expose it (the bound verifier's has two extra roots). */
+const encodeVerify = (proof, ctx) => "0x" + sel("verify(bytes,bytes32)") + pad32(0x40) + S.hex(toBytes32(ctx)) + dyn(proofBytes(proof));
+/** verifyBound(bytes proof, bytes32 ctx, bytes32 rootPrev, bytes32 rootOut) on BoundLineageVerifier. */
+const encodeVerifyBound = (proof, ctx, prevRoot, outRoot) => "0x" + sel("verifyBound(bytes,bytes32,bytes32,bytes32)") + pad32(0x80) + S.hex(toBytes32(ctx)) + S.hex(toBytes32(prevRoot)) + S.hex(toBytes32(outRoot)) + dyn(proofBytes(proof));
+/** submit(bytes proof, bytes32 ctx, bytes32 tag) on PublicProofs: record a lineage bundle the verifier accepted. */
+const encodeSubmit = (proof, ctx, tag = "0x" + "0".repeat(64)) => "0x" + sel("submit(bytes,bytes32,bytes32)") + pad32(0x60) + S.hex(toBytes32(ctx)) + S.hex(toBytes32(tag)) + dyn(proofBytes(proof));
+/** attest(bytes proof, bytes32 ctx) on RangeVerifier: verify and emit a public RangeVerified receipt for the sender. */
+const encodeAttest = (proof, ctx) => "0x" + sel("attest(bytes,bytes32)") + pad32(0x40) + S.hex(toBytes32(ctx)) + dyn(proofBytes(proof));
+/** prove(bytes32 purpose, bytes proof) on PrivateGate. `purpose` may be a name or a bytes32 hex. */
+const encodeGateProve = (purpose, proof) => { const p = /^0x[0-9a-fA-F]{64}$/.test(String(purpose)) ? strip(purpose) : S.hex(purposeId(String(purpose))); return "0x" + sel("prove(bytes32,bytes)") + p + pad32(0x40) + dyn(proofBytes(proof)); };
+/** isEligible(address user, bytes32 purpose, uint256 minThreshold, uint256 maxAge) on PrivateGate. */
+const encodeIsEligible = (user, purpose, minThreshold, maxAge = 0) => { const p = /^0x[0-9a-fA-F]{64}$/.test(String(purpose)) ? strip(purpose) : S.hex(purposeId(String(purpose))); return "0x" + sel("isEligible(address,bytes32,uint256,uint256)") + pad32(user) + p + pad32(minThreshold) + pad32(maxAge); };
+
+/* ------------------------------------------------------------ chain */
+const word = (data, i) => data.slice(2 + i * 64, 2 + (i + 1) * 64);
+const num = (h) => Number(BigInt(h));
+
+/** Read-only client for the deployed contracts. Pass { rpcUrl, addresses } to point elsewhere. */
+class Chain {
+  constructor(opts = {}) {
+    this.rpcUrl = opts.rpcUrl || MAINNET.rpcUrl;
+    this.addresses = { ...MAINNET, ...(opts.addresses || {}) };
+  }
+  async rpc(method, params) {
+    const r = await fetch(this.rpcUrl, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }) });
+    const j = await r.json();
+    if (j.error) throw new Error(j.error.message || "rpc error");
+    return j.result;
+  }
+  call(to, data) { return this.rpc("eth_call", [{ to, data }, "latest"]); }
+  async isTrue(to, data) { return /1$/.test(await this.call(to, data)); }
+
+  /** Does the deployed LineageVerifier accept this bundle for this context? */
+  verifyLineage(proof, ctx) { return this.isTrue(this.addresses.lineageVerifier, encodeVerify(proof, ctx)); }
+  /** Does the deployed RangeVerifier accept this range proof for this context? */
+  verifyRange(proof, ctx) { return this.isTrue(this.addresses.rangeVerifier, encodeVerify(proof, ctx)); }
+  /** Does the deployed BoundLineageVerifier accept this bound bundle for these public roots? */
+  verifyTrustless(proof, ctx, prevRoot, outRoot) { return this.isTrue(this.addresses.boundVerifier, encodeVerifyBound(proof, ctx, prevRoot, outRoot)); }
+  /** Is `user` eligible on a PrivateGate? */
+  isEligible(gate, user, purpose, minThreshold, maxAge = 0) { return this.isTrue(gate, encodeIsEligible(user, purpose, minThreshold, maxAge)); }
+
+  /** Head of the trustless lineage. */
+  async lineage() {
+    const ta = this.addresses.trustlessAnchor;
+    const [seq, end, root, latest] = await Promise.all([
+      this.call(ta, "0x" + sel("lastSeq()")), this.call(ta, "0x" + sel("lastEndBlock()")), this.call(ta, "0x" + sel("lastRoot()")), this.rpc("eth_blockNumber", []),
+    ]);
+    return { contract: ta, lastSeq: num(seq), lastEndBlock: num(end), lastRoot: root, latestBlock: num(latest) };
+  }
+  /** One TrustlessAnchor record. */
+  async record(seq) {
+    const r = await this.call(this.addresses.trustlessAnchor, "0x" + sel("records(uint64)") + pad32(seq));
+    return { seq: Number(seq), stateRootPrev: "0x" + word(r, 0), stateRootOut: "0x" + word(r, 1), cInDigest: "0x" + word(r, 2), cOutDigest: "0x" + word(r, 3), startBlock: num("0x" + word(r, 4)), endBlock: num("0x" + word(r, 5)), timestamp: num("0x" + word(r, 6)), prover: "0x" + word(r, 7).slice(24) };
+  }
+  /** Independent audit of one record: the end block is re-read from the node and compared, and the link to the previous record is checked. */
+  async auditAnchor(seq) {
+    const head = await this.lineage();
+    const s = seq === undefined ? head.lastSeq : Number(seq);
+    if (s < 1 || s > head.lastSeq) throw new Error(`seq must be between 1 and ${head.lastSeq}`);
+    const rec = await this.record(s);
+    const blk = await this.rpc("eth_getBlockByNumber", ["0x" + rec.endBlock.toString(16), false]);
+    const rootMatchesBlock = String(blk.stateRoot).toLowerCase() === rec.stateRootOut.toLowerCase();
+    let linksToPrevious = "genesis";
+    if (s > 1) { const prev = await this.record(s - 1); linksToPrevious = prev.stateRootOut.toLowerCase() === rec.stateRootPrev.toLowerCase() && rec.startBlock === prev.endBlock + 1; }
+    return { ...rec, blockStateRoot: blk.stateRoot, rootMatchesBlock, linksToPrevious, ok: rootMatchesBlock && linksToPrevious !== false };
+  }
+}
+
+module.exports = {
+  MAINNET, Chain,
+  commit, proveLineage, verifyLineage, proveRange, verifyRange, proveTrustless, verifyTrustless,
+  context, purposeId, gateContext, toBytes32,
+  encodeVerify, encodeVerifyBound, encodeSubmit, encodeAttest, encodeGateProve, encodeIsEligible,
+  NBITS: R.NBITS, keccak256: S.keccak256, hex, fromHex,
+};

package/lib/prove.js

@@ -0,0 +1,113 @@
+// GENERATED COPY of zk/prove.js from the zkThunder protocol. Do not edit here; run "npm run sync" in sdk/.
+// zkThunder sigma prover CLI + contract-logic mirror. Bare node, no deps.
+//
+//   node zk/prove.js <stateRootPrevHex32> <stateRootOutHex32> <ctxHex32>
+//
+// Emits a 23-word proof bundle (hex) ready for LineageVerifier.verify,
+// where publicInputsHash = ctx. Commits to:
+//   prevCout = Commit(rootPrev)   (previous window's outgoing root)
+//   C_in     = Commit(rootPrev)   (this window's incoming root, fresh blinding)
+//   C_out    = Commit(rootOut)
+// and proves: opening of C_in, opening of C_out, equality(prevCout, C_in).
+//
+// Also exports verifyBundleJS(): an exact JS mirror of the Solidity
+// verification path (same challenges, same helper points, same address
+// checks) so the contract logic is testable without a chain.
+"use strict";
+const S = require("./sigma.js");
+const { mod, N, P, G, H, ecAdd, ecMul, ecNeg, onCurve, pointAddr,
+        commit, keccak256, bigTo32, hex } = S;
+
+const w32 = v => bigTo32(typeof v === "bigint" ? v : BigInt(v));
+
+const TAG_OPEN_B = S.utf8(S.TAG_OPEN), TAG_EQ_B = S.utf8(S.TAG_EQ);
+function packChallenge(tagBytes, points, ctx32){
+  const buf = new Uint8Array(tagBytes.length + 64*points.length + 32); let o = 0;
+  buf.set(tagBytes, o); o += tagBytes.length;
+  for (const Q of points){ buf.set(bigTo32(Q.x), o); buf.set(bigTo32(Q.y), o+32); o += 64; }
+  buf.set(ctx32, o);
+  return mod(S.bytesToBig(keccak256(buf)), N);
+}
+function challengeOpen(C, A, ctx32){ return packChallenge(TAG_OPEN_B, [C, A], ctx32); }
+function challengeEq(C1, C2, A, ctx32){ return packChallenge(TAG_EQ_B, [C1, C2, A], ctx32); }
+
+/** Build the 23-word bundle for LineageVerifier. */
+function proveBundle(rootPrev32, rootOut32, ctx32){
+  const prev = commit(rootPrev32);
+  const cin  = commit(rootPrev32);       // same value, fresh blinding
+  const cout = commit(rootOut32);
+
+  // openings (contract-compatible challenges: on C, A, ctx)
+  function open(cm){
+    const a=S.randScalar(), b=S.randScalar();
+    const A=ecAdd(ecMul(a,G), ecMul(b,H));
+    const c=challengeOpen(cm.C, A, ctx32);
+    return { A, z1: mod(a+c*cm.x,N), z2: mod(b+c*cm.r,N),
+             CC: ecMul(c, cm.C) };
+  }
+  const oi = open(cin), oo = open(cout);
+
+  // equality(prevCout, C_in)
+  const rho = mod(prev.r - cin.r, N);
+  const k = S.randScalar();
+  const Aeq = ecMul(k, H);
+  const ceq = challengeEq(prev.C, cin.C, Aeq, ctx32);
+  const zeq = mod(k + ceq*rho, N);
+  const D = ecAdd(prev.C, ecNeg(cin.C));
+  const CD = ecMul(ceq, D);
+
+  const words = [
+    cin.C.x, cin.C.y, cout.C.x, cout.C.y, prev.C.x, prev.C.y,
+    oi.A.x, oi.A.y, oi.z1, oi.z2, oi.CC.x, oi.CC.y,
+    oo.A.x, oo.A.y, oo.z1, oo.z2, oo.CC.x, oo.CC.y,
+    Aeq.x, Aeq.y, zeq, CD.x, CD.y,
+  ];
+  const buf = new Uint8Array(23*32);
+  words.forEach((v,i)=>buf.set(w32(v), i*32));
+  return { hex: "0x"+hex(buf), words,
+           commitments: { prevCout: prev.C, C_in: cin.C, C_out: cout.C },
+           secrets: { note: "blindings held by prover; roots never revealed" } };
+}
+
+/** Exact JS mirror of LineageVerifier.verify (same checks, same order). */
+function verifyBundleJS(words, ctx32){
+  const pt=(i)=>({x:words[i], y:words[i+1]});
+  const [Cin, Cout, Prev] = [pt(0), pt(2), pt(4)];
+  const onc=[0,2,4,6,10,12,16,18,21].every(i=>onCurve(pt(i)));
+  if(!onc) return false;
+
+  function vOpen(C, Ai, z1i, CCi){
+    const A=pt(Ai), z1=words[z1i], z2=words[z1i+1], CC=pt(CCi);
+    const c=challengeOpen(C, A, ctx32);
+    if(pointAddr(ecMul(c, C)) !== pointAddr(CC)) return false;
+    const R=ecAdd(A, CC);
+    return pointAddr(ecAdd(ecMul(z1,G), ecMul(z2,H))) === pointAddr(R);
+  }
+  if(!vOpen(Cin, 6, 8, 10)) return false;
+  if(!vOpen(Cout, 12, 14, 16)) return false;
+
+  const Aeq=pt(18), zeq=words[20], CD=pt(21);
+  const c=challengeEq(Prev, Cin, Aeq, ctx32);
+  const D=ecAdd(Prev, ecNeg(Cin));
+  if(D===null) return false;
+  if(pointAddr(ecMul(c,D)) !== pointAddr(CD)) return false;
+  const R=ecAdd(Aeq, CD);
+  return pointAddr(ecMul(zeq,H)) === pointAddr(R);
+}
+
+module.exports = { proveBundle, verifyBundleJS, challengeOpen, challengeEq };
+
+if (require.main === module) {
+  const [,, prevHex, outHex, ctxHex] = process.argv;
+  const h2b = h => Uint8Array.from((h||"").replace(/^0x/,"").padStart(64,"0")
+                   .match(/../g).map(x=>parseInt(x,16)));
+  const rootPrev = prevHex ? h2b(prevHex) : keccak256(S.utf8("demo-root-prev"));
+  const rootOut  = outHex  ? h2b(outHex)  : keccak256(S.utf8("demo-root-out"));
+  const ctx      = ctxHex  ? h2b(ctxHex)  : keccak256(S.utf8("demo-ctx"));
+  const b = proveBundle(rootPrev, rootOut, ctx);
+  console.log(JSON.stringify({
+    publicInputsHash: "0x"+hex(ctx),
+    proof: b.hex,
+    verifies_locally: verifyBundleJS(b.words, ctx),
+  }, null, 2));
+}

package/lib/range.js

@@ -0,0 +1,121 @@
+// GENERATED COPY of zk/range.js from the zkThunder protocol. Do not edit here; run "npm run sync" in sdk/.
+// zkThunder range proofs: prove a committed value satisfies  v >= X
+// without revealing v. Zero dependencies; same primitives as sigma.js.
+//
+// Construction (bit decomposition, CDS OR-proofs):
+//   d = v - X must fit in NBITS bits.  C' = C - X*G  commits to d (same r).
+//   For each bit i: B_i = b_i*G + r_i*H with sum(2^i * r_i) = r, so that
+//   sum(2^i * B_i) == C'  (holds iff the bits encode d and blindings add up).
+//   Each bit carries an OR-proof: "B_i = r_i*H"  OR  "B_i - G = r_i*H".
+//
+// On-chain friendliness: every scalar multiplication the verifier needs is
+// supplied by the prover as a point and address-checked with the ecrecover
+// trick (exactly like LineageVerifier), so verification needs no on-chain
+// scalar multiplication, only affine additions.
+"use strict";
+const S = require("./sigma.js");
+const { mod, N, G, H, ecAdd, ecMul, ecNeg, onCurve, pointAddr, keccak256, bigTo32, bytesToBig, utf8, randScalar } = S;
+
+const NBITS = 32;
+const TAG_BIT = utf8("zkThunder/range/bit/v1");
+
+/* Fiat-Shamir challenge for one bit: keccak(tag | B | A0 | A1 | ctx) */
+function bitChallenge(B, A0, A1, ctx32) {
+  const buf = new Uint8Array(TAG_BIT.length + 64 * 3 + 32); let o = 0;
+  buf.set(TAG_BIT, o); o += TAG_BIT.length;
+  for (const Q of [B, A0, A1]) { buf.set(bigTo32(Q.x), o); buf.set(bigTo32(Q.y), o + 32); o += 64; }
+  buf.set(ctx32, o);
+  return mod(bytesToBig(keccak256(buf)), N);
+}
+
+/**
+ * Prove v >= threshold for commitment C = v*G + r*H.
+ * Returns { words } laid out as (all uint256):
+ *   [0..1]  C            [2] threshold
+ *   then per bit i (0..NBITS-1), 13 words:
+ *     B.x B.y  A0.x A0.y  A1.x A1.y  c0  z0  z1  cB0.x cB0.y  cB1.x cB1.y
+ *   where cB0 = c0*B  and  cB1 = c1*(B - G)  (helper points, address-checked)
+ *   then per bit i, 2 words: P_i = 2^i * B_i  (helper points for the sum)
+ *   then 2 words: XG = threshold * G           (helper point)
+ */
+function proveRange(C, v, r, threshold, ctx32, nbits = NBITS) {
+  const d = v - threshold;
+  if (d < 0n) throw new Error("value is below the threshold; cannot prove");
+  if (d >= (1n << BigInt(nbits))) throw new Error("difference exceeds range");
+  const blind = [];
+  let acc = 0n;
+  for (let i = 0; i < nbits - 1; i++) { blind.push(randScalar()); acc = mod(acc + (blind[i] << BigInt(i)), N); }
+  // last blinding makes sum(2^i r_i) == r
+  const inv2 = powmodN(1n << BigInt(nbits - 1), N - 2n);
+  blind.push(mod((r - acc) * inv2, N));
+
+  const words = [C.x, C.y, threshold];
+  const bits = [], helpers = [];
+  for (let i = 0; i < nbits; i++) {
+    const b = (d >> BigInt(i)) & 1n;
+    const B = ecAdd(b ? G : null, ecMul(blind[i], H));
+    const BmG = ecAdd(B, ecNeg(G));
+    // CDS OR-proof: real branch for the true bit, simulated branch for the other
+    let A0, A1, c0, c1, z0, z1;
+    const k = randScalar();
+    if (b === 0n) {
+      // real: B = r H. simulate branch 1 (B - G = r H)
+      c1 = randScalar(); z1 = randScalar();
+      A1 = ecAdd(ecMul(z1, H), ecNeg(ecMul(c1, BmG)));
+      A0 = ecMul(k, H);
+      const c = bitChallenge(B, A0, A1, ctx32);
+      c0 = mod(c - c1, N); z0 = mod(k + c0 * blind[i], N);
+    } else {
+      c0 = randScalar(); z0 = randScalar();
+      A0 = ecAdd(ecMul(z0, H), ecNeg(ecMul(c0, B)));
+      A1 = ecMul(k, H);
+      const c = bitChallenge(B, A0, A1, ctx32);
+      c1 = mod(c - c0, N); z1 = mod(k + c1 * blind[i], N);
+    }
+    const cB0 = ecMul(c0, B), cB1 = ecMul(c1, BmG);
+    bits.push(B.x, B.y, A0.x, A0.y, A1.x, A1.y, c0, z0, z1, cB0.x, cB0.y, cB1.x, cB1.y);
+    const P = ecMul(1n << BigInt(i), B); helpers.push(P.x, P.y);
+  }
+  const XG = ecMul(threshold, G);
+  words.push(...bits, ...helpers, XG.x, XG.y);
+  return { words, nbits };
+}
+
+/** Exact mirror of the on-chain verification path. */
+function verifyRangeJS(words, ctx32, nbits = NBITS) {
+  const pt = (i) => ({ x: words[i], y: words[i + 1] });
+  const C = pt(0), threshold = words[2];
+  if (!onCurve(C)) return false;
+  let o = 3;
+  let sum = null;
+  const helperBase = 3 + 13 * nbits;
+  for (let i = 0; i < nbits; i++, o += 13) {
+    const B = pt(o), A0 = pt(o + 2), A1 = pt(o + 4), c0 = words[o + 6], z0 = words[o + 7], z1 = words[o + 8], cB0 = pt(o + 9), cB1 = pt(o + 11);
+    if (![B, A0, A1, cB0, cB1].every(onCurve)) return false;
+    const c = bitChallenge(B, A0, A1, ctx32);
+    const c1 = mod(c - c0, N);
+    const BmG = ecAdd(B, ecNeg(G));
+    if (BmG === null) return false;
+    // helper points must be the claimed multiples (address check, as on chain)
+    if (pointAddr(ecMul(c0, B)) !== pointAddr(cB0)) return false;
+    if (pointAddr(ecMul(c1, BmG)) !== pointAddr(cB1)) return false;
+    // z0 H == A0 + c0 B     and     z1 H == A1 + c1 (B - G)
+    const R0 = ecAdd(A0, cB0), R1 = ecAdd(A1, cB1);
+    if (!R0 || !R1) return false;
+    if (pointAddr(ecMul(z0, H)) !== pointAddr(R0)) return false;
+    if (pointAddr(ecMul(z1, H)) !== pointAddr(R1)) return false;
+    // sum helper: P_i == 2^i * B_i
+    const P = pt(helperBase + 2 * i);
+    if (!onCurve(P) || pointAddr(ecMul(1n << BigInt(i), B)) !== pointAddr(P)) return false;
+    sum = ecAdd(sum, P);
+  }
+  const XG = pt(helperBase + 2 * nbits);
+  if (!onCurve(XG) || pointAddr(ecMul(threshold, G)) !== pointAddr(XG)) return false;
+  const Cprime = ecAdd(C, ecNeg(XG));
+  if (!sum || !Cprime) return false;
+  return sum.x === Cprime.x && sum.y === Cprime.y;
+}
+
+function powmodN(b, e) { let r = 1n; b = mod(b, N); while (e > 0n) { if (e & 1n) r = (r * b) % N; b = (b * b) % N; e >>= 1n; } return r; }
+
+module.exports = { proveRange, verifyRangeJS, NBITS, bitChallenge };

package/lib/sigma.js

@@ -0,0 +1,244 @@
+// GENERATED COPY of zk/sigma.js from the zkThunder protocol. Do not edit here; run "npm run sync" in sdk/.
+// zkThunder sigma layer — zero-dependency zero-knowledge proofs.
+//
+// Primitives (all from scratch, bare Node, no packages):
+//   - secp256k1 group arithmetic (BigInt)
+//   - Pedersen commitments  C = x*G + r*H   (perfectly hiding,
+//     computationally binding; H derived nothing-up-my-sleeve)
+//   - NIZK proof of opening (Okamoto / Schnorr on two generators,
+//     Fiat-Shamir with keccak256, domain-separated)
+//   - NIZK equality proof (Chaum-Pedersen variant): two commitments
+//     hide the SAME value, without revealing it
+//
+// zkThunder use: state roots become hiding commitments; each anchor
+// proves its commitments are well-formed, and consecutive windows'
+// boundary commitments are linked in zero knowledge.
+//
+// Scope, stated plainly: these proofs give privacy of the committed
+// roots and integrity of the commitment structure. They do NOT prove
+// the state transition itself is correct — that is the zkVM tier.
+
+"use strict";
+
+/* ---------------- keccak-256 (same impl as kats.js) ---------------- */
+function keccak256(bytes){
+  const RC=[0x0000000000000001n,0x0000000000008082n,0x800000000000808an,0x8000000080008000n,
+  0x000000000000808bn,0x0000000080000001n,0x8000000080008081n,0x8000000000008009n,
+  0x000000000000008an,0x0000000000000088n,0x0000000080008009n,0x000000008000000an,
+  0x000000008000808bn,0x800000000000008bn,0x8000000000008089n,0x8000000000008003n,
+  0x8000000000008002n,0x8000000000000080n,0x000000000000800an,0x800000008000000an,
+  0x8000000080008081n,0x8000000000008080n,0x0000000080000001n,0x8000000080008008n];
+  const ROT=[[0,36,3,41,18],[1,44,10,45,2],[62,6,43,15,61],[28,55,25,21,56],[27,20,39,8,14]];
+  const M=(1n<<64n)-1n; const rotl=(x,nn)=>((x<<BigInt(nn))|(x>>BigInt(64-nn)))&M;
+  const rate=136;
+  const padded=new Uint8Array(Math.ceil((bytes.length+1)/rate)*rate);
+  padded.set(bytes); padded[bytes.length]=0x01; padded[padded.length-1]|=0x80;
+  const S=Array.from({length:5},()=>new Array(5).fill(0n));
+  for(let off=0;off<padded.length;off+=rate){
+    for(let i=0;i<rate/8;i++){let lane=0n;
+      for(let b=7;b>=0;b--)lane=(lane<<8n)|BigInt(padded[off+i*8+b]);
+      S[i%5][(i/5)|0]^=lane;}
+    for(let r=0;r<24;r++){
+      const C=[],D=[];
+      for(let x=0;x<5;x++)C[x]=S[x][0]^S[x][1]^S[x][2]^S[x][3]^S[x][4];
+      for(let x=0;x<5;x++){D[x]=C[(x+4)%5]^rotl(C[(x+1)%5],1);
+        for(let y=0;y<5;y++)S[x][y]^=D[x];}
+      const B=Array.from({length:5},()=>new Array(5).fill(0n));
+      for(let x=0;x<5;x++)for(let y=0;y<5;y++)B[y][(2*x+3*y)%5]=rotl(S[x][y],ROT[x][y]);
+      for(let x=0;x<5;x++)for(let y=0;y<5;y++)S[x][y]=B[x][y]^(~B[(x+1)%5][y]&B[(x+2)%5][y]);
+      S[0][0]^=RC[r];
+    }
+  }
+  const out=new Uint8Array(32);
+  for(let i=0;i<4;i++){let lane=S[i%5][(i/5)|0];
+    for(let b=0;b<8;b++){out[i*8+b]=Number(lane&0xffn);lane>>=8n;}}
+  return out;
+}
+const utf8=s=>new TextEncoder().encode(s);
+const bytesToBig=u8=>u8.reduce((a,b)=>(a<<8n)|BigInt(b),0n);
+function bigTo32(x){const u=new Uint8Array(32);for(let i=31;i>=0;i--){u[i]=Number(x&0xffn);x>>=8n;}return u;}
+const hex=u8=>[...u8].map(b=>b.toString(16).padStart(2,"0")).join("");
+
+/* ---------------- secp256k1 ---------------- */
+const P = 0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2fn;
+const N = 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n;
+const Gx= 0x79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798n;
+const Gy= 0x483ada7726a3c4655da4fbfc0e1108a8fd17b448a68554199c47d08ffb10d4b8n;
+const G = {x:Gx, y:Gy};
+const O = null; // point at infinity
+
+const mod=(a,m)=>((a%m)+m)%m;
+function powmod(b,e,m){let r=1n;b=mod(b,m);while(e>0n){if(e&1n)r=(r*b)%m;b=(b*b)%m;e>>=1n;}return r;}
+const inv=(a,m)=>powmod(mod(a,m),m-2n,m);
+
+function onCurve(Q){ if(Q===O)return true;
+  return mod(Q.y*Q.y - (Q.x*Q.x*Q.x + 7n), P)===0n; }
+function ecAdd(A,B){
+  if(A===O)return B; if(B===O)return A;
+  if(A.x===B.x){
+    if(mod(A.y+B.y,P)===0n) return O;
+    // doubling
+    const l=mod(3n*A.x*A.x * inv(2n*A.y,P), P);
+    const x=mod(l*l - 2n*A.x, P);
+    return {x, y: mod(l*(A.x-x)-A.y, P)};
+  }
+  const l=mod((B.y-A.y)*inv(B.x-A.x,P), P);
+  const x=mod(l*l - A.x - B.x, P);
+  return {x, y: mod(l*(A.x-x)-A.y, P)};
+}
+/* Scalar multiplication in Jacobian coordinates: one modular inversion per
+   multiplication instead of one per step (~10x faster than affine). Same
+   results as the affine version; ecAdd/onCurve/serialization unchanged. */
+function jDouble(X,Y,Z){
+  if(Y===0n) return [0n,1n,0n];
+  const A=mod(X*X,P), B=mod(Y*Y,P), C=mod(B*B,P);
+  const D=mod(2n*(mod((X+B)*(X+B),P)-A-C),P);
+  const E=mod(3n*A,P), F=mod(E*E,P);
+  const X3=mod(F-2n*D,P);
+  return [X3, mod(E*(D-X3)-8n*C,P), mod(2n*Y*Z,P)];
+}
+function jAdd(X1,Y1,Z1,X2,Y2,Z2){
+  if(Z1===0n) return [X2,Y2,Z2]; if(Z2===0n) return [X1,Y1,Z1];
+  const Z1Z1=mod(Z1*Z1,P), Z2Z2=mod(Z2*Z2,P);
+  const U1=mod(X1*Z2Z2,P), U2=mod(X2*Z1Z1,P);
+  const S1=mod(Y1*Z2*Z2Z2,P), S2=mod(Y2*Z1*Z1Z1,P);
+  const Hh=mod(U2-U1,P), r=mod(S2-S1,P);
+  if(Hh===0n){ return r===0n ? jDouble(X1,Y1,Z1) : [0n,1n,0n]; }
+  const HH=mod(Hh*Hh,P), HHH=mod(HH*Hh,P), V=mod(U1*HH,P);
+  const X3=mod(r*r-HHH-2n*V,P);
+  return [X3, mod(r*(V-X3)-S1*HHH,P), mod(Z1*Z2*Hh,P)];
+}
+function ecMul(k,Q){
+  k=mod(k,N); if(Q===O||k===0n) return O;
+  let R=[0n,1n,0n], T=[Q.x,Q.y,1n];
+  while(k>0n){ if(k&1n) R=jAdd(R[0],R[1],R[2],T[0],T[1],T[2]); T=jDouble(T[0],T[1],T[2]); k>>=1n; }
+  if(R[2]===0n) return O;
+  const zi=inv(R[2],P), zi2=mod(zi*zi,P);
+  return {x:mod(R[0]*zi2,P), y:mod(R[1]*zi2*zi,P)};
+}
+function ecNeg(Q){ return Q===O?O:{x:Q.x, y:mod(-Q.y,P)}; }
+
+/* Ethereum-style address of a point: last 20 bytes of keccak(x||y).
+   Used by the on-chain verifier (ecrecover trick compares addresses). */
+function pointAddr(Q){
+  const u=new Uint8Array(64); u.set(bigTo32(Q.x),0); u.set(bigTo32(Q.y),32);
+  return "0x"+hex(keccak256(u).slice(12));
+}
+
+/* ---------------- H: second generator, nothing-up-my-sleeve ----------------
+   Try-and-increment from a fixed tag; discrete log of H wrt G unknown. */
+function deriveH(){
+  for(let i=0;;i++){
+    const x=mod(bytesToBig(keccak256(utf8("zkThunder/H/v1/"+i))),P);
+    const y2=mod(x*x*x+7n,P);
+    const y=powmod(y2,(P+1n)/4n,P);           // p ≡ 3 mod 4
+    if(mod(y*y,P)===y2){ return {x, y: (y&1n)?mod(-y,P):y}; } // even y
+  }
+}
+const H=deriveH();
+
+/* ---------------- randomness ---------------- */
+const nodeCrypto=require("crypto");
+function randScalar(){
+  while(true){
+    const k=bytesToBig(new Uint8Array(nodeCrypto.randomBytes(32)));
+    const r=mod(k,N); if(r>0n) return r;
+  }
+}
+
+/* ---------------- Fiat-Shamir challenge ---------------- */
+function challenge(tag, points, extra32s){
+  const parts=[utf8(tag)];
+  for(const Q of points){ parts.push(bigTo32(Q.x), bigTo32(Q.y)); }
+  for(const e of (extra32s||[])) parts.push(e);
+  const total=parts.reduce((s,p2)=>s+p2.length,0);
+  const buf=new Uint8Array(total); let o=0;
+  for(const p2 of parts){ buf.set(p2,o); o+=p2.length; }
+  return mod(bytesToBig(keccak256(buf)), N);
+}
+
+/* ---------------- Pedersen commitment ----------------
+   Commit to a 32-byte value (e.g. a state root). The value is reduced
+   mod n; binding is to (value mod n). C = x*G + r*H. */
+function commit(value32, r){
+  const x=mod(bytesToBig(value32), N);
+  r = r===undefined ? randScalar() : r;
+  return { C: ecAdd(ecMul(x,G), ecMul(r,H)), x, r };
+}
+
+/* ---------------- NIZK: proof of opening (Okamoto) ----------------
+   Proves knowledge of (x, r) with C = xG + rH, revealing neither. */
+const TAG_OPEN="zkThunder/sigma/open/v1";
+function proveOpening(C, x, r, ctx32){
+  const a=randScalar(), b=randScalar();
+  const A=ecAdd(ecMul(a,G), ecMul(b,H));
+  const c=challenge(TAG_OPEN,[C,A],[ctx32]);
+  return { A, z1: mod(a+c*x,N), z2: mod(b+c*r,N) };
+}
+function verifyOpening(C, prf, ctx32){
+  if(!onCurve(C)||!onCurve(prf.A)) return false;
+  const c=challenge(TAG_OPEN,[C,prf.A],[ctx32]);
+  const L=ecAdd(ecMul(prf.z1,G), ecMul(prf.z2,H));
+  const R=ecAdd(prf.A, ecMul(c,C));
+  return L!==O && R!==O && L.x===R.x && L.y===R.y;
+}
+
+/* ---------------- NIZK: equality of committed values ----------------
+   C1 = xG + r1H and C2 = xG + r2H hide the SAME x  ⇔
+   D = C1 - C2 = (r1-r2)H. Schnorr proof of knowledge of dlog of D
+   base H. Reveals nothing about x. */
+const TAG_EQ="zkThunder/sigma/eq/v1";
+function proveEquality(C1, r1, C2, r2, ctx32){
+  const rho=mod(r1-r2,N);
+  const k=randScalar();
+  const A=ecMul(k,H);
+  const c=challenge(TAG_EQ,[C1,C2,A],[ctx32]);
+  return { A, z: mod(k+c*rho,N) };
+}
+function verifyEquality(C1, C2, prf, ctx32){
+  if(!onCurve(C1)||!onCurve(C2)||!onCurve(prf.A)) return false;
+  const D=ecAdd(C1, ecNeg(C2));
+  if(D===O) return false;                 // identical commitments: reject
+  const c=challenge(TAG_EQ,[C1,C2,prf.A],[ctx32]);
+  const L=ecMul(prf.z,H);
+  const R=ecAdd(prf.A, ecMul(c,D));
+  return L!==O && R!==O && L.x===R.x && L.y===R.y;
+}
+
+/* ---------------- serialization (for on-chain + transport) ---------------- */
+function pt(Qp){ return { x:"0x"+Qp.x.toString(16).padStart(64,"0"),
+                          y:"0x"+Qp.y.toString(16).padStart(64,"0") }; }
+function sc(s){ return "0x"+s.toString(16).padStart(64,"0"); }
+
+module.exports={ keccak256, utf8, hex, bigTo32, bytesToBig,
+  P,N,G,H,O, mod, inv, onCurve, ecAdd, ecMul, ecNeg, pointAddr,
+  randScalar, challenge, commit,
+  proveOpening, verifyOpening, proveEquality, verifyEquality,
+  pt, sc, TAG_OPEN, TAG_EQ };
+
+/* ---------------- NIZK: opening to a PUBLIC value ----------------
+   Proves C = v*G + r*H for a public v (e.g. a block's state root), i.e.
+   knowledge of r with C - v*G = r*H. Schnorr on base H. The contract
+   computes v*G itself (via the ecrecover trick on the prover-supplied
+   point) so the prover cannot substitute a different value. */
+const TAG_PUB="zkThunder/sigma/pub/v1";
+function proveOpeningToPublic(C, v, r, ctx32){
+  const vG=ecMul(mod(bytesToBig(v),N),G);
+  const D=ecAdd(C, ecNeg(vG));            // = r*H
+  const k=randScalar();
+  const A=ecMul(k,H);
+  const c=challenge(TAG_PUB,[C,vG,A],[ctx32]);
+  return { vG, A, z: mod(k+c*r,N), CD: ecMul(c,D) };
+}
+function verifyOpeningToPublic(C, v, prf, ctx32){
+  const vG=ecMul(mod(bytesToBig(v),N),G);
+  if(pointAddr(vG)!==pointAddr(prf.vG)) return false;
+  const D=ecAdd(C, ecNeg(vG)); if(D===O) return false;
+  const c=challenge(TAG_PUB,[C,vG,prf.A],[ctx32]);
+  if(pointAddr(ecMul(c,D))!==pointAddr(prf.CD)) return false;
+  const R=ecAdd(prf.A, prf.CD);
+  return pointAddr(ecMul(prf.z,H))===pointAddr(R);
+}
+module.exports.proveOpeningToPublic=proveOpeningToPublic;
+module.exports.verifyOpeningToPublic=verifyOpeningToPublic;
+module.exports.TAG_PUB=TAG_PUB;

package/lib/trustless.js

@@ -0,0 +1,53 @@
+// GENERATED COPY of zk/trustless.js from the zkThunder protocol. Do not edit here; run "npm run sync" in sdk/.
+// Trustless anchoring bundle: the lineage bundle (23 words) followed by an
+// opening-to-public proof (7 words) binding C_out to the window end block's
+// REAL state root, which the contract extracts from the block header and
+// checks against blockhash(endBlock).
+//   words[0..22]  lineage bundle (zk/prove.js)
+//   words[23..29]  opening of C_out to the header state root (vG, A, z, CD)
+//   words[30..36]  opening of C_in  to the previous window's stored root
+"use strict";
+const S = require("./sigma.js");
+const { proveBundle, verifyBundleJS } = require("./prove.js");
+
+/** Build a full trustless bundle with an openable C_out. */
+function proveTrustlessFull(rootPrev, rootOut, ctx32) {
+  // Recreate prove.js's construction with access to C_out's blinding.
+  const prev = S.commit(rootPrev), cin = S.commit(rootPrev), cout = S.commit(rootOut);
+  const { challengeOpen, challengeEq } = require("./prove.js");
+  const open = (cm) => {
+    const a = S.randScalar(), bb = S.randScalar();
+    const A = S.ecAdd(S.ecMul(a, S.G), S.ecMul(bb, S.H));
+    const c = challengeOpen(cm.C, A, ctx32);
+    return { A, z1: S.mod(a + c * cm.x, S.N), z2: S.mod(bb + c * cm.r, S.N), CC: S.ecMul(c, cm.C) };
+  };
+  const oi = open(cin), oo = open(cout);
+  const rho = S.mod(prev.r - cin.r, S.N), k = S.randScalar(), Aeq = S.ecMul(k, S.H);
+  const ceq = challengeEq(prev.C, cin.C, Aeq, ctx32);
+  const zeq = S.mod(k + ceq * rho, S.N);
+  const D = S.ecAdd(prev.C, S.ecNeg(cin.C)), CD = S.ecMul(ceq, D);
+  const pubOut = S.proveOpeningToPublic(cout.C, rootOut, cout.r, ctx32);
+  const pubIn  = S.proveOpeningToPublic(cin.C,  rootPrev, cin.r,  ctx32);
+  const pub = pubOut;
+  const words = [
+    cin.C.x, cin.C.y, cout.C.x, cout.C.y, prev.C.x, prev.C.y,
+    oi.A.x, oi.A.y, oi.z1, oi.z2, oi.CC.x, oi.CC.y,
+    oo.A.x, oo.A.y, oo.z1, oo.z2, oo.CC.x, oo.CC.y,
+    Aeq.x, Aeq.y, zeq, CD.x, CD.y,
+    pub.vG.x, pub.vG.y, pub.A.x, pub.A.y, pub.z, pub.CD.x, pub.CD.y,
+    pubIn.vG.x, pubIn.vG.y, pubIn.A.x, pubIn.A.y, pubIn.z, pubIn.CD.x, pubIn.CD.y,
+  ];
+  const buf = new Uint8Array(37 * 32);
+  words.forEach((v, i) => buf.set(S.bigTo32(v), i * 32));
+  return { words, hex: "0x" + S.hex(buf), commitments: { prevCout: prev.C, C_in: cin.C, C_out: cout.C } };
+}
+
+/** Mirror of TrustlessAnchor's checks on the bundle (given the public root). */
+function verifyTrustlessJS(words, ctx32, rootPrev, rootOut) {
+  if (words.length !== 37) return false;
+  if (!verifyBundleJS(words.slice(0, 23), ctx32)) return false;
+  const pt = (i) => ({ x: words[i], y: words[i + 1] });
+  if (!S.verifyOpeningToPublic(pt(2), rootOut,  { vG: pt(23), A: pt(25), z: words[27], CD: pt(28) }, ctx32)) return false;
+  return   S.verifyOpeningToPublic(pt(0), rootPrev, { vG: pt(30), A: pt(32), z: words[34], CD: pt(35) }, ctx32);
+}
+module.exports = { proveTrustlessFull, verifyTrustlessJS };

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@zkthunder_/sdk",
+  "version": "0.1.0",
+  "description": "Zero-knowledge proofs for Robinhood Chain: lineage bundles, range proofs and trustless anchors, generated locally with no dependencies, plus a tiny client for the deployed zkThunder contracts.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": ["index.js", "index.d.ts", "lib/", "README.md"],
+  "scripts": {
+    "test": "node test.js",
+    "sync": "node sync.js"
+  },
+  "keywords": ["zero-knowledge", "pedersen", "range-proof", "robinhood-chain", "zkthunder", "secp256k1"],
+  "license": "Apache-2.0",
+  "engines": { "node": ">=18" }
+}