Tenzro Network

Developer Documentation

Tenzro Network

Introduction

The Tenzro Network is a decentralized computing platform that distributes computational tasks across a network of nodes. This documentation provides a detailed reference for developers looking to understand the Tenzro codebase and architecture.

Network Architecture

Node Types

The Tenzro Network consists of three types of nodes:

  1. Global Nodes: Coordinate task distribution across regions, participate in consensus, and aggregate final results. Key components:

    • GlobalNodeManager: Main entry point. Initializes and connects components.
    • GlobalTaskCoordinator: Handles cross-region task distribution.
    • CrossRegionTaskCoordinator: Manages task distribution to regions based on capacity and performance.
    • NetworkParameterManager: Manages global network parameters and validator requirements.
    • NetworkStateManager: Maintains a view of the global network state.

  2. Regional Nodes: Validate task execution within a region and aggregate results from Local Nodes. Key components:

    • ValidatorNode: Main entry point. Initializes and connects components.
    • ValidatorSystem: Handles task assignment to Local Nodes and result aggregation.
    • SignalingServer: Manages WebSocket connections and message routing.
    • MetricsCollector: Collects and aggregates network and node metrics.

  3. Local Nodes: Execute tasks and return results. Organized into tiers based on capabilities. Key components:

    • LocalNode: Main entry point. Initializes and connects components.
    • TaskManager: Handles task queueing, execution, and result reporting.
    • HardwareProfiler: Assesses node capabilities and tier.
    • ResourceManager: Manages allocation of node resources to tasks.
    • NodeAggregator: Allows nodes to dynamically aggregate to meet task requirements.

Networking

Nodes communicate over WebSocket connections. The networking layer is managed by:

  • DHTNetwork: A distributed hash table for node discovery and data storage.
  • LocalNetworkManager: Manages local network discovery, connections, and aggregations.

Messages are JSON-serialized and follow a defined type structure (NetworkMessage, SignalingMessage, etc.).

Task Execution Flow

  1. Task is submitted to a Global Node via the GlobalNodeManager.
  2. GlobalTaskCoordinator determines suitable regions and forwards the task.
  3. Within each region, the ValidatorSystem of a Regional Node distributes subtasks to capable Local Nodes.
  4. Local Nodes execute tasks via the TaskManager, utilizing resources managed by the ResourceManager.
  5. Local Nodes return results to their Regional Node's ValidatorSystem.
  6. Regional Nodes aggregate and validate results, forwarding them to the originating Global Node.
  7. The Global Node aggregates final results and returns them to the task submitter.

Node Configuration

Node configuration is managed via a combination of:

  • Environment variables (loaded via dotenv)
  • Configuration files (config/index.ts, config/default.json, etc.)
  • Command line arguments

Key configuration aspects include:

  • Node type and tier
  • Networking ports and discovery settings
  • Resource and capacity thresholds
  • Task execution and aggregation parameters

Security

Security features are integrated throughout the system:

  • Node identity is established via asymmetric key pairs (TBD: specific cryptographic scheme).
  • All network communications are encrypted (TBD: specific protocols - TLS, Noise, etc.).
  • Consensus is achieved via a proof-of-stake model, with Global Nodes required to stake TUXT tokens.
  • Regional Nodes stake tokens to participate in result validation. Malicious behavior can result in stake slashing.
  • Task and result data is encrypted end-to-end (TBD: specific encryption scheme).

Tokenomics

The TUXT token is central to the Tenzro economy:

  • Used for staking by Global and Regional Nodes.
  • Used for task payment by users.
  • Rewarded to Local Nodes for successful task completion.
  • Governs participation in network governance and upgrade decisions.

Token dynamics (supply, distribution, inflation, etc.) are defined in the system's economic model (TBD: link to economic model documentation).

Governance

Tenzro implements a decentralized governance model:

  • Protocol upgrades are governed by token-weighted voting.
  • Improvement proposals follow a structured process: draft, review, voting, implementation.
  • On-chain governance is implemented via a governance contract (TBD: link to contract).
  • Off-chain governance occurs via community forums and communication channels (TBD: links to community hubs).

Getting Started

Running a Node

  1. Clone the repository:

    git clone https://github.com/tenzro/tenzro-global-node.git
git clone https://github.com/tenzro/tenzro-regional-node.git
git clone https://github.com/tenzro/tenzro-local-node.git

  2. Install dependencies:

    npm install

  3. Configure your node: Copy the env.example file:

    cp .env.example .env

    Edit the .env file, setting your node type, tier, staking amount, etc.

  4. Start your node: Global Node:

    npm run start:global

    Regional Node:

    npm run start:regional

    Local Node:

    npm run start:local

Submitting a Task

Tasks can be submitted to a Global Node via its REST API:

curl -X POST -H "Content-Type: application/json" -d '{
  "type": "compute",
  "requirements": {
    "minTier": "aggregator",
    "cpu": 80,
    "memoryMB": 1024
  },
  "data": {
    "input": [1, 2, 3, 4, 5],
    "operations": ["square", "sum"] 
  }
}' http://global-node.tenzro.org/tasks

Retrieving Task Results

Task results can be retrieved from the Global Node via its REST API:

curl http://global-node.tenzro.org/tasks/TASK_ID/result

API Reference

Global Node API

POST /tasks

Submit a new task to the network.

Request:

{
  "type": "compute",
  "requirements": {
    "minTier": "aggregator",
    "cpu": 80,
    "memoryMB": 1024
  },
  "data": {
    "input": [1, 2, 3, 4, 5],
    "operations": ["square", "sum"]
  }  
}

Response:

{
  "taskId": "abc123",
  "status": "pending"
}

GET /tasks/:taskId

Get the status of a task.

Response:

{
  "taskId": "abc123",
  "status": "running",
  "progress": 0.5
}

GET /tasks/:taskId/result

Get the result of a completed task.

Response:

{
  "taskId": "abc123",
  "status": "completed",
  "result": 45
}

GET /network/state

Get the current global network state.

Response:

{
  "regions": [
    {
      "id": "us-east",
      "capacity": {
        "cpu": 0.7,
        "memory": 0.8,
        "storage": 0.5
      },
      "performanceScore": 0.9
    },
    {
      "id": "eu-west",
      "capacity": {
        "cpu": 0.6,
        "memory": 0.7,
        "storage": 0.8  
      },
      "performanceScore": 0.85
    }
  ],
  "globalCapacity": {
    "cpu": 0.65,
    "memory": 0.75,
    "storage": 0.6
  },
  "totalValidators": 10,
  "activeValidators": 8
}

Regional Node API

POST /tasks

Distribute a task to Local Nodes in the region.

Request:

{
  "taskId": "abc123",
  "type": "compute",
  "requirements": {
    "minTier": "aggregator",
    "cpu": 80,
    "memoryMB": 1024
  },
  "data": {
    "input": [1, 2, 3, 4, 5],
    "operations": ["square", "sum"]
  }
}

Response:

{
  "status": "distributing",
  "nodesAssigned": 5
}

POST /results

Submit a task result for aggregation and validation.

Request:

{
  "taskId": "abc123",
  "nodeId": "node123",
  "result": 25
}

Response:

{
  "status": "aggregating"
}

GET /network/state

Get the current regional network state.

Response:

{
  "nodes": [
    {
      "id": "node123",
      "type": "local", 
      "tier": "aggregator",
      "capacity": {
        "cpu": 0.8,
        "memory": 0.6,
        "storage": 0.7
      },
      "activeTaskCount": 2
    },
    {
      "id": "node456",
      "type": "local",
      "tier": "trainer",
      "capacity": {
        "cpu": 0.9,
        "memory": 0.8,
        "storage": 0.85
      },
      "activeTaskCount": 1  
    }
  ],
  "aggregations": [
    {
      "id": "agg123",
      "nodes": ["node123", "node456"],
      "capacity": {
        "cpu": 0.95,
        "memory": 0.9,
        "storage": 0.95
      }
    }
  ],
  "totalTasksInProgress": 5,
  "averageTaskDuration": 2500
}

Local Node API

POST /tasks

Receive a new task assignment.

Request:

{
  "taskId": "abc123",
  "type": "compute",
  "data": {
    "input": [1, 2],
    "operations": ["square", "sum"]
  }
}

Response:

{
  "status": "accepted"
}

GET /status

Get the current status of the node.

Response:

{
  "id": "node123",
  "type": "local", 
  "tier": "aggregator",
  "capacity": {
    "cpu": 0.8, 
    "memory": 0.6,
    "storage": 0.7
  },
  "activeTaskCount": 2,
  "aggregatedWith": "agg123"
}

POST /aggregate

Initiate an aggregation proposal with nearby nodes.

Request:

{
  "targetTier": "trainer",
  "timeout": 60000
}

Response:

{
  "proposalId": "proposal123",
  "status": "pending"
}

Events and Logging

Each node emits events that can be subscribed to for monitoring and logging purposes. Key events include:

Global Node Events

  • task_received: A new task was received from a user.
  • task_distributed: A task was successfully distributed to regions.
  • task_failed: A task failed to be processed.
  • network_state_changed: The global network state changed.

Regional Node Events

  • task_received: A new task was received from the Global Node.
  • subtask_completed: A Local Node completed its subtask.
  • task_aggregated: A task's results were fully aggregated from Local Nodes.
  • aggregation_state_changed: The state of an aggregation changed.

Local Node Events

  • task_assigned: The node was assigned a new task.
  • task_completed: The node completed a task.
  • aggregation_proposed: The node proposed an aggregation.
  • aggregation_succeeded: An aggregation proposal succeeded.
  • aggregation_failed: An aggregation proposal failed.
  • resource_critical: Node resources are critically low.
  • resource_recovered: Node resources recovered to normal levels.

Detailed logs are written to each node's logs directory, with log levels configurable via the LOG_LEVEL environment variable.

Conclusion

The Tenzro Network presents a complex, multi-tiered architecture for decentralized computing. Developers can participate by running nodes at any tier, or by submitting tasks to the network for processing.

This documentation provides a high-level overview of the key system components and APIs. For more detailed information, please refer to the source code and inline documentation.

As always, the Tenzro team welcomes feedback and contributions from the developer community. Together, we can build a robust, secure, and efficient platform for the future of decentralized computing.