@veilo/sdk-core 0.4.0 → 0.6.0

package/dist/esm/accounts/errors.js

@@ -0,0 +1,95 @@
+// Program error normalization is dependency-free by design.
+// -----------------------------------------------------------------------------
+// Error Parsing
+// -----------------------------------------------------------------------------
+/**
+ * Convert a Solana/Anchor transaction error into a user-friendly message.
+ * Maps privacy_pool program error codes (6000–6060) to readable strings.
+ * Mirrors relayer-server/src/controllers/transaction.helpers.ts `parseOnChainError`.
+ */
+export function parseOnChainError(error) {
+    const raw = (error?.message ?? error?.toString() ?? "").toLowerCase();
+    const hexMatch = raw.match(/custom program error:\s*0x([0-9a-f]+)/);
+    const numMatch = raw.match(/error number:\s*(\d+)/);
+    const code = hexMatch
+        ? parseInt(hexMatch[1], 16)
+        : numMatch
+            ? parseInt(numMatch[1], 10)
+            : null;
+    const PROGRAM_ERRORS = {
+        6000: "The pool is temporarily paused. Please try again later.",
+        6001: "No denominations configured for this pool.",
+        6002: "Too many denominations configured.",
+        6003: "Bad denomination index.",
+        6004: "Math overflow in the contract. Please try again.",
+        6005: "These funds have already been spent.",
+        6006: "The nullifier table is full. Please contact support.",
+        6007: "The relayer is out of sync with the network. Please wait a moment and try again.",
+        6008: "This relayer is not authorised for this pool.",
+        6009: "The pool does not have enough funds to fulfil this request.",
+        6010: "Too many relayers registered for this pool.",
+        6011: "Proof encoding is invalid. Please try again.",
+        6012: "Zero-knowledge proof verification failed. Please try again.",
+        6013: "The pool is at capacity. Please try again later.",
+        6014: "Merkle hash computation failed. Please try again.",
+        6015: "Transaction data mismatch. Please refresh and try again.",
+        6016: "Recipient address mismatch.",
+        6017: "Invalid token address.",
+        6018: "The fee exceeds the allowed limit.",
+        6019: "The relayer fee was insufficient. Please try again.",
+        6020: "Arithmetic error in the contract. Please try again.",
+        6021: "Your balance is not enough to cover the withdrawal including network fees.",
+        6022: "Your balance is not enough to cover the fee.",
+        6023: "Invalid transaction amount. Please try again.",
+        6024: "Invalid fee amount. Please try again.",
+        6025: "Duplicate fund inputs detected. Please refresh and try again.",
+        6026: "Duplicate output detected. Please refresh and try again.",
+        6027: "Token account required for SPL token operations.",
+        6028: "Token program required for SPL token operations.",
+        6029: "Invalid token account authority.",
+        6030: "Relayer account does not match the expected relayer.",
+        6031: "Relayer token account not owned by the expected relayer.",
+        6032: "Recipient token account not owned by the expected recipient.",
+        6033: "Depositor token account not owned or delegated to the relayer.",
+        6034: "Private transfers must have zero fee and refund.",
+        6035: "Amount is below the pool minimum.",
+        6036: "Amount exceeds the pool maximum.",
+        6037: "Withdrawal amount is below the pool minimum.",
+        6038: "Withdrawal amount exceeds the pool maximum.",
+        6039: "Invalid pool configuration: minimum exceeds maximum.",
+        6040: "Fee basis points exceed the maximum allowed (1%).",
+        6041: "Fee error margin exceeds the maximum allowed (50%).",
+        6042: "Only the authorized admin can initialize.",
+        6043: "Unauthorized: only admin or relayers can perform this action.",
+        6044: "Invalid tree ID: tree does not exist.",
+        6045: "Maximum number of Merkle trees reached for this pool.",
+        6046: "Deposits must use zero nullifiers (no notes consumed).",
+        6047: "Nullifier cannot be zero for withdrawals or transfers.",
+        6048: "Output commitment cannot be zero.",
+        6049: "Token account must be owned by SPL Token Program.",
+        6050: "Vault token account must be the canonical Associated Token Account.",
+        6051: "Amount is too small to cover the minimum fee. Try a larger amount.",
+        6052: "Nullifier marker account does not correspond to zero nullifier for deposits.",
+        6053: "Insufficient token delegation for deposit.",
+        6054: "Invalid swap program. Please try again.",
+        6055: "Invalid swap accounts. Please refresh and try again.",
+        6056: "Jupiter swap requires additional routing accounts.",
+        6057: "Swap instruction is invalid or unsupported. Please try again.",
+        6058: "Swap parameters are inconsistent. Please refresh and try again.",
+        6059: "Missing required swap instructions in transaction. Both fund_native_source and transact_swap must be present.",
+        6060: "The transaction deadline expired. Please try again.",
+    };
+    if (code !== null && PROGRAM_ERRORS[code])
+        return PROGRAM_ERRORS[code];
+    if (raw.includes("blockhash not found") ||
+        raw.includes("block height exceeded"))
+        return "The transaction expired before it could be confirmed. Please try again.";
+    if (raw.includes("insufficient funds") ||
+        raw.includes("insufficient lamports"))
+        return "Insufficient SOL to pay for the transaction fee.";
+    if (raw.includes("timeout") || raw.includes("timed out"))
+        return "The request timed out. Please try again.";
+    if (raw.includes("simulation failed"))
+        return "Transaction simulation failed. Please refresh and try again.";
+    return "The transaction could not be completed. Your funds are safe — please try again.";
+}

package/dist/esm/accounts/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./pdas.js";
+export * from "./queries.js";
+export * from "./admin.js";
+export * from "./errors.js";

package/dist/esm/accounts/index.js

@@ -0,0 +1,4 @@
+export * from "./pdas.js";
+export * from "./queries.js";
+export * from "./admin.js";
+export * from "./errors.js";

package/dist/esm/accounts/pdas.d.ts

@@ -0,0 +1,23 @@
+import { PublicKey } from "@solana/web3.js";
+/**
+ * Get pool PDAs for a given mint address.
+ * Note: All seeds use "v3" suffix.
+ */
+export declare function getPoolPdas(programId: PublicKey, mintAddress: PublicKey): {
+    config: PublicKey;
+    vault: PublicKey;
+    nullifiers: PublicKey;
+};
+/**
+ * Get the note tree PDA for a specific tree ID.
+ */
+export declare function getNoteTreePda(programId: PublicKey, mintAddress: PublicKey, treeId: number): PublicKey;
+/**
+ * Get the global config PDA.
+ */
+export declare function getGlobalConfigPda(programId: PublicKey): PublicKey;
+/**
+ * Get the nullifier marker PDA for a specific nullifier.
+ * NOTE: Nullifier markers are global (no tree_id) to prevent cross-tree double-spend.
+ */
+export declare function getNullifierMarkerPda(programId: PublicKey, mintAddress: PublicKey, nullifier: Uint8Array): PublicKey;

package/dist/esm/accounts/pdas.js

@@ -0,0 +1,38 @@
+import { PublicKey } from "@solana/web3.js";
+// -----------------------------------------------------------------------------
+// PDA Helpers
+// -----------------------------------------------------------------------------
+/**
+ * Get pool PDAs for a given mint address.
+ * Note: All seeds use "v3" suffix.
+ */
+export function getPoolPdas(programId, mintAddress) {
+    const [config] = PublicKey.findProgramAddressSync([Buffer.from("privacy_config_v3"), mintAddress.toBuffer()], programId);
+    const [vault] = PublicKey.findProgramAddressSync([Buffer.from("privacy_vault_v3"), mintAddress.toBuffer()], programId);
+    const [nullifiers] = PublicKey.findProgramAddressSync([Buffer.from("privacy_nullifiers_v3"), mintAddress.toBuffer()], programId);
+    return { config, vault, nullifiers };
+}
+/**
+ * Get the note tree PDA for a specific tree ID.
+ */
+export function getNoteTreePda(programId, mintAddress, treeId) {
+    const treeIdBuffer = Buffer.alloc(2);
+    treeIdBuffer.writeUInt16LE(treeId);
+    const [noteTree] = PublicKey.findProgramAddressSync([Buffer.from("privacy_note_tree_v3"), mintAddress.toBuffer(), treeIdBuffer], programId);
+    return noteTree;
+}
+/**
+ * Get the global config PDA.
+ */
+export function getGlobalConfigPda(programId) {
+    const [globalConfig] = PublicKey.findProgramAddressSync([Buffer.from("global_config_v1")], programId);
+    return globalConfig;
+}
+/**
+ * Get the nullifier marker PDA for a specific nullifier.
+ * NOTE: Nullifier markers are global (no tree_id) to prevent cross-tree double-spend.
+ */
+export function getNullifierMarkerPda(programId, mintAddress, nullifier) {
+    const [marker] = PublicKey.findProgramAddressSync([Buffer.from("nullifier_v3"), mintAddress.toBuffer(), nullifier], programId);
+    return marker;
+}

package/dist/esm/accounts/queries.d.ts

@@ -0,0 +1,41 @@
+import type { Program, Idl } from "@coral-xyz/anchor";
+import { PublicKey } from "@solana/web3.js";
+import type { PrivacyConfigAccount } from "../config.js";
+/**
+ * Fetch and decode the on-chain PrivacyConfig account for a pool.
+ */
+export declare function fetchPoolConfig<T extends Idl>(program: Program<T>, mintAddress: PublicKey): Promise<PrivacyConfigAccount>;
+/**
+ * Check whether a nullifier has been spent on-chain.
+ * Returns true if the nullifier marker PDA exists (funds already spent).
+ */
+export declare function checkNullifierSpent<T extends Idl>(program: Program<T>, mintAddress: PublicKey, nullifier: Uint8Array): Promise<boolean>;
+/** On-chain tree utilization info */
+export type TreeInfo = {
+    treeId: number;
+    leafCount: number;
+    capacity: number;
+    utilizationPercent: number;
+    remainingCapacity: number;
+    isFull: boolean;
+    treePDA: PublicKey;
+};
+/**
+ * Fetch utilization info for a specific tree.
+ * Returns null if the tree does not exist yet.
+ */
+export declare function getTreeInfo<T extends Idl>(program: Program<T>, mintAddress: PublicKey, treeId: number): Promise<TreeInfo | null>;
+/**
+ * Fetch utilization info for all trees in a pool.
+ */
+export declare function getAllTreeInfo<T extends Idl>(program: Program<T>, mintAddress: PublicKey): Promise<TreeInfo[]>;
+/**
+ * Find the best tree to deposit into.
+ *
+ * Strategy (matches veilo-dapp):
+ * 1. Discard full trees.
+ * 2. Prefer the LOWEST tree ID with remaining capacity ≥ minCapacity (default 0.01%).
+ * 3. Ensures trees fill sequentially: 0 → 1 → 2 → …
+ * 4. Fallback to the tree with the most remaining capacity.
+ */
+export declare function getBestTreeForDeposit<T extends Idl>(program: Program<T>, mintAddress: PublicKey, minCapacity?: number): Promise<TreeInfo | null>;

package/dist/esm/accounts/queries.js

@@ -0,0 +1,88 @@
+import { getNoteTreePda, getNullifierMarkerPda, getPoolPdas, } from "./pdas.js";
+// -----------------------------------------------------------------------------
+// On-Chain Account Fetchers
+// -----------------------------------------------------------------------------
+/**
+ * Fetch and decode the on-chain PrivacyConfig account for a pool.
+ */
+export async function fetchPoolConfig(program, mintAddress) {
+    const { config } = getPoolPdas(program.programId, mintAddress);
+    return program.account.privacyConfig.fetch(config);
+}
+/**
+ * Check whether a nullifier has been spent on-chain.
+ * Returns true if the nullifier marker PDA exists (funds already spent).
+ */
+export async function checkNullifierSpent(program, mintAddress, nullifier) {
+    const marker = getNullifierMarkerPda(program.programId, mintAddress, nullifier);
+    const info = await program.provider.connection.getAccountInfo(marker);
+    return info !== null;
+}
+const TREE_CAPACITY = Math.pow(2, 22); // 4,194,304 leaves (depth 22)
+/**
+ * Fetch utilization info for a specific tree.
+ * Returns null if the tree does not exist yet.
+ */
+export async function getTreeInfo(program, mintAddress, treeId) {
+    try {
+        const treePDA = getNoteTreePda(program.programId, mintAddress, treeId);
+        const tree = await program.account.merkleTreeAccount.fetch(treePDA);
+        const leafCount = Number(tree.nextIndex);
+        const remainingCapacity = TREE_CAPACITY - leafCount;
+        return {
+            treeId,
+            leafCount,
+            capacity: TREE_CAPACITY,
+            utilizationPercent: (leafCount / TREE_CAPACITY) * 100,
+            remainingCapacity,
+            isFull: leafCount >= TREE_CAPACITY,
+            treePDA,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch utilization info for all trees in a pool.
+ */
+export async function getAllTreeInfo(program, mintAddress) {
+    try {
+        const { config } = getPoolPdas(program.programId, mintAddress);
+        const cfg = await program.account.privacyConfig.fetch(config);
+        const numTrees = Number(cfg.numTrees);
+        const results = [];
+        for (let id = 0; id < numTrees; id++) {
+            const info = await getTreeInfo(program, mintAddress, id);
+            if (info)
+                results.push(info);
+        }
+        return results;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Find the best tree to deposit into.
+ *
+ * Strategy (matches veilo-dapp):
+ * 1. Discard full trees.
+ * 2. Prefer the LOWEST tree ID with remaining capacity ≥ minCapacity (default 0.01%).
+ * 3. Ensures trees fill sequentially: 0 → 1 → 2 → …
+ * 4. Fallback to the tree with the most remaining capacity.
+ */
+export async function getBestTreeForDeposit(program, mintAddress, minCapacity = Math.floor(TREE_CAPACITY * 0.0001)) {
+    const trees = await getAllTreeInfo(program, mintAddress);
+    const available = trees.filter((t) => !t.isFull);
+    if (available.length === 0)
+        return null;
+    // Prefer lowest-id tree that still has meaningful capacity
+    const preferred = available
+        .filter((t) => t.remainingCapacity >= minCapacity)
+        .sort((a, b) => a.treeId - b.treeId);
+    if (preferred.length > 0)
+        return preferred[0];
+    // Fallback: most remaining capacity
+    return available.sort((a, b) => b.remainingCapacity - a.remainingCapacity)[0];
+}