@xandeum/web3.js 1.2.0 → 1.3.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 (22) hide show
  1. package/dist/createDirectory.js +1 -1
  2. package/dist/createFile.js +1 -1
  3. package/docs/markdown/README.md +163 -2
  4. package/docs/markdown/functions/armageddon.md +1 -2
  5. package/docs/markdown/functions/bigbang.md +1 -1
  6. package/docs/markdown/functions/copyPath.md +1 -1
  7. package/docs/markdown/functions/createDirectory.md +1 -1
  8. package/docs/markdown/functions/createFile.md +1 -1
  9. package/docs/markdown/functions/exists.md +8 -8
  10. package/docs/markdown/functions/getMetadata.md +8 -8
  11. package/docs/markdown/functions/listDirectoryEntry.md +8 -8
  12. package/docs/markdown/functions/peek.md +1 -1
  13. package/docs/markdown/functions/poke.md +1 -1
  14. package/docs/markdown/functions/removeDirectory.md +1 -1
  15. package/docs/markdown/functions/removeFile.md +1 -1
  16. package/docs/markdown/functions/renamePath.md +1 -1
  17. package/docs/markdown/functions/subscribeResult.md +8 -8
  18. package/docs/markdown/functions/unsubscribeResult.md +8 -8
  19. package/docs/markdown/globals.md +2 -2
  20. package/package.json +1 -1
  21. package/src/createDirectory.ts +1 -1
  22. package/src/createFile.ts +1 -1
package/dist/createDirectory.js CHANGED
@@ -58,7 +58,7 @@ function createDirectory(fsid, path, name, wallet) {
58
58
  return __awaiter(this, void 0, void 0, function () {
59
59
  var combinedPath, rest, instructionData, instruction, tx;
60
60
  return __generator(this, function (_a) {
61
- combinedPath = path + '/' + name;
61
+ combinedPath = path.endsWith('/') ? "".concat(path).concat(name) : "".concat(path, "/").concat(name);
62
62
  (0, sanitizePath_1.sanitizePath)(combinedPath);
63
63
  rest = Buffer.from("".concat(path, "\0").concat(name), 'utf-8');
64
64
  instructionData = Buffer.concat([
package/dist/createFile.js CHANGED
@@ -59,7 +59,7 @@ function createFile(fsid, path, name, wallet) {
59
59
  return __awaiter(this, void 0, void 0, function () {
60
60
  var combinedPath, rest, instructionData, instruction, tx;
61
61
  return __generator(this, function (_a) {
62
- combinedPath = path + '/' + name;
62
+ combinedPath = path.endsWith('/') ? "".concat(path).concat(name) : "".concat(path, "/").concat(name);
63
63
  (0, sanitizePath_1.sanitizePath)(combinedPath);
64
64
  rest = Buffer.from("".concat(path, "\0").concat(name), 'utf-8');
65
65
  instructionData = Buffer.concat([
package/docs/markdown/README.md CHANGED
@@ -1,5 +1,166 @@
1
- **Xandeum Web3 Library v9.2.0**
1
+ **Xandeum Web3 Library v1.1.0**
2
2
 
3
3
  ***
4
4
 
5
- #Xandeum Web3.js
5
+ # @xandeum/web3.js
6
+
7
+ > Solana transaction builder for interacting with a file system on the Xandeum network.
8
+
9
+ This package provides a JavaScript/TypeScript interface to construct Solana transactions for creating, modifying, and managing file systems on-chain using the Xandeum program.
10
+
11
+ ## ✨ Features
12
+
13
+ - Create and delete file systems (`bigbang`, `armageddon`)
14
+ - Manage files and directories (`create`, `rename`, `remove`, `copy`)
15
+ - Read and write file contents with byte-level control (`peek`, `poke`)
16
+ - Secure path validation and serialization
17
+ - Compatible with `@solana/web3.js`
18
+
19
+ ## 📦 Installation
20
+
21
+ ```bash
22
+ npm install @xandeum/web3.js
23
+ ```
24
+
25
+ or
26
+
27
+ ```
28
+ yarn add @xandeum/web3.js
29
+ ```
30
+ 🚀 Usage
31
+
32
+ ```
33
+ import {
34
+ bigbang,
35
+ armageddon,
36
+ createFile,
37
+ poke,
38
+ peek,
39
+ copyPath
40
+ } from '@xandeum/web3.js'
41
+
42
+ import {
43
+ Connection,
44
+ sendAndConfirmTransaction,
45
+ Keypair
46
+ } from '@solana/web3.js'
47
+
48
+ const connection = new Connection('https://apis.devnet.xandeum.com)
49
+ const signer = Keypair.generate()
50
+ const wallet = signer.publicKey
51
+
52
+ async function main() {
53
+ // Create a new file system
54
+ const tx1 = await bigbang(wallet)
55
+ await sendAndConfirmTransaction(connection, tx1, [signer])
56
+
57
+ // Create a file
58
+ const tx2 = await createFile('1', '/1','hello.txt', wallet)
59
+ await sendAndConfirmTransaction(connection, tx2, [signer])
60
+
61
+ // Write data
62
+ const tx3 = await poke('1', '/1/hello.txt', 0, Buffer.from('Hello Xandeum!'), wallet)
63
+ await sendAndConfirmTransaction(connection, tx3, [signer])
64
+
65
+ // Read data
66
+ const tx4 = await peek('1', '/1/hello.txt', 0, 14, wallet)
67
+ await sendAndConfirmTransaction(connection, tx4, [signer])
68
+ }
69
+ ```
70
+
71
+ ## 🧩 API Overview
72
+
73
+ bigbang(wallet: PublicKey): Promise<Transaction>
74
+ Creates a new file system account.
75
+
76
+ armageddon(fsid: string, wallet: PublicKey): Promise<Transaction>
77
+ Deletes a file system by ID.
78
+
79
+ createFile(fsid: string, path: string, wallet: PublicKey): Promise<Transaction>
80
+ Creates a new file at the given path.
81
+
82
+ poke(fsid: string, path: string, offset: number, data: Buffer, wallet: PublicKey): Promise<Transaction>
83
+ Writes bytes to a file starting at a specific offset.
84
+
85
+ peek(fsid: string, path: string, offset: number, length: number, wallet: PublicKey): Promise<Transaction>
86
+ Reads bytes from a file.
87
+
88
+ copyPath(fsid: string, srcPath: string, destPath: string, wallet: PublicKey): Promise<Transaction>
89
+ Copies a file or directory from one path to another.
90
+
91
+ Other available functions <br />
92
+ renamePath <br />
93
+ removeFile <br />
94
+ removeDirectory <br />
95
+ createDirectory <br />
96
+ exists <br />
97
+ listDirectoryEntry <br />
98
+ getMetadata <br />
99
+
100
+ All functions that accept a file or directory path will validate inputs using sanitizePath to prevent invalid characters.
101
+
102
+ ## 🌐 WebSocket Subscription
103
+
104
+ subscribeResult(connection: Connection,tx: string, onResult: (result: ResultValue) => void, onError?: (err: any) => void, onClose?: () => void): void
105
+ Subscribes to results from a transaction via WebSocket. Used for listening events triggered by the transaction.
106
+
107
+ #### Parameters:
108
+
109
+ connection - The solana web3 connection with Xandeum-compatible JSON-RPC endpoint (e.g., `'https://api.devnet.solana.com'`).
110
+ tx — Transaction signature to subscribe to
111
+ onResult(result) — Called when a valid result is received
112
+ onError(err) — Optional callback for connection errors
113
+ onClose() — Optional callback for connection closure
114
+ Example:
115
+
116
+ ```
117
+ subscribeResult(
118
+ connection,
119
+ 'transactionSignatureHere',
120
+ result => {
121
+ console.log('Result:', result)
122
+ }
123
+ )
124
+ ```
125
+
126
+ Example
127
+ ```
128
+ import {
129
+ bigbang,
130
+ createFile,
131
+ poke,
132
+ peek,
133
+ subscribeResult
134
+ } from '@xandeum/web3.js'
135
+
136
+ import {
137
+ Connection,
138
+ sendAndConfirmTransaction,
139
+ Keypair
140
+ } from '@solana/web3.js'
141
+
142
+ const connection = new Connection('https://api.mainnet-beta.solana.com')
143
+ const signer = Keypair.generate()
144
+ const wallet = signer.publicKey
145
+
146
+ async function main() {
147
+ const tx = await createFile('1', '/1/hello.txt', wallet)
148
+ const txSignature = await sendAndConfirmTransaction(connection, tx, [signer])
149
+
150
+ subscribeResult(
151
+ connection,
152
+ txSignature,
153
+ result => {
154
+ console.log('Received result:', result)
155
+ },
156
+ err => console.error('WebSocket error:', err),
157
+ () => console.log('WebSocket closed')
158
+ )
159
+ }
160
+ ```
161
+
162
+ MIT © Xandeum
163
+
164
+ 👤 Author
165
+
166
+ Built by Xandeum to provide decentralized, programmable file systems on Solana via the Xandeum protocol.
package/docs/markdown/functions/armageddon.md CHANGED
@@ -1,4 +1,4 @@
1
- [**Xandeum Web3 Library v9.2.0**](../README.md)
1
+ [**Xandeum Web3 Library v1.1.0**](../README.md)
2
2
 
3
3
  ***
4
4
 
@@ -12,7 +12,6 @@ Defined in: [armageddon.ts:13](https://github.com/Xandeum/test_web3/blob/main/sr
12
12
 
13
13
  Constructs a Solana transaction that triggers the "armageddon" instruction
14
14
  on the specified file system (fsid).
15
- ### Requested Fields:
16
15
 
17
16
  ## Parameters
18
17
 
package/docs/markdown/functions/bigbang.md CHANGED
@@ -1,4 +1,4 @@
1
- [**Xandeum Web3 Library v9.2.0**](../README.md)
1
+ [**Xandeum Web3 Library v1.1.0**](../README.md)
2
2
 
3
3
  ***
4
4
 
package/docs/markdown/functions/copyPath.md CHANGED
@@ -1,4 +1,4 @@
1
- [**Xandeum Web3 Library v9.2.0**](../README.md)
1
+ [**Xandeum Web3 Library v1.1.0**](../README.md)
2
2
 
3
3
  ***
4
4
 
package/docs/markdown/functions/createDirectory.md CHANGED
@@ -1,4 +1,4 @@
1
- [**Xandeum Web3 Library v9.2.0**](../README.md)
1
+ [**Xandeum Web3 Library v1.1.0**](../README.md)
2
2
 
3
3
  ***
4
4
 
package/docs/markdown/functions/createFile.md CHANGED
@@ -1,4 +1,4 @@
1
- [**Xandeum Web3 Library v9.2.0**](../README.md)
1
+ [**Xandeum Web3 Library v1.1.0**](../README.md)
2
2
 
3
3
  ***
4
4
 
package/docs/markdown/functions/exists.md CHANGED
@@ -1,4 +1,4 @@
1
- [**Xandeum Web3 Library v9.2.0**](../README.md)
1
+ [**Xandeum Web3 Library v1.1.0**](../README.md)
2
2
 
3
3
  ***
4
4
 
@@ -6,9 +6,9 @@
6
6
 
7
7
  # Function: exists()
8
8
 
9
- > **exists**(`path`, `url`): `Promise`\<`any`\>
9
+ > **exists**(`connection`, `path`): `Promise`\<`any`\>
10
10
 
11
- Defined in: [exists.ts:22](https://github.com/Xandeum/test_web3/blob/main/src/exists.ts#L22)
11
+ Defined in: [exists.ts:23](https://github.com/Xandeum/test_web3/blob/main/src/exists.ts#L23)
12
12
 
13
13
  Sends a JSON-RPC request to the Xandeum RPC endpoint to check if a file or directory exists.
14
14
 
@@ -17,17 +17,17 @@ by the backend to validate the existence of metadata (files/directories) at a gi
17
17
 
18
18
  ## Parameters
19
19
 
20
- ### path
20
+ ### connection
21
21
 
22
- `string`
22
+ `Connection`
23
23
 
24
- The filesystem path to check (e.g., `/documents/myfile.txt`).
24
+ The solana web3 connection with Xandeum-compatible JSON-RPC endpoint (e.g., `'https://api.devnet.solana.com'`).
25
25
 
26
- ### url
26
+ ### path
27
27
 
28
28
  `string`
29
29
 
30
- The full URL of the Xandeum-compatible JSON-RPC endpoint (e.g., `'https://api.devnet.solana.com'`).
30
+ The filesystem path to check (e.g., `/documents/myfile.txt`).
31
31
 
32
32
  ## Returns
33
33
 
package/docs/markdown/functions/getMetadata.md CHANGED
@@ -1,4 +1,4 @@
1
- [**Xandeum Web3 Library v9.2.0**](../README.md)
1
+ [**Xandeum Web3 Library v1.1.0**](../README.md)
2
2
 
3
3
  ***
4
4
 
@@ -6,9 +6,9 @@
6
6
 
7
7
  # Function: getMetadata()
8
8
 
9
- > **getMetadata**(`path`, `url`): `Promise`\<`any`\>
9
+ > **getMetadata**(`connection`, `path`): `Promise`\<`any`\>
10
10
 
11
- Defined in: [getMetadata.ts:24](https://github.com/Xandeum/test_web3/blob/main/src/getMetadata.ts#L24)
11
+ Defined in: [getMetadata.ts:26](https://github.com/Xandeum/test_web3/blob/main/src/getMetadata.ts#L26)
12
12
 
13
13
  Sends a JSON-RPC request to the Xandeum RPC endpoint to retrieve metadata
14
14
  about a file or directory at the given path.
@@ -19,17 +19,17 @@ timestamps etc.
19
19
 
20
20
  ## Parameters
21
21
 
22
- ### path
22
+ ### connection
23
23
 
24
- `string`
24
+ `Connection`
25
25
 
26
- The filesystem path to query metadata for (e.g., `/documents/myfile.txt`).
26
+ The solana web3 connection with Xandeum-compatible JSON-RPC endpoint (e.g., `'https://api.devnet.solana.com'`).
27
27
 
28
- ### url
28
+ ### path
29
29
 
30
30
  `string`
31
31
 
32
- The full URL of the Xandeum-compatible JSON-RPC endpoint (e.g., `'https://api.devnet.solana.com'`).
32
+ The filesystem path to query metadata for (e.g., `/documents/myfile.txt`).
33
33
 
34
34
  ## Returns
35
35
 
package/docs/markdown/functions/listDirectoryEntry.md CHANGED
@@ -1,4 +1,4 @@
1
- [**Xandeum Web3 Library v9.2.0**](../README.md)
1
+ [**Xandeum Web3 Library v1.1.0**](../README.md)
2
2
 
3
3
  ***
4
4
 
@@ -6,9 +6,9 @@
6
6
 
7
7
  # Function: listDirectoryEntry()
8
8
 
9
- > **listDirectoryEntry**(`path`, `url`): `Promise`\<`any`\>
9
+ > **listDirectoryEntry**(`connection`, `path`): `Promise`\<`any`\>
10
10
 
11
- Defined in: [listDirectoryEntery.ts:22](https://github.com/Xandeum/test_web3/blob/main/src/listDirectoryEntery.ts#L22)
11
+ Defined in: [listDirectoryEntery.ts:24](https://github.com/Xandeum/test_web3/blob/main/src/listDirectoryEntery.ts#L24)
12
12
 
13
13
  Sends a JSON-RPC request to the Xandeum RPC endpoint to list all entries (files and subdirectories)
14
14
  within a specified path.
@@ -18,17 +18,17 @@ directory entry metadata — names, types etc.
18
18
 
19
19
  ## Parameters
20
20
 
21
- ### path
21
+ ### connection
22
22
 
23
- `string`
23
+ `Connection`
24
24
 
25
- The filesystem path representing the directory to list (e.g., `/documents`).
25
+ The solana web3 connection with Xandeum-compatible JSON-RPC endpoint (e.g., `'https://api.devnet.solana.com'`).
26
26
 
27
- ### url
27
+ ### path
28
28
 
29
29
  `string`
30
30
 
31
- The full URL of the Xandeum-compatible JSON-RPC endpoint (e.g., `'https://api.devnet.solana.com'`).
31
+ The filesystem path representing the directory to list (e.g., `/documents`).
32
32
 
33
33
  ## Returns
34
34
 
package/docs/markdown/functions/peek.md CHANGED
@@ -1,4 +1,4 @@
1
- [**Xandeum Web3 Library v9.2.0**](../README.md)
1
+ [**Xandeum Web3 Library v1.1.0**](../README.md)
2
2
 
3
3
  ***
4
4
 
package/docs/markdown/functions/poke.md CHANGED
@@ -1,4 +1,4 @@
1
- [**Xandeum Web3 Library v9.2.0**](../README.md)
1
+ [**Xandeum Web3 Library v1.1.0**](../README.md)
2
2
 
3
3
  ***
4
4
 
package/docs/markdown/functions/removeDirectory.md CHANGED
@@ -1,4 +1,4 @@
1
- [**Xandeum Web3 Library v9.2.0**](../README.md)
1
+ [**Xandeum Web3 Library v1.1.0**](../README.md)
2
2
 
3
3
  ***
4
4
 
package/docs/markdown/functions/removeFile.md CHANGED
@@ -1,4 +1,4 @@
1
- [**Xandeum Web3 Library v9.2.0**](../README.md)
1
+ [**Xandeum Web3 Library v1.1.0**](../README.md)
2
2
 
3
3
  ***
4
4
 
package/docs/markdown/functions/renamePath.md CHANGED
@@ -1,4 +1,4 @@
1
- [**Xandeum Web3 Library v9.2.0**](../README.md)
1
+ [**Xandeum Web3 Library v1.1.0**](../README.md)
2
2
 
3
3
  ***
4
4
 
package/docs/markdown/functions/subscribeResult.md CHANGED
@@ -1,4 +1,4 @@
1
- [**Xandeum Web3 Library v9.2.0**](../README.md)
1
+ [**Xandeum Web3 Library v1.1.0**](../README.md)
2
2
 
3
3
  ***
4
4
 
@@ -6,9 +6,9 @@
6
6
 
7
7
  # Function: subscribeResult()
8
8
 
9
- > **subscribeResult**(`tx`, `wsUrl`, `onResult`, `onError?`, `onClose?`): `void`
9
+ > **subscribeResult**(`connection`, `tx`, `onResult`, `onError?`, `onClose?`): `void`
10
10
 
11
- Defined in: [webSocket.ts:38](https://github.com/Xandeum/test_web3/blob/main/src/webSocket.ts#L38)
11
+ Defined in: [webSocket.ts:40](https://github.com/Xandeum/test_web3/blob/main/src/webSocket.ts#L40)
12
12
 
13
13
  Opens a WebSocket connection and subscribes to the result of a transaction
14
14
  via the custom `xandeumResultSubscribe` method.
@@ -25,17 +25,17 @@ if a valid result with `fsid`, `status`, or `data` is received.
25
25
 
26
26
  ## Parameters
27
27
 
28
- ### tx
28
+ ### connection
29
29
 
30
- `string`
30
+ `Connection`
31
31
 
32
- The transaction ID you want to listen for results from.
32
+ The solana web3 connection with Xandeum-compatible JSON-RPC endpoint (e.g., `'https://api.devnet.solana.com'`).
33
33
 
34
- ### wsUrl
34
+ ### tx
35
35
 
36
36
  `string`
37
37
 
38
- The full WebSocket endpoint (e.g., `wss://...`) to connect to.
38
+ The transaction ID you want to listen for results from.
39
39
 
40
40
  ### onResult
41
41
 
package/docs/markdown/functions/unsubscribeResult.md CHANGED
@@ -1,4 +1,4 @@
1
- [**Xandeum Web3 Library v9.2.0**](../README.md)
1
+ [**Xandeum Web3 Library v1.1.0**](../README.md)
2
2
 
3
3
  ***
4
4
 
@@ -6,9 +6,9 @@
6
6
 
7
7
  # Function: unsubscribeResult()
8
8
 
9
- > **unsubscribeResult**(`subscriptionId`, `wsUrl`): `void`
9
+ > **unsubscribeResult**(`connection`, `subscriptionId`): `void`
10
10
 
11
- Defined in: [webSocket.ts:93](https://github.com/Xandeum/test_web3/blob/main/src/webSocket.ts#L93)
11
+ Defined in: [webSocket.ts:96](https://github.com/Xandeum/test_web3/blob/main/src/webSocket.ts#L96)
12
12
 
13
13
  Sends a WebSocket JSON-RPC message to unsubscribe from a previously subscribed transaction result
14
14
  using the `xandeumResultUnsubscribed` method (note: custom method, ensure server-side implementation matches).
@@ -17,17 +17,17 @@ This function automatically closes the WebSocket connection after sending the un
17
17
 
18
18
  ## Parameters
19
19
 
20
- ### subscriptionId
20
+ ### connection
21
21
 
22
- `string`
22
+ `Connection`
23
23
 
24
- The ID of the active subscription you want to cancel.
24
+ The solana web3 connection with Xandeum-compatible JSON-RPC endpoint (e.g., `'https://api.devnet.solana.com'`).
25
25
 
26
- ### wsUrl
26
+ ### subscriptionId
27
27
 
28
28
  `string`
29
29
 
30
- The WebSocket endpoint (e.g., `wss://...`) to connect to for unsubscribing.
30
+ The ID of the active subscription you want to cancel.
31
31
 
32
32
  ## Returns
33
33
 
package/docs/markdown/globals.md CHANGED
@@ -1,8 +1,8 @@
1
- [**Xandeum Web3 Library v9.2.0**](README.md)
1
+ [**Xandeum Web3 Library v1.1.0**](README.md)
2
2
 
3
3
  ***
4
4
 
5
- # Xandeum Web3 Library v9.2.0
5
+ # Xandeum Web3 Library v1.1.0
6
6
 
7
7
  ## Functions
8
8
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xandeum/web3.js",
3
- "version": "1.2.0",
3
+ "version": "1.3.0",
4
4
  "description": "Xandeum javascript api",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
package/src/createDirectory.ts CHANGED
@@ -21,7 +21,7 @@ export async function createDirectory (
21
21
  wallet: PublicKey
22
22
  ): Promise<Transaction> {
23
23
  // Validate path: only letters, numbers, and /
24
- let combinedPath = path + '/' + name
24
+ const combinedPath = path.endsWith('/') ? `${path}${name}` : `${path}/${name}`
25
25
  sanitizePath(combinedPath)
26
26
  const rest = Buffer.from(`${path}\0${name}`, 'utf-8')
27
27
  const instructionData = Buffer.concat([
package/src/createFile.ts CHANGED
@@ -20,7 +20,7 @@ export async function createFile (
20
20
  name: string,
21
21
  wallet: PublicKey
22
22
  ): Promise<Transaction> {
23
- let combinedPath = path + '/' + name
23
+ const combinedPath = path.endsWith('/') ? `${path}${name}` : `${path}/${name}`
24
24
  sanitizePath(combinedPath);
25
25
 
26
26
  const rest = Buffer.from(`${path}\0${name}`, 'utf-8')