Migration Guide: PoT-O v4.0 → v4.1 (Hexchain Integration)

PoT-O v4.1 introduces Hexchain, a spatially-organized consensus layer. This guide covers the changes and migration steps.

What's New in v4.1

1. Hexchain Consensus

New: Blocks are now organized in a hexagonal lattice using Hex Coordinate Projection (HCP).

Impact:

• Deterministic, leaderless consensus
• No central validator bottleneck
• Better support for distributed mining pools

2. New API Endpoints

Added to /api/hexchain/:

• POST /challenge – get challenge for current slot
• POST /submit – submit proof (returns depth and block_hash)
• GET /status – view lattice state
• GET /lattice – fetch all blocks
• GET /lattice/{q}/{r}/{s} – fetch block at coordinate

Deprecated: Old /challenge and /submit endpoints still work but are superseded by hexchain versions.

3. Client Updates Required

Miner CLI

If using pot-o-mine v4.0, update to v4.1:

# Get latest with hexchain support
git clone https://github.com/TribeWarez/pot-o-miner-cli.git
cd pot-o-miner-cli
git checkout main  # pulls hexchain dashboard + serialization alignment

New features:

• Automatic hexchain endpoint detection
• pot-o-mine-dashboard.py – TUI with hexchain metrics
• PoW serialization aligned with v4.1

Status API

The status dashboard (status.rpc.gateway.tribewarez.com) now proxies hexchain endpoints.

Old endpoint:

GET /api/live  → returns PoT-O state

New hexchain endpoints:

POST /api/hexchain/challenge
POST /api/hexchain/submit
GET /api/hexchain/status
GET /api/hexchain/lattice

ESP32 Firmware

ESP firmware (esp-pot-o-miner) v4.1 is hexchain-ready. Deploy via:

cd pot-o-validator/firmware/esp-pot-o-miner
platformio upload

No additional configuration needed; firmware auto-discovers hexchain endpoints.

Breaking Changes

1. Proof Submission Response

v4.0:

{
  "accepted": true,
  "tx_sig": "..."
}

v4.1:

{
  "accepted": true,
  "depth": 64,
  "block_hash": "0x..."
}

Migration: Update clients to expect depth and block_hash instead of tx_sig.

2. Challenge Structure

v4.0:

{
  "id": "challenge_123",
  "target_nonce": 1000
}

v4.1:

{
  "id": "challenge_123",
  "coord": {"q": 5, "r": -3, "s": -2},
  "slot": 98765
}

Migration: Update proof-of-work computation to target HCP coordinates instead of nonce targets.

3. Device Registration

v4.0:

POST /devices/register { "pubkey": "...", "device_type": "esp32" }

v4.1:

POST /devices/register {
  "pubkey": "...",
  "device_type": "esp32",
  "port": 5000  # NEW: local service port for callbacks
}

Migration: Include port field in device registration.

Migration Checklist

• [ ] Update pot-o-miner-cli to latest main
• [ ] Update miner scripts to call hexchain endpoints (/api/hexchain/...)
• [ ] Update device registration calls to include port field
• [ ] Update proof validation logic to handle depth and block_hash
• [ ] Deploy new ESP32 firmware from v4.1 branch
• [ ] Test challenge generation and proof submission
• [ ] Validate hexchain lattice queries
• [ ] Monitor /api/hexchain/status for lattice health

Testing Migration

1. Verify Hexchain Endpoints

# Check lattice status
curl https://status.rpc.gateway.tribewarez.com/api/hexchain/status

# Get current challenge
curl -X POST https://status.rpc.gateway.tribewarez.com/api/hexchain/challenge \
  -H "Content-Type: application/json" \
  -d '{"slot": 98765, "slot_hash": "0x..."}'

# Query lattice
curl https://status.rpc.gateway.tribewarez.com/api/hexchain/lattice

2. Test Proof Submission

curl -X POST https://status.rpc.gateway.tribewarez.com/api/hexchain/submit \
  -H "Content-Type: application/json" \
  -d '{
    "challenge_id": "challenge_xyz",
    "block": {
      "coord": {"q": 3, "r": -1, "s": -2},
      "pow_hash": "0x..."
    }
  }'

# Expect: { "accepted": true, "depth": N, "block_hash": "0x..." }

3. Monitor Dashboard

The status dashboard now shows:

• Hexchain lattice visualization
• Block depth distribution
• Occupied coordinate count
• P2P peer topology

Visit: https://status.rpc.gateway.tribewarez.com/

4. Run Miner with Dashboard

# Terminal 1: Start miner
./pot-o-mine --device-type cpu

# Terminal 2: Launch dashboard (shows hexchain metrics in real-time)
python3 pot-o-mine-dashboard.py

Rollback Plan

If issues arise, PoT-O v4.0 endpoints remain available but are deprecated:

# v4.0 fallback (still works in v4.1)
POST /challenge
POST /submit
GET /status

# But prefer v4.1 hexchain endpoints
POST /api/hexchain/challenge
POST /api/hexchain/submit
GET /api/hexchain/status

Support

• Issues: https://github.com/TribeWarez/pot-o-validator/issues
• Docs: https://docs.tribewarez.com/pot-o/hexchain
• Status Dashboard: https://status.rpc.gateway.tribewarez.com/