@opaquecash/psr-core 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Base class for PSR errors surfaced to applications.
+ */
+export declare class PsrError extends Error {
+    /** Machine-readable tag for logging and UI. */
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Groth16 or witness pipeline failed. */
+export declare class ProofError extends PsrError {
+    constructor(message: string);
+}
+/** Merkle root is missing or past verifier TTL. */
+export declare class RootExpiredError extends PsrError {
+    constructor(message?: string);
+}
+/** On-chain nullifier already consumed. */
+export declare class NullifierUsedError extends PsrError {
+    constructor(message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED,0CAA0C;AAC1C,qBAAa,UAAW,SAAQ,QAAQ;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED,mDAAmD;AACnD,qBAAa,gBAAiB,SAAQ,QAAQ;gBAChC,OAAO,SAA+C;CAInE;AAED,2CAA2C;AAC3C,qBAAa,kBAAmB,SAAQ,QAAQ;gBAClC,OAAO,SAAqD;CAIzE"}

package/dist/errors.js

@@ -0,0 +1,34 @@
+/**
+ * Base class for PSR errors surfaced to applications.
+ */
+export class PsrError extends Error {
+    /** Machine-readable tag for logging and UI. */
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "PsrError";
+        this.code = code;
+    }
+}
+/** Groth16 or witness pipeline failed. */
+export class ProofError extends PsrError {
+    constructor(message) {
+        super("PROOF_ERROR", message);
+        this.name = "ProofError";
+    }
+}
+/** Merkle root is missing or past verifier TTL. */
+export class RootExpiredError extends PsrError {
+    constructor(message = "Merkle root expired or unknown on verifier") {
+        super("ROOT_EXPIRED", message);
+        this.name = "RootExpiredError";
+    }
+}
+/** On-chain nullifier already consumed. */
+export class NullifierUsedError extends PsrError {
+    constructor(message = "Nullifier already used for this reputation proof") {
+        super("NULLIFIER_USED", message);
+        this.name = "NullifierUsedError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,+CAA+C;IACtC,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,0CAA0C;AAC1C,MAAM,OAAO,UAAW,SAAQ,QAAQ;IACtC,YAAY,OAAe;QACzB,KAAK,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED,mDAAmD;AACnD,MAAM,OAAO,gBAAiB,SAAQ,QAAQ;IAC5C,YAAY,OAAO,GAAG,4CAA4C;QAChE,KAAK,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED,2CAA2C;AAC3C,MAAM,OAAO,kBAAmB,SAAQ,QAAQ;IAC9C,YAAY,OAAO,GAAG,kDAAkD;QACtE,KAAK,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@opaquecash/psr-core` — Programmable Stealth Reputation types and deterministic scoping.
+ *
+ * Safe to import in Node, edge workers, and browsers (no snarkjs / WASM required).
+ *
+ * @packageDocumentation
+ */
+export { PSR_CIRCUIT_VERSION } from "./scope.js";
+export { buildActionScope, externalNullifierFromScope } from "./scope.js";
+export type { Attestation, DiscoveredTrait, MerkleRootMeta, ProofData, } from "./types.js";
+export { PsrError, ProofError, RootExpiredError, NullifierUsedError, } from "./errors.js";
+export { attestationsToDiscoveredTraits } from "./traits.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAE1E,YAAY,EACV,WAAW,EACX,eAAe,EACf,cAAc,EACd,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,QAAQ,EACR,UAAU,EACV,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * `@opaquecash/psr-core` — Programmable Stealth Reputation types and deterministic scoping.
+ *
+ * Safe to import in Node, edge workers, and browsers (no snarkjs / WASM required).
+ *
+ * @packageDocumentation
+ */
+export { PSR_CIRCUIT_VERSION } from "./scope.js";
+export { buildActionScope, externalNullifierFromScope } from "./scope.js";
+export { PsrError, ProofError, RootExpiredError, NullifierUsedError, } from "./errors.js";
+export { attestationsToDiscoveredTraits } from "./traits.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAS1E,OAAO,EACL,QAAQ,EACR,UAAU,EACV,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC"}

package/dist/scope.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Semantic version string for Circom / artifact compatibility (bump when circuits change).
+ */
+export declare const PSR_CIRCUIT_VERSION: "0.1.0";
+/**
+ * Build a deterministic action scope string from chain + module + action id.
+ *
+ * Use stable `actionId` values (proposal id, campaign id, …). **Do not** use timestamps alone in production.
+ *
+ * @param params - Scope components.
+ * @returns Canonical `chainId:module:actionId` string.
+ *
+ * @example
+ * ```ts
+ * const scope = buildActionScope({
+ *   chainId: 11155111,
+ *   module: "governance",
+ *   actionId: "proposal-42",
+ * });
+ * ```
+ */
+export declare function buildActionScope(params: {
+    chainId: number;
+    module: string;
+    actionId: string | bigint | number;
+}): string;
+/**
+ * Map a scope string to a `uint256` external nullifier using Keccak-256 (left-padded to 32 bytes).
+ *
+ * Must stay consistent with how your circuit expects the external nullifier input.
+ *
+ * @param scope - Output of {@link buildActionScope}.
+ */
+export declare function externalNullifierFromScope(scope: string): bigint;
+//# sourceMappingURL=scope.d.ts.map

package/dist/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../src/scope.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,mBAAmB,SAAmB,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;CACpC,GAAG,MAAM,CAMT;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGhE"}

package/dist/scope.js

@@ -0,0 +1,40 @@
+import { keccak256, stringToBytes } from "viem";
+/**
+ * Semantic version string for Circom / artifact compatibility (bump when circuits change).
+ */
+export const PSR_CIRCUIT_VERSION = "0.1.0";
+/**
+ * Build a deterministic action scope string from chain + module + action id.
+ *
+ * Use stable `actionId` values (proposal id, campaign id, …). **Do not** use timestamps alone in production.
+ *
+ * @param params - Scope components.
+ * @returns Canonical `chainId:module:actionId` string.
+ *
+ * @example
+ * ```ts
+ * const scope = buildActionScope({
+ *   chainId: 11155111,
+ *   module: "governance",
+ *   actionId: "proposal-42",
+ * });
+ * ```
+ */
+export function buildActionScope(params) {
+    const id = typeof params.actionId === "bigint"
+        ? params.actionId.toString()
+        : String(params.actionId);
+    return `${params.chainId}:${params.module}:${id}`;
+}
+/**
+ * Map a scope string to a `uint256` external nullifier using Keccak-256 (left-padded to 32 bytes).
+ *
+ * Must stay consistent with how your circuit expects the external nullifier input.
+ *
+ * @param scope - Output of {@link buildActionScope}.
+ */
+export function externalNullifierFromScope(scope) {
+    const hash = keccak256(stringToBytes(scope));
+    return BigInt(hash);
+}
+//# sourceMappingURL=scope.js.map

package/dist/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../src/scope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAEhD;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAgB,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAIhC;IACC,MAAM,EAAE,GACN,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ;QACjC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE;QAC5B,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC9B,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;AACpD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAAa;IACtD,MAAM,IAAI,GAAG,SAAS,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7C,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC"}

package/dist/traits.d.ts

@@ -0,0 +1,9 @@
+import type { Attestation, DiscoveredTrait } from "./types.js";
+/**
+ * Convert raw WASM/JSON {@link Attestation} rows into {@link DiscoveredTrait}.
+ *
+ * @param rows - Parsed JSON array from `scan_attestations_wasm`.
+ * @param nowMs - Optional clock override (defaults to `Date.now()`).
+ */
+export declare function attestationsToDiscoveredTraits(rows: Attestation[], nowMs?: number): DiscoveredTrait[];
+//# sourceMappingURL=traits.d.ts.map

package/dist/traits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traits.d.ts","sourceRoot":"","sources":["../src/traits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE/D;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,WAAW,EAAE,EACnB,KAAK,GAAE,MAAmB,GACzB,eAAe,EAAE,CASnB"}

package/dist/traits.js

@@ -0,0 +1,17 @@
+/**
+ * Convert raw WASM/JSON {@link Attestation} rows into {@link DiscoveredTrait}.
+ *
+ * @param rows - Parsed JSON array from `scan_attestations_wasm`.
+ * @param nowMs - Optional clock override (defaults to `Date.now()`).
+ */
+export function attestationsToDiscoveredTraits(rows, nowMs = Date.now()) {
+    return rows.map((a) => ({
+        attestationId: a.attestation_id,
+        stealthAddress: a.stealth_address,
+        txHash: a.tx_hash,
+        blockNumber: a.block_number,
+        discoveredAt: nowMs,
+        ephemeralPubkey: a.ephemeral_pubkey,
+    }));
+}
+//# sourceMappingURL=traits.js.map

package/dist/traits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traits.js","sourceRoot":"","sources":["../src/traits.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,UAAU,8BAA8B,CAC5C,IAAmB,EACnB,QAAgB,IAAI,CAAC,GAAG,EAAE;IAE1B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtB,aAAa,EAAE,CAAC,CAAC,cAAc;QAC/B,cAAc,EAAE,CAAC,CAAC,eAAe;QACjC,MAAM,EAAE,CAAC,CAAC,OAAO;QACjB,WAAW,EAAE,CAAC,CAAC,YAAY;QAC3B,YAAY,EAAE,KAAK;QACnB,eAAe,EAAE,CAAC,CAAC,gBAAgB;KACpC,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+import type { Hex } from "viem";
+/**
+ * Issuer attestation embedded in announcement metadata and discovered by the WASM scanner.
+ */
+export interface Attestation {
+    /** Stealth address the trait is bound to (hex). */
+    readonly stealth_address: string;
+    /** Numeric attestation / trait id from issuer policy. */
+    readonly attestation_id: number;
+    /** Source transaction hash. */
+    readonly tx_hash: string;
+    /** Block number containing the announcement. */
+    readonly block_number: number;
+    /** Compressed ephemeral secp256k1 pubkey bytes. */
+    readonly ephemeral_pubkey: number[];
+}
+/**
+ * Trait discovered for the connected recipient (app-level view over {@link Attestation}).
+ */
+export interface DiscoveredTrait {
+    /** Numeric attestation id (matches circuit public input). */
+    attestationId: number;
+    /** One-time stealth address. */
+    stealthAddress: string;
+    /** Announcement transaction hash. */
+    txHash: string;
+    blockNumber: number;
+    /** Unix ms when the trait was discovered client-side. */
+    discoveredAt: number;
+    /** Ephemeral pubkey from the announcement (compressed bytes). */
+    ephemeralPubkey?: number[];
+}
+/**
+ * Metadata about an on-chain Merkle root (for indexers or `OpaqueReputationVerifier` history).
+ */
+export interface MerkleRootMeta {
+    /** 32-byte root as hex. */
+    root: Hex;
+    /** Block or timestamp context from your indexer / contract. */
+    blockNumber?: bigint;
+    submittedAt?: bigint;
+    /** Whether the verifier considers the root valid right now. */
+    valid?: boolean;
+}
+/**
+ * Groth16 proof bundle compatible with {@link submitVerifyReputation} in `@opaquecash/psr-chain`.
+ */
+export interface ProofData {
+    proof: {
+        pi_a: string[];
+        pi_b: string[][];
+        pi_c: string[];
+    };
+    publicSignals: string[];
+    nullifier: string;
+    attestationId: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAEhC;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,yDAAyD;IACzD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gDAAgD;IAChD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,aAAa,EAAE,MAAM,CAAC;IACtB,gCAAgC;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,IAAI,EAAE,GAAG,CAAC;IACV,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC;QACjB,IAAI,EAAE,MAAM,EAAE,CAAC;KAChB,CAAC;IACF,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACvB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@opaquecash/psr-core",
+  "version": "0.1.0",
+  "description": "Programmable Stealth Reputation types, scoping, and error taxonomy",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "viem": "^2.21.0"
+  },
+  "sideEffects": false
+}