Orbital

Status: Phase 0 — Foundation  ·  Networks: testnet + mainnet  ·  License: MIT

Stellar's biggest developer-experience gap isn't a missing API — it's that Horizon's firehose still requires every team to build their own event delivery.

Orbital ships that delivery layer once, openly: a typed event engine that normalizes Horizon output into application-shaped events, HMAC-signed webhook delivery with retry and edge-runtime verification, and React hooks for live data in the browser. Three MIT-licensed packages, designed to be composed.

---

Table of contents

• Why this exists
• Packages
• Quickstart
• Architecture
• Documentation
• Production hosting
• Roadmap
• Contributing
• Contributors
• License

---

Why this exists

Stellar's official APIs give you the raw firehose — and not much else:

• Horizon SSE drops on idle, requires backoff, and surfaces raw operations rather than application-friendly events.
• Stellar RPC keeps only ~7 days of Soroban history and has no native subscription model.
• Webhooks aren't part of the platform — every project rebuilds HMAC signing, retry, SSRF guards, and edge-runtime verification from scratch.
• React integration doesn't exist — every dashboard rebuilds SSE plumbing and lifecycle management.

Every serious Stellar app — wallet, dashboard, anchor integration, agent — re-solves the same problem. Orbital ships those primitives once so you can pnpm add them instead of rebuilding them.

The longer-form thesis, the multi-year vision, and the SCF grant case live in PROGRESS.md, ROADMAP.md, and docs/proposal.md (in progress).

---

Packages

Package	Description	Status
@orbital/pulse-core	EventEngine — Horizon subscription, normalization, reconnection, rate-limit handling	✅ Phase 0
@orbital/pulse-webhooks	HMAC-signed webhook delivery + verification (Node + edge runtimes)	✅ Phase 0
@orbital/pulse-notify	React hooks — useStellarEvent, useStellarPayment, useStellarActivity	✅ Phase 0

The full classic-operation taxonomy is shipped (payments, account create/merge/options/bump-sequence, trustlines + auth, offers, claimables, liquidity pools, manage-data). Soroban contract events are Phase 1 (Q2–Q3 2026) — see ROADMAP.md.

---

Quickstart

Packages publish to npm at v0.1.0 (Phase 0 milestone). Until then, clone the repo and use the workspace install below.

git clone https://github.com/determined-001/orbital_stellar.git
cd orbital_stellar
pnpm install

Once published, install only what you need:

pnpm add @orbital/pulse-core             # always
pnpm add @orbital/pulse-webhooks         # if you push events to HTTPS endpoints
pnpm add @orbital/pulse-notify react     # if you render live events in React

Subscribe to events directly

import { EventEngine } from "@orbital/pulse-core";

const engine = new EventEngine({ network: "testnet" });
engine.start();

const watcher = engine.subscribe("GABC...YOUR_ACCOUNT");

watcher.on("payment.received", (event) => {
  console.log(`+${event.amount} ${event.asset} from ${event.from}`);
});

watcher.on("*", (event) => {
  // Every event for this address, regardless of type
});

Deliver events to a webhook

import { EventEngine } from "@orbital/pulse-core";
import { WebhookDelivery } from "@orbital/pulse-webhooks";

const engine = new EventEngine({ network: "mainnet" });
engine.start();

const watcher = engine.subscribe("GABC...");

new WebhookDelivery(watcher, {
  url: "https://your-app.com/hooks/stellar",
  secret: process.env.WEBHOOK_SECRET!,
  retries: 3,
});

Receivers verify the signature with verifyWebhook (Node) or verifyWebhookEdge (Cloudflare Workers / Vercel Edge / Deno / browsers).

Render live events in React

"use client";
import { useStellarPayment } from "@orbital/pulse-notify";

export function IncomingPayments({ address }: { address: string }) {
  const { event, connected } = useStellarPayment(
    process.env.NEXT_PUBLIC_ORBITAL_URL!,
    address,
  );
  if (!connected) return <p>Connecting…</p>;
  if (!event) return <p>No payments yet.</p>;
  return <p>+{event.amount} {event.asset} from {event.from.slice(0, 8)}…</p>;
}

Run it against testnet, send a test payment from the Stellar Laboratory, and you'll see the event print within seconds. The full guide lives at apps/web/content/getting-started/quick-start.md.

---

Architecture

flowchart LR
  subgraph Stellar["Stellar network"]
    Horizon["Horizon REST + SSE"]
    RPC["Stellar RPC<br/>(Soroban) — Phase 1"]
  end

  subgraph Core["@orbital/pulse-core"]
    Engine["EventEngine<br/>subscribe · reconnect · backoff"]
    Watcher["Watcher<br/>per-address pub/sub"]
    Normalize["Normalize<br/>13 op types → typed events"]
  end

  subgraph Webhooks["@orbital/pulse-webhooks"]
    Sign["HMAC-SHA256<br/>+ retry + SSRF"]
    Verify["verifyWebhook<br/>verifyWebhookEdge"]
  end

  subgraph Notify["@orbital/pulse-notify"]
    Hooks["useStellarEvent<br/>useStellarPayment<br/>useStellarActivity"]
  end

  Horizon --> Engine
  RPC -.-> Engine
  Engine --> Normalize --> Watcher
  Watcher --> Sign
  Watcher --> Hooks
  Sign -->|x-orbital-signature| YourBackend["Your endpoint"]
  YourBackend --> Verify
  Hooks --> Browser["React app"]

Loading

The reference composition — a Next.js route handler that subscribes to an address and streams events as SSE, plus an HMAC-signing route for the on-page webhook demo — lives in apps/web/app/api.

---

Documentation

Document	What it covers
PROGRESS.md	Phase 0 completion status, project structure, architecture overview
ROADMAP.md	Multi-year vision (Phase 0 → Phase 4), Soroban + cursor persistence + replay store
CHANGELOG.md	Release notes (top-level; per-package changelogs roll up)
CONTRIBUTING.md	Setup, coding standards, PR process, Drips Wave Program
SECURITY.md	Vulnerability disclosure policy
packages/pulse-core/README.md	EventEngine API, event taxonomy, configuration
packages/pulse-webhooks/README.md	Delivery contract, verification, SSRF safety
packages/pulse-notify/README.md	React hooks, type narrowing, authentication
apps/web/README.md	Marketing site + sandboxed demo API routes

---

Production hosting

Two paths:

1. Build your own backend — install the SDKs, wire them into your existing Node.js or edge worker, deploy on the infrastructure you already operate. The Next.js route handlers in apps/web/app/api are a copy-paste reference.
2. Use Orbital Cloud (in development) — managed runtime handling multi-region orchestration, persistent webhook registries, replay, and observability. Out of scope for this repository.

---

Roadmap

• Now (Phase 0) — Full classic operation taxonomy, edge-runtime webhook verification, React hooks ✅
• Q2–Q3 2026 (Phase 1, v1.0) — Soroban event subscription, ABI registry client, cursor persistence, replay adapters, npm publish, stability pledge
• 2027 (Phase 2) — @orbital/hooks, @orbital/payments, @orbital/auth, first SEP submission
• 2028+ (Phase 3) — @orbital/x402, @orbital/agent-sdk, intent compiler

Full multi-year plan in ROADMAP.md.

---

Contributing

Contributions are welcome from the Stellar community. Start here:

• Read CONTRIBUTING.md for the dev loop, coding standards, and PR process.
• Browse issues tagged good-first-issue — scoped, unblocked, reviewer-ready.
• Stellar Wave Program issues are tagged wave-program and pay per-merge per complexity points.
• Run the test suite before submitting: pnpm -r typecheck && pnpm test.

All contributors are expected to follow the Code of Conduct (in progress).

---

Contributors

Thanks to everyone who has shipped code, docs, or feedback for Orbital. The list below is maintained via the all-contributors bot — see Adding yourself to the contributors list to add or update your entry.

determined-001 💻 📖 🏗️ 🚧 📆 👀 ⚠️

Trovicdev 💻

Praxhant97 💻

Christopher Umechukwu 💻

Legacy 💻

Emoji key follows the all-contributors spec — 💻 code · 📖 docs · 🎨 design · 🏗️ infrastructure · 🚧 maintenance · 📆 project management · 👀 reviewed PRs · ⚠️ tests.

The list above is the curated all-contributors set. For the full commit history including every contributor not yet recognized here, see GitHub's contributor graph — if your name is there and not in the table, please open an issue or comment @all-contributors please add @your-username for code on any issue and the bot will add you.

---

License

MIT — free to use in commercial and open-source projects.

---

Community

• GitHub Discussions: (enable via repo settings — see Drips funding plan)
• Twitter: (handle pending)
• Discord: (invite pending)