Skip to content

CHANGELOG.md

Latest commit

 

History

History
193 lines (159 loc) · 9.51 KB

CHANGELOG.md

File metadata and controls

193 lines (159 loc) · 9.51 KB
Raw

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project follows Semantic Versioning.

This file rolls up changes across the public packages: @orbital-stellar/pulse-core, @orbital-stellar/pulse-webhooks, @orbital-stellar/pulse-notify, and @orbital-stellar/abi-registry. Per-package changelogs live in each package directory.

[Unreleased]

Added

  • STABILITY.md - strict semver on the public API of all @orbital-stellar/* packages, wire/data contracts covered (webhook headers, HMAC scheme, retry semantics, NormalizedEvent JSON shape, cursor format, registry schema format), a 6-month deprecation window, and a documented security exception. Closes the outstanding Wave 1.5 release-gate item.
  • docs/migration/0.1-to-1.0.md - procedural before/after migration guide for the 0.1.0 → 1.0.0 bump (breaking abiRegistry default, decodedData shape, Wave 8 registry configuration). Narrative release notes remain in this file’s [1.0.0] entry when cut; do not duplicate them into the guide.

Changed

  • Roadmap refocused on the decoding standard. Maintainer sign-off for scope removal per ROADMAP.md's own contribution rules. The former Phase 2 (SDK Ecosystem) is replaced by Phase 2 - The Decoding Standard (SEP draft, orbital codegen, semantic layer, hosted registry). @orbital-stellar/anchor-sdk is pulled forward into a new Phase 3 - Anchor Events. The former Phase 3 (Trust & Agent Layer: x402, agent-sdk, intent compiler, shadow-fork) and Phase 4 (Protocol Permanence: identity layer, reactor library, 10+ SEPs) are frozen and moved to an explicit Frozen section in ROADMAP.md with per-item rationale and an unfreeze procedure. No shipped code is removed - planned scope only.
  • Docs aligned with the refocused roadmap: README reframed around the decoding standard; open-source-policy and proposal forward-references updated; frozen-scope references removed from forward-looking docs.

Fixed

Security

  • @orbital-stellar/anchor-sdk 0.1.0 does not validate SEP-10 challenges before signing them. Sep10Client.authenticate() passed the anchor's challenge XDR straight to the caller-supplied sign callback with no checks: no verification of the anchor's signature, no source-account or sequence == 0 check, no <home_domain> auth Manage Data check, no time bounds. The network_passphrase in the response was parsed and then ignored, and SIGNING_KEY — the one value that can attribute a challenge to an anchor — was read from stellar.toml and never used.

    A hostile or compromised anchor, or an on-path attacker against a plain-http WEB_AUTH_ENDPOINT, could return an ordinary transaction (a payment, or a set_options adding a signer) and have it blind-signed by the consumer's wallet, hardware device, or KMS.

    Fixed in 0.2.0. Sep10Client now verifies every challenge with WebAuth.readChallengeTx before sign is invoked, rejects a network_passphrase that disagrees with the configured network, and refuses a non-https endpoint at construction.

    This is a breaking change to a surface that was itself the vulnerability, taken under the security exception in STABILITY.md. A GitHub Security Advisory is to be published per SECURITY.md.

    Migration. Sep10Client now requires the anchor's identity. The smallest change is to build it from the anchor's own stellar.toml:

    // before - no way to tell whose challenge you were signing
const client = new Sep10Client(toml.WEB_AUTH_ENDPOINT);

// after - SIGNING_KEY and NETWORK_PASSPHRASE come from the toml you already fetch
const toml = await discoverAnchor("anchor.example");
const client = Sep10Client.fromToml(toml, "anchor.example");

    Or pass them explicitly: new Sep10Client(endpoint, { serverAccountId, networkPassphrase, homeDomain, webAuthDomain }). Anchors that publish no SIGNING_KEY are now refused rather than trusted.

[0.1.0] - 2026-05-28

First versioned release. The three packages cover the full Stellar classic operation taxonomy and are stable for testnet development today. Soroban event subscription, cursor persistence, and the v1.0 stability pledge ship in Phase 1 (Q2–Q3 2026).

Added

  • @orbital-stellar/pulse-core: EventEngine - Horizon SSE subscription with AWS Full-Jitter exponential backoff, automatic reconnection, and a per-address Watcher pub/sub model built on Node's EventEmitter.
  • @orbital-stellar/pulse-core: full classic operation taxonomy normalized into a typed NormalizedEvent discriminated union:
    • Payments: payment.received, payment.sent, payment.self
    • Accounts: account.created, account.merged, account.options_changed, account.bump_sequence
    • Trustlines: trustline.added, trustline.updated, trustline.removed, trustline.authorized, trustline.deauthorized
    • DEX offers: offer.created, offer.updated, offer.deleted
    • Claimable balances: claimable.created, claimable.claimed
    • Liquidity pools: lp.deposited, lp.withdrawn
    • Data entries: data.set, data.cleared
  • @orbital-stellar/pulse-core: lifecycle notifications - engine.reconnecting, engine.reconnected, engine.rate_limited (with parsed Retry-After), and engine.stopped.
  • @orbital-stellar/pulse-core: CoreConfig.horizonUrl override for self-hosted Horizon nodes, regional mirrors, and futurenet.
  • @orbital-stellar/pulse-core: EventEngine.unsubscribeAll() to drain watchers without closing the SSE stream.
  • @orbital-stellar/pulse-core: optional filter predicate on EventEngine.subscribe() for per-watcher event suppression.
  • @orbital-stellar/pulse-webhooks: WebhookDelivery with HMAC-SHA256 signing (x-orbital-signature, x-orbital-timestamp, x-orbital-attempt), exponential-backoff retry with jitter, per-attempt AbortController timeout, and a concurrent-retry cap.
  • @orbital-stellar/pulse-webhooks: verifyWebhook (Node crypto, timing-safe comparison) and verifyWebhookEdge (Web Crypto) for Cloudflare Workers, Vercel Edge, Deno, and browsers.
  • @orbital-stellar/pulse-notify: useStellarEvent<T> with generic type narrowing, positional and config-object call signatures, and stable dep-array keys for array event allowlists.
  • @orbital-stellar/pulse-notify: useStellarPayment and useStellarActivity convenience hooks.
  • @orbital-stellar/pulse-core: testnet + mainnet network selectors via network: "mainnet" | "testnet".

Changed

  • @orbital-stellar/pulse-core: EventEngine.start() now returns a boolean (true on a fresh start, false if the engine was already running). Pass { strict: true } to throw EngineAlreadyStartedError instead.
  • @orbital-stellar/pulse-core: WatcherNotification.timestamp renamed to emittedAt to distinguish it from the on-chain created_at timestamp used in operation events.
  • @orbital-stellar/pulse-core: self-payments where from === to now emit a single payment.self event instead of separate payment.received and payment.sent events.

Fixed

  • @orbital-stellar/pulse-webhooks: cap concurrent retries to prevent unbounded memory growth when consumer endpoints are unreachable.
  • @orbital-stellar/pulse-core: align reconnect attempt numbers across logs and engine.reconnecting notifications.
  • @orbital-stellar/pulse-core: warn when listeners are added after Watcher.stop().

Security

  • @orbital-stellar/pulse-webhooks: timing-safe HMAC comparison via crypto.timingSafeEqual (Node) and constant-time XOR (Web Crypto).
  • @orbital-stellar/pulse-webhooks: SSRF hardening on delivery targets - private, loopback, and link-local IP ranges are blocked by default, with DNS rebinding defense.
  • Strict TypeScript across all packages (noUncheckedIndexedAccess, strict, NodeNext module resolution).
  • CI matrix runs on Node 20 and Node 22 with CodeQL static analysis and Dependabot CVE tracking.

Impact

  • Stellar developers can subscribe to every classic operation type with one typed API, deliver events to HTTPS endpoints with retry and signature verification baked in, and render live data in React without writing SSE plumbing.
  • Edge-runtime verification unblocks webhook receivers on Cloudflare Workers and Vercel Edge - a deployment surface QuickNode and Moralis do not natively support for Stellar.
  • The reference composition (apps/web/app/api/events/[address]/route.ts) is now a single Next.js file rather than a separate Express server, so there is one runtime to deploy when self-hosting the SDKs end-to-end.

Known limitations (as of this release)

  • Soroban contract events (invoke_host_function) are not yet normalized
    • Phase 1.
  • Webhook retries are in-process; restarting loses pending retries. Persistent retry queues ship in Phase 1 alongside cursor persistence.
  • Packages are not yet published to npm. Until v0.1.0 is tagged and released, consume via pnpm install against the workspace.

Update (2026-07-06): all three limitations above have since been resolved - Soroban event subscription, durable retry queues, and cursor persistence shipped (see ROADMAP.md Wave 1.1–1.3), and all four packages are now published to npm under the @orbital-stellar scope (published out-of-band; the release.yml npm-publish step is now uncommented for future version bumps).