Stellar Soroban: events without the pain
Inside @pulsar-stellar/sdk: reading indexed history and live Soroban events, preserving XDR data faithfully, and handling the limits of each source.
By Emmanuel Itighise

A Soroban contract can emit an event in a single operation. Turning that event into something an application can reliably use takes more work: fetching it, decoding XDR, keeping topics separate from data, preserving large integer values, and deciding where historical records will live. Those concerns sit between the contract and almost every useful feature built on top of it.
Pulsar-Stellar is a developer toolkit for that gap. This post focuses on @pulsar-stellar/sdk, its TypeScript client, which lives in the pulsar-app repository under packages/sdk. The SDK gives application developers a consistent way to consume decoded Soroban events, whether they are reading stored history from a Pulsar-Stellar indexer or following recent activity directly through Stellar RPC.
Indexed history and the live tail
The distinction between those two sources matters. Stellar RPC typically retains roughly a week of event history. That is useful for recent activity, but it is not a permanent record for a dashboard, a backend integration, or an investigation into older contract behaviour. An indexer can retain events it has collected beyond the RPC window. It does not automatically recover events that disappeared before it started collecting them.
Pulsar-Stellar's Go indexer handles that collection and storage layer. The SDK is the interface an application uses to read what the indexer serves. Keeping those responsibilities separate means the client does not need to become a database, and each application does not need to build its own HTTP wrappers and response parsing before it can work with contract activity.
Reading events from the indexer
For indexed history, PulsarClient exposes methods such as events, eventStream, and event. The events method reads a page for a particular contract, with filters for event name, ledger range, and topic content, alongside ordering and a page limit. The response contains the items and a nextCursor. That cursor is opaque: pass it back to request the next page rather than trying to interpret its contents.
When an application needs to walk through multiple pages, eventStream provides an asynchronous iterator. It fetches pages as they are needed and stops when the indexed results are exhausted. This is useful for a backend that processes a contract's history without first loading every event into memory. A contract that has not been registered with the indexer produces an error rather than silently looking like a contract with no activity.
Following live events over RPC
Live reads take a separate path. The SDK exports fetchLiveEvents and liveEventStream for reading directly from Soroban RPC. They do not require a running indexer, but their reach is limited by the RPC node's retention window. The SDK does not silently switch a failed historical query to RPC and pretend the result is equivalent. Choosing the source remains explicit, which helps an application understand what its data actually covers.
The live stream also behaves differently from a historical traversal. An RPC cursor does not signal that the network has finished producing events. liveEventStream keeps polling, including when a response contains no events, until the consumer leaves the loop. That is a live tail, not a one-time download of a completed dataset.
Preserve what the ledger actually emitted
Both paths return DecodedEvent values. Topics remain separate from the event's data, and raw XDR stays available alongside the decoded representation. A developer can inspect the underlying values when debugging instead of having to trust a transformed object with no way to check its origin. Event identifiers remain source-specific, so a live RPC identifier should not be treated as an indexer's stored event ID.
The decoding rules are deliberately careful about information loss. Integers wider than 32 bits are represented as strings so JavaScript and JSON do not silently round them. Soroban maps retain typed keys as ordered key/value entries rather than being flattened into ordinary JavaScript objects. An unsupported value can retain its base64 XDR as an unknown value, preserving something inspectable instead of discarding the entire event.
Validation and authenticated writes
Configuration and responses are validated at runtime as well as described by TypeScript types. That matters when URLs come from environment variables or data arrives over a network. The error hierarchy distinguishes validation problems, network failures, and authentication failures, giving callers a better basis for deciding whether to correct configuration, retry a request, or report a rejected operation.
Contract registration is a write operation and requires the indexer's admin bearer token. Public event reads do not carry that token. The SDK also rejects an admin token configured against a non-loopback HTTP indexer URL, preventing that configuration from sending the credential over an unencrypted connection. Registration belongs in a trusted environment where the token can remain private.
Getting started
To get started, install @pulsar-stellar/sdk together with its required peer dependency, @stellar/stellar-sdk. Configure PulsarClient with your indexer URL for stored history and an RPC URL for live reads. For a first integration, the showcase contract in pulsar-core provides a reference set of event shapes. Use the SDK README's examples and supported dependency versions rather than assuming the configuration of another Stellar tool applies unchanged.
Install the SDK and its required peer dependency:
npm install @pulsar-stellar/sdk @stellar/stellar-sdk
With an indexer running and your contract already registered, a paginated history read looks like this. Replace the example indexer URL with your own endpoint:
import { PulsarClient } from '@pulsar-stellar/sdk';
const client = new PulsarClient({
indexerUrl: 'https://your-indexer.example',
rpcUrl: 'https://soroban-testnet.stellar.org',
network: 'testnet',
});
const contractId =
'CDNWTVUDKCCGW7GOC6SBLUFXXUCD2YDHWRDUSXZ6CYBQKQWLCUYYWI5L';
const page = await client.events(contractId);
for (const event of page.items) {
console.log(event.ledger, event.name, event.data);
}
Where the SDK fits
The wider project also includes a web explorer in apps/web for people who want to inspect events in a browser. The Rust pulsar-decoder crate is a planned part of the core roadmap; the current TypeScript RPC path and Go indexer have their own decoding implementations. Keeping that distinction clear gives a more accurate picture of what a developer can use today.
For me, the useful idea behind Pulsar-Stellar is making event consumption reusable without hiding the choices that affect correctness. Stored history and a live tail serve different needs. A decoded value should preserve what the ledger actually emitted. A missing contract should not look like an empty result. Getting those details into shared tooling leaves application developers more room to work on the feature that needed the event in the first place.
Pulsar-Stellar as a reference for other coding agents
A commit from the same repository was selected for the Pulsar-Stellar reference corpus on XERJ. The selected work covers explorer states, accessibility improvements, and a health indicator in apps/web. My contributor page records the selection. As of October 26, 2026, the corpus is awaiting licence review and is not yet installable through the hub registry.
Read the story behind the selected commit for more on why its tests and detailed description matter.
Project references
About the author

Emmanuel Itighise
Founder of Stepfi-App, @Pulsar-Stellar/sdk, and Trybe.
Emmanuel Itighise, known online as Emeditweb, is a full-stack and AI-native developer based in Lagos, Nigeria. He builds practical products and developer tools, with a focus on web applications, AI, and the Stellar ecosystem. He shares lessons from building in public, contributing to open source, and turning ideas into working software.