TypeScript SDK for interacting with SoroProtocol payment streaming contracts on Stellar.
@soroprotocol/sdk provides a typed, ergonomic client for creating and managing token streams and vesting schedules on the SoroProtocol smart contracts. It handles Soroban RPC communication, Freighter wallet signing, and XDR encoding so you can focus on building your application.
npm install @soroprotocol/sdk@stellar/stellar-sdk ≥ 12.0.0 is a required peer dependency:
npm install @stellar/stellar-sdkimport { SoroProtocolClient } from '@soroprotocol/sdk';
const client = new SoroProtocolClient({
network: 'TESTNET',
contractId: 'YOUR_STREAM_CONTRACT_ID',
});
// Connect Freighter wallet
const wallet = await client.wallet.connect();
// Create a stream: 10 XLM/day for 30 days
const now = Math.floor(Date.now() / 1000);
await client.createStream({
recipient: 'G...',
token: 'C...',
ratePerSecond: 10_000_000n / 86_400n,
startTime: now,
stopTime: now + 30 * 86_400,
});
// Withdraw accrued balance
await client.withdrawStream(streamId);
// Cancel a stream
await client.cancelStream(streamId);Full documentation: docs/API.md
new SoroProtocolClient(config: ClientConfig)| Config Field | Type | Required | Description |
|---|---|---|---|
network |
'MAINNET' | 'TESTNET' | 'FUTURENET' |
Yes | Target Stellar network |
contractId |
string |
Yes | Deployed stream contract ID |
rpcUrl |
string |
No | Custom Soroban RPC URL (overrides default) |
horizonUrl |
string |
No | Custom Horizon URL (overrides default) |
| Method | Description |
|---|---|
createStream(params) |
Create a new payment stream; deposits rate × duration tokens upfront |
cancelStream(streamId, sender?) |
Cancel a stream; refunds sender and pays out accrued amount to recipient |
withdrawStream(streamId, recipient?) |
Withdraw all accrued tokens for a stream |
getStreamBalance(streamId) |
Read the current accrued balance without submitting a transaction |
getStream(streamId) |
Fetch full stream data from the contract |
batchCreateStreams(streams[], sender?) |
Create multiple streams in a single transaction |
| Method | Description |
|---|---|
createVesting(params) |
Create a vesting schedule with optional cliff |
claimVesting(scheduleId, beneficiary?) |
Claim all vested tokens for a schedule |
interface CreateStreamParams {
sender: string; // Stellar address (G...)
recipient: string;
token: string; // Token contract address (C...)
ratePerSecond: bigint; // Tokens per second in stroops
startTime: number; // Unix timestamp
stopTime: number; // Unix timestamp
}
interface CreateVestingParams {
funder: string;
beneficiary: string;
token: string;
totalAmount: bigint;
startTime: number;
cliffTime: number; // No tokens vest before this time
endTime: number;
}
interface TxResult {
txHash: string;
ledger: number;
success: boolean;
}src/
├── client.ts # SoroProtocolClient — main entry point
├── types.ts # Shared TypeScript interfaces
├── errors.ts # SoroProtocolError class
├── constants.ts # Default network config
├── index.ts # Public exports
├── stellar/ # RPC client, network config, transaction invocation
├── stream/ # create, cancel, withdraw, balance, batch
├── vesting/ # create, claim
├── wallet/ # FreighterConnector
└── utils/ # Validation and formatting helpers
| Command | Description |
|---|---|
npm run build |
Compile TypeScript to dist/ |
npm run test |
Run unit tests with Jest |
npm run test:coverage |
Run tests with coverage report |
npm run lint |
Lint source files (zero warnings allowed) |
npm run lint:fix |
Auto-fix lint issues |
npm run format |
Format all source files with Prettier |
npm run examples |
Run example scripts via ts-node |
Contributions are welcome. Please read CONTRIBUTING.md for branch conventions, commit message guidelines, and the pull request process.
MIT