@xandeum/web3.js 1.2.0 → 1.3.1

package/src/assignCoowner.ts

@@ -0,0 +1,49 @@
+import { Transaction, TransactionInstruction, PublicKey } from '@solana/web3.js'
+import { programId } from './const'
+import BN from 'bn.js'
+import { getFeeDistributorPda } from './helpers.js'
+
+/**
+ * Constructs a Solana transaction to assign a co-owner to a file or directory
+ * identified by a file system ID (`fsid`).
+ * 
+ * @param fsid - A stringified integer representing the file system ID where the co-owner is to be assigned.
+ * @param path - The path within the file system.
+ * @param coowner - The public key of the co-owner to be assigned.
+ * @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 assignCoowner instruction.
+ */
+export async function assignCoowner (
+  fsid: string,
+  path: string,
+  coowner: PublicKey,
+  wallet: PublicKey
+): Promise<Transaction> {
+  const rest = Buffer.from(`${path}\0${coowner.toString()}`, 'utf-8')
+  const instructionData = Buffer.concat([
+    Buffer.from(Int8Array.from([0]).buffer),
+    Buffer.from(Int8Array.from([14]).buffer),
+    Buffer.from(Uint8Array.of(...new BN(fsid).toArray('le', 8))),
+    rest
+  ])
+  let feeDistributorPda = getFeeDistributorPda()
+  const instruction = new TransactionInstruction({
+    keys: [
+      {
+        pubkey: wallet,
+        isSigner: true,
+        isWritable: true
+      },
+      {
+        pubkey: feeDistributorPda.pda,
+        isSigner: false,
+        isWritable: true
+      }
+    ],
+    programId: new PublicKey(programId),
+    data: instructionData
+  })
+
+  const tx = new Transaction().add(instruction)
+  return tx
+}

package/src/bigbang.ts

@@ -1,16 +1,22 @@
 import { Transaction, TransactionInstruction, PublicKey } from '@solana/web3.js'
+import BN from 'bn.js'
 import { programId } from './const'
+import { getFeeDistributorPda } from './helpers'
 
 /**
  * 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. Must be 2 or greater. The total number of copies will be replica_count + 1 (one original plus the replicas).
  * @returns A Promise that resolves to a Solana `Transaction` object containing the bigbang instruction.
  */
-export async function bigbang (wallet: PublicKey): Promise<Transaction> {
+export async function bigbang(replica_count:string,wallet: PublicKey): Promise<Transaction> {
   const instructionData = Buffer.concat([
-    Buffer.from(Int8Array.from([0]).buffer)
+    Buffer.from(Int8Array.from([0]).buffer),
+    Buffer.from(Int8Array.from([0]).buffer),
+    Buffer.from(Uint8Array.of(...new BN(replica_count).toArray('le', 8)))
   ])
+  let feeDistributorPda = getFeeDistributorPda()
 
   const instruction = new TransactionInstruction({
     keys: [
@@ -18,6 +24,11 @@ export async function bigbang (wallet: PublicKey): Promise<Transaction> {
         pubkey: wallet,
         isSigner: true,
         isWritable: true
+      },
+      {
+        pubkey: feeDistributorPda.pda,
+        isSigner: false,
+        isWritable: true
       }
     ],
     programId: new PublicKey(programId),

package/src/const.ts

@@ -1 +1,3 @@
-export const programId="xSHLJPXU8QW3A9kGiRoL94bksJ7ZZPY4dUwJPAT8CVK";
+export const programId="xSHLJPXU8QW3A9kGiRoL94bksJ7ZZPY4dUwJPAT8CVK";
+
+export const stoincProgramId="EaLDF7m76kzvrpeADHVHPLfk5qpPaPxYUYqYApByLp1S";

package/src/copyPath.ts

@@ -2,6 +2,7 @@ import { Transaction, TransactionInstruction, PublicKey } from '@solana/web3.js'
 import BN from 'bn.js'
 import { programId } from './const'
 import { sanitizePath } from './sanitizePath'
+import { getFeeDistributorPda } from './helpers.js'
 
 /**
  * Constructs a Solana transaction to copy a file or directory from one  path to another.
@@ -29,17 +30,23 @@ export async function copyPath (
   const rest = Buffer.from(`${srcPath}\0${destPath}`, 'utf-8')
 
   const instructionData = Buffer.concat([
+    Buffer.from(Int8Array.from([0]).buffer),
     Buffer.from(Int8Array.from([9]).buffer),
     Buffer.from(Uint8Array.of(...new BN(fsid).toArray('le', 8))),
     rest
   ])
-
+  let feeDistributorPda = getFeeDistributorPda()
   const instruction = new TransactionInstruction({
     keys: [
       {
         pubkey: wallet,
         isSigner: true,
         isWritable: true
+      },
+      {
+        pubkey: feeDistributorPda.pda,
+        isSigner: false,
+        isWritable: true
       }
     ],
     programId: new PublicKey(programId),

package/src/createDirectory.ts

@@ -2,6 +2,7 @@ import { Transaction, TransactionInstruction, PublicKey } from '@solana/web3.js'
 import BN from 'bn.js'
 import { programId } from './const'
 import { sanitizePath } from './sanitizePath'
+import { getFeeDistributorPda } from './helpers.js'
 
 /**
  * Constructs a Solana transaction to create a new directory within a  file system.
@@ -21,21 +22,27 @@ export async function createDirectory (
   wallet: PublicKey
 ): Promise<Transaction> {
   // Validate path: only letters, numbers, and /
-  let combinedPath = path + '/' + name
+  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([0]).buffer),
     Buffer.from(Int8Array.from([6]).buffer),
     Buffer.from(Uint8Array.of(...new BN(fsid).toArray('le', 8))),
     rest
   ])
-
+  let feeDistributorPda = getFeeDistributorPda()
   const instruction = new TransactionInstruction({
     keys: [
       {
         pubkey: wallet,
         isSigner: true,
         isWritable: true
+      },
+      {
+        pubkey: feeDistributorPda.pda,
+        isSigner: false,
+        isWritable: true
       }
     ],
     programId: new PublicKey(programId),

package/src/createFile.ts

@@ -2,7 +2,7 @@ import { Transaction, TransactionInstruction, PublicKey } from '@solana/web3.js'
 import BN from 'bn.js'
 import { programId } from './const'
 import { sanitizePath } from './sanitizePath'
-
+import { getFeeDistributorPda } from './helpers.js'
 /**
  * Constructs a Solana transaction to create a new file
  * within a file system, identified by a file system ID (`fsid`).
@@ -20,22 +20,28 @@ export async function createFile (
   name: string,
   wallet: PublicKey
 ): Promise<Transaction> {
-  let combinedPath = path + '/' + name
+  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([0]).buffer),
     Buffer.from(Int8Array.from([2]).buffer),
     Buffer.from(Uint8Array.of(...new BN(fsid).toArray('le', 8))),
     rest
   ])
-
+  let feeDistributorPda = getFeeDistributorPda()
   const instruction = new TransactionInstruction({
     keys: [
       {
         pubkey: wallet,
         isSigner: true,
         isWritable: true
+      },
+      {
+        pubkey: feeDistributorPda.pda,
+        isSigner: false,
+        isWritable: true
       }
     ],
     programId: new PublicKey(programId),

package/src/exists.ts

@@ -38,7 +38,8 @@ export interface RpcRequest {
   })
 
   if (!response.ok) {
-    throw new Error(`HTTP error! Status: ${response.status}`)
+    const errorText = await response.text(); 
+    return Error(`error! status: ${response.status}, message: ${errorText}`);
   }
 
   const data = await response.json()

package/src/find.ts

@@ -0,0 +1,53 @@
+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 search for a file or directory
+ * within a specified path.
+ *
+ * This function calls the custom RPC method `find`, 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 where the search will be performed (e.g., `/documents`).
+ * @param query - The query to search for (e.g., `'myfile.txt'`).
+ *
+ * @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 find (
+  connection: Connection,
+  path: string,
+  query: string,
+): Promise<any> {
+  const url = connection.rpcEndpoint;
+  const requestBody: RpcRequest = {
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'find',
+    params: [path,query]
+  }
+
+  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

@@ -41,7 +41,8 @@ export async function getMetadata (connection: Connection,path: string): Promise
   })
 
   if (!response.ok) {
-    throw new Error(`HTTP error! Status: ${response.status}`)
+    const errorText = await response.text(); 
+    return Error(`error! status: ${response.status}, message: ${errorText}`);
   }
 
   const data = await response.json()

package/src/getXandeumResult.ts

@@ -0,0 +1,67 @@
+
+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 maxAttempts = 3;
+    const delayMs = 5000;
+  
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      // Wait before every attempt (including the first one)
+      await sleep(delayMs);
+  
+      const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: 1,
+          method: "getXandeumResult",
+          params: [signature],
+        }),
+      });
+  
+      if (!response.ok) {
+        const text = await response.text();
+        console.error(`Attempt ${attempt}/${maxAttempts} failed: ${response.status} ${text}`);
+        if (attempt === maxAttempts) {
+          return { result: null, error: `HTTP ${response.status}` };
+        }
+        continue;
+      }
+  
+      const data = await response.json();
+  
+      // Change this condition if Xandeum uses a different "not ready" value
+      if (data?.result != null && data.result !== "pending") {
+        console.log(`Got result on attempt ${attempt}`);
+        return data; // Success — return immediately
+      }
+  
+      console.log(`Attempt ${attempt}/${maxAttempts}: still pending...`);
+    }
+  
+    // All 3 attempts done, still no result
+    console.log("Max attempts reached — result still not available");
+    return { result: null, error: "Result not ready after 3 attempts" };
+  }

package/src/helpers.ts

@@ -0,0 +1,85 @@
+import { PublicKey } from '@solana/web3.js'
+import { stoincProgramId } from './const'
+import BN from 'bn.js'
+
+/**
+ * Seed used for deriving the fee distributor PDA
+ */
+export const FEE_DISTRIBUTOR_SEED = 'fee_distributor'
+
+/**
+ * Duration of one pulse in seconds
+ */
+export const PULSE_DURATION_SECONDS = 15
+
+/**
+ * Number of pulses in one yuga
+ */
+export const PULSES_PER_YUGA = 16384
+
+/**
+ * Duration of one yuga in seconds (16384 * 15 = 245,760 seconds ≈ 2.84 days)
+ */
+export const YUGA_DURATION_SECONDS = PULSES_PER_YUGA * PULSE_DURATION_SECONDS
+
+/**
+ * Unix timestamp (in seconds) when the first yuga started
+ */
+export const YUGA_START_TIMESTAMP = 1768898445 
+
+/**
+ * Calculates the yuga number from a given unix timestamp.
+ * 
+ * @param unixTimestamp - Unix timestamp in seconds
+ * @returns The yuga number for the given timestamp
+ */
+export function getYugaFromTimestamp(unixTimestamp: number): number {
+  if (unixTimestamp < YUGA_START_TIMESTAMP) {
+    return 0
+  }
+  return Math.floor((unixTimestamp - YUGA_START_TIMESTAMP) / YUGA_DURATION_SECONDS)
+}
+
+/**
+ * Gets the current yuga value.
+ * Yuga represents an epoch or era in the Xandeum system.
+ * Each yuga lasts 245,760 seconds (approximately 2.84 days).
+ * 
+ * @returns The current yuga number
+ */
+export function getCurrentYuga(): number {
+  const currentTime = Math.floor(Date.now() / 1000)
+  return getYugaFromTimestamp(currentTime)
+}
+
+/**
+ * Derives the Program Derived Address (PDA) for the fee distributor account.
+ * 
+ * The PDA is derived using:
+ * - The fee distributor seed
+ * - The current yuga (epoch) as little-endian bytes
+ * 
+ * @returns An object containing the PDA public key and bump seed
+ * 
+ * @example
+ * ```typescript
+ * const { pda, bump } = getFeeDistributorPda()
+ * console.log('Fee Distributor PDA:', pda.toBase58())
+ * console.log('Bump seed:', bump)
+ * ```
+ */
+export function getFeeDistributorPda(): { pda: PublicKey; bump: number } {
+  const yuga = getCurrentYuga()
+  
+  const yugaBuffer = Buffer.from(new BN(yuga).toArray('le', 8))
+  
+  const [pda, bump] = PublicKey.findProgramAddressSync(
+    [
+      Buffer.from(FEE_DISTRIBUTOR_SEED, 'utf-8'),
+      yugaBuffer
+    ],
+    new PublicKey(stoincProgramId)
+  )
+  
+  return { pda, bump }
+}

package/src/index.ts

@@ -9,7 +9,11 @@ export * from "./peek";
 export * from "./poke";
 export * from "./removeDirectory";
 export * from "./copyPath";
-
+export * from "./move";
+export * from "./getXandeumResult";
+export * from "./assignCoowner";
 export {exists } from "./exists";
 export {listDirectoryEntry} from "./listDirectoryEntery";
 export {getMetadata} from "./getMetadata";
+export {find} from "./find";
+export * from "./helpers";

package/src/listDirectoryEntery.ts

@@ -42,7 +42,8 @@ export async function listDirectoryEntry (
   })
 
   if (!response.ok) {
-    throw new Error(`HTTP error! Status: ${response.status}`)
+    const errorText = await response.text(); 
+    return Error(`error! status: ${response.status}, message: ${errorText}`);
   }
 
   const data = await response.json()

package/src/move.ts

@@ -0,0 +1,62 @@
+import { Transaction, TransactionInstruction, PublicKey } from '@solana/web3.js'
+import BN from 'bn.js'
+import { programId } from './const'
+import { sanitizePath } from './sanitizePath'
+import { getFeeDistributorPda } from './helpers'
+
+/**
+ * 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([0]).buffer),
+    Buffer.from(Int8Array.from([13]).buffer),
+    Buffer.from(Uint8Array.of(...new BN(fsid).toArray('le', 8))),
+    rest
+  ])
+  let feeDistributorPda = getFeeDistributorPda()
+  const instruction = new TransactionInstruction({
+    keys: [
+      {
+        pubkey: wallet,
+        isSigner: true,
+        isWritable: true
+      },
+      {
+        pubkey: feeDistributorPda.pda,
+        isSigner: false,
+        isWritable: true
+      }
+    ],
+    programId: new PublicKey(programId),
+    data: instructionData
+  })
+
+  const tx = new Transaction().add(instruction)
+  return tx
+}

package/src/peek.ts

@@ -2,6 +2,7 @@ import { Transaction, TransactionInstruction, PublicKey } from '@solana/web3.js'
 import BN from 'bn.js'
 import { programId } from './const'
 import { sanitizePath } from './sanitizePath'
+import { getFeeDistributorPda } from './helpers'
 
 /**
  * Constructs a Solana transaction to perform a "peek" operation on a file within a file system.
@@ -28,19 +29,25 @@ export async function peek (
 
   const rest = Buffer.from(`${path}`, 'utf-8')
   const instructionData = Buffer.concat([
+    Buffer.from(Int8Array.from([0]).buffer),
     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
   ])
-
+  let feeDistributorPda = getFeeDistributorPda()
   const instruction = new TransactionInstruction({
     keys: [
       {
         pubkey: wallet,
         isSigner: true,
         isWritable: true
+      },
+      {
+        pubkey: feeDistributorPda.pda,
+        isSigner: false,
+        isWritable: true
       }
     ],
     programId: new PublicKey(programId),

package/src/poke.ts

@@ -2,6 +2,7 @@ import { Transaction, TransactionInstruction, PublicKey } from '@solana/web3.js'
 import BN from 'bn.js'
 import { programId } from './const'
 import { sanitizePath } from './sanitizePath'
+import { getFeeDistributorPda } from './helpers'
 
 /**
  * Constructs a Solana transaction to perform a poke\operation, which writes data
@@ -30,13 +31,14 @@ export async function poke (
   // 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([0]).buffer),
     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
   ])
-
+  let feeDistributorPda = getFeeDistributorPda()
   const instruction = new TransactionInstruction({
     keys: [
       {
@@ -48,6 +50,11 @@ export async function poke (
         pubkey: dataKey,
         isSigner: false,
         isWritable: false
+      },
+      {
+        pubkey: feeDistributorPda.pda,
+        isSigner: false,
+        isWritable: true
       }
     ],
     programId: new PublicKey(programId),

package/src/removeDirectory.ts

@@ -2,7 +2,7 @@ import { Transaction, TransactionInstruction, PublicKey } from '@solana/web3.js'
 import BN from 'bn.js'
 import { programId } from './const'
 import { sanitizePath } from './sanitizePath'
-
+import { getFeeDistributorPda } from './helpers'
 /**
  * Constructs a Solana transaction to perform a "remove directory" operation
  * in a  file system, identified by a file system ID (`fsid`).
@@ -21,17 +21,23 @@ export async function removeDirectory (
 ): Promise<Transaction> {
   sanitizePath(path)
   const instructionData = Buffer.concat([
+    Buffer.from(Int8Array.from([0]).buffer),
     Buffer.from(Int8Array.from([7]).buffer),
     Buffer.from(Uint8Array.of(...new BN(fsid).toArray('le', 8))),
     Buffer.from(`${path}`, 'utf-8')
   ])
-
+  let feeDistributorPda = getFeeDistributorPda()
   const instruction = new TransactionInstruction({
     keys: [
       {
         pubkey: wallet,
         isSigner: true,
         isWritable: true
+      },
+      {
+        pubkey: feeDistributorPda.pda,
+        isSigner: false,
+        isWritable: true
       }
     ],
     programId: new PublicKey(programId),

package/src/removeFile.ts

@@ -2,7 +2,7 @@ import { Transaction, TransactionInstruction, PublicKey } from '@solana/web3.js'
 import BN from 'bn.js'
 import { programId } from './const'
 import { sanitizePath } from './sanitizePath'
-
+import { getFeeDistributorPda } from './helpers'
 /**
  * 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.
@@ -22,17 +22,23 @@ export async function removeFile (
   sanitizePath(path)
 
   const instructionData = Buffer.concat([
+    Buffer.from(Int8Array.from([0]).buffer),
     Buffer.from(Int8Array.from([5]).buffer),
     Buffer.from(Uint8Array.of(...new BN(fsid).toArray('le', 8))),
     Buffer.from(`${path}`, 'utf-8')
   ])
-
+  let feeDistributorPda = getFeeDistributorPda()
   const instruction = new TransactionInstruction({
     keys: [
       {
         pubkey: wallet,
         isSigner: true,
         isWritable: true
+      },
+      {
+        pubkey: feeDistributorPda.pda,
+        isSigner: false,
+        isWritable: true
       }
     ],
     programId: new PublicKey(programId),