Connect to a Stack

For AI agents: the documentation index is at llms.txt (full corpus: llms-full.txt). A markdown source for this page is /using-stacks/connect.md.

This page shows how to add Arete to an existing project and connect to a deployed stack. It uses the hosted ORE mining stack as the example. Browser clients must authenticate with a publishable key; read-only viewing does not require a wallet.

Does a stack exist for your program?

This guide is for connecting to a stack that’s already deployed. If you want to stream data from your own on-chain program, you’ll need to build a stack for it first — see Build Your Own Stack.

Deploying custom stacks is currently in closed beta. Get in touch if you’d like early access.

Starting from scratch?

If you’re creating a new project and just want to see Arete working with the ORE demo, the Quickstart scaffolds everything automatically.

---

Install & Connect

React

React: Install

npm install @usearete/react @usearete/sdk zod
a4 install ore --ts \
  --output ./src/generated/ore-stack.ts \
  --package-name @usearete/react

Create .env.local:

VITE_ARETE_PUBLISHABLE_KEY=hspk_...

React: Add to your app

App.tsx

import { AreteProvider, useArete } from "@usearete/react";
import { ORE_STREAM_STACK } from "./generated/ore-stack";

const publishableKey = import.meta.env.VITE_ARETE_PUBLISHABLE_KEY;
if (!publishableKey) throw new Error("VITE_ARETE_PUBLISHABLE_KEY is required");

function CurrentOreRound() {
  const arete = useArete(ORE_STREAM_STACK);
  const board = arete.views.OreBoard.state.use({
    address: arete.addresses.board(),
  });
  const roundId = board.data?.state.roundId;
  const round = arete.views.OreRound.state.use(
    roundId == null ? undefined : { roundId },
  );

  if (arete.status === "error") {
    return <button onClick={() => void arete.retry()}>Reconnect</button>;
  }
  if (board.status !== "ready" || round.status !== "ready") {
    return <div>Connecting...</div>;
  }

  return (
    <div>
      <h1>Live ORE Mining Round</h1>
      <p>{arete.status === "connected" ? "Live" : arete.status}</p>
      {arete.socketIssue && <p>{arete.socketIssue.message}</p>}
      <p>
        Round #{round.data?.id.roundId?.toString() ?? "..."} - Motherlode:{" "}
        {round.data?.state.motherlode?.toString() ?? "..."}
      </p>
    </div>
  );
}

export default function App() {
  return (
    <AreteProvider stack={ORE_STREAM_STACK} auth={{ publishableKey }}>
      <CurrentOreRound />
    </AreteProvider>
  );
}

React: Run it

npm run dev

TypeScript / Node.js

TypeScript: Install

npm install @usearete/sdk
a4 install ore --ts \
  --output ./generated/ore-stack.ts \
  --package-name @usearete/sdk

TypeScript: Create a script

stream.ts

import { createSession } from "@usearete/sdk";
import { ORE_STREAM_STACK } from "./generated/ore-stack";

async function main() {
  const session = await createSession(
    { stacks: { ore: ORE_STREAM_STACK } },
    { auth: { publishableKey: process.env.ARETE_PUBLISHABLE_KEY! } },
  );

  for await (const update of session.stacks.ore.views.OreRound.latest.watch()) {
    if (update.type === "upsert") {
      const round = update.data;
      console.log(`Round #${round.id.roundId}`);
      console.log(`  Motherlode: ${round.state.motherlode}`);
    }
  }
}

main().catch(console.error);

TypeScript: Run it

ARETE_PUBLISHABLE_KEY=hspk_... npx tsx stream.ts

Rust

Rust: Add to Cargo.toml

[dependencies]
a4-sdk = "0.3.0"
a4-stacks = "0.3.0"

Rust: Write the code

src/main.rs

use a4_sdk::prelude::*;
use a4_stacks::ore::{OreStack, OreRound};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let a4 = Arete::<OreStack>::connect().await?;

    let mut stream = a4.views.ore_round.latest().listen();

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

    Ok(())
}

Rust: Run it

cargo run

Browser (Raw WebSocket)

Hosted WebSocket connections are authenticated with a short-lived token. A bare new WebSocket("wss://ore.stack.arete.run") call is not an unauthenticated shortcut. Browser applications should use @usearete/react with auth={{ publishableKey }} so the SDK performs the token exchange and refresh safely.

Use raw WebSocket code only against a self-hosted local server explicitly configured with allow_all, or after implementing the authenticated protocol described by your deployment.

---

How it Works

You connected to a deployed Arete stack. The ORE stack watches the Solana blockchain, extracts round data from on-chain transactions, and pushes typed updates to your app via WebSocket as they happen — no polling, no RPC calls, no indexer to run.

1

Solana

ORE program on-chain

→

2

Arete

ORE stack (deployed)

→

3

Your App

Typed live stream

The generated ORE definition contains the WebSocket and HTTP endpoints. The endpoint is publicly discoverable, but hosted connections still require authentication.

---

About Stack SDKs

A generated stack is like a cartridge: it packages a domain’s typed data and operations. An Arete session is the console that connects one or more of those cartridges and supplies shared session.chain reads and session.execute(...) execution. These terms are a mental model only; generated stacks keep their existing API names and types.

Insert cartridges under names you choose, then access them through session.stacks.<name>. A connected stack has stable views, queries, programs, addresses, constants, defaults, math, read, and flows namespaces when those capabilities are defined. Programs packaged by stacks are automatically promoted by reference to the canonical session.programs.<name> surface; owner-scoped stack paths remain available for disambiguation. Programs use programId, schemas, pdas, addresses, accounts, queries, raw, instructions, transactions, flows, constants, defaults, and math.

There are two ways to get a generated stack:

Install a publicly deployed stack (like ORE) - The CLI generates a deployment-pinned SDK and records its provenance:

a4 install ore --ts \
  --output ./src/generated/ore-stack.ts \
  --package-name @usearete/sdk

import { ORE_STREAM_STACK } from "./generated/ore-stack";

# Rust — add to Cargo.toml
[dependencies]
a4-stacks = "0.3.0"

use a4_stacks::ore::{OreStack, OreRound};

Generated from your own stack - Build the stack AST first, then use the CLI to generate an SDK for any language:

cargo build
a4 sdk create my-stack --ts
a4 sdk create my-stack --rust

Both approaches produce a generated stack definition that can be inserted into an Arete session. Generated directories are output boundaries: edit the stack, IDL, or extension source and regenerate instead of hand-editing core, entry, extension copies, or sdk-provenance.json.

For writes, prefer semantic .prepare(...) operations. They accept normal camelCase objects and derive or normalize protocol details before you call session.execute(prepared). Use program.raw.<idlInstruction>.build(...) only as the exact IDL escape hatch; raw instruction names, account names, argument names, and nested objects preserve the IDL shape, including snake_case.

---

Available Public Stacks

Stack	WebSocket URL	Data
ORE Mining Rounds	wss://ore.stack.arete.run	Live ORE mining round updates

---

ORE Data Shape

Each OreRound update has this structure:

{
  "id": {
    "round_id": 142857,
    "round_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
  },
  "state": {
    "expires_at": 312645000,
    "motherlode": 5000000000,
    "total_deployed": 125000000000,
    "total_vaulted": 12500000000,
    "total_winnings": 98500000000
  },
  "results": {
    "top_miner": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
    "top_miner_reward": 2500000000,
    "winning_square": 18,
    "did_hit_motherlode": false
  },
  "metrics": {
    "deploy_count": 1847,
    "total_deployed_sol": 125000000000,
    "checkpoint_count": 423
  }
}

Section	Description
id	Primary key (round_id) and lookup index (round_address)
state	Current round state from on-chain account
results	Round outcome including computed fields
metrics	Aggregated counts and sums from instructions

View the source

The full ORE stack definition is on GitHub: stacks/ore/src/stack.rs

---

Next Steps

• How It Works — Understand Stacks, Views, and how the stream model works
• React SDK — React hooks and patterns in depth
• TypeScript SDK — Use with Node.js, Vue, Svelte, or vanilla JS
• Rust SDK — Native Rust client
• Build Your Own Stack — Stream data from your own on-chain program