veritaszk-sdk 0.1.0 → 0.2.1

package/README.md

@@ -1,77 +1,189 @@
 # veritaszk-sdk
 
-Zero-knowledge solvency verification for Aleo.
-Verify any organization's proof of solvency in 3 lines of code —
-without seeing their financial data.
+TypeScript SDK for [VeritasZK](https://veritaszk.vercel.app) — the first
+zero-knowledge proof-of-solvency system on Aleo.
+
+Organizations prove assets exceed liabilities via ZK proof without revealing
+amounts, asset types, or wallet addresses. Anyone can verify the result.
+Nobody sees the underlying data. Ever.
+
+## Quick Start
 
-## Install
 ```bash
 npm install veritaszk-sdk
 ```
 
+```typescript
+import { verifySolvency } from 'veritaszk-sdk'
+
+const result = await verifySolvency('aleo1cdmu479q6duu327wgm3vnphqtq2n4q4vcvp66f5742gv5f8f9qxq0w9r00')
+console.log(result.isSolvent)          // true — no amounts revealed
+console.log(result.verificationCount)  // times verified on-chain
+```
+
+## Architecture
+
+VeritasZK runs three Leo programs on Aleo Testnet in a CPI chain:
+
+```
+veritaszk_registry.aleo  (org identity, credentials, delegation)
+         ↑
+veritaszk_core.aleo ──→ veritaszk_audit.aleo
+(ZK proof generation)    (immutable audit trail)
+```
+
+This SDK queries public mappings across all three programs.
+Private financial data is mathematically inaccessible — the amounts
+exist only in encrypted Leo Records.
+
+## API Reference
+
+### Core Functions
+
+| Function | Description | Returns |
+|----------|-------------|---------|
+| `verifySolvency(commitment)` | Full solvency status for one org | `Promise<SolvencyStatus>` |
+| `batchVerify(commitments[])` | Check multiple orgs in parallel | `Promise<BatchVerifyResult[]>` |
+| `isRegistered(commitment)` | Check if org is in registry | `Promise<boolean>` |
+| `getAuditTrail(commitment)` | Proof event history from audit program | `Promise<AuditEvent>` |
+| `getVerificationCount(commitment)` | Number of on-chain verifications | `Promise<number>` |
+| `isProofExpired(commitment)` | Check if proof has expired | `Promise<boolean>` |
+
+### React Hooks
+
+| Hook | Description |
+|------|-------------|
+| `useSolvencyStatus(commitment)` | Auto-refreshing solvency status (polls every 30s) |
+| `useAuditTrail(commitment)` | Fetches audit event history on mount |
+
+### Webhook
+
+| Class | Description |
+|-------|-------------|
+| `VeritasZKWebhook` | Polls solvency status and POSTs to your webhook URL on state changes |
+
 ## Usage
+
+### Verify a single organization
+
 ```typescript
-import { VeritasZK } from "veritaszk-sdk"
+import { verifySolvency } from 'veritaszk-sdk'
+
+const status = await verifySolvency('aleo1...')
+// {
+//   orgCommitment: 'aleo1...',
+//   isSolvent: true,
+//   timestamp: 142857,
+//   expiryBlock: 147857,
+//   verificationCount: 12,
+//   thresholdLevel: 2,
+//   hasMultiWallet: false,
+//   isExpired: false,
+//   lastProofBlock: 142857
+// }
+```
 
-const client = new VeritasZK({ network: "testnet" })
+### Batch verification
 
-// Verify an organization's solvency
-const result = await client.verifySolvency("aleo1abc...")
-console.log(result.isSolvent)         // true
-console.log(result.timestamp)         // proof timestamp
-console.log(result.verificationCount) // times verified
-// Note: no amounts, no asset types, no financial data returned
+```typescript
+import { batchVerify } from 'veritaszk-sdk'
 
-// Get organization info
-const org = await client.getOrgInfo("aleo1abc...")
-console.log(org?.isActive) // true
+const results = await batchVerify([
+  'aleo1abc...',
+  'aleo1def...',
+])
+// [{ orgCommitment: 'aleo1abc...', isSolvent: true }, ...]
+```
+
+### Check registry
+
+```typescript
+import { isRegistered } from 'veritaszk-sdk'
 
-// One-line convenience function
-import { verifySolvency } from "veritaszk-sdk"
-const { isSolvent } = await verifySolvency("aleo1abc...")
+const registered = await isRegistered('aleo1...')
+// true — organization has registered via veritaszk_registry.aleo
 ```
 
-## What the SDK does NOT return
+### Audit trail
 
-By design, `veritaszk-sdk` never returns:
-- Asset amounts or liability amounts
-- Asset types or compositions
-- Wallet addresses beyond the one queried
-- Any data that could reveal financial strategy
+```typescript
+import { getAuditTrail } from 'veritaszk-sdk'
+
+const trail = await getAuditTrail('aleo1...')
+// {
+//   orgCommitment: 'aleo1...',
+//   eventCount: 5,
+//   lastProofBlock: 142857,
+//   isExpired: false
+// }
+```
 
-This is guaranteed by the underlying Leo smart contract —
-the data does not exist in any queryable public state.
+### React hooks
 
-## API Reference
+```tsx
+import { useSolvencyStatus } from 'veritaszk-sdk/react'
 
-### `new VeritasZK(config?)`
+function SolvencyBadge({ commitment }: { commitment: string }) {
+  const { status, loading, error } = useSolvencyStatus(commitment)
+
+  if (loading) return <span>Checking...</span>
+  if (error) return <span>Error: {error}</span>
+  if (!status) return null
+
+  return (
+    <span style={{ color: status.isSolvent ? '#10b981' : '#ef4444' }}>
+      {status.isSolvent ? '✓ SOLVENT' : '✗ NOT SOLVENT'}
+    </span>
+  )
+}
+```
+
+### Webhook monitoring
+
+```typescript
+import { VeritasZKWebhook } from 'veritaszk-sdk/webhooks'
+
+const webhook = new VeritasZKWebhook({
+  url: 'https://your-server.com/webhook',
+  events: ['proof.generated', 'proof.expired', 'proof.revoked'],
+  orgCommitment: 'aleo1...',
+  pollIntervalMs: 60000,
+})
+
+webhook.start()
+// POSTs to your URL whenever solvency state changes
+```
+
+## What the SDK Does NOT Return
+
+By design, no function in this SDK can return:
+
+- Asset amounts or liability amounts
+- Wallet addresses beyond the org commitment
+- Asset types or portfolio composition
+- Any data that could reveal financial strategy
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| network | `"testnet"` \| `"mainnet"` | `"testnet"` | Aleo network |
-| rpcUrl | `string` | Aleo testnet RPC | Custom RPC endpoint |
-| programId | `string` | `"veritaszk.aleo"` | Contract program ID |
+This is guaranteed by the underlying Leo contracts — the data does not
+exist in any queryable public state on Aleo.
 
-### `client.verifySolvency(address)` → `Promise<SolvencyResult>`
+## Deployed Programs
 
-| Field | Type | Description |
-|-------|------|-------------|
-| isSolvent | boolean | Whether a valid proof exists |
-| timestamp | number | When the proof was generated |
-| proofNonce | string | BHP256 commitment — not reversible |
-| assetCount | number | Number of asset categories declared |
-| liabilityCount | number | Number of liability categories declared |
-| verificationCount | number | Times this proof has been verified |
-| lastChecked | Date | When this query was made |
+| Program | Explorer |
+|---------|----------|
+| `veritaszk_registry.aleo` | [Explorer](https://explorer.aleo.org/program/veritaszk_registry.aleo) |
+| `veritaszk_core.aleo` | [Explorer](https://explorer.aleo.org/program/veritaszk_core.aleo) |
+| `veritaszk_audit.aleo` | [Explorer](https://explorer.aleo.org/program/veritaszk_audit.aleo) |
 
-### `client.getOrgInfo(address)` → `Promise<OrgInfo | null>`
+## Related Packages
 
-### `client.getVerificationCount(address)` → `Promise<number>`
+- [veritaszk-mcp](https://www.npmjs.com/package/veritaszk-mcp) — MCP server for AI agent integration (Claude Desktop)
+- [veritaszk-cli](https://www.npmjs.com/package/veritaszk-cli) — Terminal queries for solvency proofs
 
 ## Links
 
-- [Live Demo](https://veritaszk.vercel.app)
+- [Live Dashboard](https://veritaszk.vercel.app)
 - [GitHub](https://github.com/Vinaystwt/veritaszk)
-- [Aleo Explorer](https://explorer.aleo.org)
+- [Aleo Explorer](https://explorer.aleo.org/program/veritaszk_core.aleo)
+- [Documentation](https://veritaszk.vercel.app/docs)
 
-Built on [Aleo](https://aleo.org) — privacy by default.
+Built on Aleo — privacy by default.

package/dist/index.d.ts

@@ -1,74 +1,33 @@
-export interface SolvencyResult {
-    address: string;
+export declare const PROGRAMS: {
+    readonly REGISTRY: "veritaszk_registry.aleo";
+    readonly CORE: "veritaszk_core.aleo";
+    readonly AUDIT: "veritaszk_audit.aleo";
+};
+export interface SolvencyStatus {
+    orgCommitment: string;
     isSolvent: boolean;
-    timestamp: number;
-    proofNonce: string;
-    assetCount: number;
-    liabilityCount: number;
+    timestamp: number | null;
+    expiryBlock: number | null;
     verificationCount: number;
-    lastChecked: Date;
+    thresholdLevel: number;
+    hasMultiWallet: boolean;
+    isExpired: boolean;
+    lastProofBlock: number | null;
 }
-export interface OrgInfo {
-    address: string;
-    nameHash: string;
-    registeredAt: number;
-    isActive: boolean;
+export interface AuditEvent {
+    orgCommitment: string;
+    eventCount: number;
+    lastProofBlock: number | null;
+    isExpired: boolean;
 }
-export interface VeritasZKConfig {
-    network?: "testnet" | "mainnet";
-    rpcUrl?: string;
-    programId?: string;
-}
-export declare class VeritasZK {
-    private rpcUrl;
-    private programId;
-    private network;
-    constructor(config?: VeritasZKConfig);
-    /**
-     * Verify whether an organization holds a valid solvency proof.
-     * Returns proof status without revealing any financial data.
-     *
-     * @param address - The Aleo address of the organization to verify
-     * @returns SolvencyResult containing proof status and metadata
-     *
-     * @example
-     * const client = new VeritasZK({ network: "testnet" })
-     * const result = await client.verifySolvency("aleo1abc...")
-     * console.log(result.isSolvent) // true or false — no amounts revealed
-     */
-    verifySolvency(address: string): Promise<SolvencyResult>;
-    /**
-     * Retrieve public metadata for a registered organization.
-     * Name hash only — raw organization name is never stored on-chain.
-     *
-     * @param address - The Aleo address of the organization
-     * @returns OrgInfo containing registration metadata, or null if not registered
-     */
-    getOrgInfo(address: string): Promise<OrgInfo | null>;
-    /**
-     * Get the total number of times an organization's proof
-     * has been publicly verified.
-     *
-     * @param address - The Aleo address of the organization
-     * @returns verification count as a number
-     */
-    getVerificationCount(address: string): Promise<number>;
-    /**
-     * Query any mapping from the veritaszk.aleo program.
-     * Hits: GET {rpcUrl}/program/{programId}/mapping/{mappingName}/{key}
-     *
-     * @param mappingName - The mapping to query
-     * @param key - The key to look up
-     * @returns Parsed mapping value or null if not found
-     */
-    private queryMapping;
+export interface BatchVerifyResult {
+    orgCommitment: string;
+    isSolvent: boolean;
+    error?: string;
 }
-/**
- * One-line convenience function for solvency verification.
- *
- * @example
- * import { verifySolvency } from "veritaszk-sdk"
- * const { isSolvent } = await verifySolvency("aleo1abc...")
- */
-export declare function verifySolvency(address: string, config?: VeritasZKConfig): Promise<SolvencyResult>;
-//# sourceMappingURL=index.d.ts.map
+export declare function verifySolvency(orgCommitment: string): Promise<SolvencyStatus>;
+export declare function batchVerify(orgCommitments: string[]): Promise<BatchVerifyResult[]>;
+export declare function getAuditTrail(orgCommitment: string): Promise<AuditEvent>;
+export declare function isRegistered(orgCommitment: string): Promise<boolean>;
+export declare function getVerificationCount(orgCommitment: string): Promise<number>;
+export declare function isProofExpired(orgCommitment: string): Promise<boolean>;

package/dist/index.js

@@ -1,153 +1,105 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VeritasZK = void 0;
+exports.PROGRAMS = void 0;
 exports.verifySolvency = verifySolvency;
-const node_fetch_1 = __importDefault(require("node-fetch"));
-function stripSuffix(val) {
-    return String(val ?? "").replace(/u(8|16|32|64|128)$/, "");
+exports.batchVerify = batchVerify;
+exports.getAuditTrail = getAuditTrail;
+exports.isRegistered = isRegistered;
+exports.getVerificationCount = getVerificationCount;
+exports.isProofExpired = isProofExpired;
+const EXPLORER = 'https://api.explorer.provable.com/v1/testnet';
+exports.PROGRAMS = {
+    REGISTRY: 'veritaszk_registry.aleo',
+    CORE: 'veritaszk_core.aleo',
+    AUDIT: 'veritaszk_audit.aleo',
+};
+async function queryMapping(program, mapping, key) {
+    const url = `${EXPLORER}/program/${program}/mapping/${mapping}/${key}`;
+    const res = await fetch(url);
+    if (!res.ok)
+        return null;
+    const text = await res.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
 }
-function isSolvencyProofRaw(v) {
-    return typeof v === "object" && v !== null && "is_solvent" in v;
+function parseU32(val) {
+    if (val === null || val === undefined)
+        return null;
+    return Number(String(val).replace('u32', '').trim());
 }
-function isOrgInfoRaw(v) {
-    return typeof v === "object" && v !== null && "name_hash" in v;
+function parseU8(val) {
+    if (val === null || val === undefined)
+        return 0;
+    return Number(String(val).replace('u8', '').trim());
 }
-// ─────────────────────────────────────────────────────────────────────────────
-// VeritasZK — main SDK class
-// ─────────────────────────────────────────────────────────────────────────────
-class VeritasZK {
-    constructor(config = {}) {
-        this.network = config.network ?? "testnet";
-        this.rpcUrl =
-            config.rpcUrl ?? "https://api.explorer.provable.com/v1/testnet";
-        this.programId = config.programId ?? "veritaszk.aleo";
-    }
-    /**
-     * Verify whether an organization holds a valid solvency proof.
-     * Returns proof status without revealing any financial data.
-     *
-     * @param address - The Aleo address of the organization to verify
-     * @returns SolvencyResult containing proof status and metadata
-     *
-     * @example
-     * const client = new VeritasZK({ network: "testnet" })
-     * const result = await client.verifySolvency("aleo1abc...")
-     * console.log(result.isSolvent) // true or false — no amounts revealed
-     */
-    async verifySolvency(address) {
-        const [raw, count] = await Promise.all([
-            this.queryMapping("solvency_proofs", address),
-            this.getVerificationCount(address),
-        ]);
-        if (!isSolvencyProofRaw(raw)) {
-            return {
-                address,
-                isSolvent: false,
-                timestamp: 0,
-                proofNonce: "",
-                assetCount: 0,
-                liabilityCount: 0,
-                verificationCount: count,
-                lastChecked: new Date(),
-            };
-        }
-        return {
-            address,
-            isSolvent: raw.is_solvent === true,
-            timestamp: Number(stripSuffix(raw.timestamp)),
-            proofNonce: String(raw.proof_nonce ?? ""),
-            assetCount: Number(stripSuffix(raw.asset_count)),
-            liabilityCount: Number(stripSuffix(raw.liability_count)),
-            verificationCount: count,
-            lastChecked: new Date(),
-        };
-    }
-    /**
-     * Retrieve public metadata for a registered organization.
-     * Name hash only — raw organization name is never stored on-chain.
-     *
-     * @param address - The Aleo address of the organization
-     * @returns OrgInfo containing registration metadata, or null if not registered
-     */
-    async getOrgInfo(address) {
-        const raw = await this.queryMapping("org_metadata", address);
-        if (!isOrgInfoRaw(raw))
-            return null;
-        return {
-            address,
-            nameHash: String(raw.name_hash ?? ""),
-            registeredAt: Number(stripSuffix(raw.registered_at)),
-            isActive: raw.is_active === true,
-        };
-    }
-    /**
-     * Get the total number of times an organization's proof
-     * has been publicly verified.
-     *
-     * @param address - The Aleo address of the organization
-     * @returns verification count as a number
-     */
-    async getVerificationCount(address) {
-        try {
-            const raw = await this.queryMapping("verification_count", address);
-            if (raw === null || raw === undefined)
-                return 0;
-            return Number(stripSuffix(raw));
-        }
-        catch {
-            return 0;
-        }
-    }
-    /**
-     * Query any mapping from the veritaszk.aleo program.
-     * Hits: GET {rpcUrl}/program/{programId}/mapping/{mappingName}/{key}
-     *
-     * @param mappingName - The mapping to query
-     * @param key - The key to look up
-     * @returns Parsed mapping value or null if not found
-     */
-    async queryMapping(mappingName, key) {
-        const url = `${this.rpcUrl}/program/${this.programId}/mapping/${mappingName}/${key}`;
-        let res;
-        try {
-            res = await (0, node_fetch_1.default)(url);
-        }
-        catch (err) {
-            throw new Error(`VeritasZK network error: Unable to reach ${this.rpcUrl}. ` +
-                `Check your network connection or rpcUrl config. (${String(err)})`);
-        }
-        if (res.status === 404)
-            return null;
-        if (!res.ok) {
-            throw new Error(`VeritasZK RPC error: ${res.status} ${res.statusText} for ${url}`);
-        }
-        const text = await res.text();
-        if (!text || text === "null")
-            return null;
-        try {
-            return JSON.parse(text);
-        }
-        catch {
-            return text.replace(/^"|"$/g, "");
+async function verifySolvency(orgCommitment) {
+    const [solvent, timestamp, expiry, count, threshold, multiWallet] = await Promise.all([
+        queryMapping(exports.PROGRAMS.CORE, 'solvency_proofs', orgCommitment),
+        queryMapping(exports.PROGRAMS.CORE, 'proof_timestamps', orgCommitment),
+        queryMapping(exports.PROGRAMS.CORE, 'proof_expiry', orgCommitment),
+        queryMapping(exports.PROGRAMS.CORE, 'verification_counts', orgCommitment),
+        queryMapping(exports.PROGRAMS.CORE, 'threshold_proofs', orgCommitment),
+        queryMapping(exports.PROGRAMS.CORE, 'multi_wallet_commitments', orgCommitment),
+    ]);
+    const expiryBlock = parseU32(expiry);
+    const ts = parseU32(timestamp);
+    return {
+        orgCommitment,
+        isSolvent: solvent === true || solvent === 'true',
+        timestamp: ts,
+        expiryBlock,
+        verificationCount: parseU32(count) ?? 0,
+        thresholdLevel: parseU8(threshold),
+        hasMultiWallet: multiWallet !== null,
+        isExpired: expiryBlock !== null && expiryBlock > 0 &&
+            (parseU32(timestamp) ?? 0) > expiryBlock,
+        lastProofBlock: ts,
+    };
+}
+async function batchVerify(orgCommitments) {
+    const results = await Promise.allSettled(orgCommitments.map(c => verifySolvency(c)));
+    return results.map((r, i) => {
+        if (r.status === 'fulfilled') {
+            return { orgCommitment: orgCommitments[i],
+                isSolvent: r.value.isSolvent };
         }
-    }
+        return { orgCommitment: orgCommitments[i], isSolvent: false,
+            error: r.reason?.message ?? 'Query failed' };
+    });
+}
+async function getAuditTrail(orgCommitment) {
+    const [count, lastBlock, expired] = await Promise.all([
+        queryMapping(exports.PROGRAMS.AUDIT, 'event_count', orgCommitment),
+        queryMapping(exports.PROGRAMS.AUDIT, 'last_proof_block', orgCommitment),
+        queryMapping(exports.PROGRAMS.AUDIT, 'expired_proofs', orgCommitment),
+    ]);
+    return {
+        orgCommitment,
+        eventCount: parseU32(count) ?? 0,
+        lastProofBlock: parseU32(lastBlock),
+        isExpired: expired === true || expired === 'true',
+    };
+}
+async function isRegistered(orgCommitment) {
+    const result = await queryMapping(exports.PROGRAMS.REGISTRY, 'org_registry', orgCommitment);
+    return result === true || result === 'true';
+}
+async function getVerificationCount(orgCommitment) {
+    const result = await queryMapping(exports.PROGRAMS.CORE, 'verification_counts', orgCommitment);
+    return parseU32(result) ?? 0;
 }
-exports.VeritasZK = VeritasZK;
-// ─────────────────────────────────────────────────────────────────────────────
-// Convenience export — verify in one line
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * One-line convenience function for solvency verification.
- *
- * @example
- * import { verifySolvency } from "veritaszk-sdk"
- * const { isSolvent } = await verifySolvency("aleo1abc...")
- */
-async function verifySolvency(address, config) {
-    const client = new VeritasZK(config);
-    return client.verifySolvency(address);
+async function isProofExpired(orgCommitment) {
+    const [expiry, timestamp] = await Promise.all([
+        queryMapping(exports.PROGRAMS.CORE, 'proof_expiry', orgCommitment),
+        queryMapping(exports.PROGRAMS.CORE, 'proof_timestamps', orgCommitment),
+    ]);
+    const expiryBlock = parseU32(expiry);
+    const ts = parseU32(timestamp);
+    if (!expiryBlock || !ts)
+        return false;
+    return expiryBlock > 0 && ts > expiryBlock;
 }
-//# sourceMappingURL=index.js.map

package/dist/react.d.ts

@@ -0,0 +1,12 @@
+import type { SolvencyStatus, AuditEvent } from './index';
+export declare function useSolvencyStatus(orgCommitment: string): {
+    status: SolvencyStatus | null;
+    loading: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+export declare function useAuditTrail(orgCommitment: string): {
+    events: AuditEvent | null;
+    loading: boolean;
+    error: string | null;
+};

package/dist/react.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSolvencyStatus = useSolvencyStatus;
+exports.useAuditTrail = useAuditTrail;
+const react_1 = require("react");
+const index_1 = require("./index");
+function useSolvencyStatus(orgCommitment) {
+    const [status, setStatus] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(true);
+    const [error, setError] = (0, react_1.useState)(null);
+    const refetch = (0, react_1.useCallback)(async () => {
+        if (!orgCommitment)
+            return;
+        setLoading(true);
+        try {
+            const result = await (0, index_1.verifySolvency)(orgCommitment);
+            setStatus(result);
+            setError(null);
+        }
+        catch (e) {
+            setError(e.message);
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [orgCommitment]);
+    (0, react_1.useEffect)(() => {
+        refetch();
+        const interval = setInterval(refetch, 30000);
+        return () => clearInterval(interval);
+    }, [refetch]);
+    return { status, loading, error, refetch };
+}
+function useAuditTrail(orgCommitment) {
+    const [events, setEvents] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(true);
+    const [error, setError] = (0, react_1.useState)(null);
+    (0, react_1.useEffect)(() => {
+        if (!orgCommitment)
+            return;
+        (0, index_1.getAuditTrail)(orgCommitment)
+            .then(setEvents)
+            .catch((e) => setError(e.message))
+            .finally(() => setLoading(false));
+    }, [orgCommitment]);
+    return { events, loading, error };
+}

package/dist/webhooks.d.ts

@@ -0,0 +1,16 @@
+export interface WebhookConfig {
+    url: string;
+    secret?: string;
+    events: Array<'proof.generated' | 'proof.expired' | 'proof.revoked'>;
+    orgCommitment: string;
+    pollIntervalMs?: number;
+}
+export declare class VeritasZKWebhook {
+    private config;
+    private interval;
+    private lastSolvent;
+    constructor(config: WebhookConfig);
+    start(): void;
+    stop(): void;
+    private post;
+}

package/dist/webhooks.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VeritasZKWebhook = void 0;
+const index_1 = require("./index");
+class VeritasZKWebhook {
+    constructor(config) {
+        this.interval = null;
+        this.lastSolvent = null;
+        this.config = config;
+    }
+    start() {
+        const ms = this.config.pollIntervalMs ?? 60000;
+        this.interval = setInterval(async () => {
+            try {
+                const status = await (0, index_1.verifySolvency)(this.config.orgCommitment);
+                const changed = this.lastSolvent !== null &&
+                    this.lastSolvent !== status.isSolvent;
+                if (changed || this.lastSolvent === null) {
+                    const eventType = status.isSolvent
+                        ? 'proof.generated' : 'proof.revoked';
+                    if (this.config.events.includes(eventType)) {
+                        await this.post({ event: eventType,
+                            orgCommitment: this.config.orgCommitment,
+                            isSolvent: status.isSolvent,
+                            timestamp: new Date().toISOString() });
+                    }
+                }
+                if (status.isExpired &&
+                    this.config.events.includes('proof.expired')) {
+                    await this.post({ event: 'proof.expired',
+                        orgCommitment: this.config.orgCommitment,
+                        isSolvent: false,
+                        timestamp: new Date().toISOString() });
+                }
+                this.lastSolvent = status.isSolvent;
+            }
+            catch (e) {
+                console.error('VeritasZKWebhook error:', e);
+            }
+        }, ms);
+    }
+    stop() {
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+    }
+    async post(payload) {
+        await fetch(this.config.url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+        });
+    }
+}
+exports.VeritasZKWebhook = VeritasZKWebhook;

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "veritaszk-sdk",
-  "version": "0.1.0",
-  "description": "Zero-knowledge solvency verification SDK for Aleo. Verify any organization's proof of solvency without seeing their financial data.",
+  "version": "0.2.1",
+  "description": "TypeScript SDK for VeritasZK — query zero-knowledge solvency proofs on Aleo. Verify that organizations prove assets exceed liabilities without any private financial data being revealed. Includes React hooks, batch verification, and webhook support.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist/",
+    "README.md"
+  ],
   "scripts": {
     "build": "tsc",
+    "test": "jest",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -15,19 +20,29 @@
     "solvency",
     "proof-of-reserves",
     "privacy",
-    "leo"
+    "blockchain",
+    "leo",
+    "veritaszk"
   ],
-  "author": "VeritasZK",
+  "author": "Vinay Sharma",
   "license": "MIT",
+  "homepage": "https://veritaszk.vercel.app",
   "repository": {
     "type": "git",
     "url": "https://github.com/Vinaystwt/veritaszk"
   },
-  "homepage": "https://veritaszk.vercel.app",
+  "bugs": {
+    "url": "https://github.com/Vinaystwt/veritaszk/issues"
+  },
   "devDependencies": {
-    "typescript": "^5.0.0"
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^19.2.14",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.4.0"
   },
-  "dependencies": {
-    "node-fetch": "^3.3.0"
+  "peerDependencies": {
+    "react": ">=18.0.0"
   }
-}
+}

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAgCD,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAS;gBAEZ,MAAM,GAAE,eAAoB;IAOxC;;;;;;;;;;;OAWG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA+B9D;;;;;;OAMG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAY1D;;;;;;OAMG;IACG,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAU5D;;;;;;;OAOG;YACW,YAAY;CAiC3B;AAMD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAGzB"}

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;AA6MA,wCAMC;AAnND,4DAA+B;AA4C/B,SAAS,WAAW,CAAC,GAAY;IAC/B,OAAO,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAC;AAC7D,CAAC;AAED,SAAS,kBAAkB,CAAC,CAAU;IACpC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,YAAY,IAAI,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,YAAY,CAAC,CAAU;IAC9B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,WAAW,IAAI,CAAC,CAAC;AACjE,CAAC;AAED,gFAAgF;AAChF,6BAA6B;AAC7B,gFAAgF;AAEhF,MAAa,SAAS;IAKpB,YAAY,SAA0B,EAAE;QACtC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,SAAS,CAAC;QAC3C,IAAI,CAAC,MAAM;YACT,MAAM,CAAC,MAAM,IAAI,8CAA8C,CAAC;QAClE,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,gBAAgB,CAAC;IACxD,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,cAAc,CAAC,OAAe;QAClC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACrC,IAAI,CAAC,YAAY,CAAC,iBAAiB,EAAE,OAAO,CAAC;YAC7C,IAAI,CAAC,oBAAoB,CAAC,OAAO,CAAC;SACnC,CAAC,CAAC;QAEH,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,OAAO;gBACL,OAAO;gBACP,SAAS,EAAE,KAAK;gBAChB,SAAS,EAAE,CAAC;gBACZ,UAAU,EAAE,EAAE;gBACd,UAAU,EAAE,CAAC;gBACb,cAAc,EAAE,CAAC;gBACjB,iBAAiB,EAAE,KAAK;gBACxB,WAAW,EAAE,IAAI,IAAI,EAAE;aACxB,CAAC;QACJ,CAAC;QAED,OAAO;YACL,OAAO;YACP,SAAS,EAAE,GAAG,CAAC,UAAU,KAAK,IAAI;YAClC,SAAS,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC7C,UAAU,EAAE,MAAM,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC;YACzC,UAAU,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YAChD,cAAc,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;YACxD,iBAAiB,EAAE,KAAK;YACxB,WAAW,EAAE,IAAI,IAAI,EAAE;SACxB,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,CAAC,OAAe;QAC9B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;QAC7D,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAEpC,OAAO;YACL,OAAO;YACP,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC;YACrC,YAAY,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;YACpD,QAAQ,EAAE,GAAG,CAAC,SAAS,KAAK,IAAI;SACjC,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,oBAAoB,CAAC,OAAe;QACxC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC;YACnE,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS;gBAAE,OAAO,CAAC,CAAC;YAChD,OAAO,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,CAAC;QACX,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACK,KAAK,CAAC,YAAY,CACxB,WAAmB,EACnB,GAAW;QAEX,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM,YAAY,IAAI,CAAC,SAAS,YAAY,WAAW,IAAI,GAAG,EAAE,CAAC;QAErF,IAAI,GAAG,CAAC;QACR,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,IAAA,oBAAK,EAAC,GAAG,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,4CAA4C,IAAI,CAAC,MAAM,IAAI;gBACzD,oDAAoD,MAAM,CAAC,GAAG,CAAC,GAAG,CACrE,CAAC;QACJ,CAAC;QAED,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC;QAEpC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,wBAAwB,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,QAAQ,GAAG,EAAE,CAClE,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC;QAE1C,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;CACF;AApID,8BAoIC;AAED,gFAAgF;AAChF,0CAA0C;AAC1C,gFAAgF;AAEhF;;;;;;GAMG;AACI,KAAK,UAAU,cAAc,CAClC,OAAe,EACf,MAAwB;IAExB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC;IACrC,OAAO,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;AACxC,CAAC"}

package/src/index.ts

@@ -1,212 +0,0 @@
-import fetch from "node-fetch";
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Types
-// ─────────────────────────────────────────────────────────────────────────────
-
-export interface SolvencyResult {
-  address: string;
-  isSolvent: boolean;
-  timestamp: number;
-  proofNonce: string;
-  assetCount: number;
-  liabilityCount: number;
-  verificationCount: number;
-  lastChecked: Date;
-}
-
-export interface OrgInfo {
-  address: string;
-  nameHash: string;
-  registeredAt: number;
-  isActive: boolean;
-}
-
-export interface VeritasZKConfig {
-  network?: "testnet" | "mainnet";
-  rpcUrl?: string;
-  programId?: string;
-}
-
-interface SolvencyProofRaw {
-  is_solvent: boolean;
-  timestamp: string | number;
-  proof_nonce: string;
-  asset_count: string | number;
-  liability_count: string | number;
-}
-
-interface OrgInfoRaw {
-  name_hash: string;
-  registered_at: string | number;
-  is_active: boolean;
-}
-
-function stripSuffix(val: unknown): string {
-  return String(val ?? "").replace(/u(8|16|32|64|128)$/, "");
-}
-
-function isSolvencyProofRaw(v: unknown): v is SolvencyProofRaw {
-  return typeof v === "object" && v !== null && "is_solvent" in v;
-}
-
-function isOrgInfoRaw(v: unknown): v is OrgInfoRaw {
-  return typeof v === "object" && v !== null && "name_hash" in v;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// VeritasZK — main SDK class
-// ─────────────────────────────────────────────────────────────────────────────
-
-export class VeritasZK {
-  private rpcUrl: string;
-  private programId: string;
-  private network: string;
-
-  constructor(config: VeritasZKConfig = {}) {
-    this.network = config.network ?? "testnet";
-    this.rpcUrl =
-      config.rpcUrl ?? "https://api.explorer.provable.com/v1/testnet";
-    this.programId = config.programId ?? "veritaszk.aleo";
-  }
-
-  /**
-   * Verify whether an organization holds a valid solvency proof.
-   * Returns proof status without revealing any financial data.
-   *
-   * @param address - The Aleo address of the organization to verify
-   * @returns SolvencyResult containing proof status and metadata
-   *
-   * @example
-   * const client = new VeritasZK({ network: "testnet" })
-   * const result = await client.verifySolvency("aleo1abc...")
-   * console.log(result.isSolvent) // true or false — no amounts revealed
-   */
-  async verifySolvency(address: string): Promise<SolvencyResult> {
-    const [raw, count] = await Promise.all([
-      this.queryMapping("solvency_proofs", address),
-      this.getVerificationCount(address),
-    ]);
-
-    if (!isSolvencyProofRaw(raw)) {
-      return {
-        address,
-        isSolvent: false,
-        timestamp: 0,
-        proofNonce: "",
-        assetCount: 0,
-        liabilityCount: 0,
-        verificationCount: count,
-        lastChecked: new Date(),
-      };
-    }
-
-    return {
-      address,
-      isSolvent: raw.is_solvent === true,
-      timestamp: Number(stripSuffix(raw.timestamp)),
-      proofNonce: String(raw.proof_nonce ?? ""),
-      assetCount: Number(stripSuffix(raw.asset_count)),
-      liabilityCount: Number(stripSuffix(raw.liability_count)),
-      verificationCount: count,
-      lastChecked: new Date(),
-    };
-  }
-
-  /**
-   * Retrieve public metadata for a registered organization.
-   * Name hash only — raw organization name is never stored on-chain.
-   *
-   * @param address - The Aleo address of the organization
-   * @returns OrgInfo containing registration metadata, or null if not registered
-   */
-  async getOrgInfo(address: string): Promise<OrgInfo | null> {
-    const raw = await this.queryMapping("org_metadata", address);
-    if (!isOrgInfoRaw(raw)) return null;
-
-    return {
-      address,
-      nameHash: String(raw.name_hash ?? ""),
-      registeredAt: Number(stripSuffix(raw.registered_at)),
-      isActive: raw.is_active === true,
-    };
-  }
-
-  /**
-   * Get the total number of times an organization's proof
-   * has been publicly verified.
-   *
-   * @param address - The Aleo address of the organization
-   * @returns verification count as a number
-   */
-  async getVerificationCount(address: string): Promise<number> {
-    try {
-      const raw = await this.queryMapping("verification_count", address);
-      if (raw === null || raw === undefined) return 0;
-      return Number(stripSuffix(raw));
-    } catch {
-      return 0;
-    }
-  }
-
-  /**
-   * Query any mapping from the veritaszk.aleo program.
-   * Hits: GET {rpcUrl}/program/{programId}/mapping/{mappingName}/{key}
-   *
-   * @param mappingName - The mapping to query
-   * @param key - The key to look up
-   * @returns Parsed mapping value or null if not found
-   */
-  private async queryMapping(
-    mappingName: string,
-    key: string
-  ): Promise<unknown> {
-    const url = `${this.rpcUrl}/program/${this.programId}/mapping/${mappingName}/${key}`;
-
-    let res;
-    try {
-      res = await fetch(url);
-    } catch (err) {
-      throw new Error(
-        `VeritasZK network error: Unable to reach ${this.rpcUrl}. ` +
-          `Check your network connection or rpcUrl config. (${String(err)})`
-      );
-    }
-
-    if (res.status === 404) return null;
-
-    if (!res.ok) {
-      throw new Error(
-        `VeritasZK RPC error: ${res.status} ${res.statusText} for ${url}`
-      );
-    }
-
-    const text = await res.text();
-    if (!text || text === "null") return null;
-
-    try {
-      return JSON.parse(text);
-    } catch {
-      return text.replace(/^"|"$/g, "");
-    }
-  }
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Convenience export — verify in one line
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * One-line convenience function for solvency verification.
- *
- * @example
- * import { verifySolvency } from "veritaszk-sdk"
- * const { isSolvent } = await verifySolvency("aleo1abc...")
- */
-export async function verifySolvency(
-  address: string,
-  config?: VeritasZKConfig
-): Promise<SolvencyResult> {
-  const client = new VeritasZK(config);
-  return client.verifySolvency(address);
-}

package/tsconfig.json

@@ -1,26 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "commonjs",
-    "lib": [
-      "ES2020"
-    ],
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true
-  },
-  "include": [
-    "src/**/*"
-  ],
-  "exclude": [
-    "node_modules",
-    "dist"
-  ]
-}