Orbital

Status: v0.1.0 on npm  ·  Contracts: testnet only  ·  License: MIT

The libraries read both networks. Orbital's own contracts are deployed to testnet and have not been deployed to mainnet - see What works today.

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
• What works today
• 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.

For how this sits against SEP-48, the official JS SDK, Mercury and the other Stellar indexers - including where they win - see docs/competitive-landscape.md.

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).

---

What works today

Four different states get conflated in most project READMEs. They are separated here on purpose, because "it is in the repo" and "you can install it and it works" are not the same claim.

Capability	On npm	In this repo	Notes
Horizon subscription + classic event taxonomy	✅ 0.1.0	✅	Payments, account ops, trustlines, offers, claimables, liquidity pools, manage-data
Reconnection, rate-limit backoff, cursor persistence	✅ 0.1.0	✅
HMAC webhook delivery + verification	⚠️ partial	✅	Retry-queue and signing exports landed after 0.1.0
React hooks	✅ 0.1.0	✅	4.6 kB gzip
Soroban contract-event subscription	❌	✅	CoreConfig.soroban on the published build has no rpcUrl. Needs the next release - see #1132
ABI registry client + WASM auto-discovery	⚠️ partial	✅
Worker layer (worker-core)	❌ unpublished	⚠️ partial	Triggers, scheduling, verification and reputation exist. Workers call functions anyone could call - contracts/payroll's disburse() is the reference. No custody anywhere.

The published packages are behind this repository. 0.1.0 predates a large amount of the work here, most consequentially Soroban RPC configuration. If you need contract-event subscription today, install from source. Tracked as #1132.

On-chain status

Contract	Testnet	Mainnet
registry	deployed, never invoked	not deployed
demo-emitter	deployed, never invoked	not deployed (testnet fixture by design)
payroll	deployed	not deployed

"Never invoked" is meant literally and is checkable: the deployer account has submitted only UploadContractWasm and CreateContract operations, no InvokeContract, and getEvents returns nothing for either contract across the RPC retention window. No spec has been registered in the registry yet.

---

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

Soroban contract events need a build newer than 0.1.0. The published pulse-core cannot be configured with a Soroban RPC endpoint, so contract subscription is unreachable from npm until the next release (#1132). The Horizon/classic examples below work against 0.1.0 as written; clone the repo for the Soroban ones.

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)