@zbase-protocol/core 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,172 @@
+/**
+ * @zbase-protocol/core — Chain-agnostic types for ZK privacy payments
+ */
+export interface AccountSecrets {
+    nullifier: string;
+    secret: string;
+    commitment: string;
+    value: string;
+    label: string;
+}
+export interface ZX402AccountData {
+    secrets: AccountSecrets;
+    depositTxHash?: string;
+    chain: ChainType;
+    withdrawn: boolean;
+    createdAt: number;
+}
+export type ChainType = "evm" | "svm";
+export interface DepositResult {
+    txHash: string;
+    commitment: string;
+    label: string;
+    value: string;
+    secrets: AccountSecrets;
+    chain: ChainType;
+}
+export interface WithdrawResult {
+    txHash: string;
+    recipient: string;
+    amount: string;
+    remainingValue?: string;
+    nextDeposit?: AccountSecrets;
+    proofTimeMs: number;
+    chain: ChainType;
+}
+export interface PayResult extends WithdrawResult {
+    provider: string;
+}
+export interface PoolStats {
+    depositsCount: number;
+    totalCommittedValue: string;
+    yieldEarned: string;
+    anonymitySetSize: number;
+    chain: ChainType;
+}
+export interface ZX402Pool {
+    readonly chain: ChainType;
+    /** Deposit tokens into the privacy pool */
+    deposit(amount: string): Promise<DepositResult>;
+    /** Withdraw from pool to recipient via ZK proof */
+    withdraw(secrets: AccountSecrets, recipient: string, amountAtomic?: string): Promise<WithdrawResult>;
+    /** Pay a provider privately via ZK proof */
+    pay(secrets: AccountSecrets, provider: string, amount?: string): Promise<PayResult>;
+    /** Get pool statistics */
+    getPoolStats(): Promise<PoolStats>;
+}
+export interface VerifyRequest {
+    paymentDetails: {
+        scheme: string;
+        payTo: string;
+        maxAmountRequired: string;
+        networkId: string;
+    };
+    deposit: AccountSecrets;
+    agentId?: string;
+}
+export interface VerifyResponse {
+    valid: boolean;
+    reason?: string;
+    anonymitySetSize?: number;
+    agent?: AgentInfo;
+}
+export interface SettleRequest {
+    paymentDetails: {
+        payTo: string;
+        maxAmountRequired?: string;
+        tokenMint?: string;
+    };
+    deposit: AccountSecrets;
+    agentId?: string;
+}
+export interface SettleResponse {
+    settled: boolean;
+    txHash?: string;
+    network: string;
+    amount?: string;
+    remainingValue?: string;
+    nextDeposit?: AccountSecrets;
+    proofTimeMs?: number;
+    agent?: AgentInfo;
+}
+export interface ZX402Facilitator {
+    readonly chain: ChainType;
+    /** Verify a payment can be settled */
+    verify(request: VerifyRequest): Promise<VerifyResponse>;
+    /** Generate ZK proof and settle payment */
+    settle(request: SettleRequest): Promise<SettleResponse>;
+    /** Get supported capabilities */
+    getSupported(): SupportedCapabilities;
+}
+export interface AgentPermissions {
+    maxSpendPerTx: string;
+    maxSpendPerDay: string;
+    allowedProviders: string[];
+    allowedCategories: string[];
+}
+export interface AgentInfo {
+    id: string;
+    name: string;
+    owner: string;
+    publicKey?: string;
+    hotKey?: string;
+    coldKey?: string;
+    permissions: AgentPermissions;
+    totalSpent: string;
+    dailySpent: string;
+    txCount: number;
+    registeredAt: number;
+}
+export interface RegisterAgentRequest {
+    name: string;
+    owner: string;
+    publicKey?: string;
+    hotKey?: string;
+    coldKey?: string;
+    permissions?: Partial<AgentPermissions>;
+}
+export interface ExposureReport {
+    address: string;
+    totalTransfers: number;
+    x402PaymentsDetected: number;
+    servicesExposed: string[];
+    totalSpendVisible: string;
+    riskScore: number;
+    riskLevel: "HIGH" | "MEDIUM" | "LOW";
+    providerBreakdown: Array<{
+        provider: string;
+        payments: number;
+        totalAmount: string;
+    }>;
+    recommendations: string[];
+    chain: ChainType;
+}
+export interface SupportedCapabilities {
+    facilitator: string;
+    version: string;
+    chain: ChainType;
+    networks: string[];
+    /**
+     * `false` while the cryptographic core (Poseidon, Merkle, on-chain Groth16,
+     * ASP enforcement, recipient binding) is not yet implemented for this chain.
+     * Consumers MUST treat `privacy` and `compliance` as advisory until this is
+     * `true`. See STATUS.md for the per-chain status matrix.
+     */
+    ready: boolean;
+    privacy: {
+        method: string;
+        compliance: string;
+        /** True only when on-chain proof verification is live. */
+        enforced: boolean;
+    };
+    yield: {
+        enabled: boolean;
+        protocol: string;
+        estimatedAPY: string;
+    };
+    agentRegistry: boolean;
+    encryptedMessaging: boolean;
+    bulkRelay: boolean;
+    /** Human-readable note describing any non-ready capabilities. */
+    disclosure?: string;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * @zbase-protocol/core — Chain-agnostic types for ZK privacy payments
+ */
+export {};

package/dist/viewingKeyHD.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @zbase-protocol/core — BIP32 HD derivation for viewing keys (Phase 1B)
+ *
+ * Replaces the per-session random viewing keys produced by
+ * `generateViewingKey()` in `notes.ts` with a deterministic HD scheme rooted
+ * in a BIP39 mnemonic. The mnemonic IS the recovery secret: if a user clears
+ * localStorage but kept the 12/24-word phrase, they can re-derive every
+ * viewing key and rescan the chain to rebuild their note set.
+ *
+ * Derivation path:    m/44'/60'/0'/0'/<index>
+ *  - 44'  BIP44
+ *  - 60'  coin_type = Ethereum (matches the on-chain UTXOPool domain)
+ *  - 0'   account
+ *  - 0    external chain
+ *  - i    index (0 for primary viewing key; supports per-app sub-keys later)
+ *
+ * Output: an X25519 keypair compatible with `encryptNote` / `decryptNote` in
+ * notes.ts. The X25519 private key is taken as the SHA-512 hash of the BIP32
+ * private key (NOT the BIP32 key itself — different curves; X25519 clamps
+ * scalars). The first 32 bytes of the SHA-512 are used; the remaining 32 are
+ * discarded. This matches the X25519 key-generation recipe in RFC 7748 §5
+ * which mandates clamping but accepts any uniformly-distributed 32-byte seed.
+ *
+ * NOTE: `@scure/bip32` and `@scure/bip39` are added as direct dependencies of
+ * @zbase-protocol/core in Phase 1B because they are needed for recovery.
+ */
+import type { ViewingKeyPair } from "./notes.js";
+/**
+ * BIP44 path prefix used by zBase viewing keys. The trailing index is
+ * appended by the derivation helpers below.
+ *
+ *   m / 44' / 60' / 0' / 0' / index
+ *
+ * The fourth segment is hardened (`0'`) — diverging from the canonical
+ * Ethereum address path (`m/44'/60'/0'/0/index`) — so a leaked viewing key
+ * (which is intentionally read-only) cannot be combined with a sibling
+ * Ethereum address public key to attempt key recovery.
+ */
+export declare const ZBASE_VIEWING_KEY_PATH_PREFIX = "m/44'/60'/0'/0'";
+/**
+ * Default mnemonic strength: 128 bits = 12 words. Matches MetaMask /
+ * Rabby / most consumer wallets. 256-bit (24-word) generation is supported
+ * via `generateNewMnemonic(256)`.
+ */
+export declare const DEFAULT_MNEMONIC_STRENGTH_BITS = 128;
+/**
+ * HD-derived viewing key. Adds `mnemonic` + `derivationPath` provenance on top
+ * of the bare X25519 keypair so the wallet UI can show the user which path
+ * a key came from, and so the recovery flow can confirm the mnemonic is the
+ * one that generated a given on-chain key before re-importing.
+ */
+export interface ViewingKey extends ViewingKeyPair {
+    /** Mnemonic that generated this key. Undefined for seed-derived keys. */
+    mnemonic?: string;
+    /** Full BIP32 path, e.g., "m/44'/60'/0'/0'/0". */
+    derivationPath: string;
+    /** Index appended to the path prefix. */
+    index: number;
+}
+/**
+ * Generate a fresh BIP39 mnemonic suitable for viewing-key derivation.
+ *
+ * `strengthBits` must be a multiple of 32 in [128, 256]:
+ *   128 → 12 words (default)
+ *   160 → 15 words
+ *   192 → 18 words
+ *   224 → 21 words
+ *   256 → 24 words
+ */
+export declare function generateNewMnemonic(strengthBits?: number): string;
+/**
+ * Derive a viewing key from a BIP39 mnemonic at the given index.
+ *
+ * The same mnemonic + same index always produces the same viewing key, which
+ * is exactly what makes recovery possible: re-running this with the user's
+ * 12 words reproduces every viewing-key the wallet has ever used.
+ *
+ * @throws if `mnemonic` does not validate against the BIP39 English wordlist.
+ */
+export declare function deriveViewingKeyFromMnemonic(mnemonic: string, index?: number): ViewingKey;
+/**
+ * Derive a viewing key from a raw seed (32+ bytes, typically the 64-byte
+ * BIP39 seed but any high-entropy bytes will do). Useful when the wallet has
+ * already stretched the mnemonic with a passphrase and wants to keep the
+ * passphrase out of the call site.
+ *
+ * The mnemonic field on the returned ViewingKey will be `undefined`.
+ */
+export declare function deriveViewingKeyFromSeed(seed: Uint8Array, index?: number): ViewingKey;
+/**
+ * Return the mnemonic that produced the given viewing key. Returns
+ * `undefined` for seed-derived keys (the seed-derivation path is one-way).
+ *
+ * UI flow: present this to the user during "Show recovery phrase". Never log
+ * it; never persist it beyond the wallet's seed-vault component.
+ */
+export declare function exportMnemonic(viewingKey: ViewingKey): string | undefined;
+/**
+ * Round-trip a raw entropy buffer (16 / 20 / 24 / 28 / 32 bytes) to its BIP39
+ * mnemonic. Useful for tests and for wallets that want to derive the mnemonic
+ * from a hardware-generated entropy source.
+ */
+export declare function mnemonicFromEntropy(entropy: Uint8Array): string;
+/**
+ * Validate a BIP39 mnemonic against the English wordlist. Returns false for
+ * checksum failures, non-wordlist words, and wrong word counts.
+ */
+export declare function isValidMnemonic(mnemonic: string): boolean;

package/dist/viewingKeyHD.js

@@ -0,0 +1,176 @@
+/**
+ * @zbase-protocol/core — BIP32 HD derivation for viewing keys (Phase 1B)
+ *
+ * Replaces the per-session random viewing keys produced by
+ * `generateViewingKey()` in `notes.ts` with a deterministic HD scheme rooted
+ * in a BIP39 mnemonic. The mnemonic IS the recovery secret: if a user clears
+ * localStorage but kept the 12/24-word phrase, they can re-derive every
+ * viewing key and rescan the chain to rebuild their note set.
+ *
+ * Derivation path:    m/44'/60'/0'/0'/<index>
+ *  - 44'  BIP44
+ *  - 60'  coin_type = Ethereum (matches the on-chain UTXOPool domain)
+ *  - 0'   account
+ *  - 0    external chain
+ *  - i    index (0 for primary viewing key; supports per-app sub-keys later)
+ *
+ * Output: an X25519 keypair compatible with `encryptNote` / `decryptNote` in
+ * notes.ts. The X25519 private key is taken as the SHA-512 hash of the BIP32
+ * private key (NOT the BIP32 key itself — different curves; X25519 clamps
+ * scalars). The first 32 bytes of the SHA-512 are used; the remaining 32 are
+ * discarded. This matches the X25519 key-generation recipe in RFC 7748 §5
+ * which mandates clamping but accepts any uniformly-distributed 32-byte seed.
+ *
+ * NOTE: `@scure/bip32` and `@scure/bip39` are added as direct dependencies of
+ * @zbase-protocol/core in Phase 1B because they are needed for recovery.
+ */
+import { HDKey } from "@scure/bip32";
+import { generateMnemonic, mnemonicToSeedSync, validateMnemonic, entropyToMnemonic, } from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english";
+import { x25519 } from "@noble/curves/ed25519";
+import { sha512 } from "@noble/hashes/sha2";
+// -----------------------------------------------------------------------------
+// Constants
+// -----------------------------------------------------------------------------
+/**
+ * BIP44 path prefix used by zBase viewing keys. The trailing index is
+ * appended by the derivation helpers below.
+ *
+ *   m / 44' / 60' / 0' / 0' / index
+ *
+ * The fourth segment is hardened (`0'`) — diverging from the canonical
+ * Ethereum address path (`m/44'/60'/0'/0/index`) — so a leaked viewing key
+ * (which is intentionally read-only) cannot be combined with a sibling
+ * Ethereum address public key to attempt key recovery.
+ */
+export const ZBASE_VIEWING_KEY_PATH_PREFIX = "m/44'/60'/0'/0'";
+/**
+ * Default mnemonic strength: 128 bits = 12 words. Matches MetaMask /
+ * Rabby / most consumer wallets. 256-bit (24-word) generation is supported
+ * via `generateNewMnemonic(256)`.
+ */
+export const DEFAULT_MNEMONIC_STRENGTH_BITS = 128;
+// -----------------------------------------------------------------------------
+// Generation
+// -----------------------------------------------------------------------------
+/**
+ * Generate a fresh BIP39 mnemonic suitable for viewing-key derivation.
+ *
+ * `strengthBits` must be a multiple of 32 in [128, 256]:
+ *   128 → 12 words (default)
+ *   160 → 15 words
+ *   192 → 18 words
+ *   224 → 21 words
+ *   256 → 24 words
+ */
+export function generateNewMnemonic(strengthBits = DEFAULT_MNEMONIC_STRENGTH_BITS) {
+    return generateMnemonic(wordlist, strengthBits);
+}
+// -----------------------------------------------------------------------------
+// Derivation
+// -----------------------------------------------------------------------------
+function pathFor(index) {
+    if (!Number.isInteger(index) || index < 0) {
+        throw new Error(`deriveViewingKey: index must be a non-negative integer, got ${index}`);
+    }
+    return `${ZBASE_VIEWING_KEY_PATH_PREFIX}/${index}`;
+}
+/**
+ * Convert a 32-byte BIP32 private key into an X25519 keypair.
+ *
+ * The BIP32 key is on the secp256k1 curve; X25519 expects a 32-byte scalar
+ * that will be clamped to Curve25519. We hash the BIP32 key with SHA-512 and
+ * take the first 32 bytes — this preserves uniform distribution and never
+ * exposes the secp256k1 scalar directly (so the same mnemonic can sign EVM
+ * txs *and* serve as a viewing-key source without one compromising the other).
+ */
+/**
+ * Domain-separation tag (audit F10). Prefixing the SHA-512 input ensures this
+ * X25519 viewing-key derivation can never collide with any other SHA-512 use of
+ * the same BIP32 key — an attacker who learns one derived value cannot re-hash
+ * to confirm or correlate it without also knowing this exact label.
+ *
+ * NOTE: changing this tag changes ALL derived viewing keys. Safe to set now
+ * (UTXO/viewing-key path is pre-mainnet, no production keys exist yet); MUST be
+ * frozen before any mainnet viewing key is derived, or recovery breaks.
+ */
+const X25519_VIEWING_KEY_DST = new TextEncoder().encode("zBase/viewing-key/x25519/v1");
+function bip32PrivToX25519(bip32PrivateKey) {
+    const domainSeparated = new Uint8Array(X25519_VIEWING_KEY_DST.length + bip32PrivateKey.length);
+    domainSeparated.set(X25519_VIEWING_KEY_DST, 0);
+    domainSeparated.set(bip32PrivateKey, X25519_VIEWING_KEY_DST.length);
+    const seed = sha512(domainSeparated).slice(0, 32);
+    const privateKey = new Uint8Array(seed); // copy so we own the bytes
+    const publicKey = x25519.getPublicKey(privateKey);
+    return { privateKey, publicKey };
+}
+/**
+ * Derive a viewing key from a BIP39 mnemonic at the given index.
+ *
+ * The same mnemonic + same index always produces the same viewing key, which
+ * is exactly what makes recovery possible: re-running this with the user's
+ * 12 words reproduces every viewing-key the wallet has ever used.
+ *
+ * @throws if `mnemonic` does not validate against the BIP39 English wordlist.
+ */
+export function deriveViewingKeyFromMnemonic(mnemonic, index = 0) {
+    if (!validateMnemonic(mnemonic, wordlist)) {
+        throw new Error("deriveViewingKeyFromMnemonic: invalid BIP39 mnemonic");
+    }
+    const seed = mnemonicToSeedSync(mnemonic);
+    const derivationPath = pathFor(index);
+    const node = HDKey.fromMasterSeed(seed).derive(derivationPath);
+    if (!node.privateKey) {
+        throw new Error(`deriveViewingKeyFromMnemonic: HDKey at ${derivationPath} has no private key`);
+    }
+    const { privateKey, publicKey } = bip32PrivToX25519(node.privateKey);
+    return { privateKey, publicKey, mnemonic, derivationPath, index };
+}
+/**
+ * Derive a viewing key from a raw seed (32+ bytes, typically the 64-byte
+ * BIP39 seed but any high-entropy bytes will do). Useful when the wallet has
+ * already stretched the mnemonic with a passphrase and wants to keep the
+ * passphrase out of the call site.
+ *
+ * The mnemonic field on the returned ViewingKey will be `undefined`.
+ */
+export function deriveViewingKeyFromSeed(seed, index = 0) {
+    if (seed.length < 32) {
+        throw new Error(`deriveViewingKeyFromSeed: seed must be ≥ 32 bytes, got ${seed.length}`);
+    }
+    const derivationPath = pathFor(index);
+    const node = HDKey.fromMasterSeed(seed).derive(derivationPath);
+    if (!node.privateKey) {
+        throw new Error(`deriveViewingKeyFromSeed: HDKey at ${derivationPath} has no private key`);
+    }
+    const { privateKey, publicKey } = bip32PrivToX25519(node.privateKey);
+    return { privateKey, publicKey, derivationPath, index };
+}
+// -----------------------------------------------------------------------------
+// Recovery helpers
+// -----------------------------------------------------------------------------
+/**
+ * Return the mnemonic that produced the given viewing key. Returns
+ * `undefined` for seed-derived keys (the seed-derivation path is one-way).
+ *
+ * UI flow: present this to the user during "Show recovery phrase". Never log
+ * it; never persist it beyond the wallet's seed-vault component.
+ */
+export function exportMnemonic(viewingKey) {
+    return viewingKey.mnemonic;
+}
+/**
+ * Round-trip a raw entropy buffer (16 / 20 / 24 / 28 / 32 bytes) to its BIP39
+ * mnemonic. Useful for tests and for wallets that want to derive the mnemonic
+ * from a hardware-generated entropy source.
+ */
+export function mnemonicFromEntropy(entropy) {
+    return entropyToMnemonic(entropy, wordlist);
+}
+/**
+ * Validate a BIP39 mnemonic against the English wordlist. Returns false for
+ * checksum failures, non-wordlist words, and wrong word counts.
+ */
+export function isValidMnemonic(mnemonic) {
+    return validateMnemonic(mnemonic, wordlist);
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@zbase-protocol/core",
+  "version": "0.1.0",
+  "description": "Chain-agnostic ZK privacy core for x402 AI agent payments. Poseidon hashing, Merkle trees, Groth16 proof generation, account/secrets management. Used by @zbase-protocol/svm and @zbase-protocol/mcp.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./experimental": {
+      "types": "./dist/experimental.d.ts",
+      "import": "./dist/experimental.js",
+      "default": "./dist/experimental.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "rm -rf dist && tsc"
+  },
+  "dependencies": {
+    "@noble/ciphers": "^1.0.0",
+    "@noble/curves": "^1.9.0",
+    "@noble/hashes": "^1.3.0",
+    "@scure/bip32": "^1.7.0",
+    "@scure/bip39": "^1.6.0",
+    "@zk-kit/lean-imt": "2.2.3",
+    "poseidon-lite": "^0.3.0"
+  },
+  "optionalDependencies": {
+    "snarkjs": "^0.7.6"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/goheesheng/zBase",
+    "directory": "packages/core"
+  },
+  "homepage": "https://zbase.app",
+  "bugs": {
+    "url": "https://github.com/goheesheng/zBase/issues"
+  },
+  "keywords": [
+    "zk",
+    "zero-knowledge",
+    "privacy",
+    "x402",
+    "agents",
+    "ai-agents",
+    "base",
+    "solana",
+    "groth16",
+    "poseidon",
+    "privacy-pools"
+  ],
+  "license": "Apache-2.0"
+}