Zebec Stream SDK

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.

Features

• Stream Management: Create, cancel, pause, and resume payment streams
• Token Streaming: Support for SPL token streaming with customizable parameters
• Admin Functions: Configuration management and token whitelisting
• Flexible Permissions: Granular control over stream permissions and capabilities
• Type Safety: Full TypeScript support with comprehensive type definitions

Installation

npm install @zebec-network/stream-sdk

yarn add @zebec-network/stream-sdk

Quick Start

Setting up the Service

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

// Create connection
const connection = new Connection("https://api.devnet.solana.com");

// Create provider with your wallet
const provider = createAnchorProvider(connection, wallet);

// Initialize the service
const streamService = ZebecStreamService.create(provider, "devnet");

Creating a Stream

const streamParams = {
	receiver: "ReceiverPublicKeyHere",
	sender: "SenderPublicKeyHere",
	streamToken: "TokenMintAddressHere",
	amount: "1000", // Amount in token units
	duration: 86400, // 1 day in seconds
	streamFrequency: 3600, // 1 hour in seconds
	streamName: "Monthly Salary",
	startNow: true,
	automaticWithdrawal: false,
	cancelableByRecipient: true,
	cancelableBySender: true,
	isPausable: true,
	transferableByRecipient: false,
	transferableBySender: false,
	canTopup: true,
	rateUpdatable: false,
	cliffPercentage: 0, // No cliff
	startTime: Math.floor(Date.now() / 1000),
};

const transaction = await streamService.createStream(streamParams);
const signature = await transaction.execute();

API Reference

ZebecStreamService

The main service class for interacting with Zebec streams.

Constructor

static create(provider: Provider, network: "mainnet-beta" | "devnet"): ZebecStreamService

Stream Operations

createStream(params: CreateStreamParams)

Creates a new payment stream.

Parameters:

• receiver: Address - The recipient's public key
• sender: Address - The sender's public key
• streamToken: Address - The SPL token mint address
• amount: Numeric - Amount to stream (in token units)
• duration: number - Stream duration in seconds
• streamFrequency: number - Withdrawal frequency in seconds
• streamName: string - Human-readable stream name
• startNow: boolean - Whether to start immediately
• startTime: number - Unix timestamp for stream start
• cliffPercentage: Numeric - Percentage locked until cliff period
• automaticWithdrawal: boolean - Enable automatic withdrawals
• cancelableByRecipient: boolean - Allow recipient to cancel
• cancelableBySender: boolean - Allow sender to cancel
• isPausable: boolean - Allow stream pausing
• 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

cancelStream(params: CancelStreamParams)

Cancels an existing stream.

Parameters:

• streamMetadata: Address - The stream metadata account address
• user: Address - The user canceling the stream (sender or receiver)
• feePayer?: Address - Optional custom fee payer

pauseResumeStream(params: PauseResumeStreamParams)

Pauses or resumes a stream.

Parameters:

• streamMetadata: Address - The stream metadata account address

withdrawStream(params: WithdrawStreamParams)

Withdraws available tokens from a stream.

Parameters:

• streamMetadata: Address - The stream metadata account address
• receiver: Address - The recipient's address
• withdrawer?: Address - Optional custom withdrawer (defaults to receiver)

changeStreamReceiver(params: ChangeStreamReceiverParams)

Changes the recipient of a stream.

Parameters:

• streamMetadata: Address - The stream metadata account address
• newRecipient: Address - The new recipient's address
• signer: Address - The current authorized signer

Information Retrieval

getStreamMetadataInfo(streamMetadata: Address, commitment?: Commitment)

Retrieves detailed information about a stream.

Returns: StreamMetadataInfo containing:

• parties: Sender and receiver addresses
• financials: Token info, amounts, and cliff percentage
• schedule: Timing information and status
• permissions: Stream permission settings
• streamName: The stream's name

getStreamConfigInfo(commitment?: Commitment)

Retrieves global stream configuration.

Returns: StreamConfigInfo containing:

• admin: Admin public key
• withdrawerAccount: Withdraw account address
• whitelistedTokens: Array of whitelisted token addresses
• platformFee: Platform fee percentage
• baseFee: Base fee percentage
• frequencies: Allowed stream frequencies

Admin Operations

initializeConfig(params: InitializeConfigParams)

Initializes the global stream configuration (admin only).

Parameters:

• admin?: Address - Admin address (defaults to provider wallet)
• config.baseFeePercent: Numeric - Base fee percentage
• config.platformFeePercent: Numeric - Platform fee percentage
• config.frequencies: number[] - Allowed stream frequencies
• config.withdrawAccount: Address - Platform withdraw account

whiteListTokens(params: WhiteListTokensParams)

Adds tokens to the whitelist (admin only).

Parameters:

• admin: Address - Admin address
• tokens: Address[] - Array of token mint addresses to whitelist

Types

StreamMetadataInfo

type StreamMetadataInfo = {
	parties: {
		sender: PublicKey;
		receiver: PublicKey;
	};
	financials: {
		streamToken: PublicKey;
		cliffPercentage: number;
		depositedAmount: string;
		withdrawnAmount: string;
	};
	schedule: {
		startTime: number;
		endTime: number;
		lastWithdrawTime: number;
		frequency: number;
		duration: number;
		pausedTimestamp: number;
		pausedInterval: number;
		canceledTimestamp: number;
	};
	permissions: {
		cancelableBySender: boolean;
		cancelableByRecipient: boolean;
		automaticWithdrawal: boolean;
		transferableBySender: boolean;
		transferableByRecipient: boolean;
		canTopup: boolean;
		isPausable: boolean;
		rateUpdatable: boolean;
	};
	streamName: string;
};

StreamConfigInfo

type StreamConfigInfo = {
	admin: PublicKey;
	withdrawerAccount: PublicKey;
	whitelistedTokens: PublicKey[];
	platformFee: number;
	baseFee: number;
	frequencies: number[];
};

Provider Setup

AnchorProvider (Read/Write Operations)

For operations that require signing transactions:

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

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

ReadonlyProvider (Read-Only Operations)

For read-only operations:

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

const provider = createReadonlyProvider(connection, optionalWalletAddress);

Examples

Complete Stream Lifecycle

// 1. Create a stream
const createParams = {
	receiver: receiverAddress,
	sender: senderAddress,
	streamToken: tokenMintAddress,
	amount: "1000",
	duration: 86400, // 1 day
	streamFrequency: 3600, // 1 hour
	streamName: "Test Stream",
	startNow: true,
	// ... other parameters
};

const createTx = await streamService.createStream(createParams);
await createTx.execute();

// 2. Get stream info
const streamInfo = await streamService.getStreamMetadataInfo(streamMetadata);
console.log("Stream info:", streamInfo);

// 3. Withdraw from stream
const withdrawTx = await streamService.withdrawStream({
	streamMetadata,
	receiver: receiverAddress,
});
await withdrawTx.execute();

// 4. Cancel stream
const cancelTx = await streamService.cancelStream({
	streamMetadata,
	user: senderAddress,
});
await cancelTx.execute();

Error Handling

try {
	const transaction = await streamService.createStream(params);
	const signature = await transaction.execute();
	console.log("Stream created:", signature);
} catch (error) {
	if (error.message.includes("Invalid stream frequency")) {
		console.error("Please use an allowed stream frequency");
	} else {
		console.error("Stream creation failed:", error);
	}
}

Network Support

• Mainnet Beta: Production environment
• Devnet: Development and testing environment
• Testnet: Not supported

Dependencies

• @coral-xyz/anchor: Anchor framework for Solana
• @solana/web3.js: Solana Web3 JavaScript API
• @zebec-network/core-utils: Zebec utility functions
• @zebec-network/solana-common: Common Solana utilities
• bignumber.js: Arbitrary precision arithmetic

License

This project is licensed under the MIT License.

Support

For issues and questions:

• GitHub Issues: Repository Issues