@zebec-network/zebec-stream-sdk 3.1.1 → 3.1.2

package/README.md

@@ -4,344 +4,667 @@ A TypeScript SDK for interacting with the Zebec Stream protocol on Solana. This
 
 ## 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
+- **Stream Management**: Create, cancel, pause, resume, and withdraw from payment streams
+- **Token Streaming**: SPL token streaming with configurable cliff, frequency, and duration
+- **Tiered Fee System**: Dynamic fee calculation based on stream amount via on-chain fee tiers
+- **Token Whitelisting**: Admin-controlled token whitelist with full metadata resolution via Metaplex
+- **Admin Operations**: Initialize and update global stream configuration, fee tiers, and fee vaults
+- **Flexible Permissions**: Granular per-stream control — cancellation, transfer, topup, pause, and rate update permissions
+- **PDA Utilities**: Helpers for deriving stream config and stream vault program-derived addresses
+- **Provider Abstractions**: Separate read-only and read-write provider helpers
 - **Type Safety**: Full TypeScript support with comprehensive type definitions
 
 ## Installation
 
 ```bash
-npm install @zebec-network/stream-sdk
+npm install @zebec-network/zebec-stream-sdk
 ```
 
 ```bash
-yarn add @zebec-network/stream-sdk
+yarn add @zebec-network/zebec-stream-sdk
 ```
 
 ## Quick Start
 
-### Setting up the Service
+### Setting Up the Service
 
 ```typescript
-import { Connection, PublicKey } from "@solana/web3.js";
-import { ZebecStreamService, createAnchorProvider } from "@zebec-network/stream-sdk";
+import { Connection } from "@solana/web3.js";
+import { ZebecStreamService, createAnchorProvider } from "@zebec-network/zebec-stream-sdk";
 
-// Create connection
+// Create a connection to devnet or mainnet-beta
 const connection = new Connection("https://api.devnet.solana.com");
 
-// Create provider with your wallet
+// Create an AnchorProvider using your wallet
 const provider = createAnchorProvider(connection, wallet);
 
-// Initialize the service
-const streamService = ZebecStreamService.create(provider, "devnet");
+// Initialize the service with a config name and network
+const streamService = ZebecStreamService.create("my-app-config", provider, "devnet");
 ```
 
 ### Creating a Stream
 
 ```typescript
-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 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 transaction = await streamService.createStream(streamParams);
-const signature = await transaction.execute();
+const signature = await tx.execute();
+console.log("Stream created:", signature);
 ```
 
 ## API Reference
 
-### ZebecStreamService
+### `ZebecStreamService`
 
 The main service class for interacting with Zebec streams.
 
-#### Constructor
+#### `ZebecStreamService.create(streamConfigName, provider, network)`
+
+Creates a new service instance. Validates that the provider connection network matches the specified `network`.
 
 ```typescript
-static create(provider: Provider, network: "mainnet-beta" | "devnet"): ZebecStreamService
+static create(
+  streamConfigName: string,
+  provider: Provider,
+  network: "mainnet-beta" | "devnet"
+): ZebecStreamService
 ```
 
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `streamConfigName` | `string` | Unique name identifying the stream config PDA |
+| `provider` | `Provider` | Anchor or readonly provider |
+| `network` | `RpcNetwork` | `"mainnet-beta"` or `"devnet"` |
+
+---
+
 ### Stream Operations
 
-#### createStream(params: CreateStreamParams)
+#### `createStream(params)`
 
-Creates a new payment stream.
+Creates a new payment stream. Automatically fetches the fee quote from the Zebec backend and includes the fee transfer instruction in the transaction.
 
-**Parameters:**
+**Parameters** (`CreateStreamParams`):
 
-- `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.
+| 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 |
 
-**Parameters:**
+**Returns:** `Promise<TransactionPayload>`
 
-- `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)
+#### `cancelStream(params)`
 
-Pauses or resumes a stream.
+Cancels an existing stream. Either sender or receiver can cancel (if allowed by stream permissions).
 
-**Parameters:**
+**Parameters** (`CancelStreamParams`):
+
+| 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 |
+
+**Returns:** `Promise<TransactionPayload>`
 
-- `streamMetadata`: Address - The stream metadata account address
+---
 
-#### withdrawStream(params: WithdrawStreamParams)
+#### `pauseResumeStream(params)`
 
-Withdraws available tokens from a stream.
+Toggles a stream between paused and active states. Only the sender can call this.
 
 **Parameters:**
 
-- `streamMetadata`: Address - The stream metadata account address
-- `receiver`: Address - The recipient's address
-- `withdrawer?`: Address - Optional custom withdrawer (defaults to receiver)
+| Field | Type | Description |
+| --- | --- | --- |
+| `streamMetadata` | `Address` | Stream metadata account address |
 
-#### changeStreamReceiver(params: ChangeStreamReceiverParams)
+**Returns:** `Promise<TransactionPayload>`
 
-Changes the recipient of a stream.
+---
 
-**Parameters:**
+#### `withdrawStream(params)`
+
+Withdraws vested tokens from a stream to the receiver.
+
+**Parameters** (`WithdrawStreamParams`):
+
+| 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 |
+
+**Returns:** `Promise<TransactionPayload>`
+
+---
+
+#### `changeStreamReceiver(params)`
+
+Transfers stream ownership to a new recipient.
+
+**Parameters** (`ChangeStreamReceiverParams`):
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `streamMetadata` | `Address` | Stream metadata account address |
+| `newRecipient` | `Address` | New recipient's public key |
+| `signer` | `Address` | Currently authorized signer |
 
-- `streamMetadata`: Address - The stream metadata account address
-- `newRecipient`: Address - The new recipient's address
-- `signer`: Address - The current authorized signer
+**Returns:** `Promise<TransactionPayload>`
+
+---
 
 ### Information Retrieval
 
-#### getStreamMetadataInfo(streamMetadata: Address, commitment?: Commitment)
+#### `getStreamMetadataInfo(streamMetadata, commitment?)`
 
 Retrieves detailed information about a stream.
 
-**Returns:** `StreamMetadataInfo` containing:
+**Returns:** `Promise<StreamMetadataInfo>`
+
+```typescript
+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);
+```
+
+---
 
-- `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(configName, commitment?)`
+
+Retrieves the global stream configuration for a given config name.
+
+**Returns:** `Promise<StreamConfigInfo>`
+
+```typescript
+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());
+```
 
-#### getStreamConfigInfo(commitment?: Commitment)
+---
 
-Retrieves global stream configuration.
+#### `getWhitelistedTokens(configName, commitment?)`
 
-**Returns:** `StreamConfigInfo` containing:
+Fetches the list of whitelisted tokens with full on-chain mint info and Metaplex metadata.
 
-- `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
+**Returns:** `Promise<TokenMetadata[]>`
+
+```typescript
+const tokens = await streamService.getWhitelistedTokens("my-app-config");
+tokens.forEach(t => {
+  console.log(t.metadata?.symbol, t.mint.toBase58());
+});
+```
+
+---
 
 ### Admin Operations
 
-#### initializeConfig(params: InitializeConfigParams)
+#### `initializeStreamConfig(params)`
 
-Initializes the global stream configuration (admin only).
+Initializes the global stream configuration (admin only, one-time setup).
 
-**Parameters:**
+**Parameters** (`InitializeStreamConfigParams`):
 
-- `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
+```typescript
+await streamService.initializeStreamConfig({
+  admin: adminAddress, // optional, defaults to provider wallet
+  config: {
+    baseFeePercent: "0.1",
+    platformFeePercent: "0.05",
+    frequencies: [3600, 86400, 604800], // hourly, daily, weekly
+    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" },
+    ],
+  },
+});
+```
 
-#### whiteListTokens(params: WhiteListTokensParams)
+---
 
-Adds tokens to the whitelist (admin only).
+#### `updateStreamConfig(params)`
 
-**Parameters:**
+Updates an existing stream configuration (admin only).
+
+**Parameters** (`UpdateStreamConfigParams`): Same shape as `InitializeStreamConfigParams`.
+
+**Returns:** `Promise<TransactionPayload>`
+
+---
+
+#### `whiteListTokens(params)`
+
+Adds token mint addresses to the whitelist (admin only).
+
+**Parameters** (`WhiteListTokensParams`):
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `admin` | `Address` | Admin public key |
+| `tokens` | `Address[]` | Array of token mint addresses to whitelist |
+
+**Returns:** `Promise<TransactionPayload>`
+
+---
+
+### 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>` |
+
+---
+
+## Provider Setup
+
+### AnchorProvider (Read/Write)
+
+Use for operations that sign transactions:
+
+```typescript
+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:
+
+```typescript
+import { createReadonlyProvider } from "@zebec-network/zebec-stream-sdk";
+
+const provider = createReadonlyProvider(connection, optionalWalletAddress);
+```
+
+---
+
+## PDA Utilities
+
+```typescript
+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);
+```
 
-- `admin`: Address - Admin address
-- `tokens`: Address[] - Array of token mint addresses to whitelist
+---
 
 ## Types
 
-### StreamMetadataInfo
+### `StreamMetadataInfo`
 
 ```typescript
 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;
+  address: PublicKey;
+  parties: {
+    sender: PublicKey;
+    receiver: PublicKey;
+  };
+  financials: {
+    streamToken: PublicKey;
+    cliffPercentage: number;
+    depositedAmount: string; // human-readable
+    withdrawnAmount: string; // human-readable
+  };
+  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
+### `StreamConfigInfo`
 
 ```typescript
 type StreamConfigInfo = {
-	admin: PublicKey;
-	withdrawerAccount: PublicKey;
-	whitelistedTokens: PublicKey[];
-	platformFee: number;
-	baseFee: number;
-	frequencies: number[];
+  address: PublicKey;
+  admin: PublicKey;
+  withdrawerAccount: PublicKey;
+  whitelistedTokens: PublicKey[];
+  platformFee: number;
+  baseFee: number;
+  frequencies: number[];
+  feeTiers: FeeTier[];
+  feeVault: PublicKey;
 };
 ```
 
-## Provider Setup
-
-### AnchorProvider (Read/Write Operations)
-
-For operations that require signing transactions:
+### `FeeTier`
 
 ```typescript
-import { createAnchorProvider } from "@zebec-network/stream-sdk";
-
-const provider = createAnchorProvider(connection, wallet, {
-	commitment: "confirmed",
-	preflightCommitment: "confirmed",
-});
+type FeeTier = {
+  minThreshold: Numeric; // minimum USD amount for this tier
+  maxThreshold: Numeric; // maximum USD amount for this tier
+  feeRateInPercent: Numeric;
+};
 ```
 
-### ReadonlyProvider (Read-Only Operations)
+### `StreamFeeInfo`
 
-For read-only operations:
+Returned by the Zebec backend fee quote API and used internally during stream creation:
 
 ```typescript
-import { createReadonlyProvider } from "@zebec-network/stream-sdk";
+type StreamFeeInfo = {
+  tokenSymbol: string;
+  mintAddress: string;
+  chain: string;
+  streamAmount: string;
+  streamAmountUi: string;
+  tokenPriceUsd: number;
+  streamAmountUsd: number;
+  feeTier: { tier: number; range: string; feeRatePercent: number };
+  feeRatePercent: number;
+  feeAmountUsd: number;
+  feeToken: { symbol: string; decimals: number; priceUsd: number; mintAddress: string };
+  feeAmount: number;
+  feeAmountRaw: string;
+};
+```
 
-const provider = createReadonlyProvider(connection, optionalWalletAddress);
+### `TokenMetadata`
+
+```typescript
+type TokenMetadata = {
+  mint: PublicKey;
+  decimals: number;
+  freezeAuthority: PublicKey | null;
+  supply: string;
+  isInitialized: boolean;
+  mintAuthority: PublicKey | null;
+  metadata: {
+    address: PublicKey;
+    updateAuthority: PublicKey;
+    name: string;
+    symbol: string;
+    uri: string;
+  } | null;
+};
 ```
 
-## Examples
+---
+
+## Usage Examples
 
 ### Complete Stream Lifecycle
 
 ```typescript
-// 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
-};
+import { Connection } from "@solana/web3.js";
+import { ZebecStreamService, createAnchorProvider } from "@zebec-network/zebec-stream-sdk";
+
+const connection = new Connection("https://api.devnet.solana.com");
+const provider = createAnchorProvider(connection, wallet);
+const streamService = ZebecStreamService.create("my-app-config", provider, "devnet");
 
-const createTx = await streamService.createStream(createParams);
-await createTx.execute();
+// 1. Create a stream
+const createTx = await streamService.createStream({
+  sender: senderAddress,
+  receiver: receiverAddress,
+  streamToken: tokenMintAddress,
+  amount: "1000",
+  duration: 86400,
+  autoWithdrawFrequency: 3600,
+  streamName: "Test Stream",
+  startNow: true,
+  startTime: Math.floor(Date.now() / 1000),
+  cliffPercentage: 0,
+  automaticWithdrawal: true,
+  cancelableByRecipient: false,
+  cancelableBySender: true,
+  isPausable: true,
+  transferableByRecipient: false,
+  transferableBySender: false,
+  canTopup: false,
+  rateUpdatable: false,
+});
+const streamSignature = await createTx.execute();
+console.log("Stream created:", streamSignature);
 
-// 2. Get stream info
-const streamInfo = await streamService.getStreamMetadataInfo(streamMetadata);
-console.log("Stream info:", streamInfo);
+// 2. Fetch stream info
+const streamInfo = await streamService.getStreamMetadataInfo(streamMetadataAddress);
+console.log("Deposited:", streamInfo.financials.depositedAmount);
 
-// 3. Withdraw from stream
+// 3. Withdraw vested tokens
 const withdrawTx = await streamService.withdrawStream({
-	streamMetadata,
-	receiver: receiverAddress,
+  streamMetadata: streamMetadataAddress,
+  receiver: receiverAddress,
 });
 await withdrawTx.execute();
 
-// 4. Cancel stream
+// 4. Cancel the stream
 const cancelTx = await streamService.cancelStream({
-	streamMetadata,
-	user: senderAddress,
+  streamMetadata: streamMetadataAddress,
+  user: senderAddress,
 });
 await cancelTx.execute();
 ```
 
+### Pause and Resume a Stream
+
+```typescript
+const pauseTx = await streamService.pauseResumeStream({
+  streamMetadata: streamMetadataAddress,
+});
+await pauseTx.execute(); // toggles between paused and active
+```
+
+### Change Stream Receiver
+
+```typescript
+const changeTx = await streamService.changeStreamReceiver({
+  streamMetadata: streamMetadataAddress,
+  newRecipient: newRecipientAddress,
+  signer: currentRecipientAddress,
+});
+await changeTx.execute();
+```
+
+### Fetch Whitelisted Tokens
+
+```typescript
+const tokens = await streamService.getWhitelistedTokens("my-app-config");
+tokens.forEach((token) => {
+  console.log(token.metadata?.name, token.metadata?.symbol);
+  console.log("Mint:", token.mint.toBase58());
+  console.log("Decimals:", token.decimals);
+});
+```
+
 ### Error Handling
 
 ```typescript
 try {
-	const transaction = await streamService.createStream(params);
-	const signature = await transaction.execute();
-	console.log("Stream created:", signature);
+  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("Please use an allowed stream frequency");
-	} else {
-		console.error("Stream creation failed:", error);
-	}
+  if (error.message.includes("Invalid stream frequency")) {
+    console.error("autoWithdrawFrequency must be one of the config's allowed frequencies");
+  } else {
+    console.error("Stream creation 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
 
-- **Mainnet Beta**: Production environment
-- **Devnet**: Development and testing environment
-- **Testnet**: Not supported
+| Network | Status |
+| --- | --- |
+| Mainnet Beta | Supported |
+| Devnet | Supported |
+| 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
+| Package | Purpose |
+| --- | --- |
+| `@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 |
+| `@metaplex-foundation/umi` | Metaplex UMI framework |
+| `@metaplex-foundation/umi-bundle-defaults` | UMI default bundle |
+| `@metaplex-foundation/umi-web3js-adapters` | UMI ↔ web3.js adapters |
+| `@zebec-network/core-utils` | Zebec core utility functions (BPS conversions, etc.) |
+| `@zebec-network/solana-common` | Common Solana helpers (ATAs, transaction payload, etc.) |
+| `bignumber.js` | Arbitrary-precision arithmetic for token amounts |
+
+---
+
+## Development
+
+### Install Dependencies
+
+```bash
+npm install
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Clean Build Artifacts
+
+```bash
+npm run clean
+```
+
+### Run Tests
+
+```bash
+npm test
+```
+
+### Run a Single Test File
+
+```bash
+npm run test:single -- test/e2e/stream/createStream.test.ts
+```
+
+### Format Code
+
+```bash
+npm run format
+```
+
+---
+
+## Publishing
+
+1. Bump the version in [package.json](package.json).
+
+2. Build the package:
+
+   ```bash
+   npm run build
+   ```
+
+3. Publish to npm:
+
+   ```bash
+   npm publish --access public
+   ```
+
+Only the `dist/` directory is included in the published package (as specified by the `files` field in [package.json](package.json)).
+
+---
 
 ## License
 
@@ -351,4 +674,4 @@ This project is licensed under the MIT License.
 
 For issues and questions:
 
-- GitHub Issues: [Repository Issues](https://github.com/zebec-network/stream-sdk/issues)
+- GitHub Issues: [Repository Issues](https://github.com/zebec-network/zebec-stream-sdk/issues)

package/package.json

@@ -40,5 +40,5 @@
     "test:single": "ts-mocha -p ./tsconfig.json -t 1000000000"
   },
   "types": "dist/index.d.ts",
-  "version": "3.1.1"
+  "version": "3.1.2"
 }