Stellar

Stellar Streaming SDK - TypeScript SDK for Zebec payment streams on Stellar via Soroban.

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.

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.

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.

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.

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 ContractError is thrown instead of a plain Error.

3. Transaction failures — on-chain FAILED status. The SDK inspects diagnosticEvents for a typed StreamError code and throws a ContractError when one is found.

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.

• formatSimulationError(context, rawError) — wraps a simulation error; returns ContractError when a code is detected, otherwise a plain Error.

• formatTransactionError(resultXdr, diagnosticEvents?) — wraps an on-chain failure; decodes diagnostic events first, then falls back to the raw resultXdr.

Related

• Streaming SDK overview

• Enterprise Payroll streaming guide

• Partner API overview