@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"

Webhook Receiver

import express from 'express';
import { createWebhookMiddleware } from "@stellar-split/sdk";

const app = express();

// Use raw body parser for webhook route
app.use('/webhooks/stellarsplit', express.raw({ type: 'application/json' }));

// Secure webhook receiver with HMAC-SHA256 verification and replay protection
app.post(
  '/webhooks/stellarsplit',
  createWebhookMiddleware(process.env.WEBHOOK_SECRET!, {
    toleranceSeconds: 300,    // 5 minutes
    nonceWindowSize: 1000,    // Track 1000 recent nonces
  }),
  (req, res) => {
    const { event, data } = req.webhookPayload;
    
    switch (event) {
      case 'invoice.paid':
        console.log('Payment received:', data);
        break;
      case 'invoice.released':
        console.log('Funds released:', data);
        break;
    }
    
    res.status(200).json({ received: true });
  }
);

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

Multi-Tenant Support

Class	Description
MultiTenantClient	Manage a pool of StellarSplitClient instances keyed by tenant ID, with getClient, evict, and evictAll

Profiling

Class	Description
ProfilerSession	Record SDK method timings during a session and produce a flame-graph-compatible report

Webhook Validation

Function	Returns	Description
validateWebhookSignature(payload, signature, secret)	Promise<boolean>	Verify the HMAC-SHA256 signature on incoming invoice webhook payloads
createWebhookMiddleware(secret, options)	RequestHandler	Create secure Express/Next.js middleware for receiving webhooks with HMAC verification and replay protection
generateWebhookSignature(payload, secret)	Promise<string>	Generate HMAC-SHA256 signature for a webhook payload
verifyWebhookSignature(payload, signature, secret)	Promise<boolean>	Manually verify a webhook signature without middleware

Invoice Metadata Enricher

Function	Returns	Description
enrichInvoice(invoiceId)	Promise<EnrichedInvoice>	Fetch IPFS metadata from invoice memo CID and merge it into the invoice

Pluggable Signing Key Vault Adapter

Decouple transaction signing from key storage with a narrow Signer contract — inject an HSM, cloud KMS, or AES-encrypted keystore without modifying SDK internals.

Class / Function	Description
KeypairSigner	Signer backed by an in-memory Keypair
EncryptedFileSigner	Signer reading an AES-256-GCM encrypted PEM keystore (decrypts on first use, WeakRef-cached)
CloudKmsSigner	Signer delegating to any injected KmsClient
encryptSigningKeyToPem(secret, aesKey)	Encrypt a Stellar secret seed to a PEM payload
writeEncryptedSigningKeyFile(path, secret, aesKey)	Write an encrypted keystore to disk

Pass any Signer to StellarSplitClient via the signer constructor option (exposed as client.signer). See docs/SIGNING_VAULT.md.

Soroban Transaction Footprint Optimizer

Prune stale or over-broad ledger keys from Soroban transactions before submission to cut inclusion fees.

Function	Description
optimizeFootprint(tx, sim)	Rebuild a transaction with the minimal footprint reported by simulation
footprintDiff(original, minimal)	Classify { added, removed, unchanged } ledger keys
submitTransaction(server, tx, sim, opts?)	Submit with the optimizer on by default ({ optimizeFootprint: false } disables it)

See docs/FOOTPRINT_OPTIMIZER.md.

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.