@shuffle-protocol/sdk 0.1.0

package/dist/cli/output.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Terminal Output Utilities
+ *
+ * Provides spinners, colorized output, and formatted displays
+ * for an impressive terminal UX.
+ */
+import { Ora } from "ora";
+/**
+ * Create a spinner with Shuffle branding
+ */
+export declare function createSpinner(text: string): Ora;
+/**
+ * Run an async operation with a spinner
+ */
+export declare function withSpinner<T>(text: string, operation: () => Promise<T>, successMessage?: string): Promise<T>;
+/**
+ * Show a multi-step progress spinner
+ */
+export declare function createProgressSpinner(steps: string[]): {
+    start: () => void;
+    nextStep: () => void;
+    succeed: (message?: string) => void;
+    fail: (message?: string) => void;
+};
+/**
+ * Print a section header
+ */
+export declare function printHeader(title: string): void;
+/**
+ * Print balance table showing shielded and unshielded balances side-by-side
+ * If pendingPayout is provided, add it to the relevant asset in a different color
+ */
+export declare function printBalanceTable(shielded: {
+    usdc: bigint;
+    tsla: bigint;
+    spy: bigint;
+    aapl: bigint;
+}, unshielded?: {
+    usdc: bigint;
+    tsla: bigint;
+    spy: bigint;
+    aapl: bigint;
+}, pendingPayout?: {
+    amount: bigint;
+    assetId: number;
+} | null): void;
+/**
+ * Print order status
+ */
+export declare function printOrderStatus(order: {
+    batchId: number;
+    pairId: number;
+    direction: number;
+    amount: bigint;
+} | null): void;
+/**
+ * Print batch status
+ */
+export declare function printBatchStatus(batch: {
+    batchId: number;
+    orderCount: number;
+}): void;
+/**
+ * Print transaction success with explorer link
+ */
+export declare function printTxSuccess(signature: string, network: "devnet" | "localnet"): void;
+/**
+ * Print error message
+ */
+export declare function printError(message: string): void;
+/**
+ * Print info message
+ */
+export declare function printInfo(message: string): void;
+/**
+ * Print success message
+ */
+export declare function printSuccess(message: string): void;
+/**
+ * Print mock mode warning
+ */
+export declare function printMockWarning(): void;
+/**
+ * Print batch history table
+ */
+export declare function printBatchHistory(logs: Array<{
+    batchId: number;
+    results: Array<{
+        totalAIn: {
+            toString: () => string;
+        };
+        totalBIn: {
+            toString: () => string;
+        };
+        finalPoolA: {
+            toString: () => string;
+        };
+        finalPoolB: {
+            toString: () => string;
+        };
+    }>;
+}>): void;

package/dist/cli/output.js

@@ -0,0 +1,251 @@
+"use strict";
+/**
+ * Terminal Output Utilities
+ *
+ * Provides spinners, colorized output, and formatted displays
+ * for an impressive terminal UX.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSpinner = createSpinner;
+exports.withSpinner = withSpinner;
+exports.createProgressSpinner = createProgressSpinner;
+exports.printHeader = printHeader;
+exports.printBalanceTable = printBalanceTable;
+exports.printOrderStatus = printOrderStatus;
+exports.printBatchStatus = printBatchStatus;
+exports.printTxSuccess = printTxSuccess;
+exports.printError = printError;
+exports.printInfo = printInfo;
+exports.printSuccess = printSuccess;
+exports.printMockWarning = printMockWarning;
+exports.printBatchHistory = printBatchHistory;
+const ora_1 = __importDefault(require("ora"));
+const chalk_1 = __importDefault(require("chalk"));
+// ============================================================================
+// Spinner Helpers
+// ============================================================================
+/**
+ * Create a spinner with Shuffle branding
+ */
+function createSpinner(text) {
+    return (0, ora_1.default)({
+        text: chalk_1.default.cyan(text),
+        spinner: "dots",
+        color: "cyan",
+    });
+}
+/**
+ * Run an async operation with a spinner
+ */
+async function withSpinner(text, operation, successMessage) {
+    const spinner = createSpinner(text);
+    spinner.start();
+    try {
+        const result = await operation();
+        spinner.succeed(chalk_1.default.green(successMessage || text + " ✓"));
+        return result;
+    }
+    catch (error) {
+        // Just stop the spinner, let the caller handle error display
+        spinner.stop();
+        throw error;
+    }
+}
+/**
+ * Show a multi-step progress spinner
+ */
+function createProgressSpinner(steps) {
+    let currentStep = 0;
+    const spinner = createSpinner(steps[0]);
+    return {
+        start: () => spinner.start(),
+        nextStep: () => {
+            currentStep++;
+            if (currentStep < steps.length) {
+                spinner.text = chalk_1.default.cyan(steps[currentStep]);
+            }
+        },
+        succeed: (msg) => spinner.succeed(chalk_1.default.green(msg || "Complete ✓")),
+        fail: (msg) => spinner.fail(chalk_1.default.red(msg || "Failed")),
+    };
+}
+// ============================================================================
+// Formatted Output
+// ============================================================================
+/**
+ * Print a section header
+ */
+function printHeader(title) {
+    console.log();
+    console.log(chalk_1.default.bold.cyan(`🃏 ${title}`));
+    console.log(chalk_1.default.gray("─".repeat(40)));
+}
+/**
+ * Print balance table showing shielded and unshielded balances side-by-side
+ * If pendingPayout is provided, add it to the relevant asset in a different color
+ */
+function printBalanceTable(shielded, unshielded, pendingPayout) {
+    printHeader("Your Balances");
+    const format = (val) => {
+        const num = Number(val) / 1000000; // 6 decimals
+        // Use more decimal places for small values to avoid showing 0.00 for non-zero amounts
+        if (num === 0) {
+            return "0.00";
+        }
+        else if (num < 0.01) {
+            return num.toLocaleString("en-US", { minimumFractionDigits: 6, maximumFractionDigits: 6 });
+        }
+        else if (num < 1) {
+            return num.toLocaleString("en-US", { minimumFractionDigits: 4, maximumFractionDigits: 4 });
+        }
+        return num.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+    };
+    const pad = (str, len) => str.padStart(len);
+    // Map asset IDs to keys: 0=USDC, 1=TSLA, 2=SPY, 3=AAPL
+    const assetKeys = ['usdc', 'tsla', 'spy', 'aapl'];
+    if (unshielded) {
+        // Show both shielded and unshielded
+        console.log(chalk_1.default.gray("  Token      🔒 Shielded      🔓 Unshielded"));
+        console.log();
+        const printRow = (token, color, assetId, shieldedVal, unshieldedVal) => {
+            const hasPending = pendingPayout && pendingPayout.assetId === assetId && pendingPayout.amount > 0n;
+            const effectiveBalance = hasPending ? shieldedVal + pendingPayout.amount : shieldedVal;
+            let shieldedStr;
+            if (hasPending) {
+                // Show effective balance in cyan to indicate pending payout included
+                shieldedStr = chalk_1.default.cyan(pad(format(effectiveBalance), 12));
+            }
+            else {
+                shieldedStr = chalk_1.default.white(pad(format(shieldedVal), 12));
+            }
+            const unshieldedStr = pad(format(unshieldedVal), 14);
+            console.log(`  ${color(token.padEnd(5))}  │ ${shieldedStr}   │ ${chalk_1.default.gray(unshieldedStr)}`);
+        };
+        printRow("USDC", chalk_1.default.yellow, 0, shielded.usdc, unshielded.usdc);
+        printRow("TSLA", chalk_1.default.magenta, 1, shielded.tsla, unshielded.tsla);
+        printRow("SPY", chalk_1.default.blue, 2, shielded.spy, unshielded.spy);
+        printRow("AAPL", chalk_1.default.green, 3, shielded.aapl, unshielded.aapl);
+    }
+    else {
+        // Original format (shielded only)
+        console.log(`  ${chalk_1.default.yellow("USDC")}: ${chalk_1.default.white(format(shielded.usdc))}`);
+        console.log(`  ${chalk_1.default.magenta("TSLA")}: ${chalk_1.default.white(format(shielded.tsla))}`);
+        console.log(`  ${chalk_1.default.blue("SPY")}:  ${chalk_1.default.white(format(shielded.spy))}`);
+        console.log(`  ${chalk_1.default.green("AAPL")}: ${chalk_1.default.white(format(shielded.aapl))}`);
+    }
+    console.log();
+}
+/**
+ * Print order status
+ */
+function printOrderStatus(order) {
+    if (!order) {
+        console.log(chalk_1.default.gray("  No pending order"));
+        return;
+    }
+    const pairLabels = ["TSLA/USDC", "SPY/USDC", "AAPL/USDC", "TSLA/SPY", "TSLA/AAPL", "SPY/AAPL"];
+    const directionLabel = order.direction === 0 ? chalk_1.default.green("BUY") : chalk_1.default.red("SELL");
+    const amount = (Number(order.amount) / 1000000).toLocaleString();
+    console.log(`  Batch:     ${chalk_1.default.cyan(order.batchId)}`);
+    console.log(`  Pair:      ${chalk_1.default.white(pairLabels[order.pairId] || "Unknown")}`);
+    console.log(`  Direction: ${directionLabel}`);
+    console.log(`  Amount:    ${chalk_1.default.white(amount)}`);
+}
+/**
+ * Print batch status
+ */
+function printBatchStatus(batch) {
+    console.log(`  Batch ID:     ${chalk_1.default.cyan(batch.batchId)}`);
+    console.log(`  Order Count:  ${chalk_1.default.white(batch.orderCount)}`);
+}
+/**
+ * Print transaction success with explorer link
+ */
+function printTxSuccess(signature, network) {
+    console.log();
+    console.log(chalk_1.default.green("✓ Transaction confirmed"));
+    if (network === "devnet") {
+        const url = `https://explorer.solana.com/tx/${signature}?cluster=devnet`;
+        console.log(chalk_1.default.gray(`  View: ${chalk_1.default.underline(url)}`));
+    }
+    else {
+        // Localnet: use custom RPC URL in explorer
+        const customUrl = encodeURIComponent("http://localhost:8899");
+        const url = `https://explorer.solana.com/tx/${signature}?cluster=custom&customUrl=${customUrl}`;
+        console.log(chalk_1.default.gray(`  View: ${chalk_1.default.underline(url)}`));
+    }
+    console.log();
+}
+/**
+ * Print error message
+ */
+function printError(message) {
+    console.log();
+    console.log(chalk_1.default.red(`✗ Error: ${message}`));
+    console.log();
+}
+/**
+ * Print info message
+ */
+function printInfo(message) {
+    console.log(chalk_1.default.cyan(`ℹ ${message}`));
+}
+/**
+ * Print success message
+ */
+function printSuccess(message) {
+    console.log(chalk_1.default.green(`✓ ${message}`));
+}
+/**
+ * Print mock mode warning
+ */
+function printMockWarning() {
+    console.log(chalk_1.default.yellow("⚠ Running in mock mode - no blockchain interaction"));
+}
+/**
+ * Print batch history table
+ */
+function printBatchHistory(logs) {
+    printHeader("Batch History");
+    if (logs.length === 0) {
+        console.log(chalk_1.default.gray("  No executed batches found."));
+        console.log(chalk_1.default.gray("  Batches are executed when 8+ orders accumulate."));
+        console.log();
+        return;
+    }
+    const pairLabels = ["TSLA/USDC", "SPY/USDC", "AAPL/USDC", "TSLA/SPY", "TSLA/AAPL", "SPY/AAPL"];
+    const format = (val) => {
+        const num = Number(val) / 1000000; // 6 decimals
+        if (num === 0)
+            return chalk_1.default.gray("-");
+        return num.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+    };
+    for (const log of logs) {
+        console.log();
+        console.log(chalk_1.default.bold.white(`  Batch #${log.batchId}`));
+        console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+        // Check if there was any activity
+        let hasActivity = false;
+        for (let i = 0; i < log.results.length; i++) {
+            const r = log.results[i];
+            const totalAIn = r.totalAIn.toString();
+            const totalBIn = r.totalBIn.toString();
+            if (totalAIn !== "0" || totalBIn !== "0") {
+                hasActivity = true;
+                const [baseAsset, quoteAsset] = pairLabels[i].split("/");
+                console.log(`    ${chalk_1.default.cyan(pairLabels[i])}:`);
+                console.log(`      ${chalk_1.default.gray("Inflow")}  ${baseAsset}: ${format(totalAIn)}  ${quoteAsset}: ${format(totalBIn)}`);
+                console.log(`      ${chalk_1.default.gray("Pool")}    A: ${format(r.finalPoolA.toString())}  B: ${format(r.finalPoolB.toString())}`);
+            }
+        }
+        if (!hasActivity) {
+            console.log(chalk_1.default.gray("    No trading activity"));
+        }
+    }
+    console.log();
+    console.log(chalk_1.default.gray(`  Total batches executed: ${logs.length}`));
+    console.log();
+}

package/dist/client.d.ts

@@ -0,0 +1,121 @@
+import { Program } from "@coral-xyz/anchor";
+import { PublicKey } from "@solana/web3.js";
+import { RescueCipher } from "@arcium-hq/client";
+import { AssetId, PairId, Direction } from "./constants";
+import type { ShuffleConfig, UserBalance, OrderInfo, DecryptedOrderInfo, BatchInfo, BatchResult, EstimatedPayout, EffectiveBalance } from "./types";
+export declare class ShuffleClient {
+    private connection;
+    private wallet;
+    private programId;
+    private provider;
+    private program;
+    private mxePublicKey;
+    private clusterOffset;
+    private clusterAccount;
+    private poolPDA;
+    private batchAccumulatorPDA;
+    private cipher;
+    private encryptionPublicKey;
+    private constructor();
+    /** Async factory — creates and initializes the client */
+    static create(config: ShuffleConfig): Promise<ShuffleClient>;
+    private initialize;
+    /** Get the MXE public key (needed for cipher creation) */
+    getMXEPublicKey(): Uint8Array;
+    /** Get the underlying Anchor program */
+    getProgram(): Program<any>;
+    /**
+     * Initialize encryption from a user's x25519 private key.
+     * Creates the cipher and derives the public key.
+     * Call this after create() to enable encrypted operations.
+     */
+    initEncryption(privateKey: Uint8Array): void;
+    /** Get the encryption public key (available after initEncryption) */
+    getEncryptionPublicKey(): Uint8Array | null;
+    /** Get the cipher (available after initEncryption) */
+    getCipher(): RescueCipher | null;
+    private _requireEncryption;
+    /** Create a new user privacy account. Uses internal encryption if initialized. */
+    createUserAccount(encryptionPublicKey?: Uint8Array): Promise<string>;
+    /** Fetch UserProfile data for an owner */
+    fetchUserAccount(owner?: PublicKey): Promise<any>;
+    /** Check if account exists */
+    accountExists(owner?: PublicKey): Promise<boolean>;
+    /** Deposit tokens into the protocol (add_balance). Uses internal encryption if params omitted. */
+    deposit(assetId: AssetId, amount: number, cipher?: RescueCipher, encryptionPublicKey?: Uint8Array): Promise<string>;
+    /** Withdraw tokens from the protocol (sub_balance). Uses internal encryption if params omitted. */
+    withdraw(assetId: AssetId, amount: number, cipher?: RescueCipher, encryptionPublicKey?: Uint8Array): Promise<string>;
+    /** Decrypt all 4 asset balances from on-chain account. Uses internal cipher if param omitted. */
+    getBalance(cipher?: RescueCipher, owner?: PublicKey): Promise<UserBalance>;
+    /** Get unshielded (normal SPL token) balances from wallet */
+    getUnshieldedBalances(owner?: PublicKey): Promise<UserBalance>;
+    /** Internal P2P transfer (USDC only). Uses internal encryption if params omitted. */
+    transfer(recipientPubkey: PublicKey, amount: number, cipher?: RescueCipher, encryptionPublicKey?: Uint8Array): Promise<string>;
+    /**
+     * Initialize batch state with encrypted zeros.
+     * This must be called before the first order of each new batch.
+     * After batch execution, the batch state needs to be re-initialized for the next batch.
+     */
+    initBatchState(): Promise<string>;
+    /**
+     * Place an encrypted order in the current batch.
+     * Automatically initializes batch state if needed (first order of a new batch).
+     * Uses internal encryption if params omitted.
+     */
+    placeOrder(pairId: PairId, direction: Direction, amount: number, sourceAssetId: AssetId, cipher?: RescueCipher, encryptionPublicKey?: Uint8Array): Promise<string>;
+    /** Get current pending order info, or null */
+    getPendingOrder(owner?: PublicKey): Promise<OrderInfo | null>;
+    /**
+     * Get decrypted pending order info.
+     * Decrypts pairId, direction, and amount using user's cipher.
+     * The order nonce is stored on-chain, so no need to save it locally.
+     *
+     * @param cipher - Optional cipher (uses internal if omitted)
+     * @param owner - Optional owner pubkey (uses wallet if omitted)
+     */
+    getDecryptedOrder(cipher?: RescueCipher, owner?: PublicKey): Promise<DecryptedOrderInfo | null>;
+    /** Cancel pending order — not yet implemented */
+    cancelOrder(): Promise<never>;
+    /** Execute the current batch when 8+ orders are accumulated. Anyone can call this. */
+    executeBatch(): Promise<string>;
+    /** Settle a pending order after batch execution. Uses internal encryption if param omitted. */
+    settleOrder(pairId: number, direction: number, encryptionPublicKey?: Uint8Array): Promise<string>;
+    /** Fetch current batch accumulator state */
+    getBatchInfo(): Promise<BatchInfo>;
+    /** Fetch historical batch log */
+    getBatchLog(batchId: number): Promise<BatchResult>;
+    /**
+     * Fetch all historical batch logs.
+     * Iterates from batch 1 to the current batch ID and returns all found logs.
+     * @returns Array of BatchResult for all executed batches
+     */
+    getAllBatchLogs(): Promise<BatchResult[]>;
+    /**
+     * Estimate payout for a pending order after batch execution.
+     * Uses client-side calculation: payout = (orderAmount / totalInput) * finalPoolOutput
+     *
+     * @param cipher - Optional cipher (uses internal if omitted)
+     * @param owner - Optional owner pubkey (uses wallet if omitted)
+     * @returns EstimatedPayout or null if no pending order or batch not executed
+     */
+    estimatePayout(cipher?: RescueCipher, owner?: PublicKey): Promise<EstimatedPayout | null>;
+    /**
+     * Get effective balance for an asset, including pending payout.
+     * Combines current on-chain balance with estimated payout from pending order.
+     *
+     * @param assetId - Asset to check (0=USDC, 1=TSLA, 2=SPY, 3=AAPL)
+     * @param cipher - Optional cipher (uses internal if omitted)
+     * @param owner - Optional owner pubkey (uses wallet if omitted)
+     * @returns EffectiveBalance with current, pending, and total
+     */
+    getEffectiveBalance(assetId: AssetId, cipher?: RescueCipher, owner?: PublicKey): Promise<EffectiveBalance>;
+    /**
+     * Helper to determine output asset ID based on pair and direction
+     */
+    private _getOutputAssetId;
+    /** Fetch pool account data */
+    getPoolInfo(): Promise<any>;
+    private _getArciumAccounts;
+    private _awaitComputation;
+    private _generateComputationOffset;
+}