@loyal-labs/private-transactions 0.2.7 → 0.2.9

package/dist/src/idl/telegram_private_transfer.d.ts

@@ -38,44 +38,88 @@ export type TelegramPrivateTransfer = {
                 {
                     "name": "sourceUsernameDeposit";
                     "writable": true;
+                },
+                {
+                    "name": "destinationDeposit";
+                    "writable": true;
                     "pda": {
                         "seeds": [
                             {
                                 "kind": "const";
                                 "value": [
-                                    117,
-                                    115,
-                                    101,
-                                    114,
-                                    110,
-                                    97,
-                                    109,
-                                    101,
-                                    95,
                                     100,
                                     101,
                                     112,
                                     111,
                                     115,
                                     105,
-                                    116
+                                    116,
+                                    95,
+                                    118,
+                                    50
                                 ];
                             },
                             {
                                 "kind": "account";
-                                "path": "source_username_deposit.username";
-                                "account": "usernameDeposit";
+                                "path": "destination_deposit.user";
+                                "account": "deposit";
                             },
                             {
                                 "kind": "account";
-                                "path": "source_username_deposit.token_mint";
-                                "account": "usernameDeposit";
+                                "path": "destination_deposit.token_mint";
+                                "account": "deposit";
                             }
                         ];
                     };
                 },
                 {
-                    "name": "destinationDeposit";
+                    "name": "tokenMint";
+                    "relations": [
+                        "sourceUsernameDeposit",
+                        "destinationDeposit"
+                    ];
+                },
+                {
+                    "name": "session";
+                },
+                {
+                    "name": "tokenProgram";
+                    "address": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+                }
+            ];
+            "args": [
+                {
+                    "name": "amount";
+                    "type": "u64";
+                }
+            ];
+        },
+        {
+            "name": "closeDeposit";
+            "docs": [
+                "Closes an empty user deposit account and returns its rent to the deposit owner."
+            ];
+            "discriminator": [
+                200,
+                19,
+                254,
+                192,
+                15,
+                110,
+                209,
+                179
+            ];
+            "accounts": [
+                {
+                    "name": "user";
+                    "writable": true;
+                    "signer": true;
+                    "relations": [
+                        "deposit"
+                    ];
+                },
+                {
+                    "name": "deposit";
                     "writable": true;
                     "pda": {
                         "seeds": [
@@ -96,13 +140,11 @@ export type TelegramPrivateTransfer = {
                             },
                             {
                                 "kind": "account";
-                                "path": "destination_deposit.user";
-                                "account": "deposit";
+                                "path": "user";
                             },
                             {
                                 "kind": "account";
-                                "path": "destination_deposit.token_mint";
-                                "account": "deposit";
+                                "path": "tokenMint";
                             }
                         ];
                     };
@@ -110,24 +152,48 @@ export type TelegramPrivateTransfer = {
                 {
                     "name": "tokenMint";
                     "relations": [
-                        "sourceUsernameDeposit",
-                        "destinationDeposit"
+                        "deposit"
                     ];
+                }
+            ];
+            "args": [];
+        },
+        {
+            "name": "closeUsernameDeposit";
+            "docs": [
+                "Closes an empty username deposit account after verified username ownership."
+            ];
+            "discriminator": [
+                238,
+                181,
+                185,
+                209,
+                149,
+                161,
+                124,
+                79
+            ];
+            "accounts": [
+                {
+                    "name": "authority";
+                    "writable": true;
+                    "signer": true;
                 },
                 {
-                    "name": "session";
+                    "name": "deposit";
+                    "writable": true;
                 },
                 {
-                    "name": "tokenProgram";
-                    "address": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
-                }
-            ];
-            "args": [
+                    "name": "tokenMint";
+                    "relations": [
+                        "deposit"
+                    ];
+                },
                 {
-                    "name": "amount";
-                    "type": "u64";
+                    "name": "session";
                 }
             ];
+            "args": [];
         },
         {
             "name": "createPermission";
@@ -228,41 +294,6 @@ export type TelegramPrivateTransfer = {
                 },
                 {
                     "name": "deposit";
-                    "pda": {
-                        "seeds": [
-                            {
-                                "kind": "const";
-                                "value": [
-                                    117,
-                                    115,
-                                    101,
-                                    114,
-                                    110,
-                                    97,
-                                    109,
-                                    101,
-                                    95,
-                                    100,
-                                    101,
-                                    112,
-                                    111,
-                                    115,
-                                    105,
-                                    116
-                                ];
-                            },
-                            {
-                                "kind": "account";
-                                "path": "deposit.username";
-                                "account": "usernameDeposit";
-                            },
-                            {
-                                "kind": "account";
-                                "path": "deposit.token_mint";
-                                "account": "usernameDeposit";
-                            }
-                        ];
-                    };
                 },
                 {
                     "name": "session";
@@ -673,12 +704,15 @@ export type TelegramPrivateTransfer = {
                                     111,
                                     115,
                                     105,
-                                    116
+                                    116,
+                                    95,
+                                    118,
+                                    50
                                 ];
                             },
                             {
                                 "kind": "arg";
-                                "path": "username";
+                                "path": "usernameHash";
                             },
                             {
                                 "kind": "arg";
@@ -702,8 +736,13 @@ export type TelegramPrivateTransfer = {
             ];
             "args": [
                 {
-                    "name": "username";
-                    "type": "string";
+                    "name": "usernameHash";
+                    "type": {
+                        "array": [
+                            "u8",
+                            32
+                        ];
+                    };
                 },
                 {
                     "name": "tokenMint";
@@ -824,12 +863,15 @@ export type TelegramPrivateTransfer = {
                                     111,
                                     115,
                                     105,
-                                    116
+                                    116,
+                                    95,
+                                    118,
+                                    50
                                 ];
                             },
                             {
                                 "kind": "arg";
-                                "path": "username";
+                                "path": "usernameHash";
                             },
                             {
                                 "kind": "account";
@@ -852,18 +894,33 @@ export type TelegramPrivateTransfer = {
             ];
             "args": [
                 {
-                    "name": "username";
-                    "type": "string";
+                    "name": "usernameHash";
+                    "type": {
+                        "array": [
+                            "u8",
+                            32
+                        ];
+                    };
                 }
             ];
         },
         {
             "name": "modifyBalance";
             "docs": [
-                "Modifies the balance of a user's deposit account by transferring tokens in or out.",
+                "Modifies a user's deposit balance and the backing vault position for the given mint.",
+                "",
+                "For non-USDC mints, this is a direct vault transfer: if `args.increase` is true, `args.amount`",
+                "is transferred from the user's token account to the vault token account and added to",
+                "`deposit.amount`. If false, `args.amount` is transferred from the vault token account back to",
+                "the user's token account and subtracted from `deposit.amount`.",
                 "",
-                "If `args.increase` is true, tokens are transferred from the user's token account to the deposit account.",
-                "If false, tokens are transferred from the deposit account back to the user's token account."
+                "For USDC, liquidity is routed through Kamino Lending instead of being left idle in the vault.",
+                "If `args.increase` is true, `args.amount` USDC is transferred into the vault token account,",
+                "supplied to the configured Kamino reserve, and `deposit.amount` is increased by the Kamino",
+                "reserve collateral shares (kTokens) minted to the vault. If false, `args.amount` is",
+                "interpreted as the Kamino share amount to redeem; the reserve returns the corresponding USDC",
+                "at the current exchange rate, that USDC is transferred from the vault token account to the",
+                "user's token account, and `deposit.amount` is decreased by the burned share amount."
             ];
             "discriminator": [
                 148,
@@ -1378,41 +1435,6 @@ export type TelegramPrivateTransfer = {
                 {
                     "name": "destinationDeposit";
                     "writable": true;
-                    "pda": {
-                        "seeds": [
-                            {
-                                "kind": "const";
-                                "value": [
-                                    117,
-                                    115,
-                                    101,
-                                    114,
-                                    110,
-                                    97,
-                                    109,
-                                    101,
-                                    95,
-                                    100,
-                                    101,
-                                    112,
-                                    111,
-                                    115,
-                                    105,
-                                    116
-                                ];
-                            },
-                            {
-                                "kind": "account";
-                                "path": "destination_deposit.username";
-                                "account": "usernameDeposit";
-                            },
-                            {
-                                "kind": "account";
-                                "path": "destination_deposit.token_mint";
-                                "account": "usernameDeposit";
-                            }
-                        ];
-                    };
                 },
                 {
                     "name": "tokenMint";
@@ -1554,12 +1576,15 @@ export type TelegramPrivateTransfer = {
                                     111,
                                     115,
                                     105,
-                                    116
+                                    116,
+                                    95,
+                                    118,
+                                    50
                                 ];
                             },
                             {
                                 "kind": "arg";
-                                "path": "username";
+                                "path": "usernameHash";
                             },
                             {
                                 "kind": "arg";
@@ -1580,8 +1605,13 @@ export type TelegramPrivateTransfer = {
             ];
             "args": [
                 {
-                    "name": "username";
-                    "type": "string";
+                    "name": "usernameHash";
+                    "type": {
+                        "array": [
+                            "u8",
+                            32
+                        ];
+                    };
                 },
                 {
                     "name": "tokenMint";
@@ -1717,6 +1747,21 @@ export type TelegramPrivateTransfer = {
             "code": 6011;
             "name": "invalidDepositor";
             "msg": "Invalid Depositor";
+        },
+        {
+            "code": 6012;
+            "name": "invalidKaminoAccounts";
+            "msg": "Invalid Kamino accounts";
+        },
+        {
+            "code": 6013;
+            "name": "invalidAmount";
+            "msg": "Invalid amount";
+        },
+        {
+            "code": 6014;
+            "name": "nonZeroDeposit";
+            "msg": "Deposit account must have zero amount before it can be closed";
         }
     ];
     "types": [
@@ -1738,6 +1783,10 @@ export type TelegramPrivateTransfer = {
                     },
                     {
                         "name": "amount";
+                        "docs": [
+                            "For USDC deposits, this stores the Kamino share token amount.",
+                            "For all other mints, this stores the deposited liquidity token amount."
+                        ];
                         "type": "u64";
                     }
                 ];
@@ -1793,8 +1842,13 @@ export type TelegramPrivateTransfer = {
                         "type": "pubkey";
                     },
                     {
-                        "name": "username";
-                        "type": "string";
+                        "name": "usernameHash";
+                        "type": {
+                            "array": [
+                                "u8",
+                                32
+                            ];
+                        };
                     },
                     {
                         "name": "validationBytes";
@@ -1820,16 +1874,19 @@ export type TelegramPrivateTransfer = {
         {
             "name": "usernameDeposit";
             "docs": [
-                "A deposit account for a telegram username and token mint.",
-                "",
-                "Telegram username is always lowercase (a-z, 0-9 and underscores)"
+                "A deposit account for a telegram username sha256 hash and token mint."
             ];
             "type": {
                 "kind": "struct";
                 "fields": [
                     {
-                        "name": "username";
-                        "type": "string";
+                        "name": "usernameHash";
+                        "type": {
+                            "array": [
+                                "u8",
+                                32
+                            ];
+                        };
                     },
                     {
                         "name": "tokenMint";
@@ -1837,6 +1894,10 @@ export type TelegramPrivateTransfer = {
                     },
                     {
                         "name": "amount";
+                        "docs": [
+                            "For USDC deposits, this stores the Kamino share token amount.",
+                            "For all other mints, this stores the deposited liquidity token amount."
+                        ];
                         "type": "u64";
                     }
                 ];

package/dist/src/instructions/closeDeposit.d.ts

@@ -0,0 +1,4 @@
+import type { Program } from "@coral-xyz/anchor";
+import type { CheckedTransactionInstruction, CloseDepositParams } from "../types";
+import type { TelegramPrivateTransfer } from "../idl/telegram_private_transfer";
+export declare function closeDepositIx(program: Program<TelegramPrivateTransfer>, params: CloseDepositParams): Promise<CheckedTransactionInstruction>;

package/dist/src/instructions/closePermission.d.ts

@@ -0,0 +1,2 @@
+import type { CheckedTransactionInstruction, ClosePermissionParams } from "../types";
+export declare function closePermissionIx(params: ClosePermissionParams): Promise<CheckedTransactionInstruction>;

package/dist/src/instructions/closeUsernameDeposit.d.ts

@@ -0,0 +1,4 @@
+import type { Program } from "@coral-xyz/anchor";
+import type { CheckedTransactionInstruction, CloseUsernameDepositParams } from "../types";
+import type { TelegramPrivateTransfer } from "../idl/telegram_private_transfer";
+export declare function closeUsernameDepositIx(program: Program<TelegramPrivateTransfer>, params: CloseUsernameDepositParams): Promise<CheckedTransactionInstruction>;

package/dist/src/instructions/createPermission.d.ts

@@ -0,0 +1,4 @@
+import type { Program } from "@coral-xyz/anchor";
+import type { TelegramPrivateTransfer } from "../idl/telegram_private_transfer";
+import type { CheckedTransactionInstruction, CreatePermissionParams } from "../types";
+export declare function createPermissionIx(program: Program<TelegramPrivateTransfer>, params: CreatePermissionParams): Promise<CheckedTransactionInstruction>;

package/dist/src/instructions/delegateDeposit.d.ts

@@ -0,0 +1,4 @@
+import type { Program } from "@coral-xyz/anchor";
+import type { CheckedTransactionInstruction, DelegateDepositParams } from "../types";
+import type { TelegramPrivateTransfer } from "../idl/telegram_private_transfer";
+export declare function delegateDepositIx(program: Program<TelegramPrivateTransfer>, params: DelegateDepositParams): Promise<CheckedTransactionInstruction>;

package/dist/src/instructions/initializeDeposit.d.ts

@@ -0,0 +1,4 @@
+import type { Program } from "@coral-xyz/anchor";
+import type { TelegramPrivateTransfer } from "../idl/telegram_private_transfer";
+import type { CheckedTransactionInstruction, InitializeDepositParams } from "../types";
+export declare function initializeDepositIx(program: Program<TelegramPrivateTransfer>, params: InitializeDepositParams): Promise<CheckedTransactionInstruction>;

package/dist/src/instructions/initializeUsernameDeposit.d.ts

@@ -0,0 +1,4 @@
+import type { Program } from "@coral-xyz/anchor";
+import type { CheckedTransactionInstruction, InitializeUsernameDepositParams } from "../types";
+import type { TelegramPrivateTransfer } from "../idl/telegram_private_transfer";
+export declare function initializeUsernameDepositIx(program: Program<TelegramPrivateTransfer>, params: InitializeUsernameDepositParams): Promise<CheckedTransactionInstruction>;

package/dist/src/instructions/modifyBalance.d.ts

@@ -0,0 +1,4 @@
+import { type Program } from "@coral-xyz/anchor";
+import type { CheckedTransactionInstruction, ModifyBalanceParams } from "../types";
+import type { TelegramPrivateTransfer } from "../idl/telegram_private_transfer";
+export declare function modifyBalanceIx(program: Program<TelegramPrivateTransfer>, params: ModifyBalanceParams): Promise<CheckedTransactionInstruction>;

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

@@ -0,0 +1,4 @@
+import type { Program } from "@coral-xyz/anchor";
+import type { TelegramPrivateTransfer } from "../idl/telegram_private_transfer";
+import type { CheckedTransactionInstruction, UndelegateDepositParams } from "../types";
+export declare function undelegateDepositIx(perProgram: Program<TelegramPrivateTransfer>, params: UndelegateDepositParams): Promise<CheckedTransactionInstruction>;

package/dist/src/instructions/undelegatePermission.d.ts

@@ -0,0 +1,2 @@
+import type { CheckedTransactionInstruction, UndelegatePermissionParams } from "../types";
+export declare function undelegatePermissionIx(params: UndelegatePermissionParams): Promise<CheckedTransactionInstruction>;

package/dist/src/kamino.d.ts

@@ -0,0 +1,44 @@
+import { Connection, PublicKey } from "@solana/web3.js";
+import { type KaminoModifyBalanceAccounts } from "./constants";
+import type { KaminoPositionYieldInfo, KaminoReserveSnapshot } from "./types";
+export declare function parseKaminoReserveSnapshotFromAccountData(args: {
+    data: Buffer | Uint8Array;
+    reserve: PublicKey;
+    tokenMint: PublicKey;
+}): KaminoReserveSnapshot;
+export declare function calculateKaminoRedeemableLiquidityAmountRaw(snapshot: KaminoReserveSnapshot, shareAmountRaw: bigint | number): bigint;
+export declare function calculateKaminoShareAmountForLiquidityAmountRaw(args: {
+    snapshot: KaminoReserveSnapshot;
+    liquidityAmountRaw: bigint | number;
+    rounding?: "floor" | "ceil";
+}): bigint;
+export declare function calculateKaminoTrackedLiquidityCostBasisRaw(args: {
+    currentShareAmountRaw: bigint | number;
+    trackedShareAmountRaw?: bigint | number | null;
+    trackedLiquidityAmountRaw?: bigint | number | null;
+}): bigint | null;
+export declare function calculateKaminoCollateralExchangeRateSfFromAmounts(args: {
+    collateralAmount: bigint | number;
+    liquidityAmount: bigint | number;
+}): bigint | null;
+export declare function calculateKaminoCollateralValuation(args: {
+    snapshot: KaminoReserveSnapshot;
+    collateralAmount: bigint | number;
+    principalLiquidityAmount?: bigint | number | null;
+    shieldCollateralExchangeRateSf?: bigint | number | null;
+}): {
+    currentLiquidityAmount: bigint;
+    principalLiquidityAmount: bigint | null;
+    earnedLiquidityAmount: bigint | null;
+};
+export declare function calculateKaminoPositionYieldInfoFromSnapshot(args: {
+    snapshot: KaminoReserveSnapshot;
+    shareAmountRaw: bigint | number;
+    trackedShareAmountRaw?: bigint | number | null;
+    trackedLiquidityAmountRaw?: bigint | number | null;
+}): KaminoPositionYieldInfo;
+export declare function fetchKaminoReserveSnapshot(args: {
+    connection: Connection;
+    tokenMint: PublicKey;
+    kaminoAccounts?: KaminoModifyBalanceAccounts;
+}): Promise<KaminoReserveSnapshot | null>;

package/dist/src/pda.d.ts

@@ -16,7 +16,7 @@ export declare function findDepositPda(user: PublicKey, tokenMint: PublicKey, pr
  * @param programId - Optional program ID (defaults to PROGRAM_ID)
  * @returns [PDA address, bump seed]
  */
-export declare function findUsernameDepositPda(username: string, tokenMint: PublicKey, programId?: PublicKey): [PublicKey, number];
+export declare function findUsernameDepositPda(username: string, tokenMint: PublicKey, programId?: PublicKey): Promise<[PublicKey, number]>;
 /**
  * Derive the vault PDA
  *

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

@@ -0,0 +1,46 @@
+import type { Connection, PublicKey } from "@solana/web3.js";
+export declare const MAGICBLOCK_UNDELEGATE_SESSION_FEE_LAMPORTS = 300000;
+export declare const DEPOSIT_ACCOUNT_SIZE: number;
+export declare const VAULT_ACCOUNT_SIZE: number;
+export declare const PERMISSION_ACCOUNT_SIZE = 567;
+export declare const DELEGATION_RECORD_ACCOUNT_SIZE: number;
+export type RentAccountEstimate = {
+    address: PublicKey;
+    space: number;
+    forceCreate?: boolean;
+};
+export declare function estimateNewAccountRentLamports(params: {
+    connection: Connection;
+    accounts: RentAccountEstimate[];
+}): Promise<number>;
+export declare function estimateExistingAccountLamports(params: {
+    connection: Connection;
+    accounts: PublicKey[];
+}): Promise<number>;
+export declare function estimateDepositRentLamports(params: {
+    connection: Connection;
+    depositPda: PublicKey;
+    forceCreate?: boolean;
+}): Promise<number>;
+export declare function estimateModifyBalanceRentLamports(params: {
+    connection: Connection;
+    user: PublicKey;
+    tokenMint: PublicKey;
+    isNativeSol: boolean;
+}): Promise<number>;
+export declare function estimatePermissionRentLamports(params: {
+    connection: Connection;
+    permissionPda: PublicKey;
+    forceCreate?: boolean;
+}): Promise<number>;
+export declare function estimateDepositDelegationRentLamports(params: {
+    connection: Connection;
+    user: PublicKey;
+    tokenMint: PublicKey;
+    depositPda: PublicKey;
+    forceCreate?: boolean;
+}): Promise<number>;
+export declare function estimateDepositDelegationRentCreditLamports(params: {
+    connection: Connection;
+    depositPda: PublicKey;
+}): Promise<number>;

package/dist/src/transaction-debug.d.ts

@@ -0,0 +1,40 @@
+import { Connection, Transaction, type Signer } from "@solana/web3.js";
+import type { Provider } from "@coral-xyz/anchor";
+import type { RpcOptions } from "./types";
+export declare function logFailedTransactionDiagnostics(params: {
+    label: string;
+    connection: Connection;
+    tx: Transaction;
+    error: unknown;
+    extraContext?: Record<string, unknown>;
+}): Promise<void>;
+/**
+ * Sign, broadcast, and verify a transaction while keeping the
+ * signature in hand across confirmation hiccups.
+ *
+ * The previous implementation delegated to `provider.sendAndConfirm`,
+ * which in turn called `connection.confirmTransaction({signature,
+ * blockhash, lastValidBlockHeight})`. With Seeker / Seed Vault the
+ * user may spend 5–30s between tapping our preview sheet and
+ * biometric-confirming on device; by the time Anchor starts its
+ * confirmation poll, the RPC node's poll window has often lapsed and
+ * `confirmTransaction` throws `TransactionExpiredBlockheightExceeded`
+ * — even though the tx is on chain and has moved funds. Anchor
+ * re-throws and the signature is lost, so callers surface "Shield
+ * failed" on what was actually a success.
+ *
+ * We handle the send + confirm ourselves:
+ *   1. Stamp blockhash + fee payer, sign via the provider's wallet.
+ *   2. Broadcast via `sendRawTransaction` — we now own the signature.
+ *   3. Poll `getSignatureStatuses` until landed / failed / dropped.
+ * This keeps real failures loud while immunizing callers from the
+ * "on-chain but our poll timed out" race.
+ */
+export declare function sendAndConfirmWithDiagnostics(params: {
+    label: string;
+    provider: Provider;
+    tx: Transaction;
+    signers?: Signer[];
+    rpcOptions?: RpcOptions;
+    extraContext?: Record<string, unknown>;
+}): Promise<string>;