Your First Stack

In this tutorial, you’ll build an end-to-end streaming data pipeline in 15 minutes. We’ll create an “Ore” stack that tracks ORE mining rounds and displays live round data in a React app.

What You’ll Build

A full-stack streaming application consisting of:

1. A Rust Definition: Defines how to transform on-chain ORE mining data into a queryable “OreRound” entity.
2. A Cloud Deployment: A managed Hyperstack instance that processes the stream.
3. A React Frontend: A live dashboard showing the latest ORE mining rounds that updates instantly as on-chain events occur.

Demo Version

This tutorial uses a simplified version of the ORE stack. For the full production-ready version with all features (computed fields, snapshots, round results, etc.), run hs create and select the ore template.

---

Part 1: Create the Stack (Rust)

The stack definition is the heart of your application. It tells Hyperstack which on-chain data to watch and how to project it into a useful state.

1. Create a new Rust project

cargo new ore-stack --lib
cd ore-stack

2. Add dependencies

Add hyperstack to your Cargo.toml:

[dependencies]
hyperstack = "0.5.3"
serde = { version = "1.0", features = ["derive"] }

3. Get the ORE IDL

Download the ORE program IDL file and place it in an idl/ directory:

mkdir -p idl
curl -o idl/ore.json https://docs.usehyperstack.com/ore.json

What is an IDL?

The IDL (Interface Definition Language) describes the Solana program’s account structures and instructions. Hyperstack uses it to generate type-safe code for accessing on-chain data.

Generated SDK Naming

When you point to an IDL (e.g., ore.json), Hyperstack reads the program name from the IDL metadata and generates a typed SDK module named {name}_sdk — so ore.json produces ore_sdk::accounts::* and ore_sdk::instructions::*. All #[map] and #[aggregate] paths use this prefix.

4. Write your stack definition

Open src/lib.rs and define your projection. We’ll create a simplified version of the ORE mining round tracker:

src/lib.rs

use hyperstack::prelude::*;

#[hyperstack(idl = "idl/ore.json")]
pub mod ore_stream {
    use hyperstack::macros::Stream;
    use serde::{Deserialize, Serialize};

    // The main entity representing an ORE mining round
    #[entity(name = "OreRound")]
    #[view(name = "latest", sort_by = "id.round_id", order = "desc")]
    pub struct OreRound {
        pub id: RoundId,
        pub state: RoundState,
        pub metrics: RoundMetrics,
    }

    // Round identification with primary key
    #[derive(Debug, Clone, Serialize, Deserialize, Stream)]
    pub struct RoundId {
        #[map(ore_sdk::accounts::Round::id, primary_key, strategy = SetOnce)]
        pub round_id: u64,

        #[map(ore_sdk::accounts::Round::__account_address, lookup_index, strategy = SetOnce)]
        pub round_address: String,
    }

    // Round state fields - updated on every change
    #[derive(Debug, Clone, Serialize, Deserialize, Stream)]
    pub struct RoundState {
        #[map(ore_sdk::accounts::Round::expires_at, strategy = LastWrite)]
        pub expires_at: Option<u64>,

        #[map(ore_sdk::accounts::Round::total_deployed, strategy = LastWrite)]
        pub total_deployed: Option<u64>,

        #[map(ore_sdk::accounts::Round::total_winnings, strategy = LastWrite)]
        pub total_winnings: Option<u64>,
    }

    // Aggregated metrics computed from transactions
    #[derive(Debug, Clone, Serialize, Deserialize, Stream)]
    pub struct RoundMetrics {
        // Count of deploy instructions for this round
        #[aggregate(from = ore_sdk::instructions::Deploy, strategy = Count, lookup_by = accounts::round)]
        pub deploy_count: Option<u64>,

        // Sum of all deployed SOL amounts
        #[aggregate(from = ore_sdk::instructions::Deploy, field = amount, strategy = Sum, lookup_by = accounts::round)]
        pub total_deployed_sol: Option<u64>,
    }
}

5. Build to generate the stack file

When you compile your code, Hyperstack macros automatically generate a .hyperstack/OreStream.stack.json file containing all entities in your stack.

cargo build

Checkpoint

Verify that the file .hyperstack/OreStream.stack.json exists in your project root. This JSON file contains the compiled specification for your stack, including all entities and their field mappings.

---

Part 2: Deploy to Hyperstack Cloud

Now let’s push your stack to the cloud. Hyperstack manages the infrastructure, so you don’t need to worry about scaling or WebSocket servers.

Closed Beta

Hyperstack is currently in closed beta. You’ll need an API key to deploy. Contact us on X to request access.

1. Initialize your project

This creates a hyperstack.toml file that links your local stack to the cloud.

hs init

2. Push and Deploy

The up command is a shortcut that pushes your stack, builds the container, and deploys it to a global cluster.

hs up

Expected Output:

✔ Stack pushed (v1)
✔ Build created (id: bld_123...)
✔ Build completed
🚀 Deployed to: wss://<your-stack-name>.stack.usehyperstack.com

Checkpoint

Copy the WebSocket URL from the output. You’ll need it for the React app.

---

Part 3: Generate SDK and Connect

Finally, let’s build the frontend. First, generate a typed SDK from your deployed stack, then connect using React or TypeScript.

What is the SDK?

The generated SDK contains the typed interface to your stack — it tells the Hyperstack client what entities exist, what views are available, and the TypeScript types for each. You can share this SDK with your team or publish it.

1. Generate the SDK

From your stack project directory (where you ran hs up):

hs sdk create typescript ore-stack --output ./sdk

This creates a typed SDK in ./sdk/ with full TypeScript support.

---

React

2. Set up your React app

npx create-react-app my-ore-app --template typescript
cd my-ore-app
npm install hyperstack-react zustand

Copy the generated SDK into your React app:

cp -r ../ore-stack/sdk ./src/ore-sdk

3. Configure the Provider

Wrap your app in HyperstackProvider using the URL from hs up.

src/index.tsx

import { HyperstackProvider } from "hyperstack-react";

const root = ReactDOM.createRoot(document.getElementById("root")!);
root.render(
  <HyperstackProvider websocketUrl="wss://<your-stack-name>.stack.usehyperstack.com">
    <App />
  </HyperstackProvider>,
);

4. Use the Generated Stack

src/App.tsx

import { useHyperstack } from "hyperstack-react";
import { OreStack } from "./ore-sdk";

export default function App() {
  const stack = useHyperstack(OreStack);
  const { data: rounds, isLoading } = stack.views.OreRound.latest.use({
    take: 5,
  });

  if (isLoading) return <div>Connecting to stream...</div>;

  return (
    <div>
      <h1>Latest ORE Mining Rounds</h1>
      {rounds?.map((round) => (
        <div
          key={round.id.round_id}
          style={{
            padding: "1rem",
            border: "1px solid #ccc",
            margin: "0.5rem 0",
          }}
        >
          <h3>Round #{round.id.round_id}</h3>
          <p>Address: {round.id.round_address}</p>
          <p>
            Total Deployed: {round.state.total_deployed?.toLocaleString()}{" "}
            lamports
          </p>
          <p>
            Total Winnings: {round.state.total_winnings?.toLocaleString()}{" "}
            lamports
          </p>
          <p>Deploy Count: {round.metrics.deploy_count || 0}</p>
          <p>
            Total SOL Deployed:{" "}
            {round.metrics.total_deployed_sol?.toLocaleString()} lamports
          </p>
        </div>
      ))}
    </div>
  );
}

TypeScript (Non-React)

2. Set up your project

mkdir my-ore-app && cd my-ore-app
npm init -y
npm install hyperstack-typescript typescript

Copy the generated SDK:

cp -r ../ore-stack/sdk ./src/ore-sdk

3. Connect and stream data

src/index.ts

import { HyperStack } from "hyperstack-typescript";
import { OreStack, type OreRound } from "./ore-sdk";

async function main() {
  // Connect to your deployed stack using the generated SDK
  const hs = await HyperStack.connect(
    "wss://<your-stack-name>.stack.usehyperstack.com",
    { stack: OreStack },
  );

  console.log("Connected! Streaming ORE rounds...\n");

  // Stream updates with full type safety
  for await (const update of hs.views.OreRound.latest.watch()) {
    if (update.type === "upsert") {
      const round = update.data;
      console.log(`Round #${round.id.round_id}:`);
      console.log(`  Address: ${round.id.round_address}`);
      console.log(
        `  Total Deployed: ${round.state.total_deployed?.toLocaleString()} lamports`,
      );
      console.log(
        `  Total Winnings: ${round.state.total_winnings?.toLocaleString()} lamports`,
      );
      console.log(`  Deploy Count: ${round.metrics.deploy_count || 0}`);
      console.log("");
    }
  }
}

main().catch(console.error);

4. Run your app

npx tsx src/index.ts

---

Troubleshooting

”Stack file not found”

Ensure you ran cargo build in your Rust project. The #[hyperstack] macro generates the .stack.json file during compilation.

WebSocket connection fails

1. Check that the URL matches the output of hs up.
2. Ensure your stack is successfully deployed by running hs stack list.

Data is not appearing

1. Verify that the ORE program is emitting events and updating the Round accounts.
2. Check the browser console for any subscription errors.
3. Ensure your view path matches the entity name exactly (e.g., OreRound/latest).

Next Steps

• Learn more about Stack Macros to build complex pipelines.
• Explore Population Strategies for different data access patterns.
• Check the CLI Reference for advanced deployment options.