@xandeum/web3.js 1.1.0

package/src/poke.ts

@@ -0,0 +1,59 @@
+import { Transaction, TransactionInstruction, PublicKey } from '@solana/web3.js'
+import BN from 'bn.js'
+import { programId } from './const'
+import { sanitizePath } from './sanitizePath'
+
+/**
+ * Constructs a Solana transaction to perform a poke\operation, which writes data
+ * to a file at the specified path and byte position.
+ *
+ * @param fsid - A stringified integer representing the file system ID where the file resides.
+ * @param path - The path to the file to be written to.
+ * @param position - The byte offset in the file where data should be written.
+ * @param wallet - The public key of the wallet that signs and authorizes the transaction.
+ * @param dataKey - A public key of a data account that holds the content to be written to the file.
+ * @returns A Promise that resolves to a Solana `Transaction` object containing the poke instruction.
+ * @throws Will throw an error if the `path` contains invalid characters.
+ */
+
+export async function poke (
+  fsid: string,
+  path: string,
+  position: number,
+  wallet: PublicKey,
+  dataKey: PublicKey
+): Promise<Transaction> {
+  sanitizePath(path)
+
+  // Encode the path as UTF-8
+  const pathBuffer = Buffer.from(path, 'utf-8')
+  // Encode the path length as an 8-byte little-endian unsigned integer
+  const pathLengthBuffer = Buffer.from(Uint8Array.of(...new BN(pathBuffer.length).toArray('le', 8)))
+  const instructionData = Buffer.concat([
+    Buffer.from(Int8Array.from([4]).buffer),
+    Buffer.from(Uint8Array.of(...new BN(fsid).toArray('le', 8))),
+    Buffer.from(Uint8Array.of(...new BN(position).toArray('le', 8))),
+    pathLengthBuffer,
+    pathBuffer
+  ])
+
+  const instruction = new TransactionInstruction({
+    keys: [
+      {
+        pubkey: wallet,
+        isSigner: true,
+        isWritable: true
+      },
+      {
+        pubkey: dataKey,
+        isSigner: false,
+        isWritable: false
+      }
+    ],
+    programId: new PublicKey(programId),
+    data: instructionData
+  })
+
+  const tx = new Transaction().add(instruction)
+  return tx
+}

package/src/removeDirectory.ts

@@ -0,0 +1,43 @@
+import { Transaction, TransactionInstruction, PublicKey } from '@solana/web3.js'
+import BN from 'bn.js'
+import { programId } from './const'
+import { sanitizePath } from './sanitizePath'
+
+/**
+ * Constructs a Solana transaction to perform a "remove directory" operation
+ * in a  file system, identified by a file system ID (`fsid`).
+ *
+ * @param fsid - A stringified integer representing the file system ID containing the directory.
+ * @param path - The full path to the directory that should be removed.
+ * @param wallet - The public key of the wallet that will sign and authorize the transaction.
+ * @returns A Promise that resolves to a Solana `Transaction` object containing the remove directory instruction.
+ * @throws May throw an error if the `path` fails validation in `sanitizePath`.
+ */
+
+export async function removeDirectory (
+  fsid: string,
+  path: string,
+  wallet: PublicKey
+): Promise<Transaction> {
+  sanitizePath(path)
+  const instructionData = Buffer.concat([
+    Buffer.from(Int8Array.from([7]).buffer),
+    Buffer.from(Uint8Array.of(...new BN(fsid).toArray('le', 8))),
+    Buffer.from(`${path}`, 'utf-8')
+  ])
+
+  const instruction = new TransactionInstruction({
+    keys: [
+      {
+        pubkey: wallet,
+        isSigner: true,
+        isWritable: true
+      }
+    ],
+    programId: new PublicKey(programId),
+    data: instructionData
+  })
+
+  const tx = new Transaction().add(instruction)
+  return tx
+}

package/src/removeFile.ts

@@ -0,0 +1,44 @@
+import { Transaction, TransactionInstruction, PublicKey } from '@solana/web3.js'
+import BN from 'bn.js'
+import { programId } from './const'
+import { sanitizePath } from './sanitizePath'
+
+/**
+ * Constructs a Solana transaction to remove a file from a  file system,
+ * identified by a file system ID (`fsid`) and a UTF-8 encoded file path.
+ *
+ * @param fsid - A stringified integer representing the file system ID in which the file resides.
+ * @param path - The full path to the file to be deleted.
+ * @param wallet - The public key of the wallet that signs and authorizes the transaction.
+ * @returns A Promise that resolves to a Solana `Transaction` object containing the remove file instruction.
+ * @throws May throw an error if `path` is invalid per `sanitizePath`.
+ */
+
+export async function removeFile (
+  fsid: string,
+  path: string,
+  wallet: PublicKey
+): Promise<Transaction> {
+  sanitizePath(path)
+
+  const instructionData = Buffer.concat([
+    Buffer.from(Int8Array.from([5]).buffer),
+    Buffer.from(Uint8Array.of(...new BN(fsid).toArray('le', 8))),
+    Buffer.from(`${path}`, 'utf-8')
+  ])
+
+  const instruction = new TransactionInstruction({
+    keys: [
+      {
+        pubkey: wallet,
+        isSigner: true,
+        isWritable: true
+      }
+    ],
+    programId: new PublicKey(programId),
+    data: instructionData
+  })
+
+  const tx = new Transaction().add(instruction)
+  return tx
+}

package/src/renamePath.ts

@@ -0,0 +1,50 @@
+import { Transaction, TransactionInstruction, PublicKey } from '@solana/web3.js'
+import BN from 'bn.js'
+import { programId } from './const'
+import { sanitizePath } from './sanitizePath'
+
+/**
+ * Constructs a Solana transaction to rename (or move) a file or directory
+ * within a file system, based on a provided file system ID (`fsid`).
+ *
+ * @param fsid - A stringified integer representing the file system ID where the path exists.
+ * @param oldPath - The current path of the file or directory to be renamed or moved.
+ * @param name - The new name to assign to the file or directory.
+ * @param wallet - The public key of the wallet that signs and authorizes the transaction.
+ * @returns A Promise that resolves to a Solana `Transaction` object containing the rename path instruction.
+ * @throws May throw an error if either `oldPath` or `newPath` is invalid per `sanitizePath`.
+ */
+
+export async function renamePath (
+  fsid: string,
+  oldPath: string,
+  name: string,
+  wallet: PublicKey
+): Promise<Transaction> {
+  sanitizePath(oldPath)
+
+  sanitizePath(name)
+
+  const rest = Buffer.from(`${oldPath}\0${name}`, 'utf-8')
+
+  const instructionData = Buffer.concat([
+    Buffer.from(Int8Array.from([8]).buffer),
+    Buffer.from(Uint8Array.of(...new BN(fsid).toArray('le', 8))),
+    rest
+  ])
+
+  const instruction = new TransactionInstruction({
+    keys: [
+      {
+        pubkey: wallet,
+        isSigner: true,
+        isWritable: true
+      }
+    ],
+    programId: new PublicKey(programId),
+    data: instructionData
+  })
+
+  const tx = new Transaction().add(instruction)
+  return tx
+}

package/src/sanitizePath.ts

@@ -0,0 +1,69 @@
+/**
+ * Sanitizes file path for validate path.
+ * Ensures the path contains only allowed characters, prevents path traversal,
+ * and normalizes the path to start with a single slash.
+ *
+ * Allowed characters: alphanumeric, '/', '_', '-', '.'
+ * Disallowed: consecutive slashes (//), path traversal (..), control characters,
+ *             invalid filesystem characters (<, >, :, ", \, |, ?, *),
+ *             empty or whitespace-only paths.
+ *
+ * @param path - The file path to sanitize.
+ * @throws Error if the path is invalid.
+ */
+export function sanitizePath(path: string): void {
+    // Check for empty or whitespace-only paths
+    if (!path || path.trim() === "") {
+      throw new Error("Path cannot be empty or whitespace-only");
+    }
+  
+    // Check for consecutive slashes (// or more)
+    if (/\/\/+/.test(path)) {
+      throw new Error("Consecutive slashes (//) are not allowed");
+    }
+  
+    // Check for path traversal sequences (..)
+    if (path.includes("..")) {
+      throw new Error("Path traversal sequences (..) are not allowed");
+    }
+  
+    // Check for control characters (ASCII 0-31 and 127)
+    for (let i = 0; i < path.length; i++) {
+      const code = path.charCodeAt(i);
+      if (code <= 31 || code === 127) {
+        throw new Error("Control characters are not allowed in paths");
+      }
+    }
+  
+    // Check for allowed characters: alphanumeric, /, _, -, .
+    if (!/^[a-zA-Z0-9\/_\-\.]*$/.test(path)) {
+      throw new Error(
+        "Path must contain only alphanumeric characters, single slashes, underscores (_), hyphens (-), or periods (.)"
+      );
+    }
+  
+    // Check for invalid filesystem characters
+    const invalidChars = ["<", ">", ":", '"', "\\", "|", "?", "*"];
+    for (let i = 0; i < path.length; i++) {
+      if (invalidChars.includes(path[i])) {
+        throw new Error(
+          'Path contains invalid filesystem characters (<, >, :, ", \\, |, ?, *)'
+        );
+      }
+    }
+  
+  
+    // Check path component length (max 255 bytes)
+    const components = path.split("/").filter((c) => c.length > 0);
+    for (const component of components) {
+      if (new TextEncoder().encode(component).length > 255) {
+        throw new Error("Path component exceeds 255 bytes");
+      }
+    }
+  
+    // Check total path length (max 4096 bytes)
+    if (new TextEncoder().encode(path).length > 4096) {
+      throw new Error("Total path length exceeds 4096 bytes");
+    }
+
+  }

package/src/webSocket.ts

@@ -0,0 +1,118 @@
+import WebSocket from 'ws'
+import { PublicKey, Transaction, TransactionInstruction, Keypair, Connection, clusterApiUrl,ComputeBudgetProgram } from "@solana/web3.js"
+
+/**
+ * Represents the structure of result data received from a WebSocket subscription.
+ *
+ * - `fsid` (optional): The file system ID returned from the result.
+ * - `status` (optional): The status of the transaction or operation.
+ * - `data` (optional): Any custom payload or message associated with the result.
+ * - `subscription` (optional): The ID of the WebSocket subscription.
+ */
+type ResultValue = {
+  fsid?: string
+  status?: string
+  data?: any
+  subscription?: string
+}
+
+/**
+ * Opens a WebSocket connection and subscribes to the result of a transaction
+ * via the custom `xandeumResultSubscribe` method.
+ *
+ * This is useful for receiving asynchronous results tied to an on-chain operation,
+ * such as file creation, modification, or deletion.
+ *
+ * The subscription sends a JSON-RPC request with:
+ * - `method`: "xandeumResultSubscribe"
+ * - `params`: [txId, { commitment: "finalized" }]
+ *
+ * The WebSocket listens for result messages and invokes the `onResult` callback
+ * if a valid result with `fsid`, `status`, or `data` is received.
+ *
+ * @param tx - The transaction ID you want to listen for results from.
+ * @param connection - The solana web3 connection with Xandeum-compatible JSON-RPC endpoint (e.g., `'https://api.devnet.solana.com'`).
+ * @param onResult - Callback to handle incoming result messages. Triggered when a valid response is received.
+ * @param onError - (Optional) Callback triggered if a WebSocket error occurs.
+ * @param onClose - (Optional) Callback triggered when the WebSocket connection closes.
+ */
+
+export function subscribeResult (
+  connection: Connection,
+  tx: string,
+  onResult: (value: ResultValue) => void,
+  onError?: (err: any) => void,
+  onClose?: () => void
+): void {
+  let rpcEndpoint = connection.rpcEndpoint;
+  const ws = new WebSocket(rpcEndpoint.replace('http', 'ws'));
+
+  ws.addEventListener('open', () => {
+    const subscriptionMessage = {
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'xandeumResultSubscribe',
+      params: [tx, { commitment: 'finalized' }]
+    }
+    ws.send(JSON.stringify(subscriptionMessage))
+  })
+
+  ws.addEventListener('message', event => {
+    const d = JSON.parse(String(event.data).replace(/:\s*(\d{16,})/g, ': "$1"'))
+
+    const value = d?.params?.result?.value
+    if (
+      (value?.fsid || value?.status || value?.data) &&
+      d?.params?.subscription
+    ) {
+      onResult({
+        fsid: value.fsid,
+        status: value.status,
+        data: value.message,
+        subscription: d.params.subscription
+      })
+    }
+  })
+
+  ws.addEventListener('error', error => {
+    if (onError) onError(error)
+  })
+
+  ws.addEventListener('close', () => {
+    if (onClose) onClose()
+  })
+}
+
+/**
+ * Sends a WebSocket JSON-RPC message to unsubscribe from a previously subscribed transaction result
+ * using the `xandeumResultUnsubscribed` method (note: custom method, ensure server-side implementation matches).
+ *
+ * This function automatically closes the WebSocket connection after sending the unsubscribe request.
+ *
+ * @param subscriptionId - The ID of the active subscription you want to cancel.
+ * @param connection - The solana web3 connection with Xandeum-compatible JSON-RPC endpoint (e.g., `'https://api.devnet.solana.com'`).
+ */
+
+export function unsubscribeResult(connection: Connection,subscriptionId: string): void {
+    let rpcEndpoint = connection.rpcEndpoint;
+    const ws = new WebSocket(rpcEndpoint.replace('http', 'ws'));
+
+  ws.addEventListener('open', () => {
+    const unsubscribeMessage = {
+      jsonrpc: '2.0',
+      id: 2,
+      method: 'xandeumResultUnsubscribe',
+      params: [subscriptionId]
+    }
+
+    ws.send(JSON.stringify(unsubscribeMessage))
+    console.log(
+      `Sent xandeumResultUnsubscribe for subscription ID: ${subscriptionId}`
+    )
+    ws.close()
+  })
+
+  ws.addEventListener('error', err => {
+    console.error('WebSocket error during unsubscribe:', err)
+  })
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+    "compilerOptions": {
+      "target": "ES5",
+      "module": "CommonJS",
+      "outDir": "dist",
+      "rootDir": "src",
+      "declaration": true,
+      "esModuleInterop": true,
+      "strict": true
+    },
+    "include": ["src/**/*.ts"],
+    "exclude": ["node_modules", "dist"]
+  }
+  

package/typedoc.json

@@ -0,0 +1,27 @@
+{
+    "$schema": "https://typedoc.org/schema.json",
+    "entryPoints": ["src/index.ts"],
+    "plugin": ["typedoc-plugin-markdown"],
+    "out": "docs/markdown",
+    "tsconfig": "tsconfig.json",
+    "name": "Xandeum Web3 Library",
+    "readme": "README.md",
+    "theme": "default",
+    "includeVersion": true,
+    "hideGenerator": false,
+    "githubPages": true,
+    "cleanOutputDir": true,
+    "excludePrivate": true,
+    "excludeProtected": true,
+    "excludeInternal": true,
+    "excludeNotDocumented": false,
+    "gitRemote": "origin",
+    "gitRevision": "main",
+    "sourceLinkTemplate": "https://github.com/Xandeum/test_web3/blob/{gitRevision}/{path}#L{line}",
+    "visibilityFilters": {
+      "protected": false,
+      "private": false,
+      "inherited": true,
+      "external": true
+    }
+  }