Workflow

Building a stack follows a straightforward four-step workflow: define your data model in Rust, compile to build the stack, deploy to Hyperstack Cloud, and connect from your application.

Write Rust

Define entities using #[hyperstack] macro

→

Build Stack

Compile with cargo build

→

Deploy via CLI

Push to cloud with hs up

→

Connect from App

Use generated SDK to stream

Step 1: Write Your Stack Definition

A stack definition is a Rust module that maps structure from the IDL into a rich, queryable state ready to consume in your application layer. Using Hyperstack’s expressive DSL, you define entities, field mappings, aggregations, computed fields, relationships, and more — all in declarative Rust syntax.

use hyperstack::{hyperstack, Stream};

#[hyperstack(idl = "my_program.json")]
pub mod ore_stack {
    #[entity]
    #[derive(Stream)]
    pub struct OreRound {
        #[map(RoundState::round_id, primary_key)]
        pub round_id: u64,

        #[map(RoundState::motherlode)]
        pub motherlode: u64,

        #[map(RoundState::difficulty)]
        pub difficulty: u64,
    }
}

The Rust code is purely declarative—you’re describing what data you want, not how to fetch it. Hyperstack handles all the account parsing, event processing, and state management.

→ Stack Definitions — Learn the full DSL syntax

Step 2: Build the Stack

When you compile your Rust project, Hyperstack macros transform your definition into a portable JSON specification. This is the compiled representation of your data pipeline.

cargo build

After building, you’ll find the generated specification in .hyperstack/:

my-stack/
├── src/lib.rs
├── Cargo.toml
└── .hyperstack/
    └── OreStack.stack.json    # Generated stack specification

The .stack.json file contains everything Hyperstack needs to execute your pipeline: all entities, field mappings, aggregation logic, key resolution rules, and more. A single stack file can contain multiple entities.

Step 3: Deploy with the CLI

The Hyperstack CLI (hs) handles deployment to Hyperstack Cloud. A single command pushes your stack specification, builds the execution environment, and deploys to a global edge network.

# Initialize project config (creates hyperstack.toml)
hs init

# Deploy your stack
hs up

On success, you’ll receive a WebSocket URL:

✔ Stack pushed (v1)
✔ Build completed
🚀 Deployed to: wss://ore.stack.usehyperstack.com

→ CLI Reference — Full command documentation

Step 4: Generate SDK and Connect

Once deployed, generate a typed SDK for your stack:

TypeScript
Rust

hs sdk create typescript ore

hs sdk create rust ore

This creates a package containing the stack definition that tells the Hyperstack client how to interact with your feed, including all entities and their views. Import it in your application:

import { HyperstackProvider, useHyperstack } from "hyperstack-react";
import { ORE_STREAM_STACK } from "hyperstack-stacks/ore"; // Generated in Step 4

// Wrap your app
<HyperstackProvider>
  <App />
</HyperstackProvider>;

// In your component
const stack = useHyperstack(ORE_STREAM_STACK);
const { data: rounds } = stack.views.OreRound.list.use();

import { HyperStack } from "hyperstack-typescript";
import { ORE_STREAM_STACK } from "hyperstack-stacks/ore"; // Generated in Step 4

const hs = await HyperStack.connect(ORE_STREAM_STACK);

for await (const round of hs.views.OreRound.list.use()) {
  console.log("Round updated:", round);
}

use hyperstack_sdk::prelude::*;
use ore_stack::{OreStack, OreRound};  // Generated in Step 4

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Connect to your deployed stack
    let hs = HyperStack::<OreStack>::connect().await?;

    // Stream updates via typed views
    let mut stream = hs.views.ore_round.latest().listen();

    while let Some(round) = stream.next().await {
        println!("Round #{:?}: motherlode={:?}",
            round.id.round_id, round.state.motherlode);
    }

    Ok(())
}

Share the generated SDK with your team or publish it — anyone with the SDK can connect to your stack’s feed (assuming they’re authorized).

→ Your First Stack — Complete tutorial with working code

Next Steps

Goal	Page
Understand the DSL in depth	Stack Definitions
Set up your development environment	Installation
Build a complete example	Your First Stack
Learn all available macros	Macro Reference
Master aggregation strategies	Population Strategies