@veilo/sdk-core 0.5.0 → 0.7.0

package/README.md

@@ -6,6 +6,7 @@ The SDK gives TypeScript applications a safe, typed way to:
 
 - shield SOL or SPL tokens into Veilo;
 - withdraw, privately transfer, or privately swap shielded funds;
+- open and manage private positions, Jupiter perps, and predictions;
 - work with Veilo's relayer without handling its encryption protocol yourself;
 - add partner-powered private sends and swaps through the Cloak API.
 
@@ -31,7 +32,7 @@ You will also need:
 - a Solana RPC connection;
 - a connected wallet when a user must sign;
 - the Veilo circuit `.wasm` and `.zkey` files for local proof generation;
-- a Veilo-issued API key for partner or relayer endpoints that require one.
+- an API key only for partner services such as Cloak or Jupiter Predictions.
 
 ## Choose an integration
 
@@ -39,7 +40,7 @@ You will also need:
 | --- | --- | --- |
 | Let any wallet shield funds into Veilo | `shield()` | The user's wallet |
 | Add private transfers or swaps to a partner app | `VeiloCloakClient` | The user's wallet |
-| Build a full Veilo wallet experience | `VeiloRelayerClient` | The relayer for private spends |
+| Build a full Veilo wallet experience | Managed relayer helpers | The relayer for private spends |
 | Manage proofs, notes, trees, and transactions yourself | Transaction helpers | Your application or relayer |
 
 For most third-party deposit integrations, `shield()` is the best starting
@@ -231,31 +232,240 @@ that fits your application:
 | Private transfer | `submitPrivateTransfer()` | `privateTransfer()` |
 | Private swap | `submitPrivateSwap()` | `buildPrivateSwapInstructions()` or `transactSwap()` |
 
-### Use the relayer client
+### Use the managed relayer helpers
 
-`VeiloRelayerClient` encrypts private transaction requests before sending them
-to the relayer. The request and response types are exported for TypeScript
-autocomplete.
+The SDK owns Veilo's production relayer URL, encryption key, request encryption,
+and safe retry behavior. Applications call typed functions directly; there is
+no relayer client or URL to configure.
 
 ```ts
 import {
-  VeiloRelayerClient,
+  submitWithdraw,
   type WithdrawRequest,
 } from "@veilo/sdk-core/relayer";
 
-const relayer = new VeiloRelayerClient({
-  apiKey: process.env.VEILO_RELAYER_KEY!,
-  relayerPublicKey: process.env.VEILO_RELAYER_PUBLIC_KEY!,
-  authToken: process.env.VEILO_AUTH_TOKEN,
+async function submitWithdrawal(request: WithdrawRequest) {
+  return submitWithdraw(request);
+}
+```
+
+The same focused entry point provides account authentication, encrypted note
+storage, Merkle tree reads, private transfers, private swaps, and these product
+flows:
+
+| Product | Relayer helpers |
+| --- | --- |
+| Private positions | `submitOpenPosition()`, `submitClosePosition()`, `submitMergePositions()` |
+| Jupiter perps | `submitJperpOpen()`, `submitJperpClose()`, TP/SL, cancellation, recovery, and reissue helpers |
+| Jupiter predictions | `submitPredictionOpen()` and `submitPredictionReissue()` |
+
+#### Submission always targets Veilo's relayer
+
+Every helper above submits to Veilo's relayer. There is no `baseUrl` option, no
+client to construct, and no supported way to redirect submission. That is
+deliberate, for two independent reasons:
+
+1. **The program requires it.** The privacy pool checks the submitting relayer
+   against an on-chain allowlist on every spend. Deposits (`public_amount > 0`)
+   are permissionless — which is why `shield()` and `deposit()` work with any
+   wallet — but withdrawals, transfers, swaps, positions, perps, and predictions
+   all fail with `RelayerNotAllowed` unless the transaction is signed by a
+   whitelisted relayer. Pointing the SDK at a different host would produce a
+   well-formed request that cannot land on chain.
+2. **These requests carry spending keys.** `TransactNote.privateKey`, and the
+   `claimantSecretKey` on position close and merge, *are* the spend authority for
+   the funds involved (see [A private note is valuable secret
+   data](#a-private-note-is-valuable-secret-data)). A configurable submission
+   target would be a configurable destination for user funds.
+
+Running your own relayer is a whitelisting conversation rather than a
+configuration flag — see [Support](#support). Reaching past the package's
+`exports` map to import internal modules is unsupported and not covered by
+semver.
+
+### Finding your notes on the public feed
+
+Every row in the compact feed is ciphertext plus a one-byte view tag; nothing on
+it says who a note belongs to. You find yours by trial decryption, and the view
+tag makes that cheap — it rejects roughly 255 of every 256 foreign rows with a
+single hash instead of a full decrypt.
+
+```ts
+import { scanCompactNotes, fetchNotesByCommitment } from "@veilo/sdk-core";
+
+const { notes, scanned, nextCursor } = await scanCompactNotes(walletSecretKey, {
+  onPage: ({ matched }) => console.log(`${matched} found so far`),
 });
+```
 
-async function submitWithdrawal(request: WithdrawRequest) {
-  return relayer.submitWithdraw(request);
+It paginates to exhaustion by default and derives the X25519 key once for the
+whole scan. Stop early with `maxPages` or by returning `false` from `onPage`;
+`nextCursor` is then non-null and can be passed back later to resume. The feed
+carries only unspent, unclaimed notes, and it needs no auth token — scanning
+reveals nothing without your key.
+
+`fetchNotesByCommitment(commitments)` looks up known commitments instead,
+chunked at the server's 50-per-request cap and issued concurrently. Commitments
+the relayer does not know are simply absent from the result.
+
+### Consolidating notes before a large spend
+
+When no one or two notes cover an amount, `selectNotesForAmount` reports
+`requiresMerge`. `planNoteConsolidation` says what to do about it:
+
+```ts
+const plan = planNoteConsolidation(unspentNotes, amountRaw, { mint });
+if (plan.ok) {
+  for (const { inputs, outputAmount } of plan.steps) {
+    // one 2-in-1-out privateTransfer to yourself per step
+  }
 }
 ```
 
-The same client also provides account authentication, encrypted note storage,
-Merkle tree reads, private transfers, and private swaps.
+Each step is a self-transfer combining two inputs into one, so k notes need k-2
+steps before a final two-input spend. Steps chain — a later step can consume an
+earlier step's output, and inputs are tagged `{ kind: "note" }` or
+`{ kind: "step", step }` so you always know which. The two smallest are merged
+each round, which retires dust first and leaves large notes intact. The plan is
+pure: it computes, it does not execute.
+
+### Spend status and private balance
+
+Nothing in a note says whether it has been spent — a note is yours until its
+nullifier is published. So a balance is always two steps, and the SDK gives you
+both:
+
+```ts
+import { getPrivateBalance, checkNullifiersSpent } from "@veilo/sdk-core";
+
+const { total, byMint, unspent, spent } = await getPrivateBalance(myNotes);
+```
+
+Each note needs an `amount`, a 64-character hex `nullifier`, and optionally a
+`mint` to group by. `getPrivateBalance` asks the relayer which nullifiers are
+spent, then sums what is left; `unspent` and `spent` hand back your own note
+objects, so you can render from them directly.
+
+`checkNullifiersSpent(nullifiers)` is the same question on its own. It
+deduplicates, splits into the server's 200-per-request batches, issues them
+concurrently, and returns a `Set` for membership testing. It also lower-cases
+input: the endpoint validates case-insensitively but answers in lower case, so
+upper-case hex would otherwise never match and every note would read as unspent.
+
+To compute a balance without the relayer — from a chain scan of nullifier
+events, or a local cache — supply the answer yourself:
+
+```ts
+await getPrivateBalance(myNotes, { resolveSpent: async (ns) => mySpentSet(ns) });
+```
+
+Amounts stay `bigint` end to end. A `number` amount above `Number.MAX_SAFE_INTEGER`
+is rejected rather than silently rounded, and a malformed nullifier throws
+instead of counting as unspent — either would overstate a balance.
+
+### Choosing notes to spend
+
+Two rules govern this, and both are easy to get wrong:
+
+- the transaction circuit is **2-in-2-out**, so one transaction spends at most
+  two notes;
+- notes are only co-spendable inside the **same Merkle tree**, and the tree is
+  derived from the mint.
+
+```ts
+import { selectNotesForAmount, canonicalTreeId } from "@veilo/sdk-core";
+
+const selection = selectNotesForAmount(unspentNotes, amountRaw, { mint });
+if (!selection.ok) throw new Error(selection.message); // NO_NOTES | INSUFFICIENT_FUNDS
+if (selection.requiresMerge) {
+  // more than two inputs — combine them before proving
+}
+```
+
+It searches each tree independently and returns the best result: the smallest
+single note that covers the amount, else the pair with the least change (found
+by a two-pointer scan, not an all-pairs search), else the largest notes greedily
+with `requiresMerge` set. A failure reports `available`, the largest total
+reachable within one tree.
+
+`canonicalTreeId(mint)` derives a note's tree the way the relayer does. **Derive
+it; never trust a stored `treeId`.** Change notes are written with the on-chain
+shard index while deposits and synced notes carry the mint-derived id — for
+native SOL both are 0 so the difference hides, but for SPL tokens they diverge
+and co-spending across the two fails at proof time as a commitment mismatch.
+
+### Private product keys and recovery
+
+Private positions, perps, and predictions use deterministic client-held keys.
+The SDK provides the exact derivations used by Veilo's wallet, extension,
+relayer, and program tests. Keep the spending key and claimant secret on the
+user's device; send claimant secrets only inside the SDK's encrypted relayer
+requests.
+
+```ts
+import {
+  derivePositionKeyBundle,
+  deriveSpendingKeyWithSigner,
+  encodeClaimantSecretKey,
+  initPoseidon,
+  submitOpenPosition,
+} from "@veilo/sdk-core";
+
+await initPoseidon();
+const spendingKey = await deriveSpendingKeyWithSigner(
+  (message) => wallet.signMessage(message),
+);
+const positionKeys = derivePositionKeyBundle(spendingKey, nextPositionIndex);
+
+await submitOpenPosition({
+  // Select private source notes in your wallet before calling the relayer.
+  notes,
+  sourceMintAddress,
+  destMintAddress,
+  swapAmountRaw,
+  slippageBps: 50,
+  userPublicKey: wallet.publicKey.toBase58(),
+  veiloPublicKey,
+  position: positionKeys.position,
+});
+
+// Persist the returned position data and `nextPositionIndex`. Re-derive the
+// same claimant later when closing or merging the position.
+const claimantSecretKey = encodeClaimantSecretKey(positionKeys.claimant);
+```
+
+Use `deriveJperpKeyBundle()` and `getJperpMarketPayload()` for private perps.
+Use `derivePredictionKeyBundle()` for private predictions. Lower-level key
+derivations are also exported when an application needs them individually. The
+PDA helpers in each focused entry point support on-chain recovery scans on a
+fresh device.
+
+Predictions have one additional step: Jupiter returns an unsigned order,
+close, or claim transaction. The SDK exposes that API without taking custody
+of signing:
+
+```ts
+import {
+  JupiterPredictionClient,
+  deserializePredictionTransaction,
+} from "@veilo/sdk-core/predictions";
+
+const predictions = new JupiterPredictionClient({ apiKey: jupiterApiKey });
+const order = await predictions.placeOrder({
+  ownerPubkey: ephemeral.publicKey.toBase58(),
+  marketId,
+  isYes: true,
+  isBuy: true,
+  depositAmount: "5000000",
+  depositMint: usdcMint,
+});
+const transaction = deserializePredictionTransaction(order);
+// Ask the deterministic ephemeral wallet to sign, then submit and confirm it.
+```
+
+The SDK deliberately does not own application storage or choose which notes to
+spend. Persist indexes and returned product records only after the corresponding
+transaction is confirmed.
 
 ### Use the direct helpers
 
@@ -347,8 +557,28 @@ for shields and call a deposit's `commit()` callback only after confirmation.
 ### Proof files are separate
 
 Circuit `.wasm` and `.zkey` files are intentionally not bundled with the npm
-package because they are large. Provide local paths, byte arrays, or hosted URLs
-to `createTransactionProver()` and `createSwapProver()`.
+package because they are large — `files` ships `dist/` only. Provide local
+paths, byte arrays, or hosted URLs to `createTransactionProver()` and
+`createSwapProver()`.
+
+Both arguments are optional. Omit them and the prover resolves artifacts from
+disk on first use, first hit wins:
+
+1. `$VEILO_CIRCUITS_DIR`
+2. `<package>/circuits` — populated by `npm run copy:circuits`
+3. `<cwd>/circuits`
+4. `<cwd>/node_modules/@veilo/sdk-core/circuits`
+
+```ts
+const prover = createTransactionProver();            // resolved from disk
+const prover = createTransactionProver({ wasmPath, zkeyPath }); // explicit
+```
+
+`resolveCircuitArtifacts("transaction" | "swap")` performs that lookup on its
+own if you want the paths. Resolution is **Node-only and lazy** — it imports
+`node:fs` inside the call so browser bundles can still import this module, and
+there is nothing to resolve in a browser anyway. Browser builds must pass
+`CircuitArtifacts` explicitly. A miss throws with every path it tried.
 
 ## Error handling
 
@@ -388,8 +618,11 @@ import { shield } from "@veilo/sdk-core";
 import { getPoolPdas } from "@veilo/sdk-core/accounts";
 import { createUTXO } from "@veilo/sdk-core/notes";
 import { deposit, withdraw } from "@veilo/sdk-core/transactions";
-import { VeiloRelayerClient } from "@veilo/sdk-core/relayer";
+import { submitWithdraw } from "@veilo/sdk-core/relayer";
 import { VeiloCloakClient } from "@veilo/sdk-core/cloak";
+import { derivePositionKeyBundle } from "@veilo/sdk-core/positions";
+import { getJperpMarketPayload } from "@veilo/sdk-core/perps";
+import { JupiterPredictionClient } from "@veilo/sdk-core/predictions";
 ```
 
 Available focused entry points:
@@ -397,7 +630,12 @@ Available focused entry points:
 - `@veilo/sdk-core/accounts`
 - `@veilo/sdk-core/cloak`
 - `@veilo/sdk-core/config`
+- `@veilo/sdk-core/idl`
+- `@veilo/sdk-core/identity`
 - `@veilo/sdk-core/notes`
+- `@veilo/sdk-core/perps`
+- `@veilo/sdk-core/positions`
+- `@veilo/sdk-core/predictions`
 - `@veilo/sdk-core/poseidon`
 - `@veilo/sdk-core/proof`
 - `@veilo/sdk-core/prover`
@@ -421,6 +659,32 @@ or relayer:
 These APIs are fully typed. Use their TypeScript definitions as the source of
 truth for required inputs.
 
+### Historical IDLs and commitment recovery
+
+The SDK includes the current, legacy, and legacy-2 privacy-pool IDLs used by the
+relayer. Event scans automatically try the historical layouts, so applications
+can rebuild trees across program upgrades.
+
+```ts
+import {
+  PRIVACY_POOL_IDLS,
+  buildTreeFromEvents,
+  resolveCommitmentEvents,
+} from "@veilo/sdk-core";
+```
+
+`buildTreeFromEvents()` includes Veilo's protected historical repairs by
+default and rejects gaps that would produce an incorrect root. When a confirmed
+instruction appended commitments without emitting `CommitmentEvent`, use
+`resolveCommitmentEvents()` with the expected commitments and current local
+tree. It prefers emitted metadata and computes only the missing entries.
+
+For the deployed eventless `open_position` path, use
+`recoverEventlessOpenPositionEvents()`. It decodes both commitments from the
+instruction and reads the authoritative global position-tree leaf index from
+the program-owned PositionPDA. `buildGlobalPositionTreeFromEvents()` mirrors
+the relayer's all-mint position-tree reconstruction.
+
 ## Development
 
 ```bash

package/accounts.d.ts

@@ -0,0 +1,2 @@
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+export * from "./dist/cjs/accounts/index";

package/accounts.js

@@ -0,0 +1,3 @@
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+// Resolves "@veilo/sdk-core/accounts" for legacy moduleResolution: "node".
+module.exports = require("./dist/cjs/accounts/index.js");

package/cloak.d.ts

@@ -0,0 +1,2 @@
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+export * from "./dist/cjs/cloak";

package/cloak.js

@@ -0,0 +1,3 @@
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+// Resolves "@veilo/sdk-core/cloak" for legacy moduleResolution: "node".
+module.exports = require("./dist/cjs/cloak.js");

package/config.d.ts

@@ -0,0 +1,2 @@
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+export * from "./dist/cjs/config";

package/config.js

@@ -0,0 +1,3 @@
+// Generated by scripts/gen-subpath-stubs.mjs — do not edit.
+// Resolves "@veilo/sdk-core/config" for legacy moduleResolution: "node".
+module.exports = require("./dist/cjs/config.js");

package/dist/cjs/events/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./parsing.js";
+export * from "./position.js";
+export * from "./recovery.js";
+export * from "./scanning.js";
+export * from "./tree.js";

package/dist/cjs/events/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./parsing.js"), exports);
+__exportStar(require("./position.js"), exports);
+__exportStar(require("./recovery.js"), exports);
+__exportStar(require("./scanning.js"), exports);
+__exportStar(require("./tree.js"), exports);

package/dist/cjs/events/parsing.d.ts

@@ -0,0 +1,25 @@
+import { PublicKey } from "@solana/web3.js";
+import { type VersionedPrivacyPoolIdl } from "../idl/index.js";
+import type { CommitmentEvent, NullifierSpentEvent, ParsedVeiloEvent } from "./types.js";
+/**
+ * Decode logs using the current, legacy, and legacy-2 IDLs.
+ *
+ * IDLs are evaluated in the relayer's current/legacy/legacy-2 order. Anchor's
+ * Borsh decoder accepts trailing bytes, however, so every successful parse is
+ * considered and the richest result wins. That preserves the compact fields
+ * in legacy-2 events instead of misclassifying them as the shorter legacy form.
+ * Ties retain the relayer's order.
+ */
+export declare function parseVeiloEventsWithFallback(logMessages: readonly string[] | null | undefined, programId: PublicKey, idls?: readonly VersionedPrivacyPoolIdl[]): ParsedVeiloEvent[];
+export declare function parseCommitmentEventsFromLogs(params: {
+    logMessages: readonly string[] | null | undefined;
+    programId: PublicKey;
+    txSignature: string;
+    slot: number;
+}): CommitmentEvent[];
+export declare function parseNullifierEventsFromLogs(params: {
+    logMessages: readonly string[] | null | undefined;
+    programId: PublicKey;
+    txSignature: string;
+    slot: number;
+}): NullifierSpentEvent[];

package/dist/cjs/events/parsing.js

@@ -0,0 +1,158 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseVeiloEventsWithFallback = parseVeiloEventsWithFallback;
+exports.parseCommitmentEventsFromLogs = parseCommitmentEventsFromLogs;
+exports.parseNullifierEventsFromLogs = parseNullifierEventsFromLogs;
+const anchor = __importStar(require("@coral-xyz/anchor"));
+const web3_js_1 = require("@solana/web3.js");
+const index_js_1 = require("../idl/index.js");
+/**
+ * Decode logs using the current, legacy, and legacy-2 IDLs.
+ *
+ * IDLs are evaluated in the relayer's current/legacy/legacy-2 order. Anchor's
+ * Borsh decoder accepts trailing bytes, however, so every successful parse is
+ * considered and the richest result wins. That preserves the compact fields
+ * in legacy-2 events instead of misclassifying them as the shorter legacy form.
+ * Ties retain the relayer's order.
+ */
+function parseVeiloEventsWithFallback(logMessages, programId, idls = index_js_1.PRIVACY_POOL_IDLS) {
+    if (!logMessages?.length)
+        return [];
+    let best = [];
+    let bestScore = -1;
+    for (const candidate of idls) {
+        try {
+            const parser = new anchor.EventParser(programId, new anchor.BorshCoder(candidate.idl));
+            const parsed = Array.from(parser.parseLogs([...logMessages])).map((event) => ({
+                name: event.name,
+                data: event.data,
+                idlVersion: candidate.version,
+            }));
+            const score = parsed.reduce((total, event) => total + decodedFieldCount(event.data), 0);
+            if (score > bestScore) {
+                best = parsed;
+                bestScore = score;
+            }
+        }
+        catch {
+            // The discriminator is shared while historical payload lengths differ.
+        }
+    }
+    return best;
+}
+function parseCommitmentEventsFromLogs(params) {
+    const { logMessages, programId, txSignature, slot } = params;
+    const out = [];
+    for (const event of parseVeiloEventsWithFallback(logMessages, programId)) {
+        if (event.name.toLowerCase() !== "commitmentevent")
+            continue;
+        const data = event.data;
+        const mintAddress = toPublicKey(field(data, "mintAddress", "mint_address"));
+        const ephemeralPublicKey = optionalBytes(field(data, "ephemeralPublicKey", "ephemeral_public_key"));
+        const encryptedBlob = optionalBytes(field(data, "encryptedBlob", "encrypted_blob"));
+        const rawViewTag = field(data, "viewTag", "view_tag");
+        out.push({
+            commitment: toBytes(field(data, "commitment"), 32, "commitment"),
+            leafIndex: toSafeNumber(field(data, "leafIndex", "leaf_index"), "leafIndex"),
+            newRoot: toBytes(field(data, "newRoot", "new_root"), 32, "newRoot"),
+            timestamp: toSafeNumber(field(data, "timestamp"), "timestamp"),
+            mintAddress,
+            treeId: toSafeNumber(field(data, "treeId", "tree_id"), "treeId"),
+            txSignature,
+            slot,
+            ...(ephemeralPublicKey ? { ephemeralPublicKey } : {}),
+            ...(encryptedBlob ? { encryptedBlob } : {}),
+            ...(rawViewTag !== undefined
+                ? { viewTag: toSafeNumber(rawViewTag, "viewTag") }
+                : {}),
+            source: "emitted",
+            idlVersion: event.idlVersion,
+        });
+    }
+    return out;
+}
+function parseNullifierEventsFromLogs(params) {
+    const { logMessages, programId, txSignature, slot } = params;
+    const out = [];
+    for (const event of parseVeiloEventsWithFallback(logMessages, programId)) {
+        if (event.name.toLowerCase() !== "nullifierspent")
+            continue;
+        const data = event.data;
+        out.push({
+            nullifier: toBytes(field(data, "nullifier"), 32, "nullifier"),
+            timestamp: toSafeNumber(field(data, "timestamp"), "timestamp"),
+            mintAddress: toPublicKey(field(data, "mintAddress", "mint_address")),
+            treeId: toSafeNumber(field(data, "treeId", "tree_id"), "treeId"),
+            txSignature,
+            slot,
+            idlVersion: event.idlVersion,
+        });
+    }
+    return out;
+}
+function field(data, camel, snake) {
+    return data[camel] ?? (snake ? data[snake] : undefined);
+}
+function optionalBytes(value) {
+    return value === undefined || value === null
+        ? undefined
+        : new Uint8Array(value);
+}
+function decodedFieldCount(value) {
+    return value && typeof value === "object" ? Object.keys(value).length : 0;
+}
+function toBytes(value, length, label) {
+    const bytes = new Uint8Array(value);
+    if (bytes.length !== length) {
+        throw new Error(`${label} must be ${length} bytes, got ${bytes.length}`);
+    }
+    return bytes;
+}
+function toPublicKey(value) {
+    if (value instanceof web3_js_1.PublicKey)
+        return value;
+    return new web3_js_1.PublicKey(value);
+}
+function toSafeNumber(value, label) {
+    if (value === undefined || value === null) {
+        throw new Error(`Missing ${label} in decoded event`);
+    }
+    const numeric = typeof value === "number" ? value : Number(value);
+    if (!Number.isSafeInteger(numeric)) {
+        throw new Error(`${label} is outside JavaScript's safe integer range`);
+    }
+    return numeric;
+}

package/dist/cjs/events/position.d.ts

@@ -0,0 +1,26 @@
+import type { Idl, Program } from "@coral-xyz/anchor";
+import { PublicKey } from "@solana/web3.js";
+import type { CommitmentEvent } from "./types.js";
+/**
+ * Privacy-pool mints copied from the relayer's global position-tree classifier.
+ * Position commitments use non-pool destination mints at the same tree ID.
+ */
+export declare const POSITION_TREE_POOL_MINTS: readonly PublicKey[];
+export declare function isGlobalPositionCommitment(event: CommitmentEvent): boolean;
+/**
+ * Rebuild the one global position tree shared across every position mint.
+ * This mirrors the relayer: scan all mints for the position tree ID, then drop
+ * normal privacy-pool mint events before sorting by the global leaf index.
+ */
+export declare function buildGlobalPositionTreeFromEvents<T extends Idl>(params: {
+    program: Program<T>;
+    positionTreeId?: number;
+    depth?: number;
+    additionalEvents?: readonly CommitmentEvent[];
+    includeProtectedEvents?: boolean;
+    strictLeafIndices?: boolean;
+}): Promise<{
+    tree: import("../merkle.js").MerkleTree;
+    events: CommitmentEvent[];
+    latestSignature: string;
+}>;