@stellar-split/sdk

TypeScript SDK for the StellarSplit on-chain invoice splitting dApp on Stellar Soroban.

Install

npm install @stellar-split/sdk

Quick Start

import { StellarSplitClient, connectWallet, deadlineFromDays, parseAmount } from "@stellar-split/sdk";

// Connect Freighter wallet
const publicKey = await connectWallet();

// Initialise client
const client = new StellarSplitClient({
  rpcUrl: "https://soroban-testnet.stellar.org",
  networkPassphrase: "Test SDF Network ; September 2015",
  contractId: "YOUR_CONTRACT_ID",
});

// Create an invoice splitting 100 USDC between two recipients
const { invoiceId, txHash } = await client.createInvoice({
  creator: publicKey,
  recipients: [
    { address: "GABC...RECIPIENT1", amount: parseAmount("60") },
    { address: "GDEF...RECIPIENT2", amount: parseAmount("40") },
  ],
  token: "USDC_CONTRACT_ADDRESS",
  deadline: deadlineFromDays(7),
});

console.log(`Invoice #${invoiceId} created: ${txHash}`);

// Pay toward the invoice
await client.pay({
  payer: publicKey,
  invoiceId,
  amount: parseAmount("100"),
});

// Fetch invoice status
const invoice = await client.getInvoice(invoiceId);
console.log(invoice.status); // "Released"

API Reference

StellarSplitClient

Constructor

new StellarSplitClient(config: StellarSplitClientConfig)

Field	Type	Description
rpcUrl	string	Soroban RPC endpoint
networkPassphrase	string	Stellar network passphrase
contractId	string	Deployed contract ID

Methods

Method	Returns	Description
createInvoice(params)	Promise<{ invoiceId, txHash }>	Create a new invoice
pay(params)	Promise<{ txHash }>	Pay toward an invoice
getInvoice(id)	Promise<Invoice>	Fetch invoice by ID
getPayments(id)	Promise<Payment[]>	Fetch payments for an invoice

Wallet Helpers

Function	Returns	Description
connectWallet()	Promise<string>	Connect Freighter, return public key
getPublicKey()	Promise<string>	Get connected wallet's public key
signTransaction(xdr, network)	Promise<string>	Sign a transaction XDR

Utilities

Function	Description
formatAmount(stroops)	Format stroops as USDC string (7 decimals)
parseAmount(value)	Parse USDC string to stroops
isValidAddress(address)	Validate a Stellar G... address
deadlineFromDays(days)	Unix timestamp N days from now
isExpired(deadline)	Check if a deadline has passed
truncateAddress(address)	Truncate for display: "GABC...XYZ"

Run Tests

npm test

Contributing via Drips Wave

This project participates in the Drips Wave Program by the Stellar Development Foundation. Contributors can earn rewards by completing open issues.

See CONTRIBUTING.md for the full guide.

Do not start coding until assigned to an issue by a maintainer.