@loyal-labs/private-transactions 0.2.7 → 0.2.9

package/README.md

@@ -40,32 +40,11 @@ const client = await LoyalPrivateTransactionsClient.fromConfig({
   commitment: "confirmed",
 });
 
-// Shield: move tokens into private deposit
-await client.initializeDeposit({
+// Shield: move tokens into private deposit in one base transaction
+await client.shieldTokens({
   tokenMint,
   user: signer.publicKey,
-  payer: signer.publicKey,
-});
-
-await client.modifyBalance({
-  tokenMint,
-  user: signer.publicKey,
-  payer: signer.publicKey,
-  userTokenAccount: new PublicKey("<sender-ata>"),
   amount: 1_000_000,
-  increase: true,
-});
-
-await client.createPermission({
-  tokenMint,
-  user: signer.publicKey,
-  payer: signer.publicKey,
-});
-
-await client.delegateDeposit({
-  tokenMint,
-  user: signer.publicKey,
-  payer: signer.publicKey,
   validator: ER_VALIDATOR,
 });
 
@@ -79,24 +58,15 @@ await client.transferToUsernameDeposit({
   sessionToken: null,
 });
 
-// Unshield: commit PER state and withdraw tokens
-await client.undelegateDeposit({
+// Unshield: withdraw from private deposit in one base transaction
+await client.unshieldTokens({
   tokenMint,
   user: signer.publicKey,
-  payer: signer.publicKey,
+  amount: 1_000_000,
   sessionToken: null,
   magicProgram: MAGIC_PROGRAM_ID,
   magicContext: MAGIC_CONTEXT_ID,
 });
-
-await client.modifyBalance({
-  tokenMint,
-  user: signer.publicKey,
-  payer: signer.publicKey,
-  userTokenAccount: new PublicKey("<sender-ata>"),
-  amount: 1_000_000,
-  increase: false,
-});
 ```
 
 ## PER Authentication
@@ -131,11 +101,75 @@ const client = await LoyalPrivateTransactionsClient.fromConfig({
 
 ### Shield / Unshield
 
+- `shieldTokens` — one-transaction base shield flow, with optional pre-undelegate when the deposit is already delegated
+- `unshieldTokens` — one-transaction base unshield flow, with optional pre-undelegate and automatic re-delegate when balance remains
+- `buildShieldFlowTransactionPlan` — create the planned `shield` or `unshield` transactions and instruction metadata once
+- `buildShieldTokensTransactionPlan` / `buildUnshieldTokensTransactionPlan` — explicit shield/unshield plan builders
+- `estimateShieldFlowFee` — estimate transaction-level network fees plus instruction-attributed rent from an existing plan
+- `estimateShieldTokensFee` / `estimateUnshieldTokensFee` — explicit shield/unshield estimators for an existing plan
+- `executeShieldFlowTransactionPlan` — send the exact transactions from an existing plan in order
+- `executeShieldTokensTransactionPlan` / `executeUnshieldTokensTransactionPlan` — explicit shield/unshield executors for an existing plan
 - `initializeDeposit` — create deposit account (no-op if exists)
 - `modifyBalance` — deposit (`increase: true`) or withdraw (`increase: false`) real tokens
 - `createPermission` — set up PER access control (idempotent)
 - `delegateDeposit` — delegate to TEE validator
 
+Fee estimates use Solana's `getFeeForMessage` on the planned transaction
+messages. Instruction rows report net `rentLamports`: positive values are rent
+locked for newly created accounts, negative values are rent reclaimed by close
+or undelegate cleanup. Delegation rent credits are net of MagicBlock's
+undelegate session fee, so undelegation is not a full refund of every lamport
+held by delegation accounts. For native-SOL flows, instruction rows also report
+`nativeLamports` for the shielded/unshielded SOL principal; this is separate
+from protocol fees and rent, but it does affect the payer's SOL balance.
+`feeAndRentLamports` excludes native token principal, while `totalLamports`
+is a cost-style net SOL impact for the common payer=user flow: positive values
+are debits/costs and negative values are credits/gains. If payer differs from
+user, `nativeLamports` belongs to the token owner while fees/rent may belong to
+the payer. Network fees are not attributed per
+instruction because Solana charges them at the transaction/message level. Build
+the plan once and pass the same plan into the estimator so the estimate is tied
+to the exact instructions your app is about to inspect or send. To execute that
+exact plan, pass it to the matching `execute*TransactionPlan` method; it will
+send any pre-undelegate transaction first, wait for the required owner transition
+when the plan includes one, then send the base transaction.
+
+```ts
+const shieldPlan = await client.buildShieldTokensTransactionPlan({
+  user: signer.publicKey,
+  tokenMint,
+  amount: 1_000_000,
+});
+const shieldEstimate = await client.estimateShieldTokensFee({
+  plan: shieldPlan,
+});
+
+const unshieldPlan = await client.buildUnshieldTokensTransactionPlan({
+  user: signer.publicKey,
+  tokenMint,
+  amount: 1_000_000,
+});
+const unshieldEstimate = await client.estimateUnshieldTokensFee({
+  plan: unshieldPlan,
+});
+
+console.log(shieldEstimate.feeAndRentLamports);
+console.log(shieldEstimate.totalLamports);
+console.log(unshieldEstimate.feeAndRentLamports);
+console.log(unshieldEstimate.totalLamports);
+
+const shieldResult = await client.executeShieldTokensTransactionPlan({
+  plan: shieldPlan,
+});
+
+const unshieldResult = await client.executeUnshieldTokensTransactionPlan({
+  plan: unshieldPlan,
+});
+
+console.log(shieldResult.signatures);
+console.log(unshieldResult.signatures);
+```
+
 ### Private Transfers (on PER)
 
 - `transferDeposit` — transfer between user deposits

package/dist/index.d.ts

@@ -31,9 +31,13 @@
  * await client.undelegateDeposit({ user: signer.publicKey, tokenMint, payer: signer.publicKey, sessionToken: null, magicProgram: MAGIC_PROGRAM_ID, magicContext: MAGIC_CONTEXT_ID });
  */
 export { LoyalPrivateTransactionsClient, waitForAccountOwnerChange, } from "./src/LoyalPrivateTransactionsClient";
-export type { WalletSigner, WalletLike, RpcOptions, ClientConfig, DepositData, UsernameDepositData, InitializeDepositParams, ModifyBalanceParams, ModifyBalanceResult, CreatePermissionParams, CreateUsernamePermissionParams, DelegateDepositParams, DelegateUsernameDepositParams, UndelegateDepositParams, UndelegateUsernameDepositParams, TransferDepositParams, TransferToUsernameDepositParams, DelegationRecord, DelegationStatusResult, DelegationStatusResponse, } from "./src/types";
+export { shieldTokens } from "./src/actions/shieldTokens";
+export { unshieldTokens } from "./src/actions/unshieldTokens";
+export { enumerateDepositsByUser } from "./src/enumerate-deposits";
+export type { WalletSigner, WalletLike, RpcOptions, ClientConfig, DepositData, UsernameDepositData, InitializeDepositParams, CloseDepositParams, CloseUsernameDepositParams, ClosePermissionParams, ModifyBalanceParams, ModifyBalanceResult, BuildShieldFlowTransactionPlanParams, BuildShieldTokensTransactionPlanParams, BuildUnshieldTokensTransactionPlanParams, ExecuteShieldFlowTransactionPlanParams, ExecuteShieldTokensTransactionPlanParams, ExecuteUnshieldTokensTransactionPlanParams, ShieldFlowKind, FeeEstimateCluster, EstimateShieldFlowFeeParams, EstimateShieldTokensFeeParams, EstimateUnshieldTokensFeeParams, ShieldFlowInstructionPlan, ShieldFlowOwnerChangeWait, ShieldFlowTransactionPlan, ShieldFlowPlan, InstructionCostEstimate, ShieldFlowTransactionFeeEstimate, ShieldFlowFeeEstimate, ShieldFlowTransactionExecutionResult, ShieldFlowExecutionResult, ShieldTokensClientParams, UnshieldTokensClientParams, GetKaminoShieldedBalanceQuoteParams, GetKaminoCollateralSharesForLiquidityAmountParams, KaminoReserveSnapshot, KaminoTrackedBalanceCostBasis, KaminoPositionYieldInfo, KaminoShieldedBalanceQuote, CreatePermissionParams, CreateUsernamePermissionParams, DelegateDepositParams, DelegateUsernameDepositParams, UndelegateDepositParams, UndelegateUsernameDepositParams, TransferDepositParams, TransferToUsernameDepositParams, DelegationRecord, DelegationStatusResult, DelegationStatusResponse, } from "./src/types";
 export { isKeypair, isAnchorProvider, isWalletLike } from "./src/types";
-export { ER_VALIDATOR, ER_VALIDATOR_DEVNET, ER_VALIDATOR_MAINNET, getErValidatorForSolanaEnv, getErValidatorForRpcEndpoint, PROGRAM_ID, DELEGATION_PROGRAM_ID, PERMISSION_PROGRAM_ID, MAGIC_PROGRAM_ID, MAGIC_CONTEXT_ID, DEPOSIT_SEED, DEPOSIT_SEED_BYTES, USERNAME_DEPOSIT_SEED, USERNAME_DEPOSIT_SEED_BYTES, VAULT_SEED, VAULT_SEED_BYTES, PERMISSION_SEED, PERMISSION_SEED_BYTES, LAMPORTS_PER_SOL, solToLamports, lamportsToSol, } from "./src/constants";
+export { ER_VALIDATOR, ER_VALIDATOR_DEVNET, ER_VALIDATOR_MAINNET, getErValidatorForSolanaEnv, getErValidatorForRpcEndpoint, getKaminoModifyBalanceAccountsForTokenMint, isKaminoMainnetModifyBalanceAccounts, KLEND_PROGRAM_ID, PROGRAM_ID, USDC_MINT_DEVNET, USDC_MINT_MAINNET, DELEGATION_PROGRAM_ID, PERMISSION_PROGRAM_ID, MAGIC_PROGRAM_ID, MAGIC_CONTEXT_ID, DEPOSIT_SEED, DEPOSIT_SEED_BYTES, USERNAME_DEPOSIT_SEED, USERNAME_DEPOSIT_SEED_BYTES, VAULT_SEED, VAULT_SEED_BYTES, PERMISSION_SEED, PERMISSION_SEED_BYTES, LAMPORTS_PER_SOL, solToLamports, lamportsToSol, } from "./src/constants";
+export { calculateKaminoCollateralExchangeRateSfFromAmounts, calculateKaminoCollateralValuation, calculateKaminoRedeemableLiquidityAmountRaw, calculateKaminoShareAmountForLiquidityAmountRaw, fetchKaminoReserveSnapshot, parseKaminoReserveSnapshotFromAccountData, } from "./src/kamino";
 export { findDepositPda, findUsernameDepositPda, findVaultPda, findPermissionPda, findDelegationRecordPda, findDelegationMetadataPda, findBufferPda, } from "./src/pda";
 export declare const IDL: {
     address: string;
@@ -53,6 +57,12 @@ export declare const IDL: {
             writable?: undefined;
             pda?: undefined;
             address?: undefined;
+        } | {
+            name: string;
+            writable: boolean;
+            relations?: undefined;
+            pda?: undefined;
+            address?: undefined;
         } | {
             name: string;
             writable: boolean;
@@ -88,6 +98,66 @@ export declare const IDL: {
             name: string;
             type: string;
         }[];
+    } | {
+        name: string;
+        docs: string[];
+        discriminator: number[];
+        accounts: ({
+            name: string;
+            writable: boolean;
+            signer: boolean;
+            relations: string[];
+            pda?: undefined;
+        } | {
+            name: string;
+            writable: boolean;
+            pda: {
+                seeds: ({
+                    kind: string;
+                    value: number[];
+                    path?: undefined;
+                } | {
+                    kind: string;
+                    path: string;
+                    value?: undefined;
+                })[];
+            };
+            signer?: undefined;
+            relations?: undefined;
+        } | {
+            name: string;
+            relations: string[];
+            writable?: undefined;
+            signer?: undefined;
+            pda?: undefined;
+        })[];
+        args: never[];
+    } | {
+        name: string;
+        docs: string[];
+        discriminator: number[];
+        accounts: ({
+            name: string;
+            writable: boolean;
+            signer: boolean;
+            relations?: undefined;
+        } | {
+            name: string;
+            writable: boolean;
+            signer?: undefined;
+            relations?: undefined;
+        } | {
+            name: string;
+            relations: string[];
+            writable?: undefined;
+            signer?: undefined;
+        } | {
+            name: string;
+            writable?: undefined;
+            signer?: undefined;
+            relations?: undefined;
+        })[];
+        args: never[];
     } | {
         name: string;
         docs: string[];
@@ -235,10 +305,15 @@ export declare const IDL: {
             optional?: undefined;
             pda?: undefined;
         })[];
-        args: {
+        args: ({
+            name: string;
+            type: {
+                array: (string | number)[];
+            };
+        } | {
             name: string;
             type: string;
-        }[];
+        })[];
     } | {
         name: string;
         discriminator: number[];
@@ -279,7 +354,9 @@ export declare const IDL: {
         })[];
         args: {
             name: string;
-            type: string;
+            type: {
+                array: (string | number)[];
+            };
         }[];
         docs?: undefined;
     } | {
@@ -429,6 +506,14 @@ export declare const IDL: {
             signer?: undefined;
             optional?: undefined;
             address?: undefined;
+        } | {
+            name: string;
+            writable: boolean;
+            relations?: undefined;
+            signer?: undefined;
+            optional?: undefined;
+            pda?: undefined;
+            address?: undefined;
         } | {
             name: string;
             address: string;
@@ -552,10 +637,15 @@ export declare const IDL: {
             signer?: undefined;
             pda?: undefined;
         })[];
-        args: {
+        args: ({
+            name: string;
+            type: {
+                array: (string | number)[];
+            };
+        } | {
             name: string;
             type: string;
-        }[];
+        })[];
     })[];
     accounts: {
         name: string;
@@ -568,29 +658,47 @@ export declare const IDL: {
     }[];
     types: ({
         name: string;
-        docs: string[];
         type: {
             kind: string;
-            fields: {
+            fields: ({
                 name: string;
                 type: string;
-            }[];
+            } | {
+                name: string;
+                type: {
+                    array: (string | number)[];
+                    option?: undefined;
+                };
+            } | {
+                name: string;
+                type: {
+                    option: string;
+                    array?: undefined;
+                };
+            })[];
         };
+        docs?: undefined;
     } | {
         name: string;
+        docs: string[];
         type: {
             kind: string;
             fields: ({
+                name: string;
+                type: {
+                    array: (string | number)[];
+                };
+                docs?: undefined;
+            } | {
                 name: string;
                 type: string;
+                docs?: undefined;
             } | {
                 name: string;
-                type: {
-                    option: string;
-                };
+                docs: string[];
+                type: string;
             })[];
         };
-        docs?: undefined;
     })[];
 };
 export type { TelegramPrivateTransfer } from "./src/idl/telegram_private_transfer.ts";