stacks-pong-sdk

TypeScript SDK for StacksPong. Read matches without a wallet, build safe STX staking calls through Stacks Connect-compatible wallets, settle signed results, claim refunds, and use engagement features.

Install

npm install stacks-pong-sdk @stacks/transactions

For browser wallet calls:

npm install @stacks/connect

Quick Start

import { connect, request } from '@stacks/connect';
import { PongClient } from 'stacks-pong-sdk';

const wallet = await connect({ network: 'mainnet' });
const account = wallet.addresses.find(value => value.symbol === 'STX');
if (!account) throw new Error('No STX account returned');

const pong = new PongClient({
  chain: 'mainnet',
  senderAddress: account.address,
  walletRequest: request
});

const txid = await pong.stakeAsPlayer1({
  roomCode: 'ABC123',
  amount: '0.01'
});

const receipt = await pong.wait(txid);
console.log(receipt.tx_status);

The SDK uses PostConditionMode.Deny and exact STX post-conditions for every asset-moving call.

Read-Only Usage

const pong = new PongClient({ chain: 'mainnet' });

const match = await pong.getMatch('ABC123');
const available = await pong.isRoomCodeAvailable('NEW123');
const oracle = await pong.backendOracle();
const balance = await pong.getBalance('SP...');

Result Settlement

The backend supplies the authoritative proof after a verified game ends:

const proof = {
  roomCode: 'ABC123',
  player1Address: 'SP...',
  player2Address: 'SP...',
  winnerAddress: 'SP...',
  score1: 5,
  score2: 2,
  resultReason: 'score',
  resultSignature: '0x...'
};

await pong.claimPrize(proof);
await pong.gg(proof);
await pong.reportMatch(proof);

claimPrize reads the stake amount and allows exactly twice that amount to leave escrow. Result proof helpers use the same SIP-005 tuple and SHA-256 domain as the Clarity contract.

API

Constructor

new PongClient({
  chain?: 'testnet' | 'mainnet';
  apiUrl?: string;
  contractAddress?: string;
  contractName?: string;
  senderAddress?: string;
  walletRequest?: WalletRequest;
  fetch?: typeof fetch;
});

Reads

• getBalance(address)
• isRoomCodeAvailable(roomCode)
• getMatch(roomCode)
• getMatchStatus(roomCode)
• getEngagement(player)
• getMatchScore(roomCode)
• hasSentGG(roomCode, player)
• getChallenge(roomCode)
• backendOracle()
• isPaused()

Staking and Settlement

• stakeAsPlayer1({ roomCode, amount })
• stakeAsPlayer2(roomCode)
• claimPrize(proof)
• claimRefund(roomCode)
• claimExpiredMatchRefund(roomCode)
• claimAbandonedMatchRefund(roomCode, signature)

Engagement and Challenges

• gg(proof)
• reportMatch(proof)
• checkIn()
• claimDailyReward()
• practiceMode()
• createChallenge(roomCode, amount)
• acceptChallenge(roomCode)

Utilities

• wait(txid)
• recoverResultSigner(proof)
• stxToMicroStx(amount)
• microStxToStx(amount)
• resultProofHash(proof, contract)

Deployments

| Network | Contract | | --- | --- | | Testnet | ST3GR25CCN59DF6GQGZGN226KAFFGX4W3HAJZ3PHV.pong-escrow | | Mainnet | SP3GR25CCN59DF6GQGZGN226KAFFGX4W3HAB3GC63.pong-escrow |

Contract addresses can be overridden in the constructor.

Testing

pnpm install
pnpm test
pnpm typecheck
pnpm build

RUN_STACKS_INTEGRATION=true pnpm test

License

MIT