@swarm-tips/client 0.2.0 → 0.2.1

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.1",
+  "documentNamespace": "https://swarm.tips/sbom/client/0.2.1",
   "creationInfo": {
-    "created": "2026-09-08T06:28:09.085Z",
+    "created": "2026-09-08T06:45:33.630Z",
     "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.1",
+      "downloadLocation": "https://www.npmjs.com/package/@swarm-tips/client/v/0.2.1",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
       "licenseDeclared": "MIT"

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.1";
 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.1";
 export const CLIENT_MANIFEST_SCHEMA = "swarm.client-manifest/v1";
 export { SwarmClientError } from "./errors.js";

package/dist/shillbot/api.d.ts

@@ -57,6 +57,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 +70,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/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.1" } } }) });
             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.1",
   "description": "Typed browser and Node.js clients for Swarm Tips, Shillbot, and Coordination Game",
   "type": "module",
   "main": "dist/index.js",