veritaszk-sdk 0.2.0 → 0.3.0

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

@@ -31,3 +31,16 @@ 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>;
+export interface ProofStatus {
+    commitment: string;
+    isSolvent: boolean;
+    proofStatus: number;
+    timestamp: number;
+    expiry: number;
+    isExpired: boolean;
+    verificationCount: number;
+    tier: number;
+}
+export declare function batchVerifyFromIndexer(commitments: string[], indexerUrl: string): Promise<(ProofStatus | null)[]>;
+export declare function watchProof(commitment: string, callback: (status: ProofStatus) => void, indexerUrl: string, intervalMs?: number): () => void;
+export declare function isProofExpiredFromIndexer(commitment: string, indexerUrl: string): Promise<boolean>;

package/dist/index.js

@@ -7,6 +7,9 @@ exports.getAuditTrail = getAuditTrail;
 exports.isRegistered = isRegistered;
 exports.getVerificationCount = getVerificationCount;
 exports.isProofExpired = isProofExpired;
+exports.batchVerifyFromIndexer = batchVerifyFromIndexer;
+exports.watchProof = watchProof;
+exports.isProofExpiredFromIndexer = isProofExpiredFromIndexer;
 const EXPLORER = 'https://api.explorer.provable.com/v1/testnet';
 exports.PROGRAMS = {
     REGISTRY: 'veritaszk_registry.aleo',
@@ -103,3 +106,45 @@ async function isProofExpired(orgCommitment) {
         return false;
     return expiryBlock > 0 && ts > expiryBlock;
 }
+async function batchVerifyFromIndexer(commitments, indexerUrl) {
+    const res = await fetch(`${indexerUrl}/api/proofs`);
+    if (!res.ok)
+        throw new Error(`Indexer returned ${res.status}`);
+    const all = await res.json();
+    return commitments.map(c => {
+        const found = all.find(p => p.commitment === c);
+        return found ?? null;
+    });
+}
+function watchProof(commitment, callback, indexerUrl, intervalMs = 30000) {
+    let prev = null;
+    let stopped = false;
+    const poll = async () => {
+        if (stopped)
+            return;
+        try {
+            const res = await fetch(`${indexerUrl}/api/proofs/${commitment}`);
+            if (!res.ok)
+                return;
+            const status = await res.json();
+            const key = JSON.stringify(status);
+            if (prev !== null && key !== prev)
+                callback(status);
+            prev = key;
+        }
+        catch {
+            // silently ignore network errors
+        }
+    };
+    // Do an immediate poll to seed prev, then start interval
+    poll();
+    const id = setInterval(poll, intervalMs);
+    return () => { stopped = true; clearInterval(id); };
+}
+async function isProofExpiredFromIndexer(commitment, indexerUrl) {
+    const res = await fetch(`${indexerUrl}/api/proofs/${commitment}`);
+    if (!res.ok)
+        return false;
+    const status = await res.json();
+    return status.isExpired || status.proofStatus === 2;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "veritaszk-sdk",
-  "version": "0.2.0",
-  "description": "SDK for VeritasZK zero-knowledge solvency proofs on Aleo",
+  "version": "0.3.0",
+  "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": [
@@ -16,11 +16,24 @@
   "keywords": [
     "aleo",
     "zero-knowledge",
-    "solvency",
     "zk",
-    "privacy"
+    "solvency",
+    "proof-of-reserves",
+    "privacy",
+    "blockchain",
+    "leo",
+    "veritaszk"
   ],
+  "author": "Vinay Sharma",
   "license": "MIT",
+  "homepage": "https://veritaszk.vercel.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Vinaystwt/veritaszk"
+  },
+  "bugs": {
+    "url": "https://github.com/Vinaystwt/veritaszk/issues"
+  },
   "devDependencies": {
     "@types/jest": "^29.0.0",
     "@types/node": "^20.0.0",
@@ -28,5 +41,8 @@
     "jest": "^29.0.0",
     "ts-jest": "^29.0.0",
     "typescript": "^5.4.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
   }
 }