@xandeum/web3.js 0.4.0

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@xandeum/web3.js",
+  "version": "0.4.0",
+  "description": "Xandeum javascript api",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "deploy-docs": "typedoc && gh-pages -d docs/html"
+  },
+  "author": "",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@solana/web3.js": "^1.98.2",
+    "ws": "^8.18.2"
+  },
+  "devDependencies": {
+    "@types/bn.js": "^5.1.6",
+    "gh-pages": "^6.3.0",
+    "typedoc": "^0.28.4",
+    "typedoc-plugin-markdown": "^4.6.3"
+  }
+}

package/src/armageddon.ts

@@ -0,0 +1,36 @@
+import { Transaction, TransactionInstruction, PublicKey } from '@solana/web3.js'
+import BN from 'bn.js'
+import { programId } from './const.js'
+
+/**
+ * Constructs a Solana transaction that triggers the "armageddon" instruction
+ * on the specified file system (fsid).
+ * 
+ * @param fsid - A stringified integer representing the file system ID to be used in the instruction.
+ * @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 armageddon instruction.
+ */
+export async function armageddon (
+  fsid: string,
+  wallet: PublicKey
+): Promise<Transaction> {
+  const instructionData = Buffer.concat([
+    Buffer.from(Int8Array.from([1]).buffer),
+    Buffer.from(Uint8Array.of(...new BN(fsid).toArray('le', 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/bigbang.ts

@@ -0,0 +1,32 @@
+import { Transaction, TransactionInstruction, PublicKey } from '@solana/web3.js'
+import BN from 'bn.js'
+import { programId } from './const'
+
+/**
+ * Constructs a Solana transaction that triggers the "bigbang" instruction and create new file system.
+ *
+ * @param wallet - The public key of the wallet that will sign and authorize the transaction.
+ * @param replica_count - A stringified integer representing the number of replicas for the new file system.
+ * @returns A Promise that resolves to a Solana `Transaction` object containing the bigbang instruction.
+ */
+export async function bigbang (replica_count:string,wallet: PublicKey): Promise<Transaction> {
+  const instructionData = Buffer.concat([
+    Buffer.from(Int8Array.from([0]).buffer),
+    Buffer.from(Uint8Array.of(...new BN(replica_count).toArray('le', 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/const.ts

@@ -0,0 +1 @@
+export const programId="xSHLJPXU8QW3A9kGiRoL94bksJ7ZZPY4dUwJPAT8CVK";

package/src/copyPath.ts

@@ -0,0 +1,51 @@
+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 copy a file or directory from one  path to another.
+ *
+ * @param fsid - The unique numeric identifier representing the target file system.
+ * @param srcPath - The source path to copy from (e.g., `/documents/report.txt`).
+ * @param destPath - The destination path to copy to (e.g., `/archive/report.txt`).
+ * @param wallet - The wallet public key used to sign and authorize the transaction.
+ * @returns A Promise that resolves to a Solana `Transaction` object containing the copyPath instruction.
+ * @throws Will throw an error if `srcPath` or `destPath` contains invalid characters.
+ *
+ */
+
+export async function copyPath (
+  fsid: string,
+  srcPath: string,
+  destPath: string,
+  wallet: PublicKey
+): Promise<Transaction> {
+  // Validate path: only letters, numbers, and /
+  sanitizePath(srcPath)
+
+  sanitizePath(destPath)
+
+  const rest = Buffer.from(`${srcPath}\0${destPath}`, 'utf-8')
+
+  const instructionData = Buffer.concat([
+    Buffer.from(Int8Array.from([9]).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/createDirectory.ts

@@ -0,0 +1,47 @@
+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 create a new directory within a  file system.
+ *
+ * @param fsid - A numeric filesystem identifier used to scope the directory creation.
+ * @param path - The parent path where the directory should be created (e.g., `/documents`).
+ * @param name - The name of the new directory (e.g., `reports`).
+ * @param wallet - The signer’s public key that authorizes the transaction.
+ * @returns A Promise that resolves to a Solana `Transaction` object containing the createDirectory instruction.
+ * @throws Will throw an error if `path` or `name` contains invalid characters.@throws Will throw if the combined path is invalid (non-alphanumeric or unsupported characters).
+ */
+
+export async function createDirectory (
+  fsid: string,
+  path: string,
+  name: string,
+  wallet: PublicKey
+): Promise<Transaction> {
+  // Validate path: only letters, numbers, and /
+  const combinedPath = path.endsWith('/') ? `${path}${name}` : `${path}/${name}`
+  sanitizePath(combinedPath)
+  const rest = Buffer.from(`${path}\0${name}`, 'utf-8')
+  const instructionData = Buffer.concat([
+    Buffer.from(Int8Array.from([6]).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/createFile.ts

@@ -0,0 +1,47 @@
+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 create a new file
+ * within a file system, identified by a file system ID (`fsid`).
+ * 
+ * @param fsid - A stringified integer representing the file system ID where the file is to be created.
+ * @param path - The absolute or relative path within the file system where the file should be created.
+ * @param name - The name of the new file or directory to be created.
+ * @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 createFile instruction.
+ * @throws Will throw an error if `path` or `name` contains invalid characters.
+ */
+export async function createFile (
+  fsid: string,
+  path: string,
+  name: string,
+  wallet: PublicKey
+): Promise<Transaction> {
+  const combinedPath = path.endsWith('/') ? `${path}${name}` : `${path}/${name}`
+  sanitizePath(combinedPath);
+
+  const rest = Buffer.from(`${path}\0${name}`, 'utf-8')
+  const instructionData = Buffer.concat([
+    Buffer.from(Int8Array.from([2]).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/exists.ts

@@ -0,0 +1,47 @@
+import { Connection } from "@solana/web3.js"
+
+export interface RpcRequest {
+  jsonrpc: string
+  id: number
+  method: string
+  params: any[]
+}
+
+/**
+ * Sends a JSON-RPC request to the Xandeum RPC endpoint to check if a file or directory exists.
+ *
+ * This function calls the custom RPC method `isExist`, which should be implemented
+ * by the backend to validate the existence of metadata (files/directories) at a given path.
+ * @param connection - The solana web3 connection with Xandeum-compatible JSON-RPC endpoint (e.g., `'https://api.devnet.solana.com'`).
+ * @param path - The filesystem path to check (e.g., `/documents/myfile.txt`).
+ *
+ * @returns A `Promise<any>` resolving to the RPC response JSON, typically including a `result` field
+ *          indicating existence (e.g., `true` or `false`), or `null` if not found.
+ *
+ */
+
+  export async function exists (connection: Connection,path: string): Promise<any> {
+  const url = connection.rpcEndpoint;
+  const requestBody: RpcRequest = {
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'isExist',
+    params: [path]
+  }
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(requestBody)
+  })
+
+  if (!response.ok) {
+    const errorText = await response.text(); 
+    return Error(`error! status: ${response.status}, message: ${errorText}`);
+  }
+
+  const data = await response.json()
+  return data
+}

package/src/getMetadata.ts

@@ -0,0 +1,50 @@
+import { Connection } from "@solana/web3.js"
+
+export interface RpcRequest {
+  jsonrpc: string
+  id: number
+  method: string
+  params: any[]
+}
+
+/**
+ * Sends a JSON-RPC request to the Xandeum RPC endpoint to retrieve metadata
+ * about a file or directory at the given path.
+ *
+ * This function calls the custom RPC method `getMetadata`, which is implemented
+ * by the backend to return metadata such as type (file or directory), size,
+ * timestamps etc.
+ *
+ * @param connection - The solana web3 connection with Xandeum-compatible JSON-RPC endpoint (e.g., `'https://api.devnet.solana.com'`).
+ * @param path - The filesystem path to query metadata for (e.g., `/documents/myfile.txt`).
+ *
+ * @returns A `Promise<any>` resolving to the parsed JSON response from the RPC server,
+ *          typically containing a `result` object with metadata fields.
+ *
+ */
+
+export async function getMetadata (connection: Connection,path: string): Promise<any> {
+  const url = connection.rpcEndpoint;
+  const requestBody: RpcRequest = {
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'getMetadata',
+    params: [path]
+  }
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(requestBody)
+  })
+
+  if (!response.ok) {
+    const errorText = await response.text(); 
+    return Error(`error! status: ${response.status}, message: ${errorText}`);
+  }
+
+  const data = await response.json()
+  return data
+}

package/src/getXandeumResult.ts

@@ -0,0 +1,48 @@
+
+import { Connection } from "@solana/web3.js"
+
+function sleep(ms: number) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Sends a JSON-RPC request to the Xandeum-compatible endpoint to retrieve
+ * the result of a transaction previously submitted with a specific signature.
+ *
+ * This function calls the custom RPC method `getXandeumResult`, which returns
+ * the result associated with the given transaction signature.
+ *
+ * @param connection - The Solana web3 connection object pointing to a Xandeum-compatible RPC endpoint.
+ * @param signature - The transaction signature string whose result should be queried.
+ *
+ * @returns A `Promise<any>` resolving to the parsed JSON response from the RPC server,
+ *          which includes the result of the transaction if available.
+ */
+export async function getXandeumResult(  connection: Connection, signature: string): Promise<any> {
+    const url = connection.rpcEndpoint;
+    const requestBody = {
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'getXandeumResult',
+        params: [signature]
+    }
+
+    // sleeping To let the transaction process
+    await sleep(5000);
+
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(requestBody)
+    })
+
+    if (!response.ok) {
+        const errorText = await response.text();
+        return new Error(`Error! status: ${response.status}, message: ${errorText}`);
+    }
+
+    const data = await response.json()
+    return data
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export { bigbang } from "./bigbang";
+export * from './webSocket';
+export  *  from "./armageddon";
+export  *  from "./removeFile";
+export  * from "./renamePath";
+export  * from "./createFile";
+export  * from "./createDirectory";
+export * from "./peek";
+export * from "./poke";
+export * from "./removeDirectory";
+export * from "./copyPath";
+export * from "./move";
+export * from "./getXandeumResult";
+export {exists } from "./exists";
+export {listDirectoryEntry} from "./listDirectoryEntery";
+export {getMetadata} from "./getMetadata";

package/src/listDirectoryEntery.ts

@@ -0,0 +1,51 @@
+import { Connection } from "@solana/web3.js"
+
+export interface RpcRequest {
+  jsonrpc: string
+  id: number
+  method: string
+  params: any[]
+}
+
+/**
+ * Sends a JSON-RPC request to the Xandeum RPC endpoint to list all entries (files and subdirectories)
+ * within a specified path.
+ *
+ * This function calls the custom RPC method `listDirs`, which is  return an array of
+ * directory entry metadata — names, types etc.
+ *
+ * @param connection - The solana web3 connection with Xandeum-compatible JSON-RPC endpoint (e.g., `'https://api.devnet.solana.com'`).
+ * @param path - The  filesystem path representing the directory to list (e.g., `/documents`).
+ *
+ * @returns A `Promise<any>` resolving to the parsed JSON response from the RPC server,
+ *          typically including a `result` array containing directory entry objects.
+ */
+
+export async function listDirectoryEntry (
+  connection: Connection,
+  path: string,
+): Promise<any> {
+  const url = connection.rpcEndpoint;
+  const requestBody: RpcRequest = {
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'listDirs',
+    params: [path]
+  }
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(requestBody)
+  })
+
+  if (!response.ok) {
+    const errorText = await response.text(); 
+    return Error(`error! status: ${response.status}, message: ${errorText}`);
+  }
+
+  const data = await response.json()
+  return data
+}

package/src/move.ts

@@ -0,0 +1,55 @@
+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 copy a file or directory from one  path to another.
+ *
+ * @param fsid - The unique numeric identifier representing the target file system.
+ * @param srcPath - The source path to copy from (e.g., `/documents`).
+ * @param destPath - The destination path to copy to (e.g., `/archive`).
+ * @param name - The name of the new file or directory at the destination (e.g., `report.txt`).
+ * @param wallet - The wallet public key used to sign and authorize the transaction.
+ * @returns A Promise that resolves to a Solana `Transaction` object containing the copyPath instruction.
+ * @throws Will throw an error if `srcPath` or `destPath` contains invalid characters.
+ *
+ */
+
+export async function move (
+  fsid: string,
+  srcPath: string,
+  destPath: string,
+  name: string,
+  wallet: PublicKey
+): Promise<Transaction> {
+  // Validate path: only letters, numbers, and /
+  sanitizePath(srcPath)
+
+  sanitizePath(destPath)
+  sanitizePath(name)
+
+
+  const rest = Buffer.from(`${srcPath}\0${destPath}\0${name}`, 'utf-8')
+
+  const instructionData = Buffer.concat([
+    Buffer.from(Int8Array.from([13]).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/peek.ts

@@ -0,0 +1,52 @@
+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 "peek" operation on a file within a file system.
+ *
+ * The peek operation reads data between two byte offsets within a specified file path.
+ *
+ * @param fsid - A stringified integer representing the file system ID in which the file resides.
+ * @param path - The path to the file to be peeked.
+ * @param startPosition - The starting byte offset (inclusive) to begin reading from.
+ * @param endPosition - The ending byte offset (exclusive) to stop reading at.
+ * @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 peek instruction.
+ * @throws Will throw an error if the `path` contains invalid characters.
+ */
+
+export async function peek (
+  fsid: string,
+  path: string,
+  startPosition: number,
+  endPosition: number,
+  wallet: PublicKey
+): Promise<Transaction> {
+  sanitizePath(path)
+
+  const rest = Buffer.from(`${path}`, 'utf-8')
+  const instructionData = Buffer.concat([
+    Buffer.from(Int8Array.from([3]).buffer),
+    Buffer.from(Uint8Array.of(...new BN(fsid).toArray('le', 8))),
+    Buffer.from(Uint8Array.of(...new BN(startPosition).toArray('le', 8))),
+    Buffer.from(Uint8Array.of(...new BN(endPosition).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/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
+}