veritaszk-sdk 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# 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.
+
+## Install
+```bash
+npm install veritaszk-sdk
+```
+
+## Usage
+```typescript
+import { VeritasZK } from "veritaszk-sdk"
+
+const client = new VeritasZK({ network: "testnet" })
+
+// 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
+
+// Get organization info
+const org = await client.getOrgInfo("aleo1abc...")
+console.log(org?.isActive) // true
+
+// One-line convenience function
+import { verifySolvency } from "veritaszk-sdk"
+const { isSolvent } = await verifySolvency("aleo1abc...")
+```
+
+## What the SDK does NOT return
+
+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
+
+This is guaranteed by the underlying Leo smart contract —
+the data does not exist in any queryable public state.
+
+## API Reference
+
+### `new VeritasZK(config?)`
+
+| 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 |
+
+### `client.verifySolvency(address)` → `Promise<SolvencyResult>`
+
+| 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 |
+
+### `client.getOrgInfo(address)` → `Promise<OrgInfo | null>`
+
+### `client.getVerificationCount(address)` → `Promise<number>`
+
+## Links
+
+- [Live Demo](https://veritaszk.vercel.app)
+- [GitHub](https://github.com/Vinaystwt/veritaszk)
+- [Aleo Explorer](https://explorer.aleo.org)
+
+Built on [Aleo](https://aleo.org) — privacy by default.

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+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;
+}
+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;
+}
+/**
+ * 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

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,153 @@
+"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.verifySolvency = verifySolvency;
+const node_fetch_1 = __importDefault(require("node-fetch"));
+function stripSuffix(val) {
+    return String(val ?? "").replace(/u(8|16|32|64|128)$/, "");
+}
+function isSolvencyProofRaw(v) {
+    return typeof v === "object" && v !== null && "is_solvent" in v;
+}
+function isOrgInfoRaw(v) {
+    return typeof v === "object" && v !== null && "name_hash" in v;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// 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, "");
+        }
+    }
+}
+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);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "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.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "aleo",
+    "zero-knowledge",
+    "zk",
+    "solvency",
+    "proof-of-reserves",
+    "privacy",
+    "leo"
+  ],
+  "author": "VeritasZK",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Vinaystwt/veritaszk"
+  },
+  "homepage": "https://veritaszk.vercel.app",
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "node-fetch": "^3.3.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,212 @@
+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

@@ -0,0 +1,26 @@
+{
+  "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"
+  ]
+}