Solana

Solana Streaming SDK - TypeScript SDK for Zebec payment streams on Solana via Anchor.

A TypeScript SDK for interacting with the Zebec Stream protocol on Solana. This SDK provides a comprehensive interface for creating, managing, and interacting with payment streams on the Zebec Network.

Overview

The Solana Streaming SDK enables developers to build applications that leverage continuous, programmable SPL-token streams on Solana. It wraps the underlying Anchor program interactions, handling instruction building, associated token account (ATA) resolution, fee quoting, and transaction composition 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 configurable 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/zebec-stream-sdk

yarn add @zebec-network/zebec-stream-sdk

Peer dependencies

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

• @coral-xyz/anchor — Anchor framework for Solana program interaction

• @solana/web3.js — Solana Web3 JavaScript API

• @solana/spl-token — SPL token utilities

• @metaplex-foundation/mpl-token-metadata — On-chain token metadata resolution

• @zebec-network/core-utils — Zebec core utility functions

• @zebec-network/solana-common — Common Solana helpers

• bignumber.js — Arbitrary-precision arithmetic

Requirements

• Node.js 18+ recommended

• TypeScript 5+ (when consuming from TS projects)

Quick start

import { Connection } from "@solana/web3.js";
import { ZebecStreamService, createAnchorProvider } from "@zebec-network/zebec-stream-sdk";

// 1. Create a connection to devnet or mainnet-beta
const connection = new Connection("https://api.devnet.solana.com");

// 2. Create an AnchorProvider using your wallet
const provider = createAnchorProvider(connection, wallet);

// 3. Initialize the service with a config name and network
const streamService = ZebecStreamService.create("my-app-config", provider, "devnet");

// 4. Create a stream
const tx = await streamService.createStream({
  sender: "SenderPublicKeyHere",
  receiver: "ReceiverPublicKeyHere",
  streamToken: "TokenMintAddressHere",
  amount: "1000",              // Amount in human-readable token units
  duration: 86400,             // Total stream duration in seconds (1 day)
  autoWithdrawFrequency: 3600, // Auto-withdrawal interval in seconds (1 hour)
  streamName: "Monthly Salary",
  startNow: true,
  startTime: Math.floor(Date.now() / 1000),
  cliffPercentage: 0,
  automaticWithdrawal: true,
  cancelableByRecipient: true,
  cancelableBySender: true,
  isPausable: true,
  transferableByRecipient: false,
  transferableBySender: false,
  canTopup: true,
  rateUpdatable: false,
});

const signature = await tx.execute();
console.log("Stream created:", signature);

Core concepts

Streams

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

Stream config

Every stream belongs to a named stream config PDA that holds the global protocol state: admin, fee tiers, allowed frequencies, withdraw account, fee vault, and whitelisted tokens. The config name is passed when creating the ZebecStreamService.

Fee model

Fees are configured globally per stream config:

• Platform fee — a percentage charged on every stream.

• Base fee — a flat percentage applied to every stream.

• Fee tiers — amount-banded percentage fees based on the USD value of the stream amount.

Fees are quoted dynamically from the Zebec backend at stream creation time. The SDK fetches the fee quote, computes the fee token and amount, and includes the fee transfer instruction automatically.

Decimals

The SDK automatically converts human-readable amounts to raw token units using the SPL token's on-chain decimals. Inputs like "1000" are scaled correctly before being passed to the program.

SDK methods

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

The service is constructed as:

ZebecStreamService.create(streamConfigName: string, provider: Provider, network: RpcNetwork)

Parameter	Type	Description
streamConfigName	string	Unique name identifying the stream config PDA.
provider	Provider	Anchor provider (read/write) or read-only provider.
network	"mainnet-beta" | "devnet"	Target network. Must match the connection's RPC endpoint network.

Admin methods

These methods configure the global protocol state and require the caller to be the config admin.

initializeStreamConfig(params): Promise<TransactionPayload>

Initializes the global stream configuration (admin only, one-time setup per streamConfigName).

• params.admin? — optional admin address (defaults to provider wallet).

• params.config.baseFeePercent — base fee as a percent string (e.g. "0.1").

• params.config.platformFeePercent — platform fee as a percent string (e.g. "0.05").

• params.config.frequencies — allowed auto-withdraw frequencies in seconds (e.g. [3600, 86400, 604800]).

• params.config.withdrawAccount — address that performs automatic withdrawals.

• params.config.feeVault — address that collects fees.

• params.config.feeTiers — array of FeeTier objects defining amount-banded fees.

await streamService.initializeStreamConfig({
  admin: adminAddress,
  config: {
    baseFeePercent: "0.1",
    platformFeePercent: "0.05",
    frequencies: [3600, 86400, 604800],
    withdrawAccount: "WithdrawAccountAddressHere",
    feeVault: "FeeVaultAddressHere",
    feeTiers: [
      { minThreshold: "0",     maxThreshold: "1000",  feeRateInPercent: "1.0" },
      { minThreshold: "1000",  maxThreshold: "10000", feeRateInPercent: "0.75" },
      { minThreshold: "10000", maxThreshold: "99999999", feeRateInPercent: "0.5" },
    ],
  },
});

updateStreamConfig(params): Promise<TransactionPayload>

Updates an existing stream configuration (admin only). Same parameter shape as initializeStreamConfig.

whiteListTokens(params): Promise<TransactionPayload>

Adds token mint addresses to the whitelist of streamable tokens (admin only).

Field	Type	Description
admin	Address	Admin public key.
tokens	Address[]	Array of token mint addresses to whitelist.

Stream methods

createStream(params): Promise<TransactionPayload>

Creates a new payment stream. Automatically fetches the fee quote from the Zebec backend and includes the fee transfer instruction in the transaction.

Field	Type	Description
sender	Address	Sender's public key.
receiver	Address	Recipient's public key.
streamToken	Address	SPL token mint address.
amount	Numeric	Amount to stream in human-readable token units.
duration	number	Stream duration in seconds.
autoWithdrawFrequency	number	Auto-withdrawal interval in seconds (must be in config's allowed frequencies when automaticWithdrawal is true).
streamName	string	Human-readable stream name (max 128 bytes).
startNow	boolean	Whether to start immediately.
startTime	number	Unix timestamp for scheduled start.
cliffPercentage	Numeric	Percentage of amount locked until cliff expires.
automaticWithdrawal	boolean	Enable automatic withdrawals.
cancelableByRecipient	boolean	Allow recipient to cancel.
cancelableBySender	boolean	Allow sender to cancel.
isPausable	boolean	Allow stream to be paused.
transferableByRecipient	boolean	Allow recipient to transfer.
transferableBySender	boolean	Allow sender to transfer.
canTopup	boolean	Allow adding funds to stream.
rateUpdatable	boolean	Allow rate modifications.
feePayer?	Address	Optional custom fee payer (defaults to sender).
streamMetadataKeypair?	Keypair	Optional custom metadata keypair (defaults to a generated keypair).

cancelStream(params): Promise<TransactionPayload>

Cancels an existing stream. Either sender or receiver can cancel (if allowed by stream permissions).

Field	Type	Description
streamMetadata	Address	Stream metadata account address.
user	Address	User canceling the stream (must be sender or receiver).
feePayer?	Address	Optional custom fee payer.

pauseResumeStream(params): Promise<TransactionPayload>

Toggles a stream between paused and active states. Only the sender can call this.

Field	Type	Description
streamMetadata	Address	Stream metadata account address.

withdrawStream(params): Promise<TransactionPayload>

Withdraws vested tokens from a stream to the receiver.

Field	Type	Description
streamMetadata	Address	Stream metadata account address.
receiver	Address	Recipient's public key.
withdrawer?	Address	Optional custom withdrawer (defaults to receiver).
feePayer?	Address	Optional custom fee payer.

changeStreamReceiver(params): Promise<TransactionPayload>

Transfers stream ownership to a new recipient.

Field	Type	Description
streamMetadata	Address	Stream metadata account address.
newRecipient	Address	New recipient's public key.
signer	Address	Currently authorized signer (sender or current receiver, depending on permissions).

Information retrieval

getStreamMetadataInfo(streamMetadata, commitment?): Promise<StreamMetadataInfo>

Retrieves detailed information about a stream. Amounts are returned as human-readable strings.

const info = await streamService.getStreamMetadataInfo("StreamMetadataAddressHere");
console.log(info.parties.sender.toBase58());
console.log(info.financials.depositedAmount); // human-readable
console.log(info.schedule.startTime);
console.log(info.permissions.isPausable);

getStreamConfigInfo(configName, commitment?): Promise<StreamConfigInfo>

Retrieves the global stream configuration for a given config name. Fee values are returned as human-readable percents.

const config = await streamService.getStreamConfigInfo("my-app-config");
console.log(config.frequencies);   // allowed auto-withdraw intervals
console.log(config.feeTiers);      // tiered fee schedule
console.log(config.feeVault.toBase58());

getWhitelistedTokens(configName, commitment?): Promise<TokenMetadata[]>

Fetches the list of whitelisted tokens with full on-chain mint info and Metaplex metadata.

const tokens = await streamService.getWhitelistedTokens("my-app-config");
tokens.forEach(t => {
  console.log(t.metadata?.symbol, t.mint.toBase58());
});

Low-level instruction builders

Each high-level method has a corresponding instruction builder for composing custom transactions:

Method	Returns
getCreateStreamInstruction(...)	Promise<TransactionInstruction>
getCancelStreamInstruction(...)	Promise<TransactionInstruction>
getPauseResumeStreamInstruction(...)	Promise<TransactionInstruction>
getWithdrawStreamInstruction(...)	Promise<TransactionInstruction>
getChangeStreamReceiverInstruction(...)	Promise<TransactionInstruction>
getWhitelistTokensInstruction(...)	Promise<TransactionInstruction>
getInitializeStreamConfigInstruction(...)	Promise<TransactionInstruction>
getUpdateStreamConfigInstruction(...)	Promise<TransactionInstruction>

Data types

All types are exported from the package root.

RpcNetwork

type RpcNetwork = "mainnet-beta" | "devnet";

Numeric

Human-readable number representation used for amounts and percentages.

type Numeric = string | number;

StreamConfigInfo

Read shape returned by getStreamConfigInfo.

Field	Type	Description
configName	string	The config name used to derive the PDA.
address	PublicKey	The stream config PDA address.
admin	PublicKey	Config admin address.
withdrawerAccount	PublicKey	Address that performs automatic withdrawals.
whitelistedTokens	PublicKey[]	Whitelisted token mint addresses.
platformFee	number	Platform fee as a human-readable percent.
baseFee	number	Base fee as a human-readable percent.
frequencies	number[]	Allowed auto-withdraw frequencies in seconds.
feeTiers	FeeTier[]	Tiered fee schedule.
feeVault	PublicKey	Fee collection vault address.

StreamMetadataInfo

Read shape returned by getStreamMetadataInfo.

Field	Type	Description
address	PublicKey	Stream metadata account address.
parties.sender	PublicKey	Sender's public key.
parties.receiver	PublicKey	Receiver's public key.
financials.streamToken	PublicKey	SPL token mint address.
financials.cliffPercentage	number	Cliff percentage as a human-readable percent.
financials.depositedAmount	string	Total deposited amount (human-readable).
financials.withdrawnAmount	string	Total withdrawn amount (human-readable).
schedule.startTime	number	Unix timestamp when streaming starts.
schedule.endTime	number	Unix timestamp when streaming ends.
schedule.lastWithdrawTime	number	Unix timestamp of the last withdrawal.
schedule.frequency	number	Auto-withdraw frequency in seconds.
schedule.duration	number	Total stream duration in seconds.
schedule.pausedTimestamp	number	Unix timestamp when the stream was paused (0 if never).
schedule.pausedInterval	number	Total paused duration in seconds.
schedule.canceledTimestamp	number	Unix timestamp when the stream was canceled (0 if never).
permissions.cancelableBySender	boolean	Whether sender can cancel.
permissions.cancelableByRecipient	boolean	Whether recipient can cancel.
permissions.automaticWithdrawal	boolean	Whether automatic withdrawals are enabled.
permissions.transferableBySender	boolean	Whether sender can reassign the receiver.
permissions.transferableByRecipient	boolean	Whether receiver can reassign themselves.
permissions.canTopup	boolean	Whether the stream supports top-ups.
permissions.isPausable	boolean	Whether the stream supports pause/resume.
permissions.rateUpdatable	boolean	Whether the stream rate can be updated.
streamName	string	Human-readable stream name.

CreateStreamParams

Parameters for createStream.

Field	Type	Description
sender	Address	Sender's public key.
receiver	Address	Recipient's public key.
streamToken	Address	SPL token mint address.
amount	Numeric	Amount to stream in human-readable token units.
duration	number	Stream duration in seconds.
autoWithdrawFrequency	number	Auto-withdrawal interval in seconds.
streamName	string	Human-readable stream name (max 128 bytes).
startNow	boolean	Whether to start immediately.
startTime	number	Unix timestamp for scheduled start.
cliffPercentage	Numeric	Percentage of amount locked until cliff expires.
automaticWithdrawal	boolean	Enable automatic withdrawals.
cancelableByRecipient	boolean	Allow recipient to cancel.
cancelableBySender	boolean	Allow sender to cancel.
isPausable	boolean	Allow stream to be paused.
transferableByRecipient	boolean	Allow recipient to transfer.
transferableBySender	boolean	Allow sender to transfer.
canTopup	boolean	Allow adding funds to stream.
rateUpdatable	boolean	Allow rate modifications.
feePayer?	Address	Optional custom fee payer.
streamMetadataKeypair?	Keypair	Optional custom metadata keypair.

CancelStreamParams

Parameters for cancelStream.

Field	Type	Description
streamMetadata	Address	Stream metadata account address.
user	Address	User canceling the stream (must be sender or receiver).
feePayer?	Address	Optional custom fee payer.

WithdrawStreamParams

Parameters for withdrawStream.

Field	Type	Description
streamMetadata	Address	Stream metadata account address.
receiver	Address	Recipient's public key.
withdrawer?	Address	Optional custom withdrawer.
feePayer?	Address	Optional custom fee payer.

ChangeStreamReceiverParams

Parameters for changeStreamReceiver.

Field	Type	Description
streamMetadata	Address	Stream metadata account address.
newRecipient	Address	New recipient's public key.
signer	Address	Currently authorized signer.

InitializeStreamConfigParams / UpdateStreamConfigParams

Parameters for initializeStreamConfig and updateStreamConfig.

Field	Type	Description
admin?	Address	Optional admin address (defaults to provider wallet).
config.baseFeePercent	Numeric	Base fee as a percent.
config.platformFeePercent	Numeric	Platform fee as a percent.
config.frequencies	number[]	Allowed auto-withdraw frequencies in seconds.
config.withdrawAccount	Address	Withdraw account address.
config.feeVault	Address	Fee vault address.
config.feeTiers	FeeTier[]	Tiered fee schedule.

WhiteListTokensParams

Parameters for whiteListTokens.

Field	Type	Description
admin	Address	Admin public key.
tokens	Address[]	Token mint addresses to whitelist.

FeeTier

A single fee tier band.

Field	Type	Description
minThreshold	Numeric	Minimum USD amount for this tier (inclusive).
maxThreshold	Numeric	Maximum USD amount for this tier (exclusive).
feeRateInPercent	Numeric	Fee rate for this tier as a percent.

TokenMetadata

On-chain token metadata with Metaplex resolution.

Field	Type	Description
mint	PublicKey	Token mint address.
decimals	number	Token decimals.
freezeAuthority	PublicKey | null	Freeze authority (if any).
supply	string	Total supply (human-readable).
isInitialized	boolean	Whether the mint is initialized.
mintAuthority	PublicKey | null	Mint authority (if any).
metadata	{ address, updateAuthority, name, symbol, uri } | null	Metaplex metadata (null if not found).

StreamFeeInfo

Returned by the Zebec backend fee quote API and used internally during stream creation.

Field	Type	Description
tokenSymbol	string	Stream token symbol.
mintAddress	string	Stream token mint address.
chain	string	Chain identifier.
streamAmount	string	Raw stream amount.
streamAmountUi	string	Human-readable stream amount.
tokenPriceUsd	number	Token price in USD.
streamAmountUsd	number	Stream amount in USD.
feeTier	{ tier, range, feeRatePercent }	Matched fee tier details.
feeRatePercent	number	Effective fee rate percent.
feeAmountUsd	number	Fee amount in USD.
feeToken	{ symbol, decimals, priceUsd, mintAddress }	Token used to pay fees.
feeAmount	number	Fee amount in fee token units.
feeAmountRaw	string	Raw fee amount (atomic units).

TransactionPayload

All write methods return a TransactionPayload (from @zebec-network/solana-common) rather than submitting directly, giving consumers control over the signing and submission flow.

class TransactionPayload {
  execute(): Promise<string>;
}

Call .execute() to sign (via the provider's wallet) and submit the transaction to the network. The payload internally handles address lookup tables, fee payer assignment, and optional signer injection.

The SDK also maps program error codes to human-readable messages using the IDL's error definitions, so failed transactions surface descriptive error messages.

Provider setup

AnchorProvider (read/write)

Use for operations that sign transactions:

import { createAnchorProvider } from "@zebec-network/zebec-stream-sdk";

const provider = createAnchorProvider(connection, wallet, {
  commitment: "confirmed",
  preflightCommitment: "confirmed",
});

ReadonlyProvider (read-only)

Use for read-only queries without a wallet:

import { createReadonlyProvider } from "@zebec-network/zebec-stream-sdk";

const provider = createReadonlyProvider(connection, optionalWalletAddress);

The ReadonlyProvider class exposes connection and an optional walletAddress for convenience in read-only contexts.

Wallet interface

The SDK exports an AnchorWallet interface for wallets that work with createAnchorProvider:

import type { AnchorWallet } from "@zebec-network/zebec-stream-sdk";

PDA utilities

import { deriveStreamConfigPda, deriveStreamVaultPda } from "@zebec-network/zebec-stream-sdk";

// Derive the stream config PDA
const [configPda] = deriveStreamConfigPda("my-app-config", programId);

// Derive the stream vault PDA for a given stream metadata address
const [vaultPda] = deriveStreamVaultPda(streamMetadataAddress, programId);

Utilities

Fee quote

Fetch a fee quote from the Zebec backend for a given token and stream amount. This is used internally by createStream, but can be called directly:

import { getFeeInfoForStream } from "@zebec-network/zebec-stream-sdk";

const feeInfo = await getFeeInfoForStream(tokenMint, amount, decimals, "devnet");
console.log(feeInfo.feeAmountRaw);
console.log(feeInfo.feeTier.range);

On-chain fee rate lookup

Given a USD amount and on-chain fee tiers, compute the fee rate in basis points:

import { getFeeRateForUsdAmount } from "@zebec-network/zebec-stream-sdk";

const feeBps = getFeeRateForUsdAmount("5000", feeTiers); // returns number in bps

Error handling

The SDK surfaces three classes of errors:

1. Validation errors — thrown immediately for invalid parameters (e.g., mismatched network, invalid stream frequency, stream name too long).

2. Simulation errors — returned by the Solana RPC during transaction simulation.

3. Transaction failures — on-chain errors mapped via the program IDL to human-readable messages.

Common error cases to handle:

try {
  const tx = await streamService.createStream(params);
  const signature = await tx.execute();
  console.log("Success:", signature);
} catch (error) {
  if (error.message.includes("Invalid stream frequency")) {
    console.error("autoWithdrawFrequency must be one of the config's allowed frequencies");
  } else if (error.message.includes("Network mismatch")) {
    console.error("Provider connection network does not match the service network");
  } else {
    console.error("Stream operation failed:", error);
  }
}

Constants

Constant	Description
STREAM_PROGRAM_ID	Program ID per network (zSTRMmYcFF8SPdHmsAmAUjBnx4zDHvnqqGz2mPcc5QC)
STREAM_PROGRAM_LOOKUP_TABLE_ADDRESS	Address lookup table per network
SUPERAPP_BACKEND_URL	Zebec backend URL per network (used for fee quotes)
STREAM_NAME_BUFFER_SIZE	Fixed buffer size for stream names (128 bytes)

Network support

Network	Status
Mainnet Beta	Supported
Devnet	Supported
Testnet	Not supported

Related

• Streaming SDK overview

• Enterprise Payroll streaming guide

• Partner API overview