@veilo/sdk-core 0.5.0 → 0.7.0

package/dist/cjs/notes/selection.js

@@ -0,0 +1,260 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_INPUT_NOTES = void 0;
+exports.canonicalTreeId = canonicalTreeId;
+exports.selectNotesForAmount = selectNotesForAmount;
+exports.planNoteConsolidation = planNoteConsolidation;
+const web3_js_1 = require("@solana/web3.js");
+const amount_js_1 = require("./amount.js");
+/**
+ * Choosing which notes to spend.
+ *
+ * Two constraints drive everything here:
+ *
+ *  1. The transaction circuit is 2-in-2-out, so a single transaction can spend
+ *     at most TWO notes.
+ *  2. Notes can only be co-spent if they live in the SAME Merkle tree, and the
+ *     tree is derived from the MINT — see `canonicalTreeId`.
+ */
+/** Inputs the transaction circuit accepts in one proof. */
+exports.MAX_INPUT_NOTES = 2;
+/**
+ * The tree a note belongs to, derived from its mint.
+ *
+ * Mirrors the relayer's `mintAddressToTreeId` byte for byte: the all-zero
+ * native-SOL mint maps to 0, anything else to its first four mint bytes as a
+ * big-endian uint32.
+ *
+ * DERIVE THIS, NEVER TRUST A STORED `treeId`. Change notes are written with the
+ * on-chain shard index (a small 0/1/2…) while deposits and synced notes carry
+ * the mint-derived id. For native SOL both are 0 so the difference hides; for
+ * SPL tokens the two land in different buckets, and co-spending across them
+ * fails at proof time as a commitment mismatch.
+ *
+ * An undecodable mint falls back to the SOL bucket rather than inventing a
+ * phantom tree, matching the server.
+ */
+function canonicalTreeId(mintAddress) {
+    if (!mintAddress || mintAddress.trim() === "")
+        return 0;
+    try {
+        const bytes = new web3_js_1.PublicKey(mintAddress).toBytes();
+        if (bytes.every((byte) => byte === 0))
+            return 0;
+        return (((bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3]) >>> 0);
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Pick notes to cover `amount`, preferring the fewest notes and least change.
+ *
+ * Considers each tree separately, since notes cannot be co-spent across trees,
+ * and returns the best single-tree selection:
+ *
+ *   1. one note that covers the amount (smallest such note, least change);
+ *   2. otherwise the best PAIR, found by a two-pointer scan over the
+ *      amount-sorted notes — O(n) rather than an O(n²) all-pairs search;
+ *   3. otherwise the largest notes greedily, flagged `requiresMerge` because
+ *      more than two inputs cannot go into one proof.
+ *
+ * @param amount base units to cover
+ */
+function selectNotesForAmount(notes, amount, options = {}) {
+    const target = (0, amount_js_1.toBaseUnits)(amount, "amount");
+    if (target <= 0n) {
+        throw new Error(`amount must be positive, got ${target}`);
+    }
+    const wanted = options.mint === undefined ? undefined : canonicalTreeId(options.mint);
+    const byTree = new Map();
+    notes.forEach((note, index) => {
+        const treeId = canonicalTreeId(note.mint);
+        if (wanted !== undefined && treeId !== wanted)
+            return;
+        const entry = {
+            note,
+            amount: (0, amount_js_1.toBaseUnits)(note.amount, `notes[${index}].amount`),
+        };
+        if (entry.amount <= 0n)
+            return;
+        const bucket = byTree.get(treeId);
+        if (bucket)
+            bucket.push(entry);
+        else
+            byTree.set(treeId, [entry]);
+    });
+    if (byTree.size === 0) {
+        return {
+            ok: false,
+            reason: "NO_NOTES",
+            available: 0n,
+            message: "No spendable notes for the requested mint.",
+        };
+    }
+    let best;
+    let available = 0n;
+    for (const [treeId, bucket] of byTree) {
+        const treeTotal = bucket.reduce((sum, entry) => sum + entry.amount, 0n);
+        if (treeTotal > available)
+            available = treeTotal;
+        const selection = selectWithinTree(bucket, target, treeId);
+        if (!selection)
+            continue;
+        if (!best || isBetter(selection, best))
+            best = selection;
+    }
+    if (!best) {
+        return {
+            ok: false,
+            reason: "INSUFFICIENT_FUNDS",
+            available,
+            message: `No single tree holds ${target} base units. Largest tree total is ` +
+                `${available}. Notes in different trees cannot be co-spent.`,
+        };
+    }
+    return best;
+}
+/** Fewer inputs first, then least change. */
+function isBetter(a, b) {
+    if (a.notes.length !== b.notes.length)
+        return a.notes.length < b.notes.length;
+    return a.change < b.change;
+}
+function selectWithinTree(bucket, target, treeId) {
+    // Descending by amount, compared as bigint: Number() would lose precision
+    // above 2^53 base units.
+    const sorted = [...bucket].sort((a, b) => b.amount > a.amount ? 1 : b.amount < a.amount ? -1 : 0);
+    // 1. Smallest single note that covers the target — walk up from the end.
+    let single;
+    for (let i = sorted.length - 1; i >= 0; i--) {
+        if (sorted[i].amount >= target) {
+            single = sorted[i];
+            break;
+        }
+    }
+    if (single) {
+        return {
+            ok: true,
+            notes: [single.note],
+            treeId,
+            total: single.amount,
+            change: single.amount - target,
+            requiresMerge: false,
+        };
+    }
+    // 2. Best pair by two-pointer scan over the descending list.
+    let bestPair;
+    let bestChange = 0n;
+    let lo = 0;
+    let hi = sorted.length - 1;
+    while (lo < hi) {
+        const combined = sorted[lo].amount + sorted[hi].amount;
+        if (combined >= target) {
+            const change = combined - target;
+            if (!bestPair || change < bestChange) {
+                bestChange = change;
+                bestPair = [sorted[lo], sorted[hi]];
+            }
+            lo++;
+        }
+        else {
+            hi--;
+        }
+    }
+    if (bestPair) {
+        return {
+            ok: true,
+            notes: [bestPair[0].note, bestPair[1].note],
+            treeId,
+            total: bestPair[0].amount + bestPair[1].amount,
+            change: bestChange,
+            requiresMerge: false,
+        };
+    }
+    // 3. Greedy over the largest notes. More than two inputs, so it needs a merge.
+    const chosen = [];
+    let total = 0n;
+    for (const entry of sorted) {
+        chosen.push(entry);
+        total += entry.amount;
+        if (total >= target)
+            break;
+    }
+    if (total < target)
+        return undefined;
+    return {
+        ok: true,
+        notes: chosen.map((entry) => entry.note),
+        treeId,
+        total,
+        change: total - target,
+        requiresMerge: chosen.length > exports.MAX_INPUT_NOTES,
+    };
+}
+/**
+ * Plan how to make `amount` spendable when no one or two notes cover it.
+ *
+ * `selectNotesForAmount` reports `requiresMerge` but cannot act on it: the
+ * circuit takes two inputs, so spending five notes means merging them down
+ * first. Each step here is one 2-in-1-out transfer to yourself, and k notes
+ * need k-2 of them before a final two-input spend.
+ *
+ * Merges the two SMALLEST notes each round. That retires dust first and leaves
+ * the large notes untouched, so the plan is short and the final spend has the
+ * least change.
+ *
+ * The plan is pure — it performs nothing. Execute the steps with
+ * `privateTransfer`, feeding each step's output note into the next.
+ */
+function planNoteConsolidation(notes, amount, options = {}) {
+    const target = (0, amount_js_1.toBaseUnits)(amount, "amount");
+    if (target <= 0n) {
+        throw new Error(`amount must be positive, got ${target}`);
+    }
+    const selection = selectNotesForAmount(notes, target, options);
+    if (!selection.ok)
+        return selection;
+    // Already spendable in one transaction.
+    if (!selection.requiresMerge) {
+        return {
+            ok: true,
+            treeId: selection.treeId,
+            steps: [],
+            notes: selection.notes,
+            total: selection.total,
+            change: selection.change,
+        };
+    }
+    // Ascending, so the two cheapest merge first.
+    const pool = selection.notes
+        .map((note, index) => ({
+        kind: "note",
+        note,
+        amount: (0, amount_js_1.toBaseUnits)(note.amount, `notes[${index}].amount`),
+    }))
+        .sort((a, b) => (a.amount > b.amount ? 1 : a.amount < b.amount ? -1 : 0));
+    const steps = [];
+    while (pool.length > exports.MAX_INPUT_NOTES) {
+        const first = pool.shift();
+        const second = pool.shift();
+        const outputAmount = first.amount + second.amount;
+        const step = steps.length + 1;
+        steps.push({ step, inputs: [first, second], outputAmount });
+        const produced = { kind: "step", step, amount: outputAmount };
+        // Keep the pool ordered so the next round still merges the two smallest.
+        const at = pool.findIndex((entry) => entry.amount > outputAmount);
+        if (at === -1)
+            pool.push(produced);
+        else
+            pool.splice(at, 0, produced);
+    }
+    return {
+        ok: true,
+        treeId: selection.treeId,
+        steps,
+        notes: selection.notes,
+        total: selection.total,
+        change: selection.change,
+    };
+}

package/dist/cjs/notes/spent.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Spend status and private balance.
+ *
+ * A note is yours until its nullifier is published; nothing in the note itself
+ * says whether it has been spent. So a balance is always two steps: ask which
+ * nullifiers are spent, then sum what is left. This module is that pair.
+ */
+/** Server-side cap per check-batch request (notes.constants MAX_NULLIFIERS_PER_CHECK). */
+export declare const MAX_NULLIFIERS_PER_CHECK = 200;
+/** Grouping key used for notes that carry no mint. */
+export declare const UNKNOWN_MINT = "unknown";
+/**
+ * Ask the relayer which of these nullifiers are spent.
+ *
+ * Deduplicates, lower-cases, and splits into MAX_NULLIFIERS_PER_CHECK batches
+ * that are issued concurrently. Returns a Set for membership testing; a
+ * nullifier absent from it is unspent as far as the relayer knows.
+ *
+ * @throws if any entry is not 64-char hex — a malformed nullifier that silently
+ *         read as "unspent" would overstate a balance.
+ */
+export declare function checkNullifiersSpent(nullifiers: string[]): Promise<Set<string>>;
+/** The minimum a note must carry to be counted. */
+export interface SpendableNote {
+    /** Base units. bigint preferred; strings and safe integers are accepted. */
+    amount: bigint | string | number;
+    /** 64-character hex nullifier for this note. */
+    nullifier: string;
+    /** Mint this note is denominated in. Groups the result; optional. */
+    mint?: string;
+}
+export interface PrivateBalance<T extends SpendableNote = SpendableNote> {
+    /** Sum of every unspent note, across all mints. */
+    total: bigint;
+    /** Unspent totals keyed by mint (UNKNOWN_MINT when a note carries none). */
+    byMint: Record<string, bigint>;
+    /** The caller's own note objects, partitioned. */
+    unspent: T[];
+    spent: T[];
+}
+export interface PrivateBalanceOptions {
+    /**
+     * Supply spend status yourself instead of asking the relayer — e.g. from a
+     * chain scan of nullifier events, or a local cache. Receives normalized
+     * lower-case hex.
+     */
+    resolveSpent?: (nullifiers: string[]) => Promise<Set<string>> | Set<string>;
+}
+/**
+ * Sum unspent notes, per mint and in total.
+ *
+ * ```ts
+ * const { total, byMint, unspent } = await getPrivateBalance(myNotes);
+ * ```
+ *
+ * Amounts are base units and stay bigint throughout — never sum note amounts as
+ * numbers. Notes are matched to spend status by nullifier, so every note needs
+ * one; the partitioned arrays hand back your own objects, not copies.
+ */
+export declare function getPrivateBalance<T extends SpendableNote>(notes: T[], options?: PrivateBalanceOptions): Promise<PrivateBalance<T>>;

package/dist/cjs/notes/spent.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNKNOWN_MINT = exports.MAX_NULLIFIERS_PER_CHECK = void 0;
+exports.checkNullifiersSpent = checkNullifiersSpent;
+exports.getPrivateBalance = getPrivateBalance;
+const api_js_1 = require("../relayer/api.js");
+const amount_js_1 = require("./amount.js");
+/**
+ * Spend status and private balance.
+ *
+ * A note is yours until its nullifier is published; nothing in the note itself
+ * says whether it has been spent. So a balance is always two steps: ask which
+ * nullifiers are spent, then sum what is left. This module is that pair.
+ */
+/** Server-side cap per check-batch request (notes.constants MAX_NULLIFIERS_PER_CHECK). */
+exports.MAX_NULLIFIERS_PER_CHECK = 200;
+/** Grouping key used for notes that carry no mint. */
+exports.UNKNOWN_MINT = "unknown";
+const HEX64 = /^[0-9a-f]{64}$/;
+/**
+ * Normalize a nullifier to the form the relayer answers in.
+ *
+ * The endpoint's validator is case-INSENSITIVE, but it answers with
+ * `Buffer.toString("hex")` — always lowercase. Sending upper-case hex therefore
+ * returns a `spent` list that never matches what you sent, and every note reads
+ * as unspent. Normalizing here is what makes membership testing sound.
+ */
+function normalizeNullifier(nullifier, index) {
+    const normalized = nullifier.trim().toLowerCase();
+    if (!HEX64.test(normalized)) {
+        throw new Error(`nullifiers[${index}] must be a 64-character hex string, got ` +
+            `${JSON.stringify(nullifier)}`);
+    }
+    return normalized;
+}
+function chunk(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+/**
+ * Ask the relayer which of these nullifiers are spent.
+ *
+ * Deduplicates, lower-cases, and splits into MAX_NULLIFIERS_PER_CHECK batches
+ * that are issued concurrently. Returns a Set for membership testing; a
+ * nullifier absent from it is unspent as far as the relayer knows.
+ *
+ * @throws if any entry is not 64-char hex — a malformed nullifier that silently
+ *         read as "unspent" would overstate a balance.
+ */
+async function checkNullifiersSpent(nullifiers) {
+    const unique = [...new Set(nullifiers.map(normalizeNullifier))];
+    if (unique.length === 0)
+        return new Set();
+    const batches = await Promise.all(chunk(unique, exports.MAX_NULLIFIERS_PER_CHECK).map((batch) => (0, api_js_1.checkNullifiers)(batch)));
+    const spent = new Set();
+    for (const response of batches) {
+        for (const nullifier of response.spent ?? []) {
+            spent.add(nullifier.toLowerCase());
+        }
+    }
+    return spent;
+}
+/**
+ * Sum unspent notes, per mint and in total.
+ *
+ * ```ts
+ * const { total, byMint, unspent } = await getPrivateBalance(myNotes);
+ * ```
+ *
+ * Amounts are base units and stay bigint throughout — never sum note amounts as
+ * numbers. Notes are matched to spend status by nullifier, so every note needs
+ * one; the partitioned arrays hand back your own objects, not copies.
+ */
+async function getPrivateBalance(notes, options = {}) {
+    const normalized = notes.map((note, index) => ({
+        note,
+        amount: (0, amount_js_1.toBaseUnits)(note.amount, `notes[${index}].amount`),
+        nullifier: normalizeNullifier(note.nullifier, index),
+    }));
+    const resolve = options.resolveSpent ?? checkNullifiersSpent;
+    const spentSet = await resolve(normalized.map((entry) => entry.nullifier));
+    const balance = {
+        total: 0n,
+        byMint: {},
+        unspent: [],
+        spent: [],
+    };
+    for (const entry of normalized) {
+        if (spentSet.has(entry.nullifier)) {
+            balance.spent.push(entry.note);
+            continue;
+        }
+        const mint = entry.note.mint ?? exports.UNKNOWN_MINT;
+        balance.unspent.push(entry.note);
+        balance.total += entry.amount;
+        balance.byMint[mint] = (balance.byMint[mint] ?? 0n) + entry.amount;
+    }
+    return balance;
+}

package/dist/cjs/perps/constants.d.ts

@@ -0,0 +1,16 @@
+import type { JperpMarket, JperpMarketPayload, JperpSide } from "./types.js";
+export declare const JUPITER_PERPS_PROGRAM_ID = "PERPHjGBqRHArX4DySjwM6UJHiR3sWAatqfdBS2qQJu";
+export declare const JUPITER_PERPS_EVENT_AUTHORITY = "37hJBDnntwqhGbK7L6M1bLyvccj4u55CCUiLPdYkiqBN";
+export declare const JUPITER_PERPS_POOL = "5BUwFW4nRbftYTDMbgxykoFWqWHPzahFSNAaaaJtVKsq";
+export declare const JUPITER_JLP_MINT = "27G8MtK7VtTcCHkpASjSDdkWWYfoqT6ggEuKidVJidD4";
+export declare const JPERP_USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+export declare const JPERP_NATIVE_SOL_MINT = "11111111111111111111111111111111";
+export declare const JPERP_WRAPPED_SOL_MINT = "So11111111111111111111111111111111111111112";
+export declare const JUPITER_PERPS_CUSTODIES: Record<JperpMarket | "USDC" | "USDT", string>;
+export declare const JUPITER_PERPS_DOVES_ORACLES: Record<JperpMarket, string>;
+export declare const JPERP_LONG_POOL_MINTS: Record<JperpMarket, string>;
+export declare const JPERP_LONG_JUPITER_MINTS: Record<JperpMarket, string>;
+export declare const JPERP_LONG_DECIMALS: Record<JperpMarket, number>;
+export declare const JPERP_USD_DECIMALS = 6;
+/** Resolve the exact market payload duplicated by the wallet-app reference. */
+export declare function getJperpMarketPayload(market: JperpMarket, side: JperpSide): JperpMarketPayload;

package/dist/cjs/perps/constants.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JPERP_USD_DECIMALS = exports.JPERP_LONG_DECIMALS = exports.JPERP_LONG_JUPITER_MINTS = exports.JPERP_LONG_POOL_MINTS = exports.JUPITER_PERPS_DOVES_ORACLES = exports.JUPITER_PERPS_CUSTODIES = exports.JPERP_WRAPPED_SOL_MINT = exports.JPERP_NATIVE_SOL_MINT = exports.JPERP_USDC_MINT = exports.JUPITER_JLP_MINT = exports.JUPITER_PERPS_POOL = exports.JUPITER_PERPS_EVENT_AUTHORITY = exports.JUPITER_PERPS_PROGRAM_ID = void 0;
+exports.getJperpMarketPayload = getJperpMarketPayload;
+exports.JUPITER_PERPS_PROGRAM_ID = "PERPHjGBqRHArX4DySjwM6UJHiR3sWAatqfdBS2qQJu";
+exports.JUPITER_PERPS_EVENT_AUTHORITY = "37hJBDnntwqhGbK7L6M1bLyvccj4u55CCUiLPdYkiqBN";
+exports.JUPITER_PERPS_POOL = "5BUwFW4nRbftYTDMbgxykoFWqWHPzahFSNAaaaJtVKsq";
+exports.JUPITER_JLP_MINT = "27G8MtK7VtTcCHkpASjSDdkWWYfoqT6ggEuKidVJidD4";
+exports.JPERP_USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+exports.JPERP_NATIVE_SOL_MINT = "11111111111111111111111111111111";
+exports.JPERP_WRAPPED_SOL_MINT = "So11111111111111111111111111111111111111112";
+exports.JUPITER_PERPS_CUSTODIES = {
+    SOL: "7xS2gz2bTp3fwCC7knJvUWTEU9Tycczu6VhJYKgi1wdz",
+    ETH: "AQCGyheWPLeo6Qp9WpYS9m3Qj479t7R636N9ey1rEjEn",
+    BTC: "5Pv3gM9JrFFH883SWAhvJC9RPYmo8UNxuFtv5bMMALkm",
+    USDC: "G18jKKXQwBbrHeiK3C9MRXhkHsLHf7XgCSisykV46EZa",
+    USDT: "4vkNeXiYEUizLdrpdPS1eC2mccyM4NUPRtERrk6ZETkk",
+};
+exports.JUPITER_PERPS_DOVES_ORACLES = {
+    SOL: "FYq2BWQ1V5P1WFBqr3qB2Kb5yHVvSv7upzKodgQE5zXh",
+    ETH: "AFZnHPzy4mvVCffrVwhewHbFc93uTHvDSFrVH7GtfXF1",
+    BTC: "hUqAT1KQ7eW1i6Csp9CXYtpPfSAvi835V7wKi5fRfmC",
+};
+exports.JPERP_LONG_POOL_MINTS = {
+    SOL: exports.JPERP_NATIVE_SOL_MINT,
+    ETH: "7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs",
+    BTC: "3NZ9JMVBmGAqocybic2c7LQCJScmgsAZ6vQqTDzcqmJh",
+};
+exports.JPERP_LONG_JUPITER_MINTS = {
+    SOL: exports.JPERP_WRAPPED_SOL_MINT,
+    ETH: exports.JPERP_LONG_POOL_MINTS.ETH,
+    BTC: exports.JPERP_LONG_POOL_MINTS.BTC,
+};
+exports.JPERP_LONG_DECIMALS = {
+    SOL: 9,
+    ETH: 8,
+    BTC: 8,
+};
+exports.JPERP_USD_DECIMALS = 6;
+/** Resolve the exact market payload duplicated by the wallet-app reference. */
+function getJperpMarketPayload(market, side) {
+    const isLong = side === "long";
+    return {
+        custody: exports.JUPITER_PERPS_CUSTODIES[market],
+        collateralCustody: exports.JUPITER_PERPS_CUSTODIES[isLong ? market : "USDC"],
+        inputMint: isLong ? exports.JPERP_LONG_POOL_MINTS[market] : exports.JPERP_USDC_MINT,
+        jupiterInputMint: isLong
+            ? exports.JPERP_LONG_JUPITER_MINTS[market]
+            : exports.JPERP_USDC_MINT,
+        dovesOracle: exports.JUPITER_PERPS_DOVES_ORACLES[market],
+    };
+}

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

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./constants.js";
+export * from "./keys.js";
+export * from "./pdas.js";
+export * from "./relayer.js";

package/dist/cjs/perps/index.js

@@ -0,0 +1,21 @@
+"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("./constants.js"), exports);
+__exportStar(require("./keys.js"), exports);
+__exportStar(require("./pdas.js"), exports);
+__exportStar(require("./relayer.js"), exports);

package/dist/cjs/perps/keys.d.ts

@@ -0,0 +1,16 @@
+import { Keypair } from "@solana/web3.js";
+export interface JperpKeyBundle {
+    withdrawalId: Uint8Array;
+    withdrawalIdHex: string;
+    claimant: Keypair;
+    claimantPublicKey: string;
+    claimantSecretKey: string;
+}
+export declare function deriveJperpWithdrawalId(spendingKey: Uint8Array, index: number): Uint8Array;
+export declare function deriveJperpClaimantKeypair(spendingKey: Uint8Array, withdrawalId: Uint8Array): Keypair;
+export declare function jperpWithdrawalIdToHex(withdrawalId: Uint8Array): string;
+export declare function jperpWithdrawalIdFromHex(value: string): Uint8Array;
+/** Derive every client-held key field needed across the jPerp lifecycle. */
+export declare function deriveJperpKeyBundle(spendingKey: Uint8Array, index: number): JperpKeyBundle;
+/** Match the client reference's per-request Jupiter PDA namespace. */
+export declare function createJperpCounter(): string;

package/dist/cjs/perps/keys.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveJperpWithdrawalId = deriveJperpWithdrawalId;
+exports.deriveJperpClaimantKeypair = deriveJperpClaimantKeypair;
+exports.jperpWithdrawalIdToHex = jperpWithdrawalIdToHex;
+exports.jperpWithdrawalIdFromHex = jperpWithdrawalIdFromHex;
+exports.deriveJperpKeyBundle = deriveJperpKeyBundle;
+exports.createJperpCounter = createJperpCounter;
+const sha256_1 = require("@noble/hashes/sha256");
+const web3_js_1 = require("@solana/web3.js");
+const encoding_js_1 = require("../identity/encoding.js");
+function deriveJperpWithdrawalId(spendingKey, index) {
+    (0, encoding_js_1.assertBytes)(spendingKey, 32, "spending key");
+    return (0, sha256_1.sha256)((0, encoding_js_1.concatBytes)((0, encoding_js_1.utf8)("jperp_withdrawal_v1"), spendingKey, (0, encoding_js_1.uint32Le)(index, "jPerp position index")));
+}
+function deriveJperpClaimantKeypair(spendingKey, withdrawalId) {
+    (0, encoding_js_1.assertBytes)(spendingKey, 32, "spending key");
+    (0, encoding_js_1.assertBytes)(withdrawalId, 32, "jPerp withdrawal ID");
+    return web3_js_1.Keypair.fromSeed((0, sha256_1.sha256)((0, encoding_js_1.concatBytes)((0, encoding_js_1.utf8)("jperp_claimant"), spendingKey, withdrawalId)));
+}
+function jperpWithdrawalIdToHex(withdrawalId) {
+    (0, encoding_js_1.assertBytes)(withdrawalId, 32, "jPerp withdrawal ID");
+    return (0, encoding_js_1.bytesToHex)(withdrawalId);
+}
+function jperpWithdrawalIdFromHex(value) {
+    return (0, encoding_js_1.hexToBytes)(value, 32, "jPerp withdrawal ID");
+}
+/** Derive every client-held key field needed across the jPerp lifecycle. */
+function deriveJperpKeyBundle(spendingKey, index) {
+    const withdrawalId = deriveJperpWithdrawalId(spendingKey, index);
+    const claimant = deriveJperpClaimantKeypair(spendingKey, withdrawalId);
+    return {
+        withdrawalId,
+        withdrawalIdHex: jperpWithdrawalIdToHex(withdrawalId),
+        claimant,
+        claimantPublicKey: claimant.publicKey.toBase58(),
+        claimantSecretKey: (0, encoding_js_1.encodeBase58)(claimant.secretKey),
+    };
+}
+/** Match the client reference's per-request Jupiter PDA namespace. */
+function createJperpCounter() {
+    return String(Math.floor(Math.random() * 1000000000000));
+}

package/dist/cjs/perps/pdas.d.ts

@@ -0,0 +1,29 @@
+import { PublicKey } from "@solana/web3.js";
+import type { JperpSide } from "./types.js";
+export declare const JPERP_SIDE_LONG = 1;
+export declare const JPERP_SIDE_SHORT = 2;
+export declare const JPERP_CHANGE_INCREASE = 1;
+export declare const JPERP_CHANGE_DECREASE = 2;
+export declare function deriveJupiterPerpetualsPda(): PublicKey;
+export declare function deriveJperpExecutorPda(params: {
+    programId: PublicKey;
+    mint: PublicKey;
+    claimant: PublicKey;
+    withdrawalId: Uint8Array;
+}): PublicKey;
+export declare function deriveJperpSlotPda(params: {
+    programId: PublicKey;
+    mint: PublicKey;
+    withdrawalId: Uint8Array;
+}): PublicKey;
+export declare function deriveJupiterPerpPositionPda(params: {
+    executor: PublicKey;
+    custody: PublicKey;
+    collateralCustody: PublicKey;
+    side: JperpSide;
+}): PublicKey;
+export declare function deriveJupiterPerpRequestPda(params: {
+    position: PublicKey;
+    counter: bigint;
+    change: "increase" | "decrease";
+}): PublicKey;

package/dist/cjs/perps/pdas.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JPERP_CHANGE_DECREASE = exports.JPERP_CHANGE_INCREASE = exports.JPERP_SIDE_SHORT = exports.JPERP_SIDE_LONG = void 0;
+exports.deriveJupiterPerpetualsPda = deriveJupiterPerpetualsPda;
+exports.deriveJperpExecutorPda = deriveJperpExecutorPda;
+exports.deriveJperpSlotPda = deriveJperpSlotPda;
+exports.deriveJupiterPerpPositionPda = deriveJupiterPerpPositionPda;
+exports.deriveJupiterPerpRequestPda = deriveJupiterPerpRequestPda;
+const web3_js_1 = require("@solana/web3.js");
+const encoding_js_1 = require("../identity/encoding.js");
+const constants_js_1 = require("./constants.js");
+exports.JPERP_SIDE_LONG = 1;
+exports.JPERP_SIDE_SHORT = 2;
+exports.JPERP_CHANGE_INCREASE = 1;
+exports.JPERP_CHANGE_DECREASE = 2;
+function deriveJupiterPerpetualsPda() {
+    return web3_js_1.PublicKey.findProgramAddressSync([(0, encoding_js_1.utf8)("perpetuals")], new web3_js_1.PublicKey(constants_js_1.JUPITER_PERPS_PROGRAM_ID))[0];
+}
+function deriveJperpExecutorPda(params) {
+    (0, encoding_js_1.assertBytes)(params.withdrawalId, 32, "jPerp withdrawal ID");
+    return web3_js_1.PublicKey.findProgramAddressSync([
+        (0, encoding_js_1.utf8)("jperp_executor"),
+        params.mint.toBytes(),
+        params.claimant.toBytes(),
+        params.withdrawalId,
+    ], params.programId)[0];
+}
+function deriveJperpSlotPda(params) {
+    (0, encoding_js_1.assertBytes)(params.withdrawalId, 32, "jPerp withdrawal ID");
+    return web3_js_1.PublicKey.findProgramAddressSync([(0, encoding_js_1.utf8)("jperp_slot_v1"), params.mint.toBytes(), params.withdrawalId], params.programId)[0];
+}
+function deriveJupiterPerpPositionPda(params) {
+    return web3_js_1.PublicKey.findProgramAddressSync([
+        (0, encoding_js_1.utf8)("position"),
+        params.executor.toBytes(),
+        new web3_js_1.PublicKey(constants_js_1.JUPITER_PERPS_POOL).toBytes(),
+        params.custody.toBytes(),
+        params.collateralCustody.toBytes(),
+        Uint8Array.from([
+            params.side === "long" ? exports.JPERP_SIDE_LONG : exports.JPERP_SIDE_SHORT,
+        ]),
+    ], new web3_js_1.PublicKey(constants_js_1.JUPITER_PERPS_PROGRAM_ID))[0];
+}
+function deriveJupiterPerpRequestPda(params) {
+    return web3_js_1.PublicKey.findProgramAddressSync([
+        (0, encoding_js_1.utf8)("position_request"),
+        params.position.toBytes(),
+        (0, encoding_js_1.uint64Le)(params.counter, "jPerp request counter"),
+        Uint8Array.from([
+            params.change === "increase"
+                ? exports.JPERP_CHANGE_INCREASE
+                : exports.JPERP_CHANGE_DECREASE,
+        ]),
+    ], new web3_js_1.PublicKey(constants_js_1.JUPITER_PERPS_PROGRAM_ID))[0];
+}