@swarm-tips/client 0.2.0 → 0.2.2

package/SBOM.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@swarm-tips/client-0.2.0",
-  "documentNamespace": "https://swarm.tips/sbom/client/0.2.0",
+  "name": "@swarm-tips/client-0.2.2",
+  "documentNamespace": "https://swarm.tips/sbom/client/0.2.2",
   "creationInfo": {
-    "created": "2026-09-08T06:28:09.085Z",
+    "created": "2026-09-08T07:02:42.781Z",
     "creators": [
       "Tool: sdk/client/scripts/generate-sbom.mjs",
       "Organization: Swarm Tips"
@@ -15,8 +15,8 @@
     {
       "name": "@swarm-tips/client",
       "SPDXID": "SPDXRef-Package",
-      "versionInfo": "0.2.0",
-      "downloadLocation": "https://www.npmjs.com/package/@swarm-tips/client/v/0.2.0",
+      "versionInfo": "0.2.2",
+      "downloadLocation": "https://www.npmjs.com/package/@swarm-tips/client/v/0.2.2",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
       "licenseDeclared": "MIT"

package/dist/coordination-game/protocol.js

@@ -81,8 +81,17 @@ export function decodeTournament(data) {
     };
 }
 export function decodeTournamentStats(data) {
-    const tournament = decodeTournament(data);
-    return { gameCount: Number(tournament.gameCount), prizeLamports: tournament.prizeLamports };
+    // Stats readers need only the two u64 fields through byte 80. Accept that
+    // prefix so lightweight RPC fixtures and partial account slices do not need
+    // the trailing `finalized` byte required by the full decoder.
+    if (data.length < 80) {
+        throw new RangeError(`Tournament stats data too short: ${data.length} bytes`);
+    }
+    const view = viewOf(data);
+    return {
+        prizeLamports: view.getBigUint64(64, true),
+        gameCount: Number(view.getBigUint64(72, true)),
+    };
 }
 function hasCommitted(commit) {
     return Array.from(commit).some((byte) => byte !== 0);

package/dist/coordination-game/solana.d.ts

@@ -1,5 +1,5 @@
 import { BN, Program } from "@coral-xyz/anchor";
-import { Connection, Keypair, PublicKey, Transaction, type Commitment, type TransactionInstruction, type VersionedTransaction } from "@solana/web3.js";
+import { Connection, Keypair, PublicKey, Transaction, TransactionInstruction, type Commitment, type VersionedTransaction } from "@solana/web3.js";
 import { type CoordinationGame } from "../contracts/index.js";
 import { type GlobalConfigData, type TournamentData } from "./protocol.js";
 export interface SolanaWalletSigner {
@@ -19,6 +19,9 @@ export interface CoordinationGameSolanaClientOptions {
     tournamentId?: bigint;
     commitment?: Commitment;
 }
+export declare const SESSION_FEE_HEADROOM_LAMPORTS = 10000000;
+export declare function sessionFundLamports(stakeLamports: bigint): number;
+export declare function sessionBalanceFloor(stakeLamports: bigint): number;
 export declare function generateSessionKeypair(): Keypair;
 export declare function readStoredSession(storage: SolanaSessionStorage, walletAddress: string, now?: () => number): Keypair | null;
 export declare function storeSession(storage: SolanaSessionStorage, session: Keypair, walletAddress: string, now?: () => number): void;
@@ -40,6 +43,19 @@ export declare class CoordinationGameSolanaClient {
     fetchTournament(tournamentId?: bigint): Promise<TournamentData | null>;
     fetchGlobalConfig(): Promise<GlobalConfigData>;
     buildCreatePlayerSessionInstruction(sessionPublicKey: PublicKey): Promise<TransactionInstruction>;
+    buildSessionSetupTransaction(input: {
+        sessionPublicKey: PublicKey;
+        lamports: number;
+        memoNonce?: string;
+    }): Promise<Transaction>;
+    waitForSignature(signature: string, options?: {
+        attempts?: number;
+        intervalMs?: number;
+        sleep?: (ms: number) => Promise<void>;
+    }): Promise<void>;
+    fetchPlayerProfiles(tournamentId?: bigint): Promise<Array<{
+        account: unknown;
+    }>>;
     depositStake(tournament: PublicKey, session?: Keypair | null): Promise<string>;
     buildCreateGameTransaction(input: {
         stake: BN;

package/dist/coordination-game/solana.js

@@ -1,11 +1,20 @@
 import { AnchorProvider, Program } from "@coral-xyz/anchor";
 import { Buffer } from "buffer";
-import { Connection, Keypair, SystemProgram, Transaction, } from "@solana/web3.js";
+import bs58 from "bs58";
+import { Connection, Keypair, PublicKey, SystemProgram, Transaction, TransactionInstruction, } from "@solana/web3.js";
 import { COORDINATION_GAME_IDL } from "../contracts/index.js";
 import { SwarmClientError } from "../errors.js";
-import { decodeGlobalConfig, decodeTournament, escrowPda, gameCounterPda, gamePda, globalConfigPda, playerProfilePda, playerSessionPda, tournamentPda, } from "./protocol.js";
+import { decodeGlobalConfig, decodeTournament, escrowPda, gameCounterPda, gamePda, globalConfigPda, playerProfilePda, playerSessionPda, tournamentPda, u64LE, } from "./protocol.js";
 const SESSION_STORAGE_KEY = "coordination-session";
 const SESSION_TTL_MS = 24 * 60 * 60 * 1000;
+const MEMO_PROGRAM_ID = new PublicKey("MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr");
+export const SESSION_FEE_HEADROOM_LAMPORTS = 10_000_000;
+export function sessionFundLamports(stakeLamports) {
+    return Number(stakeLamports) + SESSION_FEE_HEADROOM_LAMPORTS;
+}
+export function sessionBalanceFloor(stakeLamports) {
+    return Number(stakeLamports) + SESSION_FEE_HEADROOM_LAMPORTS / 2;
+}
 function walletForSession(session) {
     return {
         publicKey: session.publicKey,
@@ -105,6 +114,44 @@ export class CoordinationGameSolanaClient {
         const wallet = this.requireWallet();
         return this.program(wallet).methods.createPlayerSession().accountsPartial({ sessionKey: sessionPublicKey }).instruction();
     }
+    async buildSessionSetupTransaction(input) {
+        const wallet = this.requireWallet();
+        const transaction = new Transaction().add(SystemProgram.transfer({
+            fromPubkey: wallet.publicKey,
+            toPubkey: input.sessionPublicKey,
+            lamports: input.lamports,
+        }));
+        if (input.memoNonce) {
+            transaction.add(new TransactionInstruction({
+                keys: [],
+                programId: MEMO_PROGRAM_ID,
+                data: Buffer.from(input.memoNonce, "utf8"),
+            }));
+        }
+        const authority = playerSessionPda(wallet.publicKey, input.sessionPublicKey)[0];
+        if ((await this.connection.getAccountInfo(authority)) === null) {
+            transaction.add(await this.buildCreatePlayerSessionInstruction(input.sessionPublicKey));
+        }
+        return transaction;
+    }
+    async waitForSignature(signature, options = {}) {
+        const sleep = options.sleep ?? ((ms) => new Promise((resolve) => globalThis.setTimeout(resolve, ms)));
+        const attempts = options.attempts ?? 6;
+        for (let index = 0; index < attempts; index += 1) {
+            await sleep(options.intervalMs ?? 1_500);
+            const status = await this.connection.getSignatureStatus(signature);
+            const confirmation = status.value?.confirmationStatus;
+            if (confirmation === "confirmed" || confirmation === "finalized")
+                return;
+        }
+        throw new SwarmClientError({ code: "TIMEOUT", operation: "solana.waitForSignature", message: `transaction ${signature} did not confirm after ${attempts} polls`, retryable: true });
+    }
+    async fetchPlayerProfiles(tournamentId = this.tournamentId) {
+        const profiles = await this.program().account.playerProfile.all([{
+                memcmp: { offset: 40, bytes: bs58.encode(u64LE(tournamentId)) },
+            }]);
+        return profiles;
+    }
     async depositStake(tournament, session) {
         const wallet = this.requireWallet();
         const escrow = escrowPda(this.tournamentId, wallet.publicKey)[0];

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /** The unified client package version. Functional APIs live in typed subpaths. */
-export declare const CLIENT_VERSION: "0.2.0";
+export declare const CLIENT_VERSION: "0.2.2";
 export declare const CLIENT_MANIFEST_SCHEMA: "swarm.client-manifest/v1";
 export { SwarmClientError } from "./errors.js";
 export type { SwarmClientErrorCode, SwarmClientErrorOptions } from "./errors.js";

package/dist/index.js

@@ -1,4 +1,4 @@
 /** The unified client package version. Functional APIs live in typed subpaths. */
-export const CLIENT_VERSION = "0.2.0";
+export const CLIENT_VERSION = "0.2.2";
 export const CLIENT_MANIFEST_SCHEMA = "swarm.client-manifest/v1";
 export { SwarmClientError } from "./errors.js";

package/dist/shillbot/api.d.ts

@@ -1,6 +1,7 @@
 import { Connection, type BlockhashWithExpiryBlockHeight } from "@solana/web3.js";
 import { HttpClient, type HttpClientOptions } from "../http.js";
 import { type Action, type TransactionInspection, type WalletSignCallback } from "./index.js";
+export type { Action } from "./index.js";
 export interface PreparedTransactionResponse {
     message?: string;
     task_id?: string;
@@ -57,6 +58,7 @@ export interface PreparedTransactionExpectation {
     escrowLamports?: bigint;
     allowedProgramIds?: string[];
 }
+export declare function permittedPreparedProgramIds(action: Action, network: "mainnet" | "devnet"): string[];
 /**
  * Fail-closed local validation for a server-prepared Shillbot transaction.
  * The network is an explicit part of the expectation; callers must construct
@@ -69,4 +71,7 @@ export declare function signBroadcastPreparedTransaction(input: {
     expected: PreparedTransactionExpectation;
     sign: WalletSignCallback;
     confirmation?: BlockhashWithExpiryBlockHeight;
+    timeoutMs?: number;
+    setTimeout?: typeof globalThis.setTimeout;
+    clearTimeout?: typeof globalThis.clearTimeout;
 }): Promise<string>;

package/dist/shillbot/api.js

@@ -1,5 +1,5 @@
 import { Buffer } from "buffer";
-import { ComputeBudgetProgram, SystemProgram } from "@solana/web3.js";
+import { ComputeBudgetProgram, Secp256k1Program, SystemProgram } from "@solana/web3.js";
 import { HttpClient } from "../http.js";
 import { SwarmClientError } from "../errors.js";
 import { SHILLBOT_PROGRAM_ID, inspectTransaction, shillbotInstructionDiscriminator, signAndBroadcast, } from "./index.js";
@@ -28,6 +28,15 @@ export class ShillbotApiClient {
     buildFinalize(id) { return this.post(`/tasks/${encodeURIComponent(id)}/build-finalize`); }
     confirmTask(id, body) { return this.post(`/tasks/${encodeURIComponent(id)}/confirm`, body); }
 }
+const SWITCHBOARD_PROGRAM_IDS = {
+    mainnet: "SBondMDrcV3K4kxZR1HNVT7osZxAHVHgYXL5Ze1oMUv",
+    devnet: "Aio4gaXjXzJNVLtzwtNVmSqGKpANtXhybbkhtAC94ji2",
+};
+export function permittedPreparedProgramIds(action, network) {
+    return action === "verify"
+        ? [SWITCHBOARD_PROGRAM_IDS[network], Secp256k1Program.programId.toBase58()]
+        : [];
+}
 function lifecycleName(action) {
     if (action === "create")
         return "create_task";
@@ -67,6 +76,7 @@ export function validatePreparedTransaction(encoded, expected) {
         shillbotId,
         ComputeBudgetProgram.programId.toBase58(),
         SystemProgram.programId.toBase58(),
+        ...permittedPreparedProgramIds(expected.action, expected.network),
         ...(expected.allowedProgramIds ?? []),
     ]);
     const unrelated = inspected.instructions.find((instruction) => !alwaysAllowed.has(instruction.program_id));
@@ -87,5 +97,18 @@ export function validatePreparedTransaction(encoded, expected) {
 }
 export async function signBroadcastPreparedTransaction(input) {
     validatePreparedTransaction(input.transaction, input.expected);
-    return signAndBroadcast(input.connection, input.transaction, input.sign, input.confirmation);
+    const timeoutMs = input.timeoutMs ?? 60_000;
+    let timeout;
+    try {
+        return await Promise.race([
+            signAndBroadcast(input.connection, input.transaction, input.sign, input.confirmation),
+            new Promise((_, reject) => {
+                timeout = (input.setTimeout ?? globalThis.setTimeout)(() => reject(new SwarmClientError({ code: "TIMEOUT", operation: "shillbot.signBroadcastPreparedTransaction", message: `Transaction did not confirm within ${timeoutMs}ms`, retryable: true })), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeout !== undefined)
+            (input.clearTimeout ?? globalThis.clearTimeout)(timeout);
+    }
 }

package/dist/shillbot/switchboard.js

@@ -1,4 +1,5 @@
-import * as anchor from "@coral-xyz/anchor";
+import { AnchorProvider, Program } from "@coral-xyz/anchor";
+import BN from "bn.js";
 import { Buffer } from "buffer";
 import { OracleJob } from "@switchboard-xyz/common/protos";
 import { ComputeBudgetProgram, Keypair, PublicKey, Secp256k1Program, SystemProgram, TransactionInstruction, TransactionMessage, VersionedTransaction, } from "@solana/web3.js";
@@ -14,7 +15,6 @@ const SWITCHBOARD_PROGRAMS = {
 };
 const CROSSBAR_URL = "https://crossbar.switchboard.xyz";
 const SWITCHBOARD_GATEWAY_API_VERSION = "1.0.0";
-const anchorRuntime = anchor.default ?? anchor;
 async function jsonResponse(response, description) {
     if (!response.ok) {
         throw new Error(`${description} failed with HTTP ${response.status}`);
@@ -120,11 +120,23 @@ function associatedTokenAddress(mint, owner) {
 export async function buildSwitchboardCrankAndVerify(request) {
     const switchboardProgramId = SWITCHBOARD_PROGRAMS[request.network];
     const dummy = Keypair.generate();
-    const provider = new anchorRuntime.AnchorProvider(request.connection, new anchorRuntime.Wallet(dummy), { commitment: "confirmed" });
-    const idl = await anchorRuntime.Program.fetchIdl(switchboardProgramId, provider);
+    const signDummy = async (transaction) => {
+        if ("partialSign" in transaction)
+            transaction.partialSign(dummy);
+        else
+            transaction.sign([dummy]);
+        return transaction;
+    };
+    const dummyWallet = {
+        publicKey: dummy.publicKey,
+        signTransaction: signDummy,
+        signAllTransactions: async (transactions) => Promise.all(transactions.map(signDummy)),
+    };
+    const provider = new AnchorProvider(request.connection, dummyWallet, { commitment: "confirmed" });
+    const idl = await Program.fetchIdl(switchboardProgramId, provider);
     if (!idl)
         throw new Error("failed to fetch Switchboard IDL");
-    const program = new anchorRuntime.Program(idl, provider);
+    const program = new Program(idl, provider);
     const switchboardAccounts = program.account;
     const feedData = (await switchboardAccounts.pullFeedAccountData.fetch(request.feed));
     const feedHashHex = Buffer.from(feedData.feedHash).toString("hex");
@@ -152,8 +164,8 @@ export async function buildSwitchboardCrankAndVerify(request) {
     const oracleStats = oraclePubkeys.map((oracle) => PublicKey.findProgramAddressSync([Buffer.from("OracleStats"), oracle.toBuffer()], switchboardProgramId)[0]);
     const feeds = response.median_responses.map((median) => median.feed_hash === feedHashHex ? request.feed : PublicKey.default);
     const submit = program.instruction.pullFeedSubmitResponseConsensus({
-        slot: new anchorRuntime.BN(response.slot),
-        values: response.median_responses.map((median) => new anchorRuntime.BN(median.value)),
+        slot: new BN(response.slot),
+        values: response.median_responses.map((median) => new BN(median.value)),
     }, {
         accounts: {
             queue: queuePubkey,

package/dist/swarm/index.js

@@ -49,7 +49,7 @@ export class SwarmClient {
     async toolCount() {
         const headers = { "Content-Type": "application/json", Accept: "application/json, text/event-stream" };
         try {
-            const init = await this.fetchImpl(`${this.baseUrl}/mcp`, { method: "POST", headers, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "swarm-client", version: "0.2.0" } } }) });
+            const init = await this.fetchImpl(`${this.baseUrl}/mcp`, { method: "POST", headers, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "swarm-client", version: "0.2.2" } } }) });
             if (!init.ok)
                 return null;
             const session = init.headers.get("mcp-session-id");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarm-tips/client",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Typed browser and Node.js clients for Swarm Tips, Shillbot, and Coordination Game",
   "type": "module",
   "main": "dist/index.js",
@@ -96,6 +96,7 @@
     "@coral-xyz/anchor": "^0.32.1",
     "@solana/web3.js": "^1.98.4",
     "@switchboard-xyz/common": "^5.7.0",
+    "bn.js": "^5.2.2",
     "bs58": "^6.0.0",
     "buffer": "^6.0.3",
     "js-sha256": "^0.11.0"