Qubestr Relay

A specialized Nostr relay for the HyperQube Network.

Overview

Qubestr is a custom Nostr relay built using the Khatru framework. It is designed to be a secure and reliable communication channel between HyperCore One developers and the HyperQube network nodes.

The relay exclusively handles two custom event kinds:

• HyperSignal (Kind 33321): Used by HC1 developers to broadcast commands to HyperQube nodes, such as software upgrades or network reboots.
• Action Acknowledgement (Kind 3333): Used by HyperQube nodes to report back the status (success or failure) of a command they have executed.

For a detailed technical specification of these custom Nostr events, please see hyperqube-events.md.

Features

Core Features

• Built with Khatru: A high-performance, lightweight, and customizable relay framework.
• PostgreSQL Backend: Uses a PostgreSQL database for robust and persistent event storage.
• Dockerized: Comes with docker-compose.yml for easy and reproducible deployment.
• Specialized Logic: Contains strict validation rules from the hyperqube-events repository tailored specifically for HyperQube network events.

Custom Event Support

• HyperSignal (Kind 33321): Events for broadcasting node management commands.
• Action Acknowledgement (Kind 3333): Events for nodes to report the status of executed commands.

Security Policy

• Only public keys defined in the AUTHORIZED_PUBKEYS environment variable can publish HyperSignal (kind 33321) events. This ensures that only trusted HC1 developers can issue commands to the network.

API Endpoints

• WebSocket: ws://localhost:3334
• HTTP: http://localhost:3334 (Returns a simple HTML welcome page)

Production Note: For production deployments, you should use a reverse proxy (e.g., Nginx, Caddy) to provide SSL/TLS termination, enabling secure WebSocket connections (wss://) and HTTPS. This is required for web clients that only work over secure connections.

Quick Start

1. Clone the repository:

   git clone https://github.com/hypercore-one/qubestr.git
   cd qubestr

2. Configure your environment: Copy the example .env.example file to .env and fill in the required values.

   cp .env.example .env

   At a minimum, you must set AUTHORIZED_PUBKEYS and RELAY_ADMIN_PUBKEY.

3. Run with Docker Compose: This is the recommended method for production.

   docker compose up --build -d

   The relay will be available at ws://localhost:3334.

4. Updating the relay: When pulling updates from the repository, rebuild the Docker container from scratch:

   git pull
   docker compose down
   docker compose up --build -d

Development

Prerequisites

• Go (version 1.25 or higher)
• Docker (for running PostgreSQL)
• An understanding of the Nostr protocol.

Development Setup

1. Clone and enter the directory:

   git clone https://github.com/hypercore-one/qubestr.git
   cd qubestr

2. Install dependencies:

   go mod tidy

3. Start a PostgreSQL database: You can use the provided docker-compose.yml to start only the database:

   docker compose up -d postgres

   Alternatively, run PostgreSQL locally.

4. Set up environment variables: Create a .env file and configure it for your local setup. The default database connection values in the .env.example are configured for the Docker Compose setup.

5. Run the relay:

   go run ./cmd/qubestr

Project Structure

qubestr/
├── cmd/
│   └── qubestr/
│       └── main.go          # Main application entry point & server setup
├── internal/
│   ├── config/
│   │   └── config.go        # Configuration management
│   └── handlers/
│       └── handlers.go      # Event validation handlers
├── .env.example             # Example environment variables
├── go.mod                   # Go module definition
├── Dockerfile               # Container definition
└── docker-compose.yml       # Docker composition for relay and database

Configuration

The relay is configured via environment variables loaded from a .env file.

Variable	Description	Default
DB_USER	PostgreSQL username.	postgres
DB_PASSWORD	PostgreSQL password.	postgres
DB_HOST	PostgreSQL host.	localhost
DB_PORT	PostgreSQL port.	5432
DB_NAME	PostgreSQL database name.	qubestr
DB_SSLMODE	PostgreSQL SSL mode.	disable
RELAY_ADMIN_PUBKEY	The Nostr pubkey of the relay administrator (for NIP-11).	""
AUTHORIZED_PUBKEYS	A comma-separated list of pubkeys authorized to publish kind 33321 events.	""
PORT	The port for the relay to listen on.	3334
HOST	The host interface for the relay to bind to.	0.0.0.0
DB_QUERY_LIMIT	The default query limit for event requests.	100
DB_KEEP_RECENT_EVENTS	Whether to keep an in-memory cache of recent events.	false

Custom Kind Events

The custom kind events supported by this relay are:

• HyperSignal (Kind 33321)
• Action Acknowledgement (Kind 3333)

For the complete specification, including all required tags and validation rules, please refer to hyperqube-events.md.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/your-feature).
3. Commit your changes (git commit -m 'Add some feature').
4. Push to the branch (git push origin feature/your-feature).
5. Open a Pull Request.

License

This project is licensed under the MIT License.

Acknowledgments

• Built with Khatru
• Uses go-nostr for Nostr protocol implementation
• PostgreSQL storage via eventstore