@loyal-labs/private-transactions 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.md +167 -0
  2. package/dist/index.d.ts +759 -0
  3. package/dist/index.js +22830 -0
  4. package/dist/src/LoyalPrivateTransactionsClient.d.ts +139 -0
  5. package/dist/src/constants.d.ts +58 -0
  6. package/dist/src/idl/telegram_private_transfer.d.ts +2230 -0
  7. package/dist/src/idl.d.ts +1751 -0
  8. package/dist/src/pda.d.ts +59 -0
  9. package/dist/src/types.d.ts +254 -0
  10. package/dist/src/wallet-adapter.d.ts +31 -0
  11. package/package.json +63 -0
package/README.md ADDED
@@ -0,0 +1,167 @@
1
+ # @loyal-labs/private-transactions
2
+
3
+ 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.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ bun add @loyal-labs/private-transactions
9
+ # or
10
+ npm install @loyal-labs/private-transactions
11
+ ```
12
+
13
+ ### Peer Dependencies
14
+
15
+ ```bash
16
+ bun add @coral-xyz/anchor @solana/web3.js @solana/spl-token @magicblock-labs/ephemeral-rollups-sdk
17
+ ```
18
+
19
+ ## Quick Start
20
+
21
+ ```ts
22
+ import { Connection, PublicKey } from "@solana/web3.js";
23
+ import {
24
+ LoyalPrivateTransactionsClient,
25
+ MAGIC_CONTEXT_ID,
26
+ MAGIC_PROGRAM_ID,
27
+ } from "@loyal-labs/private-transactions";
28
+
29
+ const connection = new Connection("https://api.devnet.solana.com");
30
+ const client = LoyalPrivateTransactionsClient.from(connection, myKeypair);
31
+
32
+ const tokenMint = new PublicKey("<mint>");
33
+
34
+ // Initialize a user deposit
35
+ await client.initializeDeposit({
36
+ tokenMint,
37
+ user: myKeypair.publicKey,
38
+ payer: myKeypair.publicKey,
39
+ });
40
+
41
+ // Move tokens into the private deposit vault
42
+ await client.modifyBalance({
43
+ tokenMint,
44
+ amount: 1_000_000,
45
+ increase: true,
46
+ user: myKeypair.publicKey,
47
+ payer: myKeypair.publicKey,
48
+ });
49
+
50
+ // Create permission + delegate deposit to the PER validator
51
+ await client.createPermission({
52
+ tokenMint,
53
+ user: myKeypair.publicKey,
54
+ payer: myKeypair.publicKey,
55
+ });
56
+ await client.delegateDeposit({
57
+ tokenMint,
58
+ user: myKeypair.publicKey,
59
+ payer: myKeypair.publicKey,
60
+ validator: new PublicKey("<validator>")
61
+ });
62
+
63
+ // Use the PER API for operations on delegated accounts
64
+ const perClient = await LoyalPrivateTransactionsClient.fromEphemeral({
65
+ signer: myKeypair,
66
+ rpcEndpoint: "http://127.0.0.1:7799",
67
+ wsEndpoint: "ws://127.0.0.1:7800",
68
+ });
69
+
70
+ // Ensure the destination username deposit exists (and is delegated on PER)
71
+ // e.g. via depositForUsername + createUsernamePermission + delegateUsernameDeposit.
72
+ await perClient.transferToUsernameDeposit({
73
+ tokenMint,
74
+ username: "alice",
75
+ amount: 100_000,
76
+ user: myKeypair.publicKey,
77
+ payer: myKeypair.publicKey,
78
+ sessionToken: null,
79
+ });
80
+
81
+ // Undelegate and commit back to the base chain
82
+ await perClient.undelegateDeposit({
83
+ tokenMint,
84
+ user: myKeypair.publicKey,
85
+ payer: myKeypair.publicKey,
86
+ magicProgram: MAGIC_PROGRAM_ID,
87
+ magicContext: MAGIC_CONTEXT_ID,
88
+ });
89
+ ```
90
+
91
+ ## PER Authentication
92
+
93
+ When using MagicBlock hosted PER endpoints, you must attach an auth token. The SDK can fetch it automatically.
94
+
95
+ ```ts
96
+ const perClient = await LoyalPrivateTransactionsClient.fromEphemeral({
97
+ signer: walletAdapter,
98
+ rpcEndpoint: "https://tee.magicblock.app",
99
+ wsEndpoint: "wss://tee.magicblock.app",
100
+ useAuth: true,
101
+ // If your signer does not expose signMessage, pass authToken or signMessage explicitly.
102
+ // signMessage: walletAdapter.signMessage,
103
+ });
104
+ ```
105
+
106
+ You can also pre-fetch the token:
107
+
108
+ ```ts
109
+ import { getAuthToken } from "@loyal-labs/private-transactions";
110
+
111
+ const { token } = await getAuthToken(
112
+ "https://tee.magicblock.app",
113
+ wallet.publicKey,
114
+ wallet.signMessage
115
+ );
116
+
117
+ const perClient = await LoyalPrivateTransactionsClient.fromEphemeral({
118
+ signer: wallet,
119
+ rpcEndpoint: "https://tee.magicblock.app",
120
+ wsEndpoint: "wss://tee.magicblock.app",
121
+ authToken: token,
122
+ });
123
+ ```
124
+
125
+ ## API Overview
126
+
127
+ ### Factory Methods
128
+
129
+ - `fromProvider(provider)`
130
+ - `from(connection, signer)`
131
+ - `fromWallet(connection, wallet)`
132
+ - `fromKeypair(connection, keypair)`
133
+ - `fromEphemeral({ signer, rpcEndpoint, wsEndpoint, useAuth, authToken })`
134
+
135
+ ### Core Actions
136
+
137
+ - `initializeDeposit`
138
+ - `modifyBalance`
139
+ - `depositForUsername`
140
+ - `claimUsernameDeposit`
141
+ - `createPermission`
142
+ - `createUsernamePermission`
143
+ - `delegateDeposit`
144
+ - `delegateUsernameDeposit`
145
+ - `transferDeposit`
146
+ - `transferToUsernameDeposit`
147
+ - `undelegateDeposit`
148
+ - `undelegateUsernameDeposit`
149
+
150
+ ### Queries
151
+
152
+ - `getDeposit(user, tokenMint)`
153
+ - `getUsernameDeposit(username, tokenMint)`
154
+
155
+ ### PDA Helpers
156
+
157
+ - `findDepositPda(user, tokenMint)`
158
+ - `findUsernameDepositPda(username, tokenMint)`
159
+ - `findVaultPda(tokenMint)`
160
+
161
+ ## Development
162
+
163
+ ```bash
164
+ bun install
165
+ bun run typecheck
166
+ bun test --timeout 60000
167
+ ```