Orbital

Status: v0.1.0 on npm  ·  Networks: testnet + mainnet  ·  License: MIT

Stellar's biggest developer-experience gap is that Soroban events arrive as raw, untyped payloads with no shared vocabulary - every team invents its own decoding, and no two teams agree on what a swap or a liquidation even is.

Orbital ships the typed event layer once, openly: an open ABI/event-schema registry that makes decoding canonical, a typed event engine that normalizes Horizon and Soroban output into application-shaped events, codegen that puts those types into your codebase, plus composable webhook delivery and React hooks. 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:

• Soroban contract events decode to raw topic/value XDR with no shared schema - every team writes its own one-off decoder, and there's no canonical place to look up what a given contract's events mean.
• 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, analytics tool - re-solves the same problem. Orbital ships those primitives once, and the registry that makes decoding canonical, 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.

Browser bundle sizes

@orbital-stellar/pulse-notify is the only package that ships to the browser. Each entry point carries an enforced budget - CI fails on a regression and prints the top contributing modules. react and react-dom are peer dependencies and excluded.

Entry point	Minified	Minified + gzip	Budget (gzip)
@orbital-stellar/pulse-notify	14.57 kB	4.60 kB	5 kB
@orbital-stellar/pulse-notify/devtools	2.01 kB	918 B	1 kB
@orbital-stellar/pulse-notify/vitePlugin	608 B	322 B	450 B

Budgets live in packages/pulse-notify/.size-limit.json. Reproduce with pnpm --filter @orbital-stellar/pulse-notify size, or size:why for a per-module breakdown.

---

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	The decoding-standard thesis, Phase 0 → Phase 3 plan, and the Frozen section for out-of-scope items
STABILITY.md	The v1.0 semver pledge - covered API surface, wire/data contracts, deprecation policy
CHANGELOG.md	Release notes (top-level; per-package changelogs roll up)
STABILITY.md	Semver pledge, deprecation window, migration-path policy from v1.0.0
docs/ARCHITECTURE.md	Package map, event lifecycle, normalization, registry
docs/semantic-layer.md	Mappings, labels, precedence, honesty rule, mainnet worked example
docs/migration/0.1-to-1.0.md	Breaking-change before/after guide from 0.1.0 → 1.0.0
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 ✅
• In progress (Phase 1) - STABILITY.md v1.0 semver pledge merged; starter boilerplates and the v1.0.0 tag outstanding
• 2026 H2 (Phase 2 - The Decoding Standard) - SEP draft for a standardized Soroban event schema, orbital codegen, the semantic layer (event taxonomy + entity labels), hosted registry
• 2027 H1 (Phase 3 - Anchor Events) - @orbital-stellar/anchor-sdk, SEP-24/31 lifecycle events normalized into the standard taxonomy

Full multi-year plan, plus what's explicitly frozen out of scope, 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)