Documentation

Everything you need to run a node, submit tasks, and build on the EPOCH network.

EPOCH is a decentralized AI compute network. Providers contribute idle GPU, CPU, and RAM resources to process AI training and inference workloads, earning $EPOCH tokens for every verified computation. This documentation covers node setup, CLI usage, network architecture, and the developer API.

TIP

Just want to get running? Jump to Quickstart for the 60-second setup.

$EPOCH TOKEN

Contract Address (Solana):
qMZ1x49irpPzkr8JdXYLvC3sBYKnSfYx2AgJztGpump [COPY]

Quickstart

Get your node online in under 60 seconds.

bash
# Install the EPOCH node client
curl -sSf https://get.epochprotocol.tech | sh

# Initialize with your Solana wallet
epoch-node --init --wallet <YOUR_SOL_ADDRESS>

# Start contributing compute
epoch-node --start

# Check your status
epoch-node --status

That's it. The client auto-detects your hardware, registers on the network, and starts accepting tasks. Rewards begin accumulating immediately.

System Requirements

Minimum

GPU: NVIDIA GPU with 4GB+ VRAM (CUDA 11.8+) or AMD GPU with ROCm 5.7+
CPU: 4 cores
RAM: 8 GB
Storage: 20 GB free SSD space
Network: 50 Mbps down / 20 Mbps up
OS: Ubuntu 22.04+, macOS 13+, Windows 11 (WSL2)

Installation

bash
# One-line install (Ubuntu/Debian/Fedora/Arch)
curl -sSf https://get.epochprotocol.tech | sh

# Or manual install
wget https://releases.epochprotocol.tech/latest/epoch-node-linux-x64.tar.gz
tar xzf epoch-node-linux-x64.tar.gz
sudo mv epoch-node /usr/local/bin/
epoch-node --version

bash
# Homebrew
brew tap epoch-protocol/epoch
brew install epoch-node

# Or direct install
curl -sSf https://get.epochprotocol.tech | sh

powershell
# Requires WSL2 with Ubuntu
wsl --install -d Ubuntu
# Then inside WSL:
curl -sSf https://get.epochprotocol.tech | sh

bash
# NVIDIA Container Toolkit required
docker run -d \
  --gpus all \
  --name epoch-node \
  -e WALLET=<YOUR_SOL_ADDRESS> \
  -v epoch-data:/data \
  epochprotocol/node:latest

Node Setup

Initialization

After installation, initialize your node with a Solana wallet address. This is where your $EPOCH rewards will be sent.

bash
epoch-node --init --wallet <SOL_ADDRESS>

# Output:
[INFO] Hardware scan complete
[INFO] GPU: NVIDIA RTX 4090 (24576 MB VRAM)
[INFO] CUDA Version: 12.4
[INFO] CPU: AMD Ryzen 9 7950X (16 cores)
[INFO] RAM: 64 GB available
[INFO] Storage: 450 GB NVMe free
[INFO] Network: 520 Mbps down / 340 Mbps up
[OK] Node ID: ep-node-a7f3c9e2
[OK] Registered on EPOCH network
[OK] Hardware attestation passed

Starting Your Node

bash
# Start in foreground (for testing)
epoch-node --start

# Start as background daemon (recommended)
epoch-node --start --daemon

# Start with resource limits
epoch-node --start --gpu-limit 80 --ram-limit 75

# Enable auto-start on boot
epoch-node --enable-autostart

Configuration

Node configuration lives in ~/.epoch/config.toml. You can edit it directly or use the CLI.

toml
# ~/.epoch/config.toml

[node]
wallet = "YOUR_SOL_ADDRESS"
name = "my-epoch-node"
region = "us-west"

[resources]
gpu_limit = 90          # Max GPU utilization %
ram_limit = 80          # Max RAM allocation %
cpu_limit = 75          # Max CPU threads %
storage_limit = "50GB" # Max scratch space

[schedule]
active_hours = "00:00-23:59"  # When to accept tasks
idle_only = false             # Only run when system is idle

[network]
max_bandwidth = "100MB/s"
preferred_tasks = ["inference", "fine-tuning"]

[rewards]
auto_claim = true
claim_threshold = 100  # Min $EPOCH before auto-claim

GPU Management

The node client manages GPU allocation automatically. Multi-GPU systems can dedicate specific GPUs to EPOCH.

bash
# List detected GPUs
epoch-node gpu list

# Assign specific GPUs
epoch-node gpu assign 0,1    # Use GPUs 0 and 1
epoch-node gpu exclude 2     # Keep GPU 2 for personal use

# View real-time GPU utilization
epoch-node gpu stats

GPU 0: RTX 4090  | Util: 87% | VRAM: 18.2/24.0 GB | Temp: 72C | Task: llm-inference-7a3f
GPU 1: RTX 4090  | Util: 92% | VRAM: 21.1/24.0 GB | Temp: 74C | Task: lora-train-c901
GPU 2: RTX 3060  | Util:  0% | VRAM:  0.0/12.0 GB | Temp: 38C | Excluded

Monitoring

bash
# Full node status
epoch-node --status

+-----------------------------------+
|  EPOCH Node: ep-node-a7f3c9e2     |
+-----------------------------------+
  Status:       ONLINE
  Uptime:       14d 7h 23m
  Tasks Done:   1,847
  Active Tasks: 2
  $EPOCH Earned: 4,291.7
  Pending:      127.3 $EPOCH
  GPU Load:     84%
  Network:      Connected (43 peers)
  PoC Score:    99.8%

# Live dashboard in terminal
epoch-node --monitor

# Export metrics (Prometheus compatible)
epoch-node metrics --export :9090

CLI Reference

The epoch-node CLI is the primary interface for managing your node.

Commands

Command	Description	Example
`--init`	Initialize node with wallet	`epoch-node --init --wallet SOL...`
`--start`	Start accepting tasks	`epoch-node --start --daemon`
`--stop`	Gracefully stop node	`epoch-node --stop`
`--status`	Show node status summary	`epoch-node --status`
`--monitor`	Live TUI dashboard	`epoch-node --monitor`
`--benchmark`	Run hardware benchmark	`epoch-node --benchmark`
`gpu list`	List detected GPUs	`epoch-node gpu list`
`gpu assign`	Assign GPUs to EPOCH	`epoch-node gpu assign 0,1`
`gpu stats`	Real-time GPU metrics	`epoch-node gpu stats`
`rewards`	View earned rewards	`epoch-node rewards`
`rewards --claim`	Claim pending rewards	`epoch-node rewards --claim`
`network --stats`	Network-wide statistics	`epoch-node network --stats`
`config set`	Set config value	`epoch-node config set gpu_limit 90`
`logs`	View node logs	`epoch-node logs --tail 100`
`update`	Update node client	`epoch-node update`

Configuration File

Config file location: ~/.epoch/config.toml

Override any config value from CLI:

bash
epoch-node config set resources.gpu_limit 85
epoch-node config set schedule.active_hours "22:00-08:00"
epoch-node config get rewards.auto_claim
epoch-node config reset  # Reset to defaults

Network Overview

The EPOCH network consists of three node types:

Provider Nodes: Contribute compute resources and execute tasks. This is what you run.
Orchestrator Nodes: Route tasks to providers using the DHT mesh. High-uptime providers are automatically promoted.
Validator Nodes: Verify computation via the PoC challenge protocol. Require staking $EPOCH.

All communication is encrypted (TLS 1.3 + noise protocol). Node discovery uses a Kademlia-based DHT. Task data is encrypted at rest and wiped after verification.

Proof of Compute

See the Whitepaper Section 05 for the full PoC specification. In summary:

Tasks produce deterministic checkpoint hashes during execution
Validators re-execute a random 3-5% subset of checkpoints
Matching hashes verify correct computation
Verified results are settled on Solana

Task Lifecycle

text
SUBMITTED -> QUEUED -> MATCHED -> EXECUTING -> VERIFYING -> COMPLETED
                                                                 \-> FAILED (re-route)
                                                \-> DISPUTED (3-node re-exec)

SDK / API BETA

Submit AI workloads to the EPOCH network programmatically.

python
from epoch import EpochClient

client = EpochClient(api_key="ep_...")

# Submit an inference task
task = client.submit(
    workload="inference",
    model="meta-llama/Llama-3-70B",
    inputs=["What is EPOCH protocol?"],
    max_bid=0.5,  # $EPOCH per request
    timeout=60
)

# Wait for result
result = task.wait()
print(result.output)

# Submit a fine-tuning job
job = client.submit(
    workload="fine-tune",
    base_model="meta-llama/Llama-3-8B",
    dataset="s3://my-bucket/train.jsonl",
    method="lora",
    epochs=3,
    max_bid=50.0
)

print(f"Job {job.id} submitted. ETA: {job.estimated_time}")

Submitting Tasks

bash
# REST API
curl -X POST https://api.epochprotocol.tech/v1/tasks \
  -H "Authorization: Bearer ep_..." \
  -H "Content-Type: application/json" \
  -d '{
    "workload": "inference",
    "model": "meta-llama/Llama-3-70B",
    "inputs": ["Explain EPOCH protocol"],
    "max_bid": 0.5
  }'

Webhooks

Get notified when tasks complete:

json
// POST to your webhook URL
{
  "event": "task.completed",
  "task_id": "ep-task-9f2a...",
  "status": "completed",
  "result_url": "https://results.epochprotocol.tech/...",
  "cost": 0.42,
  "compute_time_ms": 3847,
  "provider_node": "ep-node-a7f3..."
}

FAQ

How much can I earn?

Earnings depend on your hardware, uptime, and network demand. A single RTX 4090 running 24/7 at current network utilization earns approximately 40-80 $EPOCH per day. Multi-GPU setups scale linearly.

Is my data safe?

Task data is encrypted in transit and at rest. The GPU sandbox prevents your node from accessing data outside assigned work packets. All data is wiped after task verification.

Can I run EPOCH alongside gaming?

Yes. Use idle_only = true in config or set active_hours to your away times. The node client detects foreground GPU usage and pauses tasks automatically.

What if my node goes offline?

Active tasks are re-routed to another node within 120 seconds. You won't be penalized for occasional downtime, but uptime affects your node score and task priority.

Do I need to stake $EPOCH to run a provider node?

No. Provider nodes require zero stake. Only validator nodes require staking. Anyone with compatible hardware can provide compute immediately.

Which blockchains are supported?

Settlement is on Solana. Rewards are paid in SPL $EPOCH tokens. Multi-chain settlement (EVM L2s) is planned for Phase 4.

Troubleshooting

Node won't start

bash
# Check CUDA/ROCm installation
epoch-node diagnose

# Common fix: update GPU drivers
sudo apt install nvidia-driver-550

# Reset node state
epoch-node --reset

# Verbose logging
epoch-node --start --log-level debug

Low task assignment

If your node isn't receiving tasks:

Check your node score: epoch-node --status (aim for 0.70+)
Ensure ports 4001 and 4002 are open (or UPnP enabled)
Verify network connectivity: epoch-node network --diagnose
Upgrade hardware if VRAM is below 8GB (most tasks require 8GB+)

Changelog

v0.3.0 (June 2025)

Added Docker deployment support
Multi-GPU assignment and exclusion
Prometheus metrics export
Auto-claim rewards feature

v0.2.0 (May 2025)

Hardware attestation v2 (faster benchmark)
macOS Metal backend (beta)
Task scheduling by time window

v0.1.0 (April 2025)

Initial release
CUDA support, basic inference tasks
Solana settlement, PoC v1