@loyal-labs/private-transactions 0.2.7 → 0.2.9

package/dist/src/LoyalPrivateTransactionsClient.d.ts

@@ -1,7 +1,7 @@
 import { Connection, PublicKey } from "@solana/web3.js";
 import { Program } from "@coral-xyz/anchor";
 import type { TelegramPrivateTransfer } from "./idl/telegram_private_transfer.ts";
-import type { WalletLike, ClientConfig, DepositData, UsernameDepositData, InitializeDepositParams, ModifyBalanceParams, ModifyBalanceResult, CreatePermissionParams, CreateUsernamePermissionParams, DelegateDepositParams, DelegateUsernameDepositParams, UndelegateDepositParams, UndelegateUsernameDepositParams, TransferDepositParams, TransferToUsernameDepositParams, InitializeUsernameDepositParams, ClaimUsernameDepositToDepositParams, DelegationStatusResponse } from "./types";
+import type { WalletLike, ClientConfig, DepositData, UsernameDepositData, InitializeDepositParams, CloseDepositParams, CloseUsernameDepositParams, ModifyBalanceParams, ModifyBalanceResult, GetKaminoShieldedBalanceQuoteParams, GetKaminoCollateralSharesForLiquidityAmountParams, KaminoReserveSnapshot, KaminoShieldedBalanceQuote, BuildShieldFlowTransactionPlanParams, BuildShieldTokensTransactionPlanParams, BuildUnshieldTokensTransactionPlanParams, ExecuteShieldFlowTransactionPlanParams, ExecuteShieldTokensTransactionPlanParams, ExecuteUnshieldTokensTransactionPlanParams, EstimateShieldFlowFeeParams, EstimateShieldTokensFeeParams, EstimateUnshieldTokensFeeParams, ShieldFlowExecutionResult, ShieldFlowFeeEstimate, ShieldFlowPlan, ShieldTokensClientParams, UnshieldTokensClientParams, CreatePermissionParams, CreateUsernamePermissionParams, DelegateDepositParams, DelegateUsernameDepositParams, UndelegateDepositParams, UndelegateUsernameDepositParams, TransferDepositParams, TransferToUsernameDepositParams, InitializeUsernameDepositParams, ClaimUsernameDepositToDepositParams, DelegationStatusResponse } from "./types";
 export declare function waitForAccountOwnerChange(connection: Connection, account: PublicKey, expectedOwner: PublicKey, timeoutMs?: number, intervalMs?: number): {
     wait: () => Promise<void>;
     cancel: () => Promise<void>;
@@ -44,11 +44,24 @@ export declare class LoyalPrivateTransactionsClient {
      * Verifies TEE RPC integrity and obtains an auth token automatically.
      */
     static fromConfig(config: ClientConfig): Promise<LoyalPrivateTransactionsClient>;
+    shieldTokens(params: ShieldTokensClientParams): Promise<string>;
+    unshieldTokens(params: UnshieldTokensClientParams): Promise<string>;
+    buildShieldFlowTransactionPlan(params: BuildShieldFlowTransactionPlanParams): Promise<ShieldFlowPlan>;
+    buildShieldTokensTransactionPlan(params: BuildShieldTokensTransactionPlanParams): Promise<ShieldFlowPlan>;
+    buildUnshieldTokensTransactionPlan(params: BuildUnshieldTokensTransactionPlanParams): Promise<ShieldFlowPlan>;
+    estimateShieldFlowFee(params: EstimateShieldFlowFeeParams): Promise<ShieldFlowFeeEstimate>;
+    estimateShieldTokensFee(params: EstimateShieldTokensFeeParams): Promise<ShieldFlowFeeEstimate>;
+    estimateUnshieldTokensFee(params: EstimateUnshieldTokensFeeParams): Promise<ShieldFlowFeeEstimate>;
+    executeShieldFlowTransactionPlan(params: ExecuteShieldFlowTransactionPlanParams): Promise<ShieldFlowExecutionResult>;
+    executeShieldTokensTransactionPlan(params: ExecuteShieldTokensTransactionPlanParams): Promise<ShieldFlowExecutionResult>;
+    executeUnshieldTokensTransactionPlan(params: ExecuteUnshieldTokensTransactionPlanParams): Promise<ShieldFlowExecutionResult>;
     /**
      * Initialize a deposit account for a user and token mint
      */
     initializeDeposit(params: InitializeDepositParams): Promise<string>;
     initializeUsernameDeposit(params: InitializeUsernameDepositParams): Promise<string>;
+    closeDeposit(params: CloseDepositParams): Promise<string>;
+    closeUsernameDeposit(params: CloseUsernameDepositParams): Promise<string>;
     /**
      * Modify the balance of a user's deposit account
      */
@@ -57,7 +70,7 @@ export declare class LoyalPrivateTransactionsClient {
     /**
      * Create a permission for a deposit account (required for PER)
      */
-    createPermission(params: CreatePermissionParams): Promise<string | null>;
+    createPermission(params: CreatePermissionParams): Promise<string>;
     /**
      * Create a permission for a username-based deposit account
      */
@@ -93,23 +106,38 @@ export declare class LoyalPrivateTransactionsClient {
      */
     getBaseDeposit(user: PublicKey, tokenMint: PublicKey): Promise<DepositData | null>;
     getEphemeralDeposit(user: PublicKey, tokenMint: PublicKey): Promise<DepositData | null>;
+    /**
+     * Enumerate every Deposit account owned by a user across both the base
+     * program and the ephemeral program. Used by the wallet UI to discover
+     * shielded holdings even when the user no longer has a matching base-chain
+     * token balance.
+     *
+     * Delegated deposits only exist on the ephemeral chain (on base the PDA is
+     * owned by the delegation program and Anchor cannot deserialize it as a
+     * `Deposit`). Undelegated deposits only exist on base. We query both and
+     * merge by PDA address, preferring the ephemeral amount when both return
+     * an entry because ephemeral reflects the live balance.
+     */
+    getAllDepositsByUser(user: PublicKey): Promise<DepositData[]>;
     /**
      * Get username deposit data
      */
     getBaseUsernameDeposit(username: string, tokenMint: PublicKey): Promise<UsernameDepositData | null>;
     getEphemeralUsernameDeposit(username: string, tokenMint: PublicKey): Promise<UsernameDepositData | null>;
     /**
-     * Find the deposit PDA for a user and token mint
-     */
-    findDepositPda(user: PublicKey, tokenMint: PublicKey): [PublicKey, number];
-    /**
-     * Find the username deposit PDA
-     */
-    findUsernameDepositPda(username: string, tokenMint: PublicKey): [PublicKey, number];
-    /**
-     * Find the vault PDA
+     * Get the live base lending APY for the configured Kamino reserve in basis points.
+     * This is reserve supply APY only and does not include farm reward APY.
+     * Returns null when the token mint has no hardcoded Kamino reserve config.
+     * Devnet reserves intentionally return 0 because the UI APY source is mainnet-only.
      */
-    findVaultPda(tokenMint: PublicKey): [PublicKey, number];
+    getKaminoLendingApyBps(tokenMint: PublicKey): Promise<number | null>;
+    getKaminoReserveSnapshot(tokenMint: PublicKey): Promise<KaminoReserveSnapshot | null>;
+    getKaminoShieldedBalanceQuote(params: GetKaminoShieldedBalanceQuoteParams): Promise<KaminoShieldedBalanceQuote | null>;
+    getKaminoCollateralSharesForLiquidityAmount(params: GetKaminoCollateralSharesForLiquidityAmountParams): Promise<bigint | null>;
+    calculateKaminoCollateralExchangeRateSfFromAmounts(args: {
+        collateralAmountRaw: number | bigint;
+        liquidityAmountRaw: number | bigint;
+    }): bigint | null;
     /**
      * Get the connected wallet's public key
      */
@@ -123,7 +151,6 @@ export declare class LoyalPrivateTransactionsClient {
      * Get the program ID
      */
     getProgramId(): PublicKey;
-    private validateUsername;
     private permissionAccountExists;
     private isAccountAlreadyInUse;
     private ensureNotDelegated;

package/dist/src/actions/shieldTokens.d.ts

@@ -0,0 +1,69 @@
+import { type AccountInfo, type PublicKey, type TransactionInstruction } from "@solana/web3.js";
+import type { FeeEstimateCluster, InstructionCheck, RpcOptions } from "../types";
+import type { TelegramPrivateTransfer } from "../idl/telegram_private_transfer";
+import type { Program } from "@coral-xyz/anchor";
+export type LabeledTransactionInstruction = {
+    label: string;
+    ix: TransactionInstruction;
+    rentLamports?: number;
+    nativeLamports?: number;
+};
+export type LabeledTransactionPlan = {
+    label: string;
+    cluster: FeeEstimateCluster;
+    instructions: LabeledTransactionInstruction[];
+    checks: InstructionCheck[];
+};
+export type ShieldTokensInstructionPlan = {
+    instructions: LabeledTransactionInstruction[];
+    checks: InstructionCheck[];
+    needsUndelegate: boolean;
+    context: {
+        isNativeSol: boolean;
+        validator: PublicKey;
+        depositPda: PublicKey;
+        permissionPda: PublicKey;
+        depositAccountInfo: AccountInfo<Buffer> | null;
+        permissionAccountInfo: AccountInfo<Buffer> | null;
+    };
+};
+export type ShieldTokensTransactionPlan = {
+    preUndelegateTransaction: LabeledTransactionPlan | null;
+    baseTransaction: LabeledTransactionPlan;
+    context: ShieldTokensInstructionPlan["context"];
+};
+export declare function labelTransactionInstructions(prefix: string, instructions: TransactionInstruction[]): LabeledTransactionInstruction[];
+export declare function buildShieldTokensInstructionPlan(params: {
+    user: PublicKey;
+    payer: PublicKey;
+    tokenMint: PublicKey;
+    amount: bigint;
+    baseProgram: Program<TelegramPrivateTransfer>;
+    perProgram: Program<TelegramPrivateTransfer>;
+    validator?: PublicKey;
+}): Promise<ShieldTokensInstructionPlan>;
+export declare function buildShieldTokensTransactionPlan(params: {
+    user: PublicKey;
+    payer: PublicKey;
+    tokenMint: PublicKey;
+    amount: bigint;
+    baseProgram: Program<TelegramPrivateTransfer>;
+    perProgram: Program<TelegramPrivateTransfer>;
+    validator?: PublicKey;
+    sessionToken?: PublicKey | null;
+    magicProgram?: PublicKey;
+    magicContext?: PublicKey;
+}): Promise<ShieldTokensTransactionPlan>;
+export declare function shieldTokens(params: {
+    user: PublicKey;
+    payer: PublicKey;
+    tokenMint: PublicKey;
+    amount: bigint;
+    baseProgram: Program<TelegramPrivateTransfer>;
+    perProgram: Program<TelegramPrivateTransfer>;
+    validator?: PublicKey;
+    sessionToken?: PublicKey | null;
+    magicProgram?: PublicKey;
+    magicContext?: PublicKey;
+    rpcOptions?: RpcOptions;
+}): Promise<string>;

package/dist/src/actions/undelegateDeposit.d.ts

@@ -0,0 +1,25 @@
+import type { Program } from "@coral-xyz/anchor";
+import { type PublicKey, type TransactionInstruction } from "@solana/web3.js";
+import type { InstructionCheck, RpcOptions, UndelegateDepositParams } from "../types";
+import type { TelegramPrivateTransfer } from "../idl/telegram_private_transfer";
+export type PlannedUndelegateDepositTransaction = {
+    label: string;
+    instructions: {
+        ix: TransactionInstruction;
+    }[];
+    checks: InstructionCheck[];
+};
+export declare function sendPlannedUndelegateDepositTransaction(params: {
+    baseProgram: Program<TelegramPrivateTransfer>;
+    perProgram: Program<TelegramPrivateTransfer>;
+    transaction: PlannedUndelegateDepositTransaction;
+    user: PublicKey;
+    tokenMint: PublicKey;
+    rpcOptions?: RpcOptions;
+}): Promise<string>;
+/**
+ * Undelegate a deposit account from the ephemeral rollup.
+ * Waits for both base and ephemeral connections to confirm the deposit
+ * is owned by PROGRAM_ID before returning.
+ */
+export declare function undelegateDeposit(baseProgram: Program<TelegramPrivateTransfer>, perProgram: Program<TelegramPrivateTransfer>, params: UndelegateDepositParams): Promise<string>;

package/dist/src/actions/unshieldTokens.d.ts

@@ -0,0 +1,62 @@
+import { type PublicKey } from "@solana/web3.js";
+import type { Program } from "@coral-xyz/anchor";
+import type { TelegramPrivateTransfer } from "../idl/telegram_private_transfer";
+import type { InstructionCheck, RpcOptions } from "../types";
+import { type LabeledTransactionInstruction, type LabeledTransactionPlan } from "./shieldTokens";
+export type UnshieldTokensInstructionPlan = {
+    instructions: LabeledTransactionInstruction[];
+    checks: InstructionCheck[];
+    needsUndelegate: boolean;
+    shouldRedelegate: boolean;
+    context: {
+        isNativeSol: boolean;
+        validator: PublicKey;
+        depositPda: PublicKey;
+        currentDepositAmount: bigint | null;
+    };
+};
+export type UnshieldTokensTransactionPlan = {
+    preUndelegateTransaction: LabeledTransactionPlan | null;
+    baseTransaction: LabeledTransactionPlan;
+    shouldRedelegate: boolean;
+    context: UnshieldTokensInstructionPlan["context"];
+};
+export declare function buildUnshieldTokensInstructionPlan(params: {
+    user: PublicKey;
+    payer: PublicKey;
+    tokenMint: PublicKey;
+    amount: bigint;
+    baseProgram: Program<TelegramPrivateTransfer>;
+    perProgram: Program<TelegramPrivateTransfer>;
+    validator?: PublicKey;
+}): Promise<UnshieldTokensInstructionPlan>;
+export declare function buildUnshieldTokensTransactionPlan(params: {
+    user: PublicKey;
+    payer: PublicKey;
+    tokenMint: PublicKey;
+    amount: bigint;
+    baseProgram: Program<TelegramPrivateTransfer>;
+    perProgram: Program<TelegramPrivateTransfer>;
+    validator?: PublicKey;
+    sessionToken?: PublicKey | null;
+    magicProgram?: PublicKey;
+    magicContext?: PublicKey;
+}): Promise<UnshieldTokensTransactionPlan>;
+/**
+ * Unshield tokens: move from a Loyal private deposit back to a regular wallet.
+ * If the deposit is delegated, this first commits it back to base, then sends
+ * one base transaction for withdraw/native-SOL close/redelegate.
+ */
+export declare function unshieldTokens(params: {
+    user: PublicKey;
+    payer: PublicKey;
+    tokenMint: PublicKey;
+    amount: bigint;
+    baseProgram: Program<TelegramPrivateTransfer>;
+    perProgram: Program<TelegramPrivateTransfer>;
+    validator?: PublicKey;
+    sessionToken?: PublicKey | null;
+    magicProgram?: PublicKey;
+    magicContext?: PublicKey;
+    rpcOptions?: RpcOptions;
+}): Promise<string>;

package/dist/src/checks/enshureChecks.d.ts

@@ -0,0 +1,5 @@
+import type { AccountInfo, Connection, PublicKey } from "@solana/web3.js";
+import type { InstructionCheck } from "../types";
+export declare function processEnsureChecks(baseConnection: Connection, perConnection: Connection, ensure: InstructionCheck[]): Promise<void>;
+export declare function getMultipleAccountsInfoWithRetry(connection: Connection, accounts: PublicKey[], label: string): Promise<(AccountInfo<Buffer> | null)[]>;
+export declare function runEnsureFetchWithRetry<T>(label: string, task: () => Promise<T>): Promise<T>;

package/dist/src/constants.d.ts

@@ -9,11 +9,26 @@ export declare const ER_VALIDATOR_MAINNET: PublicKey;
  */
 export declare const ER_VALIDATOR: PublicKey;
 export declare function getErValidatorForSolanaEnv(env: string): PublicKey;
-export declare function getErValidatorForRpcEndpoint(rpcEndpoint: string): PublicKey;
+export declare function getErValidatorForRpcEndpoint(perRpcEndpoint: string): PublicKey;
+export declare function getKaminoModifyBalanceAccountsForTokenMint(tokenMint: PublicKey): KaminoModifyBalanceAccounts | null;
 /**
  * Telegram Private Transfer program ID
  */
 export declare const PROGRAM_ID: PublicKey;
+export declare const USDC_MINT_DEVNET: PublicKey;
+export declare const USDC_MINT_MAINNET: PublicKey;
+export declare const KLEND_PROGRAM_ID: PublicKey;
+export interface KaminoModifyBalanceAccounts {
+    lendingMarket: PublicKey;
+    lendingMarketAuthority: PublicKey;
+    reserve: PublicKey;
+    reserveLiquiditySupply: PublicKey;
+    reserveCollateralMint: PublicKey;
+    liquidityDecimals: number;
+    instructionSysvarAccount: PublicKey;
+    klendProgram: PublicKey;
+}
+export declare function isKaminoMainnetModifyBalanceAccounts(accounts: KaminoModifyBalanceAccounts): boolean;
 /**
  * MagicBlock Delegation Program ID
  */
@@ -38,7 +53,7 @@ export declare const DEPOSIT_SEED_BYTES: Buffer<ArrayBuffer>;
 /**
  * PDA seed for username deposit accounts
  */
-export declare const USERNAME_DEPOSIT_SEED = "username_deposit";
+export declare const USERNAME_DEPOSIT_SEED = "username_deposit_v2";
 export declare const USERNAME_DEPOSIT_SEED_BYTES: Buffer<ArrayBuffer>;
 /**
  * PDA seed for vault account

package/dist/src/enumerate-deposits.d.ts

@@ -0,0 +1,23 @@
+import { type Connection, PublicKey } from "@solana/web3.js";
+import type { DepositData } from "./types";
+/**
+ * Enumerate every Deposit account belonging to `user` across the base program
+ * and (optionally) the ephemeral program. Read-only — no signer required.
+ *
+ * Three sources are merged:
+ *   1. Base, owned by the deposit program — undelegated deposits (Anchor).
+ *   2. Base, owned by the delegation program — delegated deposits whose data
+ *      bytes are still readable on base. Required when no authenticated
+ *      ephemeral connection is available (e.g. browser wallet UI).
+ *   3. Ephemeral, owned by the deposit program — delegated deposits with the
+ *      live balance (Anchor). Wins over (2) for the same PDA when present.
+ *
+ * Used by wallet UIs to discover shielded holdings even when the user has no
+ * matching base-chain token balance — e.g. after fully shielding an SPL mint,
+ * where Helius `getAssetsByOwner` no longer surfaces it.
+ */
+export declare function enumerateDepositsByUser(args: {
+    user: PublicKey;
+    baseConnection: Connection;
+    ephemeralConnection?: Connection;
+}): Promise<DepositData[]>;

package/dist/src/fee-estimate.d.ts

@@ -0,0 +1,25 @@
+import { type Commitment, type Connection, type PublicKey, type TransactionInstruction } from "@solana/web3.js";
+import type { FeeEstimateCluster, InstructionCostEstimate, ShieldFlowTransactionFeeEstimate } from "./types";
+export type FeeEstimateInstructionPlan = {
+    label: string;
+    ix: TransactionInstruction;
+    rentLamports?: number;
+    nativeLamports?: number;
+};
+export type FeeEstimateTransactionPlan = {
+    label: string;
+    cluster: FeeEstimateCluster;
+    connection: Connection;
+    feePayer: PublicKey;
+    instructions: FeeEstimateInstructionPlan[];
+};
+export declare function estimatePlannedTransactionFees(params: {
+    transactions: FeeEstimateTransactionPlan[];
+    commitment?: Commitment;
+}): Promise<{
+    transactions: ShieldFlowTransactionFeeEstimate[];
+    instructions: InstructionCostEstimate[];
+    totalFeeLamports: number;
+    totalRentLamports: number;
+    totalNativeLamports: number;
+}>;