Orbital

Status: v0.1.0 on npm  ·  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, a shared ABI registry for Soroban schemas, and React hooks for live data in the browser. Four 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, surfaces raw operations rather than application-friendly events - and is deprecated in favor of Stellar RPC.
• Stellar RPC keeps only ~7 days of history and has no native subscription model - even with Protocol 23's unified event stream, delivery is still yours to build.
• 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-stellar/pulse-core	EventEngine - Horizon + Soroban subscription, normalization, reconnection, rate-limit handling, cursor persistence	✅ Shipped
@orbital-stellar/pulse-webhooks	HMAC-signed webhook delivery + verification (Node + edge runtimes), durable retry queues	✅ Shipped
@orbital-stellar/pulse-notify	React hooks - useStellarEvent, useContractEvent, useStellarPayment, useStellarActivity, useStellarAddresses, useStellarHistory, StellarConnectionStatus, StellarEventBoundary	✅ Shipped
@orbital-stellar/abi-registry	Canonical Soroban ABI client, schema helpers, and registry publisher interface	✅ Shipped

The full classic-operation taxonomy is shipped (payments, account create/merge/options/bump-sequence, trustlines + auth, offers, claimables, liquidity pools, manage-data), alongside Soroban contract event subscription (engine.subscribeContract), cursor persistence, and the ABI registry client - see ROADMAP.md.

---

Quickstart

Install only what you need from npm:

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

Or clone the repo to work from source:

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

Subscribe to events directly

import { EventEngine } from "@orbital-stellar/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-stellar/pulse-core";
import { WebhookDelivery } from "@orbital-stellar/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-stellar/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 events)"]
  end

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

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

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

  Horizon --> Engine
  RPC --> Engine
  Engine --> Normalize --> Watcher
  Engine --> Cursor
  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 plan (Phase 0 → Phase 3): the decoding standard, SEP draft, anchor events
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
packages/abi-registry/README.md	ABI Registry client, publisher interface, and shared schema helpers
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

• Shipped - Full classic operation taxonomy, edge-runtime webhook verification, React hooks, Soroban event subscription, ABI registry client, cursor persistence, durable retry queues, npm publish ✅
• v1.1.0 - Unified event ingestion via Stellar RPC (CAP-67 / Protocol 23), Horizon SSE demoted to fallback transport
• 2026 H2 (Phase 2) - The decoding standard: SEP draft building on SEP-48, orbital codegen, semantic taxonomy + entity labels as open data, hosted registry
• 2027 H1 (Phase 3) - @orbital-stellar/anchor-sdk, SEP-24/31 lifecycle events

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.

---

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 - questions, ideas, design discussion, and help.
• Twitter: (handle pending)
• Discord: (invite pending)