Skip to main content

The Namespace Object

The Koii Namespace Wrapper is a utility that helps Koii tasks interact with the network effortlessly. It handles task data, blockchain interactions, file operations, and node communication, so developers can focus on their core logic.

Core Features​

1. State Management​

Store and retrieve task data reliably:

// Store data
await namespaceWrapper.storeSet("key", "value");

// Retrieve data
const value = await namespaceWrapper.storeGet("key");

2. Blockchain Integration​

Securely interact with the Koii Network:

// Send a transaction
const tx = await namespaceWrapper.sendTransaction(
  senderAccount,
  receiverAccount,
  amount,
);

// Get network status
const nodes = await namespaceWrapper.getNodes();

3. File System Operations​

Handle files consistently across environments:

// Create a directory
await namespaceWrapper.fs("mkdir", "data");

// Write a file
await namespaceWrapper.fs("writeFile", "data/config.json", "{}");

// Read a file
const content = await namespaceWrapper.fs("readFile", "data/config.json");

4. Task Management​

Manage task state and rounds:

// Get current round
const round = await namespaceWrapper.getRound();

// Submit task results
await namespaceWrapper.checkSubmissionAndUpdateRound(submission, round);

Benefits of Using the Namespace Wrapper​

  1. Simplified Development

    • No need to handle low-level infrastructure
    • Consistent APIs across different operations
    • Built-in error handling and security

  2. Better Code Organization

    • Clear separation of concerns
    • Standardized interfaces
    • Modular architecture

  3. Enhanced Security

    • Secure blockchain interactions
    • Protected file system access
    • Safe state management

  4. Improved Reliability

    • Automatic error handling
    • Built-in retries for network operations
    • Data persistence

Common Use Cases​

1. Data Storage​

async function saveUserData(userId: string, data: object) {
  try {
    // Store user data
    await namespaceWrapper.storeSet(`user_${userId}`, JSON.stringify(data));
    // Verify storage
    const stored = await namespaceWrapper.storeGet(`user_${userId}`);
    return JSON.parse(stored);
  } catch (error) {
    console.error("Failed to save user data:", error);
    throw error;
  }
}

2. Task Submissions​

async function submitTaskResult(submission: string) {
  try {
    const round = await namespaceWrapper.getRound();
    await namespaceWrapper.checkSubmissionAndUpdateRound(submission, round);
    console.log("Task result submitted for round:", round);
  } catch (error) {
    console.error("Submission failed:", error);
    throw error;
  }
}

3. File Management​

async function processDataFile(filename: string) {
  try {
    // Read input file
    const data = await namespaceWrapper.fs("readFile", filename, "utf8");

    // Process data
    const processed = await processData(data);

    // Save results
    await namespaceWrapper.fs("writeFile", `processed_${filename}`, processed);
  } catch (error) {
    console.error("File processing failed:", error);
    throw error;
  }
}

Best Practices​

  1. Always Use Error Handling
try {
  await namespaceWrapper.storeSet("key", "value");
} catch (error) {
  console.error("Operation failed:", error);
  // Implement appropriate error recovery
}
  1. Validate Input Data
function validateData(data: any) {
  if (!data || typeof data !== "object") {
    throw new Error("Invalid data format");
  }
  // Add more validation as needed
}
  1. Log Important Operations
await namespaceWrapper.logger(
  "log",
  "Task completed successfully",
  "TaskCompletion",
);

Next Steps​

To learn more about specific features, check out these guides: