StellarLens

TypeScript SDK for the Stellar network — smart RPC routing with latency-ranked automatic fallback, Soroban transaction pre-flight simulation, and human-readable XDR error decoding.

---

Packages

Package	Version	Description
stellar-lens		Core TypeScript SDK

---

Features

• Smart RPC routing — pool multiple Soroban endpoints, rank by latency, fall back automatically on failure
• Soroban pre-flight simulation — simulate a transaction before submitting: resource fee, CPU/memory cost, footprint, auth, and return value
• Human-readable XDR error decoding — turn opaque errorResultXdr / resultXdr / ScError blobs into plain-English explanations, including contract error codes
• Typed JSON-RPC 2.0 client — structured error classes, configurable timeouts, custom headers
• TypeScript-native — full .d.ts declarations, no @types/* packages required
• Dual ESM + CJS build — works in Node.js, bundlers, and edge runtimes
• Zero heavy dependencies — no Stellar SDK required to get started

---

Scope & Limitations

StellarLens is a read- and diagnostic-focused companion to the official Stellar SDK — it deliberately covers the gaps around RPC reliability, pre-flight simulation, and error legibility, rather than replacing the full transaction lifecycle.

• It does not build, sign, or submit transactions, and it manages no keypairs or accounts. Use @stellar/stellar-sdk (or @stellar/stellar-base) to construct and sign the TransactionEnvelope XDR, then pass that XDR to StellarLens to simulate it or decode its result.
• XDR is decoded, not encoded. The decoder reads result/error blobs; it does not produce XDR.
• Soroban-focused decoding. Soroban operation results are fully decoded; classic (non-Soroban) operation results are reported with partial: true (the transaction-level verdict is still accurate).
• Pre-1.0. The API may change between minor versions until 1.0.0.

---

Installation

npm install stellar-lens

pnpm add stellar-lens

---

Quick Start

Route calls across multiple endpoints

import { RpcRouter } from 'stellar-lens';

const router = new RpcRouter({
  endpoints: [
    'https://soroban-testnet.stellar.org',
    'https://rpc.ankr.com/stellar_testnet',
  ],
  timeout: 10_000,
});

router.start(); // pings all endpoints, ranks by latency, starts health-check timer

const ledger = await router.call<{ sequence: number }>('getLatestLedger');
console.log(ledger.sequence);

router.stop();

Single endpoint

import { RpcClient } from 'stellar-lens';

const client = new RpcClient({ url: 'https://soroban-testnet.stellar.org' });
const ledger = await client.call<{ sequence: number }>('getLatestLedger');

Simulate a transaction before submitting

import { RpcClient, TransactionSimulator } from 'stellar-lens';

const client = new RpcClient({ url: 'https://soroban-testnet.stellar.org' });
const simulator = new TransactionSimulator(client);

const result = await simulator.simulate(transactionEnvelopeXdr);
if (!result.success) throw new Error(result.error ?? 'Simulation failed');

console.log('resource fee:', result.minResourceFee); // stroops, as bigint
console.log('cpu instructions:', result.cost?.cpuInstructions);

Decode a failed Soroban transaction

import { explainTransactionError } from 'stellar-lens';

const res = await client.call('sendTransaction', [signedTxXdr]);

if (res.status === 'ERROR') {
  console.error(explainTransactionError(res));
  // → "txFAILED: One or more operations failed; see the operation results.
  //    [op 0 · INVOKE_HOST_FUNCTION: The contract trapped (panicked) during execution.]"
}

Typed error handling

import { RpcTimeoutError, RpcNetworkError, RpcResponseError, RpcParseError } from 'stellar-lens';

try {
  const result = await client.call('getLatestLedger');
} catch (err) {
  if (err instanceof RpcTimeoutError)   console.error(`Timed out after ${err.timeoutMs}ms`);
  if (err instanceof RpcNetworkError)   console.error(`Network failure: ${err.message}`);
  if (err instanceof RpcResponseError)  console.error(`RPC error ${err.code}: ${err.message}`);
  if (err instanceof RpcParseError)     console.error(`Bad JSON response`);
}

---

Documentation

• RpcClient — single-endpoint JSON-RPC client
• RpcRouter — multi-endpoint router with health checking and fallback
• Transaction Simulation — pre-flight Soroban simulation: fees, cost, footprint, and auth
• Error Decoding — human-readable XDR transaction & contract error decoding

---

Repository Layout

stellarlens/
├── packages/
│   ├── sdk/                # stellar-lens npm package (TypeScript)
│   ├── demo/              # documentation site (Next.js)
│   └── vscode-extension/  # VS Code extension (placeholder — see roadmap)
├── docs/                  # Full API documentation (generated from packages/demo/content)
├── .github/
│   └── workflows/         # CI, release, Dependabot, security scanning
└── ...

Planned packages: Python SDK, Go SDK, Rust/WASM port.

---

Development

Prerequisites: Node.js 20 LTS (pinned in .nvmrc), pnpm ≥ 10

The published package supports Node.js ≥ 18 (see engines); 20 LTS is the supported toolchain for working on the repo.

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run unit tests
pnpm test

# Run integration tests (requires network access)
pnpm --filter stellar-lens test:integration

# Typecheck
pnpm --filter stellar-lens typecheck

# Lint
pnpm lint

---

Contributing

1. Fork the repository and create a branch from main
2. Make your changes and add tests — the 80% coverage threshold is enforced in CI
3. Run pnpm lint and pnpm test locally before pushing
4. Open a pull request — the CI suite (typecheck → lint → test → build) must pass
5. A maintainer will review and merge

Bug reports and feature requests are welcome via GitHub Issues.

---

License

MIT