@loyal-labs/private-transactions 0.2.1 → 0.2.3

package/README.md

@@ -1,6 +1,6 @@
 # @loyal-labs/private-transactions
 
-SDK for Telegram-based private SPL token deposits and transfers using MagicBlock Private Ephemeral Rollups (PER). This wraps the `telegram-private-transfer` Anchor program and provides helpers for permissions, delegation, private transfers, and undelegation.
+SDK for private SPL token deposits and transfers using [MagicBlock Private Ephemeral Rollups (PER)](https://docs.magicblock.gg/pages/private-ephemeral-rollups-pers/introduction/authorization). This package wraps the `telegram-private-transfer` Anchor program and provides helpers for permissions, delegation, private transfers, claims, and undelegation.
 
 ## Installation
 
@@ -19,144 +19,162 @@ bun add @coral-xyz/anchor @solana/web3.js @solana/spl-token @magicblock-labs/eph
 ## Quick Start
 
 ```ts
-import { Connection, PublicKey } from "@solana/web3.js";
+import { Keypair, PublicKey } from "@solana/web3.js";
 import {
+  ER_VALIDATOR,
   LoyalPrivateTransactionsClient,
   MAGIC_CONTEXT_ID,
   MAGIC_PROGRAM_ID,
 } from "@loyal-labs/private-transactions";
 
-const connection = new Connection("https://api.devnet.solana.com");
-const client = LoyalPrivateTransactionsClient.from(connection, myKeypair);
-
+const signer = Keypair.fromSecretKey(Uint8Array.from([...secretBytes]));
 const tokenMint = new PublicKey("<mint>");
 
-// Initialize a user deposit
+const client = await LoyalPrivateTransactionsClient.fromConfig({
+  signer,
+  baseRpcEndpoint: "https://api.devnet.solana.com",
+  // Mainnet: https://mainnet-tee.magicblock.app
+  // Devnet: https://tee.magicblock.app
+  ephemeralRpcEndpoint: "https://mainnet-tee.magicblock.app",
+  ephemeralWsEndpoint: "wss://mainnet-tee.magicblock.app",
+  commitment: "confirmed",
+});
+
+// Shield: move tokens into private deposit
 await client.initializeDeposit({
   tokenMint,
-  user: myKeypair.publicKey,
-  payer: myKeypair.publicKey,
+  user: signer.publicKey,
+  payer: signer.publicKey,
 });
 
-// Move tokens into the private deposit vault
 await client.modifyBalance({
   tokenMint,
+  user: signer.publicKey,
+  payer: signer.publicKey,
+  userTokenAccount: new PublicKey("<sender-ata>"),
   amount: 1_000_000,
   increase: true,
-  user: myKeypair.publicKey,
-  payer: myKeypair.publicKey,
 });
 
-// Create permission + delegate deposit to the PER validator
 await client.createPermission({
   tokenMint,
-  user: myKeypair.publicKey,
-  payer: myKeypair.publicKey,
+  user: signer.publicKey,
+  payer: signer.publicKey,
 });
+
 await client.delegateDeposit({
   tokenMint,
-  user: myKeypair.publicKey,
-  payer: myKeypair.publicKey,
-  validator: new PublicKey("<validator>")
+  user: signer.publicKey,
+  payer: signer.publicKey,
+  validator: ER_VALIDATOR,
 });
 
-// Use the PER API for operations on delegated accounts
-const perClient = await LoyalPrivateTransactionsClient.fromEphemeral({
-  signer: myKeypair,
-  rpcEndpoint: "http://127.0.0.1:7799",
-  wsEndpoint: "ws://127.0.0.1:7800",
-});
-
-// Ensure the destination username deposit exists (and is delegated on PER)
-// e.g. via depositForUsername + createUsernamePermission + delegateUsernameDeposit.
-await perClient.transferToUsernameDeposit({
+// Private transfer (on PER) — destination username deposit must already exist and be delegated
+await client.transferToUsernameDeposit({
   tokenMint,
-  username: "alice",
+  username: "alice_user",
   amount: 100_000,
-  user: myKeypair.publicKey,
-  payer: myKeypair.publicKey,
+  user: signer.publicKey,
+  payer: signer.publicKey,
   sessionToken: null,
 });
 
-// Undelegate and commit back to the base chain
-await perClient.undelegateDeposit({
+// Unshield: commit PER state and withdraw tokens
+await client.undelegateDeposit({
   tokenMint,
-  user: myKeypair.publicKey,
-  payer: myKeypair.publicKey,
+  user: signer.publicKey,
+  payer: signer.publicKey,
+  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
 
-When using MagicBlock hosted PER endpoints, you must attach an auth token. The SDK can fetch it automatically.
+For hosted PER endpoints (`tee.magicblock.app`, `mainnet-tee.magicblock.app`), the SDK acquires auth tokens automatically during `fromConfig`.
 
-```ts
-const perClient = await LoyalPrivateTransactionsClient.fromEphemeral({
-  signer: walletAdapter,
-  rpcEndpoint: "https://tee.magicblock.app",
-  wsEndpoint: "wss://tee.magicblock.app",
-  useAuth: true,
-  // If your signer does not expose signMessage, pass authToken or signMessage explicitly.
-  // signMessage: walletAdapter.signMessage,
-});
-```
-
-You can also pre-fetch the token:
+If you need explicit control, fetch the token externally and pass it through `authToken`:
 
 ```ts
-import { getAuthToken } from "@loyal-labs/private-transactions";
+import { getAuthToken } from "@magicblock-labs/ephemeral-rollups-sdk";
 
-const { token } = await getAuthToken(
-  "https://tee.magicblock.app",
+const authToken = await getAuthToken(
+  "https://mainnet-tee.magicblock.app",
   wallet.publicKey,
   wallet.signMessage
 );
 
-const perClient = await LoyalPrivateTransactionsClient.fromEphemeral({
+const client = await LoyalPrivateTransactionsClient.fromConfig({
   signer: wallet,
-  rpcEndpoint: "https://tee.magicblock.app",
-  wsEndpoint: "wss://tee.magicblock.app",
-  authToken: token,
+  baseRpcEndpoint: "https://api.mainnet-beta.solana.com",
+  ephemeralRpcEndpoint: "https://mainnet-tee.magicblock.app",
+  ephemeralWsEndpoint: "wss://mainnet-tee.magicblock.app",
+  authToken,
 });
 ```
 
 ## API Overview
 
-### Factory Methods
-
-- `fromProvider(provider)`
-- `from(connection, signer)`
-- `fromWallet(connection, wallet)`
-- `fromKeypair(connection, keypair)`
-- `fromEphemeral({ signer, rpcEndpoint, wsEndpoint, useAuth, authToken })`
-
-### Core Actions
-
-- `initializeDeposit`
-- `modifyBalance`
-- `depositForUsername`
-- `claimUsernameDeposit`
-- `createPermission`
-- `createUsernamePermission`
-- `delegateDeposit`
-- `delegateUsernameDeposit`
-- `transferDeposit`
-- `transferToUsernameDeposit`
-- `undelegateDeposit`
+### Factory Method
+
+- `fromConfig({ signer, baseRpcEndpoint, ephemeralRpcEndpoint, ... })`
+
+### Shield / Unshield
+
+- `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
+
+### Private Transfers (on PER)
+
+- `transferDeposit` — transfer between user deposits
+- `transferToUsernameDeposit` — transfer to username deposit
+- `claimUsernameDepositToDeposit` — claim from username deposit with verified Telegram session
+
+### Username Deposits
+
+- `initializeUsernameDeposit` — create username deposit account
+- `createUsernamePermission` — PER access control for username deposit
+- `delegateUsernameDeposit` — delegate username deposit to PER
+- `undelegateUsernameDeposit` — commit and undelegate username deposit
+
+### Commit / Undelegate
+
+- `undelegateDeposit` — commit PER state, return deposit to base layer
 - `undelegateUsernameDeposit`
 
 ### Queries
 
-- `getDeposit(user, tokenMint)`
-- `getUsernameDeposit(username, tokenMint)`
+- `getBaseDeposit` / `getEphemeralDeposit`
+- `getBaseUsernameDeposit` / `getEphemeralUsernameDeposit`
+
+### Accessors
+
+- `publicKey`
+- `getBaseProgram()`
+- `getEphemeralProgram()`
+- `getProgramId()`
 
 ### PDA Helpers
 
-- `findDepositPda(user, tokenMint)`
-- `findUsernameDepositPda(username, tokenMint)`
-- `findVaultPda(tokenMint)`
+- `findDepositPda`
+- `findUsernameDepositPda`
+- `findVaultPda`
+- `findPermissionPda`
+- `findDelegationRecordPda`
+- `findDelegationMetadataPda`
+- `findBufferPda`
 
 ## Development
 

package/dist/index.d.ts

@@ -5,37 +5,32 @@
  * MagicBlock's Private Ephemeral Rollups (PER) for confidential transactions.
  *
  * @example
- * // Base layer client for setup operations
- * import { LoyalPrivateTransactionsClient } from '@loyal-labs/private-transactions';
- * import { Connection, Keypair } from '@solana/web3.js';
+ * // Create one client that has base + ephemeral program access
+ * import { Keypair, PublicKey } from "@solana/web3.js";
+ * import {
+ *   ER_VALIDATOR,
+ *   LoyalPrivateTransactionsClient,
+ *   MAGIC_CONTEXT_ID,
+ *   MAGIC_PROGRAM_ID,
+ * } from "@loyal-labs/private-transactions";
  *
- * const connection = new Connection('https://api.devnet.solana.com');
- * const client = LoyalPrivateTransactionsClient.from(connection, keypair);
+ * const signer = Keypair.fromSecretKey(Uint8Array.from([...secretBytes]));
+ * const tokenMint = new PublicKey("<token-mint>");
  *
- * // Initialize and fund deposit
- * await client.initializeDeposit({ user, tokenMint, payer });
- * await client.modifyBalance({ user, tokenMint, amount, increase: true, ... });
- *
- * // Create permission and delegate to ephemeral rollup
- * await client.createPermission({ user, tokenMint, payer });
- * await client.delegateDeposit({ user, tokenMint, payer, validator });
- *
- * @example
- * // Ephemeral rollup client for private operations
- * const ephemeralClient = await LoyalPrivateTransactionsClient.fromEphemeral({
- *   signer: keypair,
- *   rpcEndpoint: 'http://localhost:7799',
- *   wsEndpoint: 'ws://localhost:7800',
+ * const client = await LoyalPrivateTransactionsClient.fromConfig({
+ *   signer,
+ *   baseRpcEndpoint: "https://api.devnet.solana.com",
+ *   ephemeralRpcEndpoint: "https://mainnet-tee.magicblock.app",
+ *   ephemeralWsEndpoint: "wss://mainnet-tee.magicblock.app",
  * });
  *
- * // Execute private transfer
- * await ephemeralClient.transferToUsernameDeposit({ username, tokenMint, amount, ... });
- *
- * // Commit and undelegate
- * await ephemeralClient.undelegateDeposit({ user, tokenMint, ... });
+ * await client.createPermission({ user: signer.publicKey, tokenMint, payer: signer.publicKey });
+ * await client.delegateDeposit({ user: signer.publicKey, tokenMint, payer: signer.publicKey, validator: ER_VALIDATOR });
+ * await client.transferToUsernameDeposit({ username: "alice_user", tokenMint, amount: 100_000, user: signer.publicKey, payer: signer.publicKey, sessionToken: null });
+ * 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, DepositForUsernameParams, ClaimUsernameDepositParams, CreatePermissionParams, CreateUsernamePermissionParams, DelegateDepositParams, DelegateUsernameDepositParams, UndelegateDepositParams, UndelegateUsernameDepositParams, TransferDepositParams, TransferToUsernameDepositParams, DelegationRecord, DelegationStatusResult, DelegationStatusResponse, } from "./src/types";
+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 { isKeypair, isAnchorProvider, isWalletLike } from "./src/types";
 export { ER_VALIDATOR, 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 { findDepositPda, findUsernameDepositPda, findVaultPda, findPermissionPda, findDelegationRecordPda, findDelegationMetadataPda, findBufferPda, } from "./src/pda";
@@ -51,94 +46,6 @@ export declare const IDL: {
         name: string;
         docs: string[];
         discriminator: number[];
-        accounts: ({
-            name: string;
-            writable: boolean;
-            pda?: undefined;
-            relations?: undefined;
-            address?: undefined;
-        } | {
-            name: string;
-            writable: boolean;
-            pda: {
-                seeds: ({
-                    kind: string;
-                    value: number[];
-                    path?: undefined;
-                } | {
-                    kind: string;
-                    path: string;
-                    value?: undefined;
-                })[];
-                program?: undefined;
-            };
-            relations?: undefined;
-            address?: undefined;
-        } | {
-            name: string;
-            writable: boolean;
-            pda: {
-                seeds: ({
-                    kind: string;
-                    path: string;
-                    value?: undefined;
-                } | {
-                    kind: string;
-                    value: number[];
-                    path?: undefined;
-                })[];
-                program: {
-                    kind: string;
-                    value: number[];
-                };
-            };
-            relations?: undefined;
-            address?: undefined;
-        } | {
-            name: string;
-            writable: boolean;
-            pda: {
-                seeds: ({
-                    kind: string;
-                    value: number[];
-                    path?: undefined;
-                    account?: undefined;
-                } | {
-                    kind: string;
-                    path: string;
-                    account: string;
-                    value?: undefined;
-                })[];
-                program?: undefined;
-            };
-            relations?: undefined;
-            address?: undefined;
-        } | {
-            name: string;
-            relations: string[];
-            writable?: undefined;
-            pda?: undefined;
-            address?: undefined;
-        } | {
-            name: string;
-            writable?: undefined;
-            pda?: undefined;
-            relations?: undefined;
-            address?: undefined;
-        } | {
-            name: string;
-            address: string;
-            writable?: undefined;
-            pda?: undefined;
-            relations?: undefined;
-        })[];
-        args: {
-            name: string;
-            type: string;
-        }[];
-    } | {
-        name: string;
-        discriminator: number[];
         accounts: ({
             name: string;
             relations: string[];
@@ -180,7 +87,6 @@ export declare const IDL: {
             name: string;
             type: string;
         }[];
-        docs?: undefined;
     } | {
         name: string;
         docs: string[];
@@ -332,76 +238,6 @@ export declare const IDL: {
             name: string;
             type: string;
         }[];
-    } | {
-        name: string;
-        docs: string[];
-        discriminator: number[];
-        accounts: ({
-            name: string;
-            writable: boolean;
-            signer: boolean;
-            pda?: undefined;
-            address?: undefined;
-        } | {
-            name: string;
-            writable: boolean;
-            pda: {
-                seeds: ({
-                    kind: string;
-                    value: number[];
-                    path?: undefined;
-                } | {
-                    kind: string;
-                    path: string;
-                    value?: undefined;
-                })[];
-                program?: undefined;
-            };
-            signer?: undefined;
-            address?: undefined;
-        } | {
-            name: string;
-            writable: boolean;
-            pda: {
-                seeds: ({
-                    kind: string;
-                    path: string;
-                    value?: undefined;
-                } | {
-                    kind: string;
-                    value: number[];
-                    path?: undefined;
-                })[];
-                program: {
-                    kind: string;
-                    value: number[];
-                };
-            };
-            signer?: undefined;
-            address?: undefined;
-        } | {
-            name: string;
-            writable: boolean;
-            signer?: undefined;
-            pda?: undefined;
-            address?: undefined;
-        } | {
-            name: string;
-            writable?: undefined;
-            signer?: undefined;
-            pda?: undefined;
-            address?: undefined;
-        } | {
-            name: string;
-            address: string;
-            writable?: undefined;
-            signer?: undefined;
-            pda?: undefined;
-        })[];
-        args: {
-            name: string;
-            type: string;
-        }[];
     } | {
         name: string;
         discriminator: number[];