gyro-sdk

JavaScript/TypeScript SDK for GyroBoard — a competitive spin game on Celo with USDm (Mento Dollar).

Install

npm install gyro-sdk viem

Quick Start

Read rooms and players

import { getRoomIds, getRoom, getAllRooms, getRoundPlayers } from 'gyro-sdk';

// Get all room IDs
const ids = await getRoomIds();

// Get a specific room
const room = await getRoom(1n);
console.log(room.entryFee, room.playerCount, room.currentRound);

// Get all rooms with their IDs
const rooms = await getAllRooms();

// Get players in a round
const players = await getRoundPlayers(1n, 1n);
players.forEach(p => console.log(p.player, p.spin));

Check balances and allowances

import { getUsdmBalance, getUsdmAllowance } from 'gyro-sdk';

const balance = await getUsdmBalance('0x...');
const allowance = await getUsdmAllowance('0x...');

Play a spin (browser wallet)

import { createWalletClient, custom } from 'viem';
import { celo } from 'viem/chains';
import { approveUsdm, play } from 'gyro-sdk';

const walletClient = createWalletClient({
  chain: celo,
  transport: custom(window.ethereum),
});

// Approve USDm spending (once)
const approveTx = await approveUsdm(walletClient);

// Play spin 7 in room 1
const playTx = await play(walletClient, 1n, 7);

Create a room

import { createRoom, parseUsdm } from 'gyro-sdk';

// Create room #5 with 0.5 USDm entry fee
const tx = await createRoom(walletClient, 5n, parseUsdm('0.5'));

Server-side with private key

import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { celo } from 'viem/chains';
import { play, approveUsdm } from 'gyro-sdk';

const account = privateKeyToAccount('0x...');
const walletClient = createWalletClient({
  account,
  chain: celo,
  transport: http('https://forno.celo.org'),
});

await approveUsdm(walletClient);
await play(walletClient, 1n, 5);

Configuration

Override defaults by passing config:

import { getRoom } from 'gyro-sdk';

const room = await getRoom(1n, {
  contractAddress: '0xYOUR_CONTRACT',
  rpcUrl: 'https://your-rpc.example.com',
});

API Reference

Read-only

| Function | Returns | Description | |----------|---------|-------------| | getRoomIds(opts?) | bigint[] | All created room IDs | | getRoom(roomId, opts?) | Room | Room state (entryFee, round, players, pot, highestSpin, exists) | | getAllRooms(opts?) | RoomWithId[] | All rooms with their IDs | | getRoundPlayers(roomId, round, opts?) | Player[] | Players and spins in a round | | hasPlayed(roomId, round, player, opts?) | boolean | Whether player already played | | getPlayerSpin(roomId, round, player, opts?) | bigint | Player's spin value | | getCreator(opts?) | Address | Contract creator address | | getMentoDollar(opts?) | Address | USDm token address | | getUsdmBalance(account, opts?) | bigint | USDm balance | | getUsdmAllowance(owner, opts?) | bigint | USDm allowance for GyroBoard |

Write (require viem walletClient)

| Function | Parameters | Description | |----------|-----------|-------------| | play(walletClient, roomId, spin, opts?) | spin: 1-10 | Submit a spin in a room | | createRoom(walletClient, roomId, entryFee, opts?) | entryFee in wei | Create a new room | | approveUsdm(walletClient, amount?, opts?) | defaults to max | Approve USDm spending | | transferUsdm(walletClient, to, amount) | recipient, amount | Transfer USDm tokens |

Utilities

| Function | Description | |----------|-------------| | formatUsdm(amount) | Format wei to USDm string | | parseUsdm(amount) | Parse USDm string to wei | | formatAddress(address) | Shorten address for display | | explorerUrl(txHash) | CeloScan transaction link | | addressExplorerUrl(address) | CeloScan address link |

Constants

| Constant | Value | |----------|-------| | DEFAULT_CONTRACT_ADDRESS | 0xa0C01234FEEA3401dE13598b3ef823afe0a9672B | | USDM_ADDRESS | 0x765DE816845861e75A25fCA122bb6898B8B1282a | | CELO_CHAIN_ID | 42220 | | MIN_SPIN / MAX_SPIN | 1 / 10 | | MAX_PLAYERS | 10 | | WINNER_SHARE / CREATOR_SHARE | 90% / 10% |

License

MIT