⚡ hb-status

Enterprise-grade monitoring, synchronization, and deployment toolkit for HyperBEAM node operators on the Arweave/AO network

Caution

🚨 ARCHIVAL NOTICE

This repository is permanently archived and no longer maintained.

❌ No new features will be added
❌ No bug fixes will be provided
❌ No security updates will be issued
❌ Issues and pull requests are disabled

The code is provided "AS IS" for historical reference and educational purposes only. Use at your own risk.

Overview • Features • Architecture • Quick Start • Tools • Deployment • Attribution

📖 Overview

hb-status is a comprehensive command-line toolkit designed for operating HyperBEAM nodes at scale on the Arweave / AO network. It provides deep observability into node synchronization state, automates the "hydration" process for AMM pools, and includes battle-tested scripts for deploying and managing node clusters.

┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│   🚀 MONITOR  →  📊 SYNC  →  ✅ VERIFY  →  🔄 AUTOMATE  →  📈 SCALE       │
│                                                                             │
│   Real-time      Intelligent    Cross-network    Daemon-based    Multi-node │
│   slot tracking  hydration      verification     scheduling      management │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

✨ Features

📊 Status Monitoring

Real-time slot height tracking
Endpoint health checks
Latency metrics collection
Automated report generation (MD/CSV)

🔄 Sync Automation

Intelligent batch processing
Configurable timeouts
Progress persistence across restarts
Deficit-only processing mode

✅ Data Verification

Cross-network reserve comparison
HyperBEAM ↔ AO validation
Mismatch detection & reporting
Batch verification support

🚀 Fleet Management

Parallel multi-server deployment
SSH-based remote execution
Health monitoring services
Systemd integration

🏗️ Architecture

flowchart TB
    subgraph Control["🎛️ hb-status Control Plane"]
        direction TB
        CLI["📊 index.ts<br/><i>Status Reporter</i>"]
        SYNC["🔄 sync-daemon.ts<br/><i>Orchestrator</i>"]
        HYDRATE["💧 hydrate-daemon.ts<br/><i>Advanced Sync</i>"]
        VERIFY["✅ compare-reserves.ts<br/><i>Verifier</i>"]
        UTIL["🔧 Utilities<br/><i>convert, filter, fetch</i>"]
    end

    subgraph Infra["☁️ HyperBEAM Infrastructure"]
        direction TB
        GW["🌐 Gateway / Load Balancer"]
        HB1["📦 HB Node 1"]
        HB2["📦 HB Node N"]
        CU["⚙️ Compute Unit"]
    end

    subgraph Arweave["🔗 Arweave Network"]
        AO["🌍 AO Network"]
    end

    CLI -- "GET /slot/current<br/>GET /compute/at-slot" --> GW
    SYNC -- "POST /~cron@1.0/once<br/>GET /now" --> GW
    HYDRATE -- "Batch sync<br/>Auto-schedule" --> GW
    VERIFY -- "GET /now/reserves" --> GW
    VERIFY -- "POST /dry-run" --> AO

    GW --> HB1
    GW --> HB2
    HB1 <--> CU
    HB2 <--> CU

Data Flow

┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Config     │────▶│   Monitor    │────▶│   Sync       │────▶│   Verify     │
│   (JSON)     │     │   Status     │     │   Pools      │     │   Reserves   │
└──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘
       │                    │                    │                    │
       │                    ▼                    ▼                    ▼
       │             ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
       │             │   Reports    │     │   State      │     │   Comparison │
       │             │   (MD/CSV)   │     │   (JSON)     │     │   Reports    │
       │             └──────────────┘     └──────────────┘     └──────────────┘
       │
       └─────────────────────────────────────────────────────────────────────┐
                                                                             │
┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────▼
│   Deploy     │────▶│   Setup      │────▶│   Services   │────▶│   Fleet      │
│   Scripts    │     │   Nodes      │     │   (systemd)  │     │   Management │
└──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘

🚀 Quick Start

Prerequisites

Requirement	Version	Notes
Bun	1.0+	Primary runtime
Git	2.0+	For cloning
HyperBEAM Node	—	Target endpoint

Installation

# Clone the repository
git clone https://github.com/autonomous-research/hb-status.git
cd hb-status

# Install dependencies
bun install

# Create your configuration
cp example-config.json config.json

First Run

# Check status of your configured processes
bun run index.ts config.json

📸 Example Output

🚀 Starting to query 2 processes...

📊 Process Status Report
════════════════════════════════════════════════════════════════════════════════

🔄 Example AMM Pool
   📍 Process ID: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   🌐 Base URL: http://localhost:8734/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX~process@1.0
   📊 Slots: Computed=156432, Current=156432
   ⏱️  Slot Query Time: 45ms

   📡 Endpoints (2):
      ✅ now/reserves
         Response: {"token_a":"1000000000","token_b":"500000000"...
         Time: 120ms
      ✅ compute/cache/serialize~json@1.0
         Response: {"state":"active"}
         Time: 85ms

   ⏰ Total Process Time: 250ms

════════════════════════════════════════════════════════════════════════════════

📈 Overall Summary:
   Processes: 2
   Successful Slot Queries: 2/2
   Total Endpoints: 3
   Successful Endpoints: 3/3

⏱️  Performance Metrics:
   Total Execution Time: 330ms
   Average Process Time: 165ms

════════════════════════════════════════════════════════════════════════════════

📄 Reports exported:
   - Markdown: exports/status-report-2024-01-15T10-30-00.md
   - CLI Output: exports/status-report-2024-01-15T10-30-00.txt

⚙️ Configuration

All tools read from a JSON configuration file that defines your HyperBEAM processes.

Schema

{
  "baseUrl": "http://your-hb-gateway:8734",
  "processes": [
    {
      "name": "Human-Readable Name",
      "processId": "<43-character-arweave-process-id>",
      "endpoints": ["info", "metrics", "custom/path"],
      "baseUrl": "http://override-per-process:8734"  // optional
    }
  ]
}

Field Reference

Field	Type	Required	Description
`baseUrl`	`string`	○	Default gateway URL (defaults to `http://localhost:8080`)
`processes`	`array`	●	Array of process definitions
`processes[].name`	`string`	●	Display name for reports
`processes[].processId`	`string`	●	43-character Arweave Process ID
`processes[].endpoints`	`string[]`	○	Custom endpoints to query
`processes[].baseUrl`	`string`	○	Per-process URL override

Example

{
  "baseUrl": "http://localhost:8734",
  "processes": [
    {
      "name": "Token Liquidity Pool",
      "processId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX1",
      "endpoints": ["now/reserves", "compute/cache/serialize~json@1.0"]
    },
    {
      "name": "Price Oracle",
      "processId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX2",
      "endpoints": ["compute/cache/price"]
    }
  ]
}

🛠️ Tools Reference

Overview

Tool	Purpose	Use Case
`index.ts`	Status monitoring	Dashboard & health checks
`sync.ts`	One-time sync	Manual hydration
`sync-daemon.ts`	Continuous sync	Background hydration
`hydrate-daemon.ts`	Advanced sync	Intelligent scheduling
`compare-reserves.ts`	Verification	Data integrity checks
`convert-pools.ts`	Data conversion	Config generation
`filter-big-pools.ts`	Filtering	Prioritize active pools
`fetch-current-slots.ts`	Bulk queries	Slot analysis
`syncing-pools-report.ts`	Reporting	Progress tracking

📊 Status Reporter — `index.ts`

The primary dashboard for node health monitoring.

# From config file
bun run index.ts config.json

# From inline JSON
bun run index.ts '{"processes":[{"name":"Test","processId":"...","endpoints":["info"]}]}'

# From stdin (useful in pipelines)
cat config.json | bun run index.ts

What it does:

Queries compute/at-slot → Returns computed (synced) slot
Queries slot/current → Returns current (network tip) slot
Calls each custom endpoint in endpoints[]
Measures latency for all requests
Exports reports to exports/

🔄 Sync Daemon — `sync-daemon.ts`

Continuous synchronization wrapper for long-running hydration.

bun run sync-daemon.ts <config.json> [timeout_seconds] [delay_seconds]

Argument	Default	Description
`config.json`	—	Path to configuration file
`timeout_seconds`	`300`	Max time per sync pass
`delay_seconds`	`60`	Delay between runs

💧 Hydrate Daemon — `hydrate-daemon.ts`

Advanced synchronization with intelligent scheduling and state persistence.

bun run hydrate-daemon.ts <config.json> [options]

Option	Description
`--no-schedule`	Disable auto cron scheduling
`--deficit-only`	Only process pools with deficit
`--force-reinit`	Force re-init for deficit processes
`--batch-size N`	Processes per batch (default: 20)
`--batch-delay N`	Ms between batches (default: 2000)

Generated files:

hydrate-daemon-state.json — Persistent state
hydrate-daemon-state.md — Human-readable status
hydrate-daemon-metrics.json — Historical metrics
hydrate-daemon-errors.txt — Error report

📸 Live Dashboard Output

🚀 Hydrate Daemon Status - 1/15/2024, 10:30:00 AM
🕒 Runtime: 45 minutes | 🎯 Synced: 142/200 | 🔄 Behind: 58 | ❌ Errors: 0
📈 Total Deficit: 125,430 slots | Avg Rate: 85.2 slots/min | ETA: 11:55 AM
════════════════════════════════════════════════════════════════════════════════
Process                  Process ID                             Init  Sched  Status
────────────────────────────────────────────────────────────────────────────────
Pool Alpha               XXXXXXXXX...                           ✅    ✅     ✅ Synced
Pool Beta                YYYYYYYYY...                           ✅    ⏳     🔄 Syncing
Pool Gamma               ZZZZZZZZZ...                           ✅    ⏳     🔄 Syncing

✅ Reserve Verifier — `compare-reserves.ts`

Cross-validate token reserves between HyperBEAM and AO network.

# Check first 25 pools
bun run compare-reserves.ts --limit 25

# Custom output file
bun run compare-reserves.ts --limit 100 --output audit-report.md

🔧 Utility Scripts

Tool	Command	Purpose
convert-pools.ts	`bun run convert-pools.ts pools.json -o config.json`	Convert AO pools dump to config
filter-big-pools.ts	`bun run filter-big-pools.ts config.json --threshold 50000`	Filter active pools
fetch-current-slots.ts	`bun run fetch-current-slots.ts config.json --format csv`	Bulk slot queries
syncing-pools-report.ts	`bun run syncing-pools-report.ts --format csv`	Sync progress report

🌐 API Reference

HyperBEAM Endpoints

Endpoint	Method	Description
`/{processId}/slot/current`	GET	Current network slot height
`/{processId}/compute/at-slot`	GET	Locally computed slot height
`/{processId}/now`	GET	Trigger sync to current slot
`/{processId}/now/reserves`	GET	Token reserves (AMM pools)
`/~cron@1.0/once`	GET	One-time cron execution
`/~cron@1.0/every`	GET	Schedule recurring cron

AO Network Endpoints

Endpoint	Method	Description
`/dry-run?process-id={id}`	POST	Read-only message execution

🚢 Deployment

The hb-starter/ directory contains production-ready scripts for server management.

hb-starter/
├── setup-hb-node.sh      # Provision fresh server
├── deploy-hb-node.sh     # Deploy to single server
├── deploy-multiple.sh    # Parallel multi-server deploy
├── manage-hb-nodes.sh    # Fleet management
├── hb-services.sh        # Systemd service management
├── run-node.sh           # Manual node runner
├── run-cu.sh             # Manual CU runner
└── config.flat           # Example configuration

Quick Deployment

# 1. Create hosts file
cat > hosts.txt <<EOF
192.168.1.100
192.168.1.101
192.168.1.102
EOF

# 2. Deploy to all hosts
./hb-starter/deploy-multiple.sh -f hosts.txt -u ubuntu -k ~/.ssh/key.pem -w wallet.json

# 3. Check status across fleet
./hb-starter/manage-hb-nodes.sh -f hosts.txt status

# 4. View logs from all nodes
./hb-starter/manage-hb-nodes.sh -f hosts.txt logs cu

📖 See hb-starter/README-DEPLOYMENT.md for complete documentation.

📁 Project Structure

hb-status/
├── index.ts                  # Main status reporter
├── sync.ts                   # One-time sync script
├── sync-daemon.ts            # Continuous sync wrapper
├── hydrate-daemon.ts         # Advanced hydration daemon
├── compare-reserves.ts       # Reserve verification
├── convert-pools.ts          # Config converter
├── filter-big-pools.ts       # Pool filter utility
├── fetch-current-slots.ts    # Bulk slot fetcher
├── syncing-pools-report.ts   # Progress reporter
├── lib/
│   └── runner.ts             # Process runner class
├── hb-starter/               # Deployment scripts
│   ├── *.sh                  # Shell scripts
│   └── README-*.md           # Documentation
├── example-config.json       # Example configuration
├── package.json              # Dependencies
├── tsconfig.json             # TypeScript config
└── LICENSE                   # MIT License

🤝 Attribution

Developed by

Supporting the HyperBEAM operator community

📄 License

MIT License

Copyright (c) 2024 Autonomous Research

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

_{Built with ❤️ for the Arweave ecosystem

Arweave •
AO •
HyperBEAM}

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
hb-starter		hb-starter
lib		lib
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
compare-reserves.ts		compare-reserves.ts
convert-pools.ts		convert-pools.ts
example-config.json		example-config.json
fetch-current-slots.ts		fetch-current-slots.ts
filter-big-pools.ts		filter-big-pools.ts
hydrate-daemon.ts		hydrate-daemon.ts
index.ts		index.ts
package.json		package.json
sync-daemon.ts		sync-daemon.ts
sync.ts		sync.ts
syncing-pools-report.ts		syncing-pools-report.ts
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

⚡ hb-status

🚨 ARCHIVAL NOTICE

📖 Overview

✨ Features

📊 Status Monitoring

🔄 Sync Automation

✅ Data Verification

🚀 Fleet Management

🏗️ Architecture

Data Flow

🚀 Quick Start

Prerequisites

Installation

First Run

⚙️ Configuration

Schema

Field Reference

Example

🛠️ Tools Reference

Overview

📊 Status Reporter — index.ts

🔄 Sync Daemon — sync-daemon.ts

💧 Hydrate Daemon — hydrate-daemon.ts

✅ Reserve Verifier — compare-reserves.ts

🔧 Utility Scripts

🌐 API Reference

HyperBEAM Endpoints

AO Network Endpoints

🚢 Deployment

Quick Deployment

📁 Project Structure

🤝 Attribution

📄 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

📊 Status Reporter — `index.ts`

🔄 Sync Daemon — `sync-daemon.ts`

💧 Hydrate Daemon — `hydrate-daemon.ts`

✅ Reserve Verifier — `compare-reserves.ts`

Packages