Stellar Streaming SDK

A TypeScript SDK for interacting with Zebec's Stellar Streaming Contract. This SDK provides a high-level, type-safe interface to create and manage continuous payment streams on the Stellar network using Soroban smart contracts.

Table of Contents

• Overview
• Features
• Installation
• Quick Start
• Core Concepts
• SDK Methods
  • Admin Methods
  • Tenant Methods
  • Token Methods
  • Stream Methods
  • TTL Methods
• Data Types
• TransactionPayload
• Wallet Adapter
• Error Handling
• Project Structure
• Development
• License

Overview

The Stellar Streaming SDK enables developers to build applications that leverage continuous, programmable token streams on the Stellar network. It wraps the underlying Soroban contract interactions, handling transaction building, simulation, preparation, and submission while exposing strongly-typed, ergonomic APIs.

Typical use cases include:

• Payroll: Stream salaries to employees continuously per second / minute / hour.
• Vesting: Distribute tokens over time with optional cliffs.
• Subscriptions: Recurring payments and metered billing.
• Grants & Bounties: Time-locked, cancelable token distribution.

Features

• Type-safe TypeScript API with comprehensive type definitions
• Full lifecycle management for payment streams (create, pause/resume, cancel, withdraw, transfer)
• Configurable fee model with global, tenant-level, and tiered fees
• Token whitelisting and frequency configuration
• Automatic and manual top-ups
• Storage TTL management for long-running streams
• Pluggable wallet adapter for flexible signing flows
• Built on top of @stellar/stellar-sdk

Installation

Install the package using npm or yarn:

npm install @zebec-network/stellar-payroll-sdk

yarn add @zebec-network/stellar-payroll-sdk

Peer Dependencies

The SDK relies on the following runtime dependencies (installed automatically):

• @stellar/stellar-sdk ^15.0.1
• @zebec-network/core-utils ^1.1.1
• bignumber.js ^11.1.1

Requirements

• Node.js 18+ recommended
• TypeScript 5+ (when consuming from TS projects)

Quick Start

import {
  StellarStreamingService,
  type StellarStreamingSDKConfig,
  type WalletAdapter,
  type CreateStreamParams,
} from "@zebec-network/stellar-payroll-sdk";
import { Networks, Keypair, TransactionBuilder } from "@stellar/stellar-sdk";

// 1. Configure the SDK
const config: StellarStreamingSDKConfig = {
  contractId: "CDWK5GRLUB24FMWLWEAS3NLU2JCDW7T3BMU7HWKGEZEDJRXXESGLQ4YU",
  networkPassphrase: Networks.TESTNET,
  rpcUrl: "https://soroban-testnet.stellar.org",
};

// 2. Provide a wallet adapter
const keypair = Keypair.fromSecret("S...");
const wallet: WalletAdapter = {
  getPublicKey: async () => keypair.publicKey(),
  signTransaction: async (txXDR) => {
    const tx = TransactionBuilder.fromXDR(txXDR, Networks.TESTNET);
    tx.sign(keypair);
    return tx.toXDR();
  },
  signAllTransactions: async (txXDRs) =>
    txXDRs.map((txXDR) => {
      const tx = TransactionBuilder.fromXDR(txXDR, Networks.TESTNET);
      tx.sign(keypair);
      return tx.toXDR();
    }),
};

// 3. Instantiate the service
const service = new StellarStreamingService(config, wallet);

// 4. Create a stream
const params: CreateStreamParams = {
  amount: "100",
  start_time: "0",
  duration: "3600",
  cliff_percentage: "0",
  start_now: true,
  payroll_run_id: "october-payroll-2026",
  accrual_frequency: "1",
  pausable: true,
  cancelable_by_sender: true,
  cancelable_by_recipient: false,
  transferable_by_sender: false,
  transferable_by_recipient: false,
  automatic_withdrawal: false,
  initial_buffer_amount: "0",
  auto_topup: false,
  sender_id: "sender-1",
  receiver_id: "receiver-1",
  token_price: "10000000",
  price_expiry: "1893456000",
  price_signature: "a1b2c3...",
  token_contract_id: "abcd1234...",
  xlm_price: "2000000",
  xlm_price_expiry: "1893456000",
  xlm_price_signature: "d4e5f6...",
};

const payload = await service.createStream(
  await wallet.getPublicKey(),
  "GBR...RECEIVER",
  "0a1b2c...", // streamId (hex-encoded BytesN)
  "CTOKEN...ADDR", // token contract address
  params,
);

const result = await payload.signAndSubmit();
console.log("Tx hash:", result.txHash);

Core Concepts

Streams

A stream is an on-chain agreement to transfer a token amount from a sender to a receiver over a defined duration. Streams can be paused, resumed, canceled, transferred, and topped up depending on the flags set at creation.

Stream Identifiers

Stream IDs are 32-byte values passed as hex-encoded strings. Stellar's Soroban runtime expects fixed-size byte arrays (BytesN) — the SDK converts the provided hex string into the appropriate ScVal automatically.

Fee Model

Fees are configured at two layers:

1. Global config (set by admin) — applies by default to all streams.
2. Tenant config (set by admin, per sender) — overrides global fees for a specific sender.

Each layer defines a platform_fee, a base_fee, a stream_token_fee, and a list of fee_tiers (amount-banded percentage fees).

Decimals

The SDK automatically converts human-readable amounts to atomic units using the token's on-chain decimals (fetched via getAssetDecimals). Inputs like "100.5" are scaled correctly for the underlying SAC/token contract.

SDK Methods

All write methods return a TransactionPayload that must be signed and submitted. All read methods return parsed, human-readable values directly.

The service is constructed as:

new StellarStreamingService(config: StellarStreamingSDKConfig, wallet: WalletAdapter)

Admin Methods

These methods configure the global protocol state and require the caller's wallet to match the contract admin.

getConfig(caller: string): Promise<Config>

Reads the global protocol configuration: fee recipient, withdraw account, platform fee, base fee, stream token fee, fee tiers, frequencies, whitelisted tokens, the canonical XLM token address, the admin signer, the XLM token contract ID, and whether XLM is accepted as a fee token.

setFeeConfig(admin, params, options?): Promise<TransactionPayload>

Sets the protocol-wide fee configuration. The wallet's public key must match admin.

• params: SetFeeConfigParams — recipient, withdraw account, platform/base/stream-token fees (percent), fee tiers, and whether XLM is accepted as a fee token.

whitelistTokens(admin, tokens, options?): Promise<TransactionPayload>

Adds a list of token contract addresses to the whitelist of streamable tokens.

removeWhitelistedToken(admin, token, options?): Promise<TransactionPayload>

Removes a single token contract address from the whitelist.

setFrequencies(admin, frequencies, options?): Promise<TransactionPayload>

Updates the list of allowed accrual frequencies (in seconds) that streams can use.

updateConfig(admin, params, options?): Promise<TransactionPayload>

Bulk-updates the fee config and the allowed frequencies in a single transaction.

• params: UpdateConfigParams — same as SetFeeConfigParams plus frequencies, admin_signer, and xlm_token_contract_id.

Tenant Methods

Tenant configs let the admin set custom fee rules for a specific sender, overriding the global config for that sender's streams.

getTenantConfig(sender: string): Promise<TenantConfig>

Reads the tenant configuration assigned to a sender address: fee recipient, withdraw account, platform/base/stream-token fees, and fee tiers.

setTenantConfig(admin, params, options?): Promise<TransactionPayload>

Creates or updates the tenant config for params.sender. The wallet must match admin.

removeTenantConfig(admin, sender, options?): Promise<TransactionPayload>

Removes a tenant config, reverting the sender to the global fee defaults.

Token Methods

approveTokenSpending(caller, token, spender, amount, options?): Promise<TransactionPayload>

Approves a spender to transfer up to amount of token on behalf of caller (SEP-41 allowance). Required before invoking flows that pull funds via allowance, such as triggerTopup.

• amount is in display units; the SDK scales it to raw units using the token's on-chain decimals.
• The allowance lifetime is pinned to the network-enforced maximum entry TTL (fetched via getMaxEntryTtl), so the approval persists for the largest value the network will accept.
• The wallet's public key must match caller.

establishTrustline(caller, assets, options?): Promise<TransactionPayload>

Establishes classic Stellar trustlines for the caller for one or more assets in a single transaction. Each asset becomes one changeTrust operation, using the default maximum trustline limit.

Soroban contracts cannot invoke classic Stellar operations, so trustlines (a ChangeTrust op) cannot be opened from inside the streaming contract — they have to be opened SDK-side. This method bypasses the Soroban prepareTransaction step internally since the underlying operation is classic, not a host-function call.

• assets: Asset[] — classic assets to trust. Construct with new Asset(code, issuer) from @stellar/stellar-sdk (also re-exported from this package).
• The wallet's public key must match caller.
• Submitting against an already-trusted asset is a no-op on the network — safe to call again.

import { Asset } from "@zebec-network/stellar-payroll-sdk";

const usdc = new Asset(
  "USDC",
  "GA5ZSEFYNTRECNZXVT7AYG5WDXJWFEYDKHYZQ3LZWNK3RIEGBHV4QHGN",
);
const eurc = new Asset(
  "EURC",
  "GB3Q6QDZYTHWT7E5PVS3W7FUT5GVAFC5KSZFFLPU234JZTKLATKSEPCV",
);

const payload = await service.establishTrustline(caller, [usdc, eurc]);
await payload.signAndSubmit();

checkTrustline(caller, assets): Promise<{ asset: Asset; exists: boolean }[]>

Checks whether caller has established classic Stellar trustlines for the provided assets. Looks up the corresponding trustLine ledger entries via the Soroban RPC in a single batched call and returns one { asset, exists } entry per input asset, in the same order.

• assets: Asset[] — classic assets to check. Construct with new Asset(code, issuer).
• Read-only — does not submit a transaction and does not require the caller's wallet to match the SDK's wallet.
• Throws if assets is empty or if any entry is Asset.native(); every Stellar account implicitly trusts XLM, so a native trustline check is a programming error rather than a meaningful query.

Typical pairing with establishTrustline — only sign for the missing trustlines:

import { Asset } from "@zebec-network/stellar-payroll-sdk";

const want = [
  new Asset("USDC", "GA5ZSEFYNTRECNZXVT7AYG5WDXJWFEYDKHYZQ3LZWNK3RIEGBHV4QHGN"),
  new Asset("EURC", "GB3Q6QDZYTHWT7E5PVS3W7FUT5GVAFC5KSZFFLPU234JZTKLATKSEPCV"),
];

const statuses = await service.checkTrustline(caller, want);
const missing = statuses.filter((s) => !s.exists).map((s) => s.asset);

if (missing.length > 0) {
  const payload = await service.establishTrustline(caller, missing);
  await payload.signAndSubmit();
}

bulkTransfer(sender, asset, recipients, options?): Promise<TransactionPayload>

Executes a bulk transfer to multiple recipients using classic Stellar Payment operations. This bypasses Soroban contract invocation entirely, making it suitable for simple token distributions (e.g. payroll bonuses, airdrops, mass payouts) without interacting with the streaming contract.

• asset: Asset — classic asset to transfer. Construct with new Asset(code, issuer) from @stellar/stellar-sdk (also re-exported from this package). For SAC tokens, derive the asset from the token's code and issuer; the SDK automatically computes the SAC contract ID to query on-chain decimals and adjust amounts correctly.
• recipients — array of { destination: string; amount: string }. Each amount is in display units (e.g. "100.5"). The SDK converts each amount to the token's atomic units, accounting for the difference between the token's on-chain decimals and Stellar classic's 7-decimal precision.
• The wallet's public key must match sender.
• This method bypasses Soroban prepareTransaction internally because classic Payment operations are not host-function calls.
• Every destination account must exist on the ledger and must have established a trustline for the asset (unless the destination is the sender itself).

import { Asset } from "@zebec-network/stellar-payroll-sdk";

const usdc = new Asset(
  "USDC",
  "GA5ZSEFYNTRECNZXVT7AYG5WDXJWFEYDKHYZQ3LZWNK3RIEGBHV4QHGN",
);

const payload = await service.bulkTransfer(sender, usdc, [
  { destination: "GBR...RECEIVER_1", amount: "100" },
  { destination: "GBR...RECEIVER_2", amount: "250.5" },
  { destination: "GBR...RECEIVER_3", amount: "75" },
]);

const result = await payload.signAndSubmit();
console.log("Bulk transfer tx:", result.txHash);

Stream Methods

createStream(sender, receiver, streamId, token, params, options?): Promise<TransactionPayload>

Creates a new payment stream from sender to receiver.

• streamId — 32-byte hex string. The SDK encodes it as a BytesN.
• token — token contract address (Stellar Asset Contract or custom).
• params: CreateStreamParams — full stream configuration (see Data Types).

The amount in params.amount is scaled to the token's decimals automatically. The wallet must match sender.

createMultipleStreams(sender, entries, options?): Promise<TransactionPayload>

Creates multiple payment streams from sender in a single transaction.

• entries: CreateStreamEntry[] — one entry per stream, each carrying its own stream_id, receiver, token, and params.
• Each entry's params.amount and params.initial_buffer_amount are scaled to the entry's token decimals. Decimals are fetched once per unique token across the batch.
• The wallet must match sender.

createMultipleStreamsBatch(sender, entries, options?): Promise<BatchChunk<string[]>[]>

Creates multiple payment streams split across several transactions to stay within Soroban resource limits.

• entries: CreateStreamEntry[] — same as createMultipleStreams.
• options.chunkSize — optional, defaults to 5. Number of streams per chunk.
• Returns an array of BatchChunk<string[]>. Each chunk carries a payload (a TransactionPayload) and meta (the list of stream_ids in that chunk).
• The chunks can be signed and submitted all at once via TransactionPayload.signAndSubmitBatch.
• ⚠️ Not atomic across chunks. If a chunk fails, earlier chunks may already be committed on-chain. Inspect the responses (or catch BatchTransactionError) to determine partial success.

const chunks = await service.createMultipleStreamsBatch(
  sender.publicKey(),
  entries,
  { chunkSize: 7 },
);

const results = await TransactionPayload.signAndSubmitBatch(chunks, {
  abortOnFailure: false,
});

for (const result of results) {
  if (result.response?.status === "SUCCESS") {
    console.log("Created streams:", result.meta);
  } else {
    console.error("Failed chunk:", result.meta, result.buildError);
  }
}

getStream(caller, streamId): Promise<Stream>

Reads the full state of a stream by its ID. Amounts are returned as human-readable strings (scaled down by token decimals); timestamps as numbers; status as an array of strings.

getWithdrawableAmount(caller, streamId): Promise<string>

Returns the currently-vested, withdrawable amount as a human-readable decimal string. Internally fetches the stream first to determine the token decimals.

pauseResumeStream(caller, streamId, options?): Promise<TransactionPayload>

Toggles the paused/active state of a stream. caller must be the stream's sender, and the stream must have pausable: true.

pauseResumeAllStreams(caller, streamIds, options?): Promise<TransactionPayload>

Toggles the paused/active state of multiple streams in a single transaction.

• streamIds — array of 32-byte hex-encoded stream IDs.
• caller must be the sender of every stream in the batch. Streams that are non-pausable, terminal, or whose sender does not match caller are silently skipped by the contract.

pauseResumeAllStreamsBatch(caller, streamIds, options?): Promise<BatchChunk<string[]>[]>

Toggles the paused/active state of multiple streams split across several transactions to stay within Soroban resource limits.

• streamIds — array of 32-byte hex-encoded stream IDs.
• options.chunkSize — optional, defaults to 5. Number of stream IDs per chunk.
• Returns an array of BatchChunk<string[]>. Each chunk carries a payload and meta (the list of streamIds in that chunk).
• The chunks can be signed and submitted all at once via TransactionPayload.signAndSubmitBatch.
• ⚠️ Not atomic across chunks. If a chunk fails, earlier chunks may already be committed on-chain.

const chunks = await service.pauseResumeAllStreamsBatch(caller, streamIds, {
  chunkSize: 5,
});

const results = await TransactionPayload.signAndSubmitBatch(chunks, {
  abortOnFailure: false,
});

for (const result of results) {
  if (result.response?.status === "SUCCESS") {
    console.log("Toggled streams:", result.meta);
  } else {
    console.error("Failed chunk:", result.meta, result.buildError);
  }
}

cancelStream(caller, streamId, options?): Promise<TransactionPayload>

Cancels a stream. caller must be the sender (if cancelable_by_sender) or the receiver (if cancelable_by_recipient). Unvested funds are refunded to the sender.

cancelAllStreams(caller, streamIds, options?): Promise<TransactionPayload>

Cancels multiple streams in a single transaction.

• streamIds — array of 32-byte hex-encoded stream IDs.
• The caller-eligibility rule for cancelStream applies to each stream individually (sender with cancelable_by_sender, or receiver with cancelable_by_recipient). Streams that fail authorization, are terminal, or lack the vault balance to cover vested debt are silently skipped by the contract.

cancelAllStreamsBatch(caller, streamIds, options?): Promise<BatchChunk<string[]>[]>

Cancels multiple streams split across several transactions to stay within Soroban resource limits.

• streamIds — array of 32-byte hex-encoded stream IDs.
• options.chunkSize — optional, defaults to 5. Number of stream IDs per chunk.
• Returns an array of BatchChunk<string[]>. Each chunk carries a payload and meta (the list of streamIds in that chunk).
• The chunks can be signed and submitted all at once via TransactionPayload.signAndSubmitBatch.
• ⚠️ Not atomic across chunks. If a chunk fails, earlier chunks may already be committed on-chain.

const chunks = await service.cancelAllStreamsBatch(caller, streamIds, {
  chunkSize: 5,
});

const results = await TransactionPayload.signAndSubmitBatch(chunks, {
  abortOnFailure: false,
});

for (const result of results) {
  if (result.response?.status === "SUCCESS") {
    console.log("Canceled streams:", result.meta);
  } else {
    console.error("Failed chunk:", result.meta, result.buildError);
  }
}

withdrawStream(caller, streamId, options?): Promise<TransactionPayload>

Withdraws the vested amount.

• If automatic_withdrawal == true, caller must be stream.withdraw_account.
• If automatic_withdrawal == false, caller must be stream.receiver.

withdrawAllStreams(caller, streamIds, options?): Promise<TransactionPayload>

Withdraws the vested amount from multiple streams in a single transaction.

• streamIds — array of 32-byte hex-encoded stream IDs.
• The caller-eligibility rule for withdrawStream applies to each stream individually (stream.withdraw_account if automatic_withdrawal == true, otherwise stream.receiver); the same caller must satisfy this for every stream in the batch.

changeRecipient(caller, streamId, newReceiver, options?): Promise<TransactionPayload>

Reassigns the stream's receiver. caller must be the sender (if transferable_by_sender) or the current receiver (if transferable_by_recipient).

topupStream(caller, streamId, amount, options?): Promise<TransactionPayload>

Manually deposits additional funds into a stream. caller must be the stream's sender. amount is in display units; the SDK fetches the stream's token decimals and scales it to atomic units automatically.

triggerTopup(caller, streamId, amount, options?): Promise<TransactionPayload>

Triggers an automated top-up for a stream that has auto_topup_enabled. Callable by anyone (subject to contract rules). amount is in display units and is auto-scaled to the stream token's decimals. Requires a prior approveTokenSpending call so the contract can pull funds via allowance.

topupAllStreams(caller, entries, options?): Promise<TransactionPayload>

Top-ups multiple streams in a single transaction. caller must be the sender of every stream; entries owned by a different sender are silently skipped by the contract. No prior approveTokenSpending is needed because auth is collected once from caller.

• entries: TopupEntry[] — one entry per stream (see Data Types). Each amount is in display units; the SDK looks up each stream's token, fetches its decimals, and scales the amount to atomic units automatically. Duplicate stream IDs are deduplicated internally.

triggerTopupAllStreams(caller, entries, options?): Promise<TransactionPayload>

Triggers automated top-ups for multiple streams in a single transaction. Callable by anyone (subject to contract rules). Streams with auto_topup_enabled == false are silently skipped by the contract.

• entries: TopupEntry[] — one entry per stream. Each amount is in display units and is auto-scaled to the stream token's decimals. Requires a prior approveTokenSpending call for each stream's token so the contract can pull funds via allowance.

TTL Methods

Soroban contract data has a time-to-live (TTL) for persistent storage. These methods extend it.

bumpStreamTtl(caller, streamId, options?): Promise<TransactionPayload>

Extends the TTL of a specific stream's persistent storage entry. Callable by anyone.

bumpConfigTtl(caller, options?): Promise<TransactionPayload>

Extends the TTL of the protocol's config instance storage. Callable by anyone.

Data Types

All types are exported from the package root.

StellarStreamingSDKConfig

SDK constructor configuration.

| Field | Type | Description | | ------------------- | -------- | ------------------------------------------------------------------------- | | contractId | string | Soroban contract address of the streaming contract. | | networkPassphrase | string | Stellar network passphrase (Networks.TESTNET, Networks.PUBLIC, etc.). | | rpcUrl | string | URL of a Soroban RPC endpoint. |

WalletAdapter

Interface every wallet implementation must satisfy.

| Field | Type | Description | | --------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | getPublicKey | () => Promise<string> | Returns the source account's public key (G…). | | signTransaction | (txXDR: string) => Promise<string> | Signs a transaction in XDR format and returns the signed XDR. | | signAllTransactions | (txXDRs: string[]) => Promise<string[]> (optional) | Signs an array of transaction XDRs and returns the signed XDRs in the same order. Used by batch / multi-sign flows. Optional — only needed if you intend to use multi-sign helpers. |

TransactionOptions

Optional overrides for transaction building.

| Field | Type | Description | | --------- | --------- | -------------------------------------------------- | | fee | string? | Custom fee (stroops). Defaults to BASE_FEE. | | timeout | number? | Transaction timeout in seconds. Defaults to 180. |

FeeTier

A single fee tier band, expressed in human-readable units.

| Field | Type | Description | | ------------- | ------------------ | -------------------------------------- | | min_amount | string \| number | Lower bound (inclusive) for this tier. | | max_amount | string \| number | Upper bound (exclusive) for this tier. | | fee_percent | number | Fee percentage (e.g. 0.5 for 0.5%). |

ParsedFeeTier

Internal representation after scaling: amounts in atomic units and fee converted to basis points. Returned by the conversion utilities.

| Field | Type | | ------------ | -------- | | min_amount | string | | max_amount | string | | fee_bps | string |

TenantConfig

Read shape returned by getTenantConfig, and base shape for fee-related parameter types.

| Field | Type | Description | | ------------------ | ----------- | -------------------------------------------- | | fee_recipient | string | Address that receives collected fees. | | withdraw_account | string | Address that performs automatic withdrawals. | | platform_fee | number | Platform-level fee percent. | | base_fee | number | Base fee percent applied to every stream. | | stream_token_fee | number | Fee percent charged in the stream token. | | fee_tiers | FeeTier[] | Amount-banded percentage fees. |

SetFeeConfigParams

Parameters for setFeeConfig. Same fields as TenantConfig, plus:

| Field | Type | Description | | ------------ | --------- | --------------------------------------- | | xlm_as_fee | boolean | Whether XLM is accepted as a fee token. |

UpdateConfigParams

Parameters for updateConfig. Same fields as SetFeeConfigParams, plus:

| Field | Type | Description | | ----------------------- | ---------- | ----------------------------------------------- | | frequencies | number[] | Allowed accrual frequencies in seconds. | | admin_signer | string | Hex-encoded admin signer public key (32 bytes). | | xlm_token_contract_id | string | Hex-encoded XLM token contract ID (32 bytes). |

SetTenantConfigParams

Parameters for setTenantConfig. Same shape as TenantConfig, plus:

| Field | Type | Description | | -------- | -------- | ------------------------------------------------ | | sender | string | The sender address the tenant config applies to. |

Config

Read shape returned by getConfig. Extends TenantConfig with:

| Field | Type | Description | | ----------------------- | ---------- | ----------------------------------------------- | | frequencies | number[] | Allowed accrual frequencies in seconds. | | whitelisted_tokens | string[] | Token contract addresses permitted for streams. | | xlm_token | string | Canonical XLM (Stellar Asset Contract) address. | | admin_signer | string | Hex-encoded admin signer public key. | | xlm_token_contract_id | string | Hex-encoded XLM token contract ID. | | xlm_as_fee | boolean | Whether XLM is accepted as a fee token. |

CreateStreamParams

Full parameters for creating a stream.

| Field | Type | Description | | --------------------------- | --------- | ------------------------------------------------------------------------ | | amount | string | Total stream amount (human-readable; scaled by token decimals). | | start_time | string | Unix timestamp (seconds) when streaming begins (ignored if start_now). | | duration | string | Stream duration in seconds. | | cliff_percentage | string | Percent of total that vests at start (basis-point–like input). | | start_now | boolean | If true, streaming starts at on-chain submission time. | | payroll_run_id | string | Off-chain identifier linking the stream to a payroll run. | | accrual_frequency | string | Vesting tick interval, in seconds. Must be in the allowed frequencies. | | pausable | boolean | Whether the stream supports pause/resume. | | cancelable_by_sender | boolean | Whether the sender may cancel. | | cancelable_by_recipient | boolean | Whether the receiver may cancel. | | transferable_by_sender | boolean | Whether the sender may reassign the receiver. | | transferable_by_recipient | boolean | Whether the receiver may reassign themselves. | | automatic_withdrawal | boolean | If true, the configured withdraw_account performs withdrawals. | | initial_buffer_amount | string | Optional buffer amount (human-readable; scaled by token decimals). | | auto_topup | boolean | If true, the stream supports automated top-ups. | | sender_id | string | Off-chain identifier for the sender (e.g. employer ref). | | receiver_id | string | Off-chain identifier for the receiver (e.g. employee ref). | | token_price | string | Token price in USD. | | price_expiry | string | Unix timestamp when the token price signature expires. | | price_signature | string | Hex-encoded admin signature over the token price data. | | token_contract_id | string | Hex-encoded token contract ID (32 bytes). | | xlm_price | string | XLM price in USD. | | xlm_price_expiry | string | Unix timestamp when the XLM price signature expires. | | xlm_price_signature | string | Hex-encoded admin signature over the XLM price data. |

CreateStreamEntry

One entry in a createMultipleStreams batch. Carries everything createStream would otherwise take as positional arguments.

| Field | Type | Description | | ----------- | -------------------- | --------------------------------------------------------------- | | stream_id | string | 32-byte hex-encoded stream identifier (BytesN). | | receiver | string | Receiver account address. | | token | string | Token contract address (SAC or custom) for this stream. | | params | CreateStreamParams | Full stream configuration; amounts are in human-readable units. |

TopupEntry

One entry in a topupAllStreams or triggerTopupAllStreams batch.

| Field | Type | Description | | ----------- | -------- | ------------------------------------------------------------------------- | | stream_id | string | 32-byte hex-encoded stream identifier (BytesN). | | amount | string | Top-up amount in human-readable display units (scaled by token decimals). |

BatchChunk<T>

A single chunk in a batch submission, pairing a deferred payload with caller-defined metadata (e.g. the stream IDs contained in the chunk).

| Field | Type | Description | | --------- | -------------------- | --------------------------------------------------------------- | | payload | TransactionPayload | The deferred transaction payload for this chunk. | | meta | T | Caller-defined metadata — for batch methods this is string[]. |

BatchChunkResult<T>

Result of processing one chunk in a batch.

| Field | Type | Description | | ------------ | ----------------------------- | ------------------------------------------------------------------------ | | meta | T | The same metadata from the original BatchChunk. | | response | Api.GetTransactionResponse? | Present when the chunk was successfully built and submitted. | | buildError | Error? | Present when the chunk failed during buildTransactionXDR (simulation). |

Exactly one of response or buildError will be set.

TransactionPayload

All write methods return a TransactionPayload rather than submitting directly, giving consumers control over the signing/submission flow.

class TransactionPayload {
  readonly server: Server;
  readonly sourcePublicKey: string;
  readonly operations: xdr.Operation[];
  readonly networkPassphrase: string;
  readonly memo?: string;

  buildTransaction(
    options?: TransactionOptions,
  ): Promise<Transaction | FeeBumpTransaction>;
  buildTransactionXDR(options?: TransactionOptions): Promise<string>;
  signAndSubmit(
    options?: TransactionOptions,
  ): Promise<Api.GetTransactionResponse>;
}

Build + simulate work is deferred until one of these methods is called, so the source account's sequence number and Soroban resource fees stay fresh even if the user pauses between the SDK call and the wallet popup.

• buildTransaction(options?) — Fetches a fresh sequence number, simulates the operation, applies the Soroban footprint and resource fees, and returns the prepared transaction (unsigned). Throws "Simulation failed: ..." if the RPC reports a simulation error.
• buildTransactionXDR(options?) — Convenience wrapper that returns the prepared transaction's base64 XDR string. Useful for handing to an external signer (hardware wallet, multi-sig coordinator, browser wallet).
• signAndSubmit(options?) — Builds, signs via the configured WalletAdapter, submits to the network, and polls until a final status is available.

options (TransactionOptions) shallow-merges on top of any construction-time options; per-call values win.

This separation lets you, for example, build the payload server-side and submit it client-side, or sign with multiple parties before submission.

Batch Submission

TransactionPayload also exposes a static signAndSubmitBatch method for executing multiple chunks as a single batch. All payloads must share the same server, source public key, and network passphrase. Sequence numbers are assigned contiguously starting from the current ledger sequence, so the transactions can be signed all at once (via WalletAdapter.signAllTransactions) and then submitted sequentially.

TransactionPayload.signAndSubmitBatch(chunks, options?): Promise<BatchChunkResult<T>[]>

• chunks: BatchChunk<T>[] — array of chunks to execute.
• options.abortOnFailure — optional, defaults to true. When true, the first failing chunk aborts the entire batch and throws a BatchTransactionError.
• Returns an array of BatchChunkResult<T> in the same order as chunks.

When abortOnFailure is false, failed chunks are included in the results with their error or non-success status, letting you inspect partial success:

const results = await TransactionPayload.signAndSubmitBatch(chunks, {
  abortOnFailure: false,
});

for (let i = 0; i < results.length; i++) {
  const result = results[i];
  if (result.buildError) {
    console.error(`Chunk ${i + 1} failed to build:`, result.buildError.message);
  } else if (result.response?.status !== "SUCCESS") {
    console.error(`Chunk ${i + 1} failed on-chain:`, result.response?.txHash);
  } else {
    console.log(`Chunk ${i + 1} succeeded:`, result.response.txHash);
  }
}

BatchTransactionError

Thrown by signAndSubmitBatch when abortOnFailure is true and a chunk fails.

| Property | Type | Description | | ------------- | -------------------- | -------------------------------------------------- | | results | BatchChunkResult[] | Every result processed so far, including failures. | | failedIndex | number | Index of the first failing chunk. | | meta | unknown | Metadata of the first failing chunk. |

Wallet Adapter

The SDK is signer-agnostic. Any object satisfying the WalletAdapter interface works — Freighter, Albedo, Rabet, a Keypair-backed local signer, or a custom remote signer.

Example with a local Keypair:

import { Keypair, Networks, TransactionBuilder } from "@stellar/stellar-sdk";

const keypair = Keypair.fromSecret(process.env.SECRET!);
const wallet: WalletAdapter = {
  getPublicKey: async () => keypair.publicKey(),
  signTransaction: async (txXDR) => {
    const tx = TransactionBuilder.fromXDR(txXDR, Networks.TESTNET);
    tx.sign(keypair);
    return tx.toXDR();
  },
  signAllTransactions: async (txXDRs) =>
    txXDRs.map((txXDR) => {
      const tx = TransactionBuilder.fromXDR(txXDR, Networks.TESTNET);
      tx.sign(keypair);
      return tx.toXDR();
    }),
};

Example with Freighter (browser):

import freighter from "@stellar/freighter-api";

const wallet: WalletAdapter = {
  getPublicKey: () => freighter.getPublicKey(),
  signTransaction: (txXDR) =>
    freighter.signTransaction(txXDR, { networkPassphrase: Networks.PUBLIC }),
  signAllTransactions: async (txXDRs) =>
    Promise.all(
      txXDRs.map((txXDR) =>
        freighter.signTransaction(txXDR, {
          networkPassphrase: Networks.PUBLIC,
        }),
      ),
    ),
};

Error Handling

The SDK distinguishes three classes of errors:

1. Wallet / caller mismatch — thrown immediately when the supplied admin/sender/caller does not match the wallet's public key.
2. Simulation errors — returned by the Soroban RPC during transaction simulation. If the raw error contains a recognized contract error code, a {@link ContractError} is thrown instead of a plain Error.
3. Transaction rejections / failures — RPC ERROR and on-chain FAILED statuses. The SDK first inspects diagnostic events for a typed StreamError; otherwise it decodes the Stellar transaction result into a StellarTransactionError.

StellarTransactionError

Stellar Core failures such as an underfunded wallet, stale sequence number, or expired transaction are exposed as a typed error. The message is safe to display by default, while structured fields let an application choose product-specific copy and actions.

import {
  StellarTransactionError,
  formatTransactionSubmissionError,
} from "@zebec-network/stellar-payroll-sdk";

try {
  await payload.signAndSubmit();
} catch (err) {
  if (err instanceof StellarTransactionError) {
    console.error(err.code, err.recoveryAction, err.resultXdr);
    showError(err.message);
  }
}

// Use the same decoder when an application submits a signed transaction itself.
const response = await rpcServer.sendTransaction(signedTransaction);
if (response.status === "ERROR") {
  throw formatTransactionSubmissionError(response);
}

For txInsufficientBalance, for example, the default message explains that the wallet lacks spendable XLM while maintaining its minimum reserve and tells the user to add XLM. The raw result XDR remains available in resultXdr for logs; it is not included in message.

| Property | Description | | ----------------- | --------------------------------------------------------- | | code | Stellar result code, e.g. "txInsufficientBalance" | | recoveryAction | Stable UI category, e.g. "fund_source_account" | | retryable | Whether retrying is appropriate after the recovery action | | stage | "submission" or "confirmation" | | feeChargedXlm | Fee from the Stellar result XDR, converted from stroops | | transactionHash | Transaction hash when supplied by RPC | | latestLedger | Latest ledger reported by RPC | | resultXdr | Raw base64 result retained for diagnostics |

ContractError

When the streaming contract rejects an operation it returns a StreamError (a numeric code). The SDK decodes this into a ContractError so you can react programmatically instead of parsing strings.

import {
  ContractError,
  StreamErrorCode,
} from "@zebec-network/stellar-payroll-sdk";

try {
  const payload = await service.cancelStream(caller, streamId);
  await payload.signAndSubmit();
} catch (err) {
  if (err instanceof ContractError) {
    console.error(`Contract rejected: ${err.errorName} (code ${err.code})`);

    if (err.code === StreamErrorCode.StreamNotCancelable) {
      // show user-friendly "this stream cannot be cancelled" message
    }
  } else {
    console.error("Unexpected error:", (err as Error).message);
  }
}

| Property | Type | Description | | ----------- | -------- | ----------------------------------------------------- | | code | number | Numeric error code returned by the contract. | | errorName | string | Human-readable enum name (e.g. "StreamNotStarted"). | | message | string | "Contract error #2: StreamNotStarted" |

StreamErrorCode

All known contract error codes are exported as a typed enum:

enum StreamErrorCode {
  StreamAlreadyCanceled = 1,
  StreamNotStarted = 2,
  StreamAlreadyEnded = 3,
  StreamNotPausable = 4,
  InsufficientFundsToWithdraw = 5,
  StreamNotCancelable = 6,
  SenderCannotBeReceiver = 7,
  InvalidStartTime = 8,
  InvalidDuration = 9,
  InvalidAmount = 10,
  InvalidCliffPercentage = 11,
  FeesExceedAmount = 12,
  InvalidTopupAmount = 14,
  AutoTopupNotEnabled = 15,
  TopupNotAvailable = 16,
  StreamNotCancelableByRecipient = 17,
  RecipientTransferNotAllowed = 18,
  UnauthorizedWithdrawal = 19,
  StreamAlreadyExists = 20,
  StreamNameTooLong = 21,
  InsufficientAllowanceForTopup = 22,
  MaxWhitelistedTokensExceeded = 30,
  TokenNotWhitelisted = 31,
  InvalidFeeConfig = 32,
  MaxFeetiersExceeded = 35,
  InvalidFrequency = 36,
  MaxFrequenciesExceeded = 37,
  PriceExpired = 38,
  TokenMismatch = 39,
  InvalidPriceSignature = 40,
  FeeTiersNotSet = 41,
}

Polling timeout

signAndSubmit polls the RPC until the transaction is final. To prevent infinite loops, polling stops after 30 attempts (roughly 30 seconds) and throws:

Transaction polling timed out after 30 attempts. Hash: <hash>

Utilities

The following helpers are exported for advanced use cases:

• parseContractError(error) — tries to extract a ContractError from a raw string, number, or SDK error object.
• parseContractErrorFromDiagnosticEvents(events) — scans Soroban DiagnosticEvent[] for a contract error topic.
• decodeStellarTransactionFailure(error) — decodes SDK, RPC, Horizon, raw XDR, and legacy SDK transaction failures.
• describeStellarTransactionFailure(failure) — returns actionable default copy for a decoded Stellar result.
• formatTransactionSubmissionError(response) — converts an RPC ERROR response into a structured error.
• formatSimulationError(context, rawError) — wraps a simulation error; returns ContractError when a code is detected, otherwise a plain Error.
• formatTransactionError(resultXdr, diagnosticEvents?, context?) — wraps an on-chain failure; decodes diagnostic events first, then the Stellar transaction result.

Project Structure

src/
├── constants.ts         # Network-keyed contract addresses
├── conversions.ts       # ScVal <-> native conversion helpers
├── errors.ts            # Contract error decoding and formatting
├── index.ts             # Public exports
├── services.ts          # StellarStreamingService — main entrypoint
├── transactionPayload.ts# TransactionPayload class
├── types.ts             # All public type definitions
└── utils.ts             # getAssetDecimals, submitTransaction, etc.
test/                    # Mocha + ts-mocha integration tests

Development

Clone the repository and install dependencies:

git clone https://github.com/zebec-network/stellar-streaming-sdk.git
cd stellar-streaming-sdk
npm install

Scripts

| Script | Description | | ---------------- | ----------------------------------------- | | npm run build | Cleans dist/ and compiles TypeScript. | | npm run clean | Removes the dist/ directory. | | npm run format | Formats source files with Biome. | | npm test | Runs the Mocha test suite via ts-mocha. |

Running Tests

The test suite expects a .env file with the necessary keys (sender/receiver secrets, RPC URL, contract ID, stream ID). See the existing tests under test/ for required variables.

npm test

License

MIT © Zebec Network