@streamlock/operator-sdk

TypeScript SDK for the Streamlock Operator API. Run zero-sum games against Streamlock streams without custodying keys. Streamlock builds the transaction bytes; you sign and broadcast.

What this is. Streamlock's conviction-locking primitive carries an entitlement ledger on every locked stream. A trusted operator can rewrite the ledger via signed, zero-sum game results. At unlock, SOL proceeds distribute according to the final bps. This SDK is the integration contract for that.

Install

npm install @streamlock/operator-sdk @solana/web3.js

Quickstart

import { StreamlockOperator } from "@streamlock/operator-sdk";
import { Keypair } from "@solana/web3.js";

const op = new StreamlockOperator({
  apiKey: process.env.STREAMLOCK_OPERATOR_KEY!,
  chain: "soldev",
  rpcUrl: "https://api.devnet.solana.com",
  signer: async (tx) => {
    const kp = Keypair.fromSecretKey(/* your bytes */);
    tx.sign([kp]);
    return tx;
  },
});

// 1. Discover eligible players
const { streams } = await op.tokens.streams("Bhjta…6S1v");

// 2. Start a game
const session = await op.sessions.create({
  tokenMint: "Bhjta…6S1v",
  participants: streams.slice(0, 8).map((s) => ({ wallet: s.holder, streamId: s.streamId })),
  endTs: Math.floor(Date.now() / 1000) + 3600,
  disputeWindowSec: 600,
});

// 3. …game runs, you compute a zero-sum scoresheet…

// 4. Submit + finalize
await op.sessions.submit(session.result.gameSessionPda, {
  startChunkIndex: 0,
  deltas: scoresheet,
});

// after dispute window:
await op.sessions.finalizeAndApplyAll(session.result.gameSessionPda, [
  { chunkIndex: 0, deltas: scoresheet },
]);

A full runnable example lives at examples/poker-operator.ts.

Design points

• Signer is a callback. (tx: VersionedTransaction) => Promise<VersionedTransaction>. Use a Keypair, an HSM, a remote signer service — anything that can sign.
• .build*() escape hatches. Every writer has a sibling .build*() that returns the unsigned tx bytes. Sophisticated operators who want HTTP-free writes (or to inspect the tx first) use those.
• Client-side zero-sum validation. Bad scoresheets fail before the round-trip.
• Idempotency keys. SDK auto-generates Idempotency-Key headers per write. Server-side memoization is rolled out incrementally.
• WSS push events. op.stream.on("session.finalized", handler) connects lazily and reconnects with exponential backoff.

Spec

Full Operator API spec: docs/architecture/OPERATOR_API.md in the Streamlock monorepo. OpenAPI 3.1 schema served at https://streamlock.fun/v1/openapi.json (Phase 7).

License

MIT