Self-hosting Setup

This guide will walk you through setting up a self-hosted Hyperstack server using the hyperstack-server crate.

Prerequisites Checklist

• Rust toolchain (1.75+) installed via rustup
• A Yellowstone Geyser gRPC endpoint URL
• (Optional) An X-Token for gRPC authentication
• A Hyperstack spec (bytecode) for your Solana program

1. Installation

Add the hyperstack-server dependency to your Cargo.toml. You will also need tokio for the async runtime.

[dependencies]
hyperstack-server = "0.1"
tokio = { version = "1.0", features = ["full"] }
anyhow = "1.0"

2. Configure the Server

In your main.rs, use the Server::builder() to configure your instance.

Geyser Connection

The most critical part is connecting to your data source.

use hyperstack_server::YellowstoneConfig;

let yellowstone_config = YellowstoneConfig {
    endpoint: "https://your-geyser-endpoint.com".into(),
    x_token: Some("your-secret-token".into()),
};

Server Specification

You need a Spec which contains the compiled bytecode of your projections and the parser setup.

use hyperstack_server::Spec;

// Usually generated by the #[stream_spec] macro
fn my_spec() -> Spec {
    // ... your spec implementation
}

3. Build and Run

Combine everything into the server builder and start it.

use hyperstack_server::Server;
use std::net::SocketAddr;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Setup logging
    tracing_subscriber::fmt::init();

    let addr: SocketAddr = "[::]:8877".parse()?;

    Server::builder()
        .spec(my_spec())
        .yellowstone(yellowstone_config)
        .websocket()
        .bind(addr)
        .health_monitoring() // Highly recommended
        .start()
        .await
}

4. Connecting Clients

Once your server is running, you can connect to it using any Hyperstack SDK (TypeScript, Rust, or Python).

Instead of using a managed environment URL, point the SDK to your local or self-hosted address:

// TypeScript SDK example
import { HyperStack } from 'hyperstack-react';

const stack = new HyperStack({
  endpoint: 'ws://localhost:8877', // Your self-hosted address
});

5. Production Considerations

If you are deploying this to production, consider the following:

Graceful Shutdown

hyperstack-server handles SIGINT and SIGTERM signals out of the box to ensure that the stream is closed gracefully.

Health Monitoring

Enable the HTTP health server to allow your orchestrator (like Kubernetes) to perform liveness and readiness checks.

Server::builder()
    .http_health() // Starts health server on port 8081 by default
    .health_bind("0.0.0.0:8081".parse()?)
    // ...

Metrics

If you use Prometheus or OpenTelemetry, enable the otel feature in hyperstack-server to export metrics about stream latency and connection counts.

[dependencies]
hyperstack-server = { version = "0.1", features = ["otel"] }

Resource Limits

The Yellowstone gRPC stream can be bandwidth-intensive. Ensure your hosting environment has sufficient network throughput and CPU to handle the deserialization of Solana blocks in real-time.