@hyperdag/proof-verifier 0.1.0 → 0.2.0

package/README.md

@@ -1,51 +1,54 @@
-# @hyperdag/proof-verifier
-Verify HyperDAG STARK proofs in your browser or Node app. No server trust.
-
-## Why this exists
-HyperDAG's zkp-postcard service generates Plonky3 STARK proofs for every agent decision. If you trust HyperDAG's server when it says `verified: true`, you're just trusting a server. With this package, your code verifies the cryptographic proof itself — locally, deterministically, with no network call.
-
-## Install
-```bash
-npm install @hyperdag/proof-verifier
-```
-
-## Usage (3 lines)
-```js
-import { verify } from '@hyperdag/proof-verifier';
-const result = await verify(proofBytes, statement);
-console.log(result.verified); // true | false
-```
-
-## End-to-end example with the SDK
-```js
-import { TrustShell } from '@hyperdag/trustshell';
-import { verify } from '@hyperdag/proof-verifier';
-
-const trust = new TrustShell({ ...config });
-const decision = await trust.report({ ... });
-const proof = await trust.getProof(decision.proof_job_id);
-const result = await verify(proof.proof_bytes, proof.statement);
-if (!result.verified) throw new Error('proof failed verification — DO NOT TRUST');
-```
-
-## What gets verified
-- The agent had the claimed RepID at the claimed time.
-- The RepID fits within the 32-bit range check relative to the threshold.
-- The statement claim (score > threshold) is cryptographically consistent with the proof.
-
-## Bundle size
-| Target  | .wasm size |
-|---------|-----------|
-| bundler | 230 KB    |
-| nodejs  | 230 KB    |
-| web     | 230 KB    |
-
-## Performance
-Verify time (avg on Node 22, Windows): ~110 ms
-Verify time (estimated Chrome/M3): ~150 ms
-
-## Plonky3 version pinning
-This verifier is pinned to the EXACT Plonky3 revisions used by zkp-postcard. Mismatched versions cannot verify. See Cargo.toml.
-
-## License
-MIT OR Apache-2.0
+# @hyperdag/proof-verifier
+
+Verify HyperDAG Plonky3 STARK RepID proofs in your browser or Node app. **Trust math, not a server.**
+
+## Why this exists
+HyperDAG's `zkp-postcard` service generates a Plonky3 STARK proof that an agent's RepID exceeds a threshold. If you trust the server when it says `verified: true`, you're trusting a server. With this package your code verifies the cryptographic proof itself — locally, deterministically, no network call.
+
+## Install
+```bash
+npm install @hyperdag/proof-verifier
+```
+
+## Usage (3 lines)
+```js
+import { verify } from '@hyperdag/proof-verifier';
+const result = await verify(proofBytes, statement); // statement = { agent_id, repid_score, threshold, tier }
+console.log(result.verified); // true | false
+```
+
+## End-to-end with the SDK
+```js
+import { TrustShell } from '@hyperdag/trustshell';
+const ts = new TrustShell();
+const proof = await ts.presentProof(agentId, { verify: true }); // fetches the proof + verifies it client-side
+if (!proof.verification?.verified) throw new Error('proof failed verification — DO NOT TRUST');
+```
+
+## What it PROVES
+The public statement is exactly `{ agent_id, threshold, repid_score }` — **no timestamp, no hidden data beyond the proof witness.** A `verified: true` means, cryptographically:
+
+- **Agent-bound.** The proof is bound to `agent_id` (its 16 bytes are public inputs observed into the Fiat-Shamir transcript). A proof minted for agent A **fails** verification under any other agent_id — it cannot be replayed.
+- **Range-sound (16-bit range check).** The circuit proves `repid_score > threshold` by range-checking the gap `repid_score − threshold − 1` into **16 bits** (the high 16 bits are constrained to zero). A claim where `repid_score ≤ threshold` has no satisfying witness — including the field-wrap case (`gap = −1 = p−1`), which an earlier 31-bit check would have admitted. (Soundness assumption: `repid_score − threshold < 65536`, always true for RepID where `repid_score ≤ 10000`.)
+- **Value-bound.** An AIR boundary constraint ties the range-checked gap to the public `{threshold, repid_score}` — the proof attests *this* agent's score exceeds *this* threshold, not merely "some 32-bit value exists."
+
+## What it does NOT prove
+- It does **not** hide `repid_score` — the score is part of the public statement. This is a verifiable attestation that the proof is consistent with the stated values, not a zero-knowledge concealment of the score.
+- It carries **no timestamp** — there is no "had RepID X at time T" claim. The statement is timeless `{agent_id, threshold, repid_score}`.
+- It does not re-verify the server's upstream RepID computation — it verifies the proof matches the stated `{agent_id, threshold, repid_score}`.
+
+## Plonky3 version pinning
+Pinned to the EXACT Plonky3 revision used by `zkp-postcard` (`27d59f7350daf6b02d11b01c3a55af453554b515`). A mismatched pin cannot verify. See `Cargo.toml`.
+
+## Bundle size
+| Target  | .wasm size |
+|---------|-----------|
+| bundler | ~245 KB   |
+| nodejs  | ~245 KB   |
+| web     | ~245 KB   |
+
+## Performance
+Verify time (avg, Node 22): ~30 ms per proof (native build; in-browser WASM is comparable).
+
+## License
+Apache-2.0

package/js/index.js

@@ -1,38 +1,38 @@
-let verifier;
-
-async function getVerifier() {
-  if (verifier) return verifier;
-
-  const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
-
-  if (isNode) {
-    // Node.js target
-    verifier = await import('../pkg-node/hyperdag_proof_verifier.js');
-  } else {
-    // Browser/Bundler target - assumes WASM is bundled or served
-    verifier = await import('../pkg/hyperdag_proof_verifier.js');
-    await verifier.default(); // Initialize WASM
-  }
-  
-  verifier.init_panic_hook();
-  return verifier;
-}
-
-/**
- * Verify a HyperDAG STARK proof locally.
- * 
- * @param {string} proofBytes - Base64 encoded proof bytes
- * @param {object} statement - The public statement (agent_id, repid_score, threshold, tier)
- * @returns {Promise<object>} - { verified: boolean, error: string | null, proof_size_bytes: number, verifier_version: string }
- */
-export async function verify(proofBytes, statement) {
-  const v = await getVerifier();
-  
-  const input = {
-    proof_bytes: proofBytes,
-    statement: statement
-  };
-  
-  const resultJson = v.verify_proof(JSON.stringify(input));
-  return JSON.parse(resultJson);
-}
+let verifier;
+
+async function getVerifier() {
+  if (verifier) return verifier;
+
+  const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
+
+  if (isNode) {
+    // Node.js target
+    verifier = await import('../pkg-node/hyperdag_proof_verifier.js');
+  } else {
+    // Browser/Bundler target - assumes WASM is bundled or served
+    verifier = await import('../pkg/hyperdag_proof_verifier.js');
+    await verifier.default(); // Initialize WASM
+  }
+  
+  verifier.init_panic_hook();
+  return verifier;
+}
+
+/**
+ * Verify a HyperDAG STARK proof locally.
+ * 
+ * @param {string} proofBytes - Base64 encoded proof bytes
+ * @param {object} statement - The public statement (agent_id, repid_score, threshold, tier)
+ * @returns {Promise<object>} - { verified: boolean, error: string | null, proof_size_bytes: number, verifier_version: string }
+ */
+export async function verify(proofBytes, statement) {
+  const v = await getVerifier();
+  
+  const input = {
+    proof_bytes: proofBytes,
+    statement: statement
+  };
+  
+  const resultJson = v.verify_proof(JSON.stringify(input));
+  return JSON.parse(resultJson);
+}

package/package.json

@@ -1,37 +1,36 @@
-{
-  "name": "@hyperdag/proof-verifier",
-  "version": "0.1.0",
-  "description": "Verify HyperDAG Plonky3 STARK proofs client-side. Trust math, not a server.",
-  "main": "js/index.js",
-  "types": "js/index.d.ts",
-  "type": "module",
-  "files": [
-    "js/",
-    "pkg/",
-    "pkg-node/",
-    "pkg-web/",
-    "README.md",
-    "LICENSE-APACHE",
-    "LICENSE-MIT"
-  ],
-  "keywords": [
-    "stark",
-    "plonky3",
-    "zkp",
-    "hyperdag",
-    "wasm",
-    "verifier"
-  ],
-  "license": "MIT OR Apache-2.0",
-  "repository": "github:DealAppSeo/hyperdag-proof-verifier",
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "wasm-pack build --target bundler --out-dir pkg --release && wasm-pack build --target nodejs --out-dir pkg-node --release && wasm-pack build --target web --out-dir pkg-web --release",
-    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
-  },
-  "devDependencies": {
-    "jest": "^30.3.0"
-  }
-}
+{
+  "name": "@hyperdag/proof-verifier",
+  "version": "0.2.0",
+  "description": "Verify HyperDAG Plonky3 STARK proofs client-side. Trust math, not a server.",
+  "main": "js/index.js",
+  "types": "js/index.d.ts",
+  "type": "module",
+  "files": [
+    "js/",
+    "pkg/",
+    "pkg-node/",
+    "pkg-web/",
+    "README.md",
+    "LICENSE-APACHE"
+  ],
+  "keywords": [
+    "stark",
+    "plonky3",
+    "zkp",
+    "hyperdag",
+    "wasm",
+    "verifier"
+  ],
+  "license": "Apache-2.0",
+  "repository": "github:DealAppSeo/hyperdag-proof-verifier",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "wasm-pack build --target bundler --out-dir pkg --release && wasm-pack build --target nodejs --out-dir pkg-node --release && wasm-pack build --target web --out-dir pkg-web --release",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+  },
+  "devDependencies": {
+    "jest": "^30.3.0"
+  }
+}

package/pkg/README.md

@@ -1,50 +1,51 @@
-# @hyperdag/proof-verifier
-Verify HyperDAG STARK proofs in your browser or Node app. No server trust.
-
-## Why this exists
-HyperDAG's zkp-postcard service generates Plonky3 STARK proofs for every agent decision. If you trust HyperDAG's server when it says `verified: true`, you're just trusting a server. With this package, your code verifies the cryptographic proof itself — locally, deterministically, with no network call.
-
-## Install
-```bash
-npm install @hyperdag/proof-verifier
-```
-
-## Usage (3 lines)
-```js
-import { verify } from '@hyperdag/proof-verifier';
-const result = await verify(proofBytes, statement);
-console.log(result.verified); // true | false
-```
-
-## End-to-end example with the SDK
-```js
-import { TrustShell } from '@hyperdag/trustshell';
-import { verify } from '@hyperdag/proof-verifier';
-
-const trust = new TrustShell({ ...config });
-const decision = await trust.report({ ... });
-const proof = await trust.getProof(decision.proof_job_id);
-const result = await verify(proof.proof_bytes, proof.statement);
-if (!result.verified) throw new Error('proof failed verification — DO NOT TRUST');
-```
-
-## What gets verified
-- The agent had the claimed RepID at the claimed time.
-- The RepID fits within the 32-bit range check relative to the threshold.
-- The statement claim (score > threshold) is cryptographically consistent with the proof.
-
-## Bundle size
-| Target  | .wasm size |
-|---------|-----------|
-| bundler | TBD        |
-| nodejs  | TBD        |
-| web     | TBD        |
-
-## Performance
-Verify time (10-run avg on Node 20, Windows): TBD ms
-
-## Plonky3 version pinning
-This verifier is pinned to the EXACT Plonky3 revisions used by zkp-postcard. Mismatched versions cannot verify. See Cargo.toml.
-
-## License
-MIT OR Apache-2.0
+# @hyperdag/proof-verifier
+Verify HyperDAG STARK proofs in your browser or Node app. No server trust.
+
+## Why this exists
+HyperDAG's zkp-postcard service generates Plonky3 STARK proofs for every agent decision. If you trust HyperDAG's server when it says `verified: true`, you're just trusting a server. With this package, your code verifies the cryptographic proof itself — locally, deterministically, with no network call.
+
+## Install
+```bash
+npm install @hyperdag/proof-verifier
+```
+
+## Usage (3 lines)
+```js
+import { verify } from '@hyperdag/proof-verifier';
+const result = await verify(proofBytes, statement);
+console.log(result.verified); // true | false
+```
+
+## End-to-end example with the SDK
+```js
+import { TrustShell } from '@hyperdag/trustshell';
+import { verify } from '@hyperdag/proof-verifier';
+
+const trust = new TrustShell({ ...config });
+const decision = await trust.report({ ... });
+const proof = await trust.getProof(decision.proof_job_id);
+const result = await verify(proof.proof_bytes, proof.statement);
+if (!result.verified) throw new Error('proof failed verification — DO NOT TRUST');
+```
+
+## What gets verified
+- The agent had the claimed RepID at the claimed time.
+- The RepID fits within the 32-bit range check relative to the threshold.
+- The statement claim (score > threshold) is cryptographically consistent with the proof.
+
+## Bundle size
+| Target  | .wasm size |
+|---------|-----------|
+| bundler | 230 KB    |
+| nodejs  | 230 KB    |
+| web     | 230 KB    |
+
+## Performance
+Verify time (avg on Node 22, Windows): ~110 ms
+Verify time (estimated Chrome/M3): ~150 ms
+
+## Plonky3 version pinning
+This verifier is pinned to the EXACT Plonky3 revisions used by zkp-postcard. Mismatched versions cannot verify. See Cargo.toml.
+
+## License
+MIT OR Apache-2.0

package/pkg/hyperdag_proof_verifier.d.ts

@@ -1,6 +1,6 @@
-/* tslint:disable */
-/* eslint-disable */
-
-export function init_panic_hook(): void;
-
-export function verify_proof(input_json: string): string;
+/* tslint:disable */
+/* eslint-disable */
+
+export function init_panic_hook(): void;
+
+export function verify_proof(input_json: string): string;

package/pkg/hyperdag_proof_verifier.js

@@ -1,9 +1,9 @@
-/* @ts-self-types="./hyperdag_proof_verifier.d.ts" */
-import * as wasm from "./hyperdag_proof_verifier_bg.wasm";
-import { __wbg_set_wasm } from "./hyperdag_proof_verifier_bg.js";
-
-__wbg_set_wasm(wasm);
-
-export {
-    init_panic_hook, verify_proof
-} from "./hyperdag_proof_verifier_bg.js";
+/* @ts-self-types="./hyperdag_proof_verifier.d.ts" */
+import * as wasm from "./hyperdag_proof_verifier_bg.wasm";
+import { __wbg_set_wasm } from "./hyperdag_proof_verifier_bg.js";
+
+__wbg_set_wasm(wasm);
+
+export {
+    init_panic_hook, verify_proof
+} from "./hyperdag_proof_verifier_bg.js";