@suigar/sdk 2.0.0-beta.0 → 2.0.0-beta.10

package/README.md

@@ -2,73 +2,95 @@
 
 TypeScript SDK for building Suigar v2 game transactions on Sui.
 
-The published package entrypoint currently exposes:
-
-- `suigar`
-- `SuigarClient`
-
-It does not currently export the individual game builder functions from the package root.
-
 ## Installation
 
 ```bash
-npm install @suigar/sdk
+npm install --save @suigar/sdk @mysten/sui @mysten/bcs
 ```
 
 Runtime requirements:
 
 - Node.js `>=22`
+- ESM project configuration (`"type": "module"`)
+- `@mysten/sui` v2
+- `@mysten/bcs` v2
+
+This SDK targets Sui TypeScript SDK 2.0+ only. Follow the official [Sui 2.0 migration guide](https://sdk.mystenlabs.com/sui/migrations/sui-2.0) if your app still uses the pre-2.0 client API.
+
+## What This Package Exposes
 
-## Public API
+The package ships three public entrypoints:
+
+- `@suigar/sdk` for the extension factory and runtime client class
+- `@suigar/sdk/games` for game-specific public types
+- `@suigar/sdk/utils` for public parser, constants, and numeric helpers
+
+The package root exposes the extension factory and client class:
 
 ```ts
-import { suigar } from '@suigar/sdk';
+import { suigar, SuigarClient } from '@suigar/sdk';
 ```
 
-### `suigar(options?)`
+It does not export the individual transaction builders from the package root.
+Those stay on the registered extension instance under `client.suigar.tx`.
 
-Creates a named Sui client extension. By default, it registers under `client.suigar`.
+Utility exports are available from the utils subpath:
 
 ```ts
-const client = new SuiClient({ url }).$extend(suigar());
-client.suigar;
+import {
+	DEFAULT_GAS_BUDGET_MIST,
+	DEFAULT_LIMBO_MULTIPLIER_SCALE,
+	DEFAULT_RANGE_SCALE,
+	fromMoveFloat,
+	fromMoveI64,
+	parseCoinType,
+	parseGameDetails,
+	RANGE_POINT_LIMIT,
+	toBigInt,
+	toU8,
+} from '@suigar/sdk/utils';
 ```
 
-You can rename the extension:
+Game-specific type exports are available from the dedicated `games` subpath:
 
 ```ts
-const client = new SuiClient({ url }).$extend(suigar({ name: 'casino' }));
-
-client.casino;
+import type {
+	BuildCoinflipTransactionOptions,
+	BuildCreatePvPCoinflipTransactionOptions,
+	CoinSide,
+	PvPCoinflipAction,
+} from '@suigar/sdk/games';
 ```
 
-### `SuigarClient`
+Current game-type subpath exports:
+
+- `@suigar/sdk/games`: `CoinSide`, `PvPCoinflipAction`, `BuildCoinflipTransactionOptions`, `BuildLimboTransactionOptions`, `BuildPlinkoTransactionOptions`, `BuildRangeTransactionOptions`, `BuildWheelTransactionOptions`, `BuildCreatePvPCoinflipTransactionOptions`, `BuildJoinPvPCoinflipTransactionOptions`, `BuildCancelPvPCoinflipTransactionOptions`
+
+What you actually use at runtime is the registered extension instance:
 
-The registered extension instance exposes:
+```ts
+const client = new SuiGrpcClient({ baseUrl, network }).$extend(suigar());
 
-- `serializeTransactionToBase64(transaction)`
-- `bcs.BetResultEvent`
-- `tx.createBetTransaction(gameId, options)`
+client.suigar.serializeTransactionToBase64(...);
+client.suigar.getConfig();
+client.suigar.getPvPCoinflipGames(...);
+client.suigar.bcs;
+client.suigar.tx;
+```
 
-## Quick start
+## Quick Start
 
 ```ts
-import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
+import { SuiGrpcClient } from '@mysten/sui/grpc';
 import { suigar } from '@suigar/sdk';
 
-const client = new SuiClient({
-	url: getFullnodeUrl('testnet'),
-}).$extend(
-	suigar({
-		pyth: {
-			suiPriceInfoObjectId: '0xPYTH_SUI_PRICE_INFO',
-			usdcPriceInfoObjectId: '0xPYTH_USDC_PRICE_INFO',
-		},
-	}),
-);
+const client = new SuiGrpcClient({
+	baseUrl: 'https://fullnode.testnet.sui.io:443',
+	network: 'testnet',
+}).$extend(suigar());
 
 const tx = client.suigar.tx.createBetTransaction('coinflip', {
-	owner: '0x123',
+	playerAddress: '0x123',
 	coinType: '0x2::sui::SUI',
 	stake: 1_000_000_000n,
 	side: 'heads',
@@ -77,9 +99,142 @@ const tx = client.suigar.tx.createBetTransaction('coinflip', {
 const base64 = await client.suigar.serializeTransactionToBase64(tx);
 ```
 
-## Game transactions
+## Extension Registration
+
+### `suigar(options?)`
+
+Creates a named Sui client extension. By default, it registers under `client.suigar`.
+
+### Partner Setup
+
+> **Important:** `partner` is the partner wallet address. Configure it once
+> when you register the extension so the SDK can prepend that wallet address to
+> supported bet metadata automatically.
+
+```ts
+const client = new SuiGrpcClient({ baseUrl, network }).$extend(
+	suigar({ partner: '0xpartner_wallet_address' }),
+);
+
+client.suigar;
+```
+
+Do not pass a partner slug, label, or display name here. Use the wallet
+address that should receive partner attribution onchain.
+
+You can rename the extension:
+
+```ts
+const client = new SuiGrpcClient({ baseUrl, network }).$extend(
+	suigar({ name: 'games' }),
+);
+
+client.games.tx;
+client.games.bcs;
+```
+
+## Config
+
+`suigar(options?)` resolves config from:
+
+- internal package ids by network
+- internal supported coin types by network
+- internal price info object ids by network
+- the connected client network
+- the extension name
+
+Supported override areas:
+
+- `name`
+- `partner`
+
+If `partner` is configured, the SDK automatically writes that partner wallet
+address into the onchain metadata vec-map. Transaction builder options may also
+include `metadata`, but reserved keys such as `partner` and `referrer` are
+ignored with a warning when provided manually.
+
+## Runtime Surface
+
+The registered extension instance exposes the main runtime surface:
+
+- `getConfig()`
+- `serializeTransactionToBase64(transaction, options?)`
+- `getPvPCoinflipGames(options?)`
+- `bcs`
+- `tx`
+
+### `getConfig()`
+
+Returns the resolved SDK configuration for the connected network.
+
+This is intended mainly for debugging and inspection, for example to verify the
+resolved package ids or supported coin mappings for the active client network.
+
+It includes:
+
+- `packageIds`
+- `registryIds`
+- `coinTypes`
+- `priceInfoObjectIds`
+
+```ts
+const config = client.suigar.getConfig();
+console.log(config.packageIds);
+```
+
+### `serializeTransactionToBase64(transaction, options?)`
+
+Builds a transaction with the configured Sui client and returns base64-encoded transaction bytes.
+
+Use this when you need a transport-safe payload for a wallet, API, or external signer.
+
+```ts
+const base64 = await client.suigar.serializeTransactionToBase64(tx);
+```
+
+### `getPvPCoinflipGames(options?)`
+
+Lists unresolved PvP coinflip games from the configured PvP registry.
+
+This reads the registry dynamic fields for the active network and resolves each
+entry into parsed game state through a bulk `client.core.getObjects()` lookup.
+Registry membership is the unresolved-state signal: once a match is joined and
+resolved, the Move flow removes it from the registry and deletes the live
+`Game` object.
+
+Use this when a product needs the current set of open PvP coinflip matches for
+browsing or lobby views.
+
+By default, per-object fetch or parse failures are skipped so one broken or
+already-deleted registry entry does not reject the full lookup. Pass
+`throwOnError: true` if you want the call to reject instead.
+
+Any supported `listDynamicFields()` options such as `limit`, `cursor`, or
+`signal` can be passed through `options`.
+
+```ts
+const games = await client.suigar.getPvPCoinflipGames({ limit: 20 });
+
+for (const game of games) {
+	console.log(game.id);
+	console.log(game.coinType);
+}
+```
+
+```ts
+const games = await client.suigar.getPvPCoinflipGames({
+	limit: 20,
+	throwOnError: true,
+});
+```
+
+## `tx`
+
+Transaction builders live under `client.suigar.tx`.
+
+### Standard Games
 
-`tx.createBetTransaction(gameId, options)` supports these game ids:
+Use `createBetTransaction(gameId, options)` for:
 
 - `coinflip`
 - `limbo`
@@ -87,183 +242,206 @@ const base64 = await client.suigar.serializeTransactionToBase64(tx);
 - `range`
 - `wheel`
 
-All games share this base option shape:
+```ts
+const tx = client.suigar.tx.createBetTransaction('coinflip', {
+	playerAddress: '0x123',
+	coinType: '0x2::sui::SUI',
+	stake: 1_000_000_000n,
+	side: 'tails',
+});
+```
+
+Shared option shape:
 
-- `owner: string`
+- `playerAddress: string`
 - `coinType: string`
 - `stake: number | bigint`
 - `cashStake?: number | bigint`
 - `betCount?: number | bigint`
 - `metadata?: Record<string, string | number | boolean | bigint | Uint8Array | number[] | null | undefined>`
 - `gasBudget?: number | bigint`
-- `sender?: string`
 - `allowGasCoinShortcut?: boolean`
 
 Shared behavior:
 
-- `stake` is the logical game stake passed into the Move call
-- `cashStake` is the actual coin balance withdrawn into the bet coin and defaults to `stake`
+- `stake` is the logical stake passed into the Move call
+- `cashStake` controls the withdrawn balance and defaults to `stake`
 - `betCount` defaults to `1`
-- `sender` overrides the transaction sender
 - `metadata` is encoded into `keys` and `values` byte arrays
-- the SDK resolves the Pyth price object from the configured coin mapping
-- the built reward object is transferred back to the owner
+- `partner` configured via `suigar({ partner })` is prepended automatically to metadata as the partner wallet address
+- `metadata.partner` and `metadata.referrer` are reserved and ignored with a warning
+- the SDK resolves the price info object from the configured supported-coin mapping
+- the reward object is transferred back to `playerAddress`
 
-### Coinflip
+Per-game options:
 
-Additional options:
+- `coinflip`: `side: 'heads' | 'tails'`
+- `limbo`: `targetMultiplier: number`, `scale?: number`
+- `plinko`: `configId: number`
+- `range`: `leftPoint: number`, `rightPoint: number`, `outOfRange?: boolean`, `scale?: number`
+- `wheel`: `configId: number`
 
-- `side: 'heads' | 'tails'`
-
-Example:
+Examples:
 
 ```ts
-const tx = client.suigar.tx.createBetTransaction('coinflip', {
-	owner: '0x123',
+const limboTx = client.suigar.tx.createBetTransaction('limbo', {
+	playerAddress: '0x123',
 	coinType: '0x2::sui::SUI',
 	stake: 1_000_000_000n,
-	side: 'tails',
+	targetMultiplier: 2.5,
 });
-```
-
-### Limbo
-
-Additional options:
 
-- `targetMultiplier: number`
-- `scale?: number`
-
-Behavior:
-
-- `scale` defaults to the SDK limbo multiplier scale
-- `targetMultiplier` is converted with `Math.round(targetMultiplier * scale)`
-
-Example:
-
-```ts
-const tx = client.suigar.tx.createBetTransaction('limbo', {
-	owner: '0x123',
+const rangeTx = client.suigar.tx.createBetTransaction('range', {
+	playerAddress: '0x123',
 	coinType: '0x2::sui::SUI',
 	stake: 1_000_000_000n,
-	targetMultiplier: 2.5,
+	leftPoint: 25,
+	rightPoint: 75,
+	outOfRange: false,
 });
 ```
 
-### Plinko
+> **Note:**
+>
+> - limbo converts `targetMultiplier` with `Math.round(targetMultiplier * scale)`
+> - with the default limbo scale `100`, exposed as `DEFAULT_LIMBO_MULTIPLIER_SCALE`, a target multiplier of `2.5` becomes `250` onchain
+> - range converts each point with `Math.round(value * scale)`
+> - range points are bounded by the contract limit exposed as `RANGE_POINT_LIMIT`
+> - with the default range scale `1_000_000`, exposed as `DEFAULT_RANGE_SCALE`, valid UI values are `0` to `100`
+> - plinko and wheel `configId` must fit in `u8`
 
-Additional options:
+> **Tip:**
+>
+> - if you set `scale` to `10_000_000`, valid UI values become `0` to `10`
+> - do not pre-scale range points before passing them to the SDK; pass the human value and let the SDK scale it once
 
-- `configId: number`
+### PvP Coinflip
 
-Behavior:
+Use `createPvPCoinflipTransaction(action, options)` for PvP coinflip flows:
 
-- `configId` must fit in `u8`
+- `create`
+- `join`
+- `cancel`
 
-Example:
+Create:
 
 ```ts
-const tx = client.suigar.tx.createBetTransaction('plinko', {
-	owner: '0x123',
+const tx = client.suigar.tx.createPvPCoinflipTransaction('create', {
+	playerAddress: '0x123',
 	coinType: '0x2::sui::SUI',
 	stake: 1_000_000_000n,
-	configId: 3,
+	side: 'heads',
+	isPrivate: false,
 });
 ```
 
-### Range
-
-Additional options:
-
-- `leftPoint: number`
-- `rightPoint: number`
-- `outOfRange?: boolean`
-- `scale?: number`
+Join:
 
-Behavior:
-
-- `scale` defaults to the SDK fixed-point range scale
-- `leftPoint` and `rightPoint` are converted with `Math.round(value * scale)`
-- `outOfRange` is coerced with `Boolean(...)`
+```ts
+const tx = client.suigar.tx.createPvPCoinflipTransaction('join', {
+	playerAddress: '0x123',
+	coinType: '0x2::sui::SUI',
+	gameId: '0xGAME_ID',
+});
+```
 
-Example:
+Cancel:
 
 ```ts
-const tx = client.suigar.tx.createBetTransaction('range', {
-	owner: '0x123',
+const tx = client.suigar.tx.createPvPCoinflipTransaction('cancel', {
+	playerAddress: '0x123',
 	coinType: '0x2::sui::SUI',
-	stake: 1_000_000_000n,
-	leftPoint: 0.95,
-	rightPoint: 1.05,
-	outOfRange: false,
+	gameId: '0xGAME_ID',
 });
 ```
 
-### Wheel
+Join derives the stake from `gameId` and uses the configured price info object
+id for `coinType`.
 
-Additional options:
+PvP shared options:
 
-- `configId: number`
+- `playerAddress: string`
+- `coinType: string`
+- `metadata?: Record<string, string | number | boolean | bigint | Uint8Array | number[] | null | undefined>`
+- `gasBudget?: number | bigint`
+- `allowGasCoinShortcut?: boolean`
 
-Behavior:
+Action-specific options:
 
-- `configId` must fit in `u8`
+- `create`: `stake`, `side`, `isPrivate?`
+- `join`: `gameId`
+- `cancel`: `gameId`
 
-Example:
+## `bcs`
 
-```ts
-const tx = client.suigar.tx.createBetTransaction('wheel', {
-	owner: '0x123',
-	coinType: '0x2::sui::SUI',
-	stake: 1_000_000_000n,
-	configId: 1,
-});
-```
+BCS helpers live under `client.suigar.bcs`.
 
-## BCS helpers
+Current exposed helpers:
 
-The client extension also exposes a generated MoveStruct helper for Suigar bet result data:
+- `PvPCoinflipGame`
+- `BetResultEvent`
+- `PvPCoinflipGameCreatedEvent`
+- `PvPCoinflipGameResolvedEvent`
+- `PvPCoinflipGameCancelledEvent`
 
-- `client.suigar.bcs.BetResultEvent`
+These are generated Move event decoders. Use them to parse Suigar event payloads from transaction results. The `@suigar/sdk/utils` subpath also exposes parser helpers for generated BCS values:
 
-Use generated BCS types to parse onchain object data. Fetch the object with `include: { content: true }` and pass `object.content` to the generated type's `.parse()` method.
+- `PvPCoinflipGame` parses a PvP coinflip game object's `content`
+- `fromMoveI64(float.exp)` converts a generated Move `i64` exponent to a JavaScript number
+- `fromMoveFloat(float)` converts a generated Move `Float` struct to a JavaScript number
+- `parseCoinType(type)` extracts the normalized coin type from generic Move object type strings such as PvP coinflip `Game<T>`
+- `parseGameDetails(game_details)` decodes `BetResultEvent.game_details` entries into the expected string, number, and boolean values
 
-Always use `content`, not `objectBcs`, when parsing with generated types. The `objectBcs` field contains a full object envelope with additional metadata and is not the payload expected by the generated struct parser.
+### Parse PvP Coinflip Game Object Data
 
-### Parse onchain object content
+Use the generated BCS helper when you want to fetch and parse a game object:
 
 ```ts
-async function readBetResult(client: ClientWithCoreApi, id: string) {
-	const { object } = await client.core.getObject({
-		objectId: id,
-		include: {
-			content: true,
-		},
-	});
-
-	const parsed = client.suigar.bcs.BetResultEvent.parse(object.content);
-
-	console.log(parsed.player);
-	console.log(parsed.coin_type.name);
-	console.log(parsed.stake_amount);
-	console.log(parsed.outcome_amount);
-
-	return parsed;
-}
-```
+const game = await client.suigar.bcs.PvPCoinflipGame.get({
+	client,
+	objectId: '0xGAME_ID',
+});
 
-### Using the generated helper directly
+console.log(game.json);
+```
 
-If you already have a content-bearing object response, parse `object.content` directly:
+### Parse Standard Bet Result Data
 
 ```ts
-const { object } = await client.core.getObject({
-	objectId: '0xOBJECT_ID',
+const executeResult = await client.core.executeTransaction({
+	transaction: transactionBytes,
+	signatures: [signature],
 	include: {
-		content: true,
+		events: true,
 	},
 });
 
-const decoded = client.suigar.bcs.BetResultEvent.parse(object.content);
+const finalResult = await client.core.waitForTransaction({
+	result: executeResult,
+	include: {
+		effects: true,
+		events: true,
+	},
+});
+
+if (finalResult.$kind === 'FailedTransaction') {
+	throw new Error(finalResult.FailedTransaction.status.error?.message);
+}
+
+console.log(finalResult.Transaction.digest);
+
+const transactionResult = finalResult.Transaction;
+
+const betResults = [];
+
+for (const event of transactionResult.events ?? []) {
+	try {
+		const decoded = client.suigar.bcs.BetResultEvent.parse(event.bcs);
+		betResults.push(decoded);
+	} catch {
+		// Ignore non-BetResultEvent payloads.
+	}
+}
 ```
 
 Parsed fields include:
@@ -277,75 +455,68 @@ Parsed fields include:
 - `game_details`
 - `metadata`
 
-For `game_details` and `metadata`, the decoded value is a `VecMap<string, vector<u8>>`-shaped structure, so values come back as byte arrays.
-
-Example conversion to strings:
+`game_details` and `metadata` decode as `VecMap<string, vector<u8>>`-shaped data, so values come back as byte arrays. Use `parseGameDetails` from `@suigar/sdk/utils` to decode `game_details` with the SDK's known game-detail schemas.
 
 ```ts
-const decoded = client.suigar.bcs.BetResultEvent.parse(object.data.content);
-const textDecoder = new TextDecoder();
-
-const metadata = new Map(
-	decoded.metadata.contents.map(({ key, value }) => [
-		key,
-		textDecoder.decode(new Uint8Array(value)),
-	]),
-);
+import { parseGameDetails } from '@suigar/sdk/utils';
+
+const decoded = client.suigar.bcs.BetResultEvent.parse(event.bcs);
+const gameDetails = parseGameDetails(decoded.game_details);
 ```
 
-## Config
+`parseGameDetails` preserves the onchain keys and only changes the value representation. For example, coinflip details keep keys such as `player_bet` and `coin_outcome`; range details keep keys such as `roll_value`, `win`, and `payout_multiplier`.
 
-`suigar(options?)` resolves config from:
+When the extension is configured with `partner`, decoded event `metadata` will
+contain that partner wallet address under the `partner` entry.
 
-- the connected Sui network
-- internal default package ids
-- internal default SweetHouse package id by network
-- default coin types for `SUI`, `USDC`, and FlowX `USDC`
-- user overrides
+> **Important:**
+>
+> - execute or wait for the transaction with `include: { events: true }`
+> - unwrap the core API union with `result.$kind`, `result.Transaction`, and `result.FailedTransaction`
+> - parse emitted events from the unwrapped transaction result
+> - use `event.bcs` for consistent decoding across transports
+> - use `parseGameDetails(decoded.game_details)` instead of hand-decoding standard game detail byte arrays
 
-Supported override areas:
+> **Tip:**
+>
+> - `waitForTransaction({ result, include: { effects: true, events: true } })` is useful when you want the finalized transaction result before decoding
+> - these helpers decode the event payload itself, not a full transaction response
 
-- `name`
-- `sweetHousePackageId`
-- `coinTypes.sui`
-- `coinTypes.usdc`
-- `coinTypes.usdcFlowx`
-- `gamesPackageId.coinflip`
-- `gamesPackageId.limbo`
-- `gamesPackageId.plinko`
-- `gamesPackageId['pvp-coinflip']`
-- `gamesPackageId.range`
-- `gamesPackageId.wheel`
-- `pyth.packageId`
-- `pyth.suiPriceInfoObjectId`
-- `pyth.usdcPriceInfoObjectId`
-- `pyth.priceInfoObjectIds[coinType]`
-
-Example:
+### Parse PvP Coinflip Event Data
 
-```ts
-const client = new SuiClient({ url }).$extend(
-	suigar({
-		sweetHousePackageId: '0xsweethouse',
-		pyth: {
-			suiPriceInfoObjectId: '0xsui',
-			usdcPriceInfoObjectId: '0xusdc',
-			priceInfoObjectIds: {
-				'0x123::custom::TOKEN': '0xprice',
-			},
-		},
-		gamesPackageId: {
-			coinflip: '0xcoinflip',
-			wheel: '0xwheel',
-		},
-	}),
-);
-```
+Use the matching helper for each PvP coinflip event payload found in `transactionResult.events`:
+
+- `client.suigar.bcs.PvPCoinflipGameCreatedEvent`
+- `client.suigar.bcs.PvPCoinflipGameResolvedEvent`
+- `client.suigar.bcs.PvPCoinflipGameCancelledEvent`
 
 ## Development
 
 ```bash
-npm run build
-npm run typecheck
-npm test
+pnpm --dir packages/sdk build
+pnpm --dir packages/sdk typecheck
+pnpm --dir packages/sdk test
+```
+
+## Example App
+
+This repository includes a Next.js integration playground in [apps/playground](../../apps/playground).
+
+It demonstrates:
+
+- standard game transactions through `client.suigar.tx.createBetTransaction(...)`
+- PvP coinflip create, join, and cancel flows through `client.suigar.tx.createPvPCoinflipTransaction(...)`, exposed in the example through a PvP coinflip action selector
+- unresolved PvP lobby browsing through `client.suigar.getPvPCoinflipGames(...)`, including public join cards while disconnected, an optional private-lobby join toggle, and connected-wallet filtering for cancel
+- wallet connection and execution with `@mysten/dapp-kit-core` and `@mysten/dapp-kit-react`
+- supported coin selection from `client.suigar.getConfig()`
+- connected-wallet balance display for each supported coin in the example app
+- privacy badges and copyable PvP game ids in the lobby UI
+- decoding `BetResultEvent` and PvP events into a persistent event log
+- parsing `BetResultEvent.game_details` with `parseGameDetails`
+
+Run it from the repo root with:
+
+```bash
+pnpm install
+pnpm turbo run dev --filter='./apps/playground'
 ```