@suigar/sdk 2.0.0-beta.1 → 2.0.0-beta.11

package/README.md

@@ -5,31 +5,92 @@ TypeScript SDK for building Suigar v2 game transactions on Sui.
 ## Installation
 
 ```bash
-npm install @suigar/sdk
+npm install --save @suigar/sdk @mysten/sui @mysten/bcs
 ```
 
 Runtime requirements:
 
 - Node.js `>=22`
-- `@mysten/sui`
+- 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
 
-The package root currently exposes the extension factory:
+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';
 ```
 
 It does not export the individual transaction builders from the package root.
-It also does not export `SuigarClient` as a public root symbol.
+Those stay on the registered extension instance under `client.suigar.tx`.
+
+Utility exports are available from the utils subpath:
+
+```ts
+import {
+	DEFAULT_GAS_BUDGET_MIST,
+	DEFAULT_LIMBO_MULTIPLIER_SCALE,
+	DEFAULT_RANGE_SCALE,
+	fromMoveFloat,
+	fromMoveI64,
+	parseCoinType,
+	parseGameDetails,
+	RANGE_POINT_LIMIT,
+	toBigInt,
+	toU8,
+	toU16,
+} from '@suigar/sdk/utils';
+```
+
+Numeric helper behavior:
+
+- `toBigInt(value)` accepts `bigint`, finite `number`, non-negative integer
+  `string`, and `boolean` inputs and returns a normalized non-negative `bigint`
+- `toU8(value)` accepts a finite integer `number` or plain integer `string` in
+  the inclusive `0..255` range and rejects booleans or fractional values
+- `toU16(value)` accepts a finite integer `number` or plain integer `string`
+  in the inclusive `0..65535` range and rejects booleans or fractional values
+- `fromMoveI64(value)` converts a generated Move `i64` wrapper into a
+  JavaScript `number`
+- `fromMoveFloat(value)` converts a generated Move float struct into a
+  JavaScript `number`
+- `parseGameDetails(gameDetails)` decodes standard `BetResultEvent.game_details`
+  byte arrays into the expected string, number, and boolean values while
+  preserving the original onchain keys
+
+Game-specific type exports are available from the dedicated `games` subpath:
+
+```ts
+import type {
+	BuildCoinflipTransactionOptions,
+	BuildCreatePvPCoinflipTransactionOptions,
+	CoinSide,
+	PvPCoinflipAction,
+} from '@suigar/sdk/games';
+```
+
+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:
 
 ```ts
-const client = new SuiClient({ url }).$extend(suigar());
+const client = new SuiGrpcClient({ baseUrl, network }).$extend(suigar());
 
 client.suigar.serializeTransactionToBase64(...);
+client.suigar.getConfig();
+client.suigar.getPvPCoinflipGames(...);
 client.suigar.bcs;
 client.suigar.tx;
 ```
@@ -37,22 +98,16 @@ client.suigar.tx;
 ## Quick Start
 
 ```ts
-import { getFullnodeUrl, SuiClient } 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',
@@ -67,78 +122,114 @@ const base64 = await client.suigar.serializeTransactionToBase64(tx);
 
 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 SuiClient({ url }).$extend(suigar());
+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 SuiClient({ url }).$extend(suigar({ name: 'casino' }));
+const client = new SuiGrpcClient({ baseUrl, network }).$extend(
+	suigar({ name: 'games' }),
+);
 
-client.casino.tx;
-client.casino.bcs;
+client.games.tx;
+client.games.bcs;
 ```
 
 ## Config
 
 `suigar(options?)` resolves config from:
 
-- 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
+- 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`
-- `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:
+- `partner`
+- `cacheTtl`
 
-```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',
-		},
-	}),
-);
-```
+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.
+
+`cacheTtl` controls the SDK cache for onchain reads such as parsed game
+parameters. It is expressed in milliseconds and defaults to 30 minutes.
 
 ## Runtime Surface
 
-The registered extension instance exposes three main areas:
+The registered extension instance exposes the main runtime surface:
 
+- `getConfig()`
+- `getGameParameters(game, options?)`
 - `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);
+```
+
+### `getGameParameters(game, options?)`
+
+Returns the onchain `Parameters<T>` object for any supported game and coin type.
+The return type is inferred from `game`.
+
+The SDK first reads the selected game's settings object from the configured
+SweetHouse object, then reads that game's coin-specific `Parameters<T>` object.
+This is useful for displaying or validating current limits such as min/max
+stake, house edge, or game-specific config bounds. The parsed result is cached
+using the extension `cacheTtl`.
+
+When a parameter field is a generated Move float struct, such as
+`min_target_multiplier`, `max_target_multiplier`, `min_rtp`, or `max_rtp`, use
+`fromMoveFloat()` before treating it as a normal JavaScript number.
+
+```ts
+const parameters = await client.suigar.getGameParameters('coinflip', {
+	coinType: '0x2::sui::SUI',
+});
+
+console.log(parameters.min_stake);
+```
+
+Pass `ignoreCache: true` to refresh the onchain read and replace the cached
+value.
+
 ### `serializeTransactionToBase64(transaction, options?)`
 
 Builds a transaction with the configured Sui client and returns base64-encoded transaction bytes.
@@ -149,6 +240,42 @@ Use this when you need a transport-safe payload for a wallet, API, or external s
 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`.
@@ -165,7 +292,7 @@ Use `createBetTransaction(gameId, options)` for:
 
 ```ts
 const tx = client.suigar.tx.createBetTransaction('coinflip', {
-	owner: '0x123',
+	playerAddress: '0x123',
 	coinType: '0x2::sui::SUI',
 	stake: 1_000_000_000n,
 	side: 'tails',
@@ -174,14 +301,13 @@ const tx = client.suigar.tx.createBetTransaction('coinflip', {
 
 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:
@@ -189,10 +315,11 @@ Shared behavior:
 - `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 info object from the configured coin mapping
-- the reward object is transferred back to `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`
 
 Per-game options:
 
@@ -206,27 +333,35 @@ Examples:
 
 ```ts
 const limboTx = client.suigar.tx.createBetTransaction('limbo', {
-	owner: '0x123',
+	playerAddress: '0x123',
 	coinType: '0x2::sui::SUI',
 	stake: 1_000_000_000n,
 	targetMultiplier: 2.5,
 });
 
 const rangeTx = client.suigar.tx.createBetTransaction('range', {
-	owner: '0x123',
+	playerAddress: '0x123',
 	coinType: '0x2::sui::SUI',
 	stake: 1_000_000_000n,
-	leftPoint: 0.95,
-	rightPoint: 1.05,
+	leftPoint: 25,
+	rightPoint: 75,
 	outOfRange: false,
 });
 ```
 
-Notes:
+> **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`
 
-- limbo converts `targetMultiplier` with `Math.round(targetMultiplier * scale)`
-- range converts each point with `Math.round(value * scale)`
-- plinko and wheel `configId` must fit in `u8`
+> **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
 
 ### PvP Coinflip
 
@@ -240,7 +375,7 @@ Create:
 
 ```ts
 const tx = client.suigar.tx.createPvPCoinflipTransaction('create', {
-	owner: '0x123',
+	playerAddress: '0x123',
 	coinType: '0x2::sui::SUI',
 	stake: 1_000_000_000n,
 	side: 'heads',
@@ -252,11 +387,9 @@ Join:
 
 ```ts
 const tx = client.suigar.tx.createPvPCoinflipTransaction('join', {
-	owner: '0x123',
+	playerAddress: '0x123',
 	coinType: '0x2::sui::SUI',
 	gameId: '0xGAME_ID',
-	extraObjectId: '0xEXTRA_OBJECT_ID',
-	stake: 1_000_000_000n,
 });
 ```
 
@@ -264,25 +397,27 @@ Cancel:
 
 ```ts
 const tx = client.suigar.tx.createPvPCoinflipTransaction('cancel', {
-	owner: '0x123',
+	playerAddress: '0x123',
 	coinType: '0x2::sui::SUI',
 	gameId: '0xGAME_ID',
 });
 ```
 
+Join derives the stake from `gameId` and uses the configured price info object
+id for `coinType`.
+
 PvP shared options:
 
-- `owner: string`
+- `playerAddress: string`
 - `coinType: string`
-- `metadata?: ...`
+- `metadata?: Record<string, string | number | boolean | bigint | Uint8Array | number[] | null | undefined>`
 - `gasBudget?: number | bigint`
-- `sender?: string`
 - `allowGasCoinShortcut?: boolean`
 
 Action-specific options:
 
 - `create`: `stake`, `side`, `isPrivate?`
-- `join`: `gameId`, `extraObjectId`, `stake`
+- `join`: `gameId`
 - `cancel`: `gameId`
 
 ## `bcs`
@@ -291,24 +426,70 @@ BCS helpers live under `client.suigar.bcs`.
 
 Current exposed helpers:
 
+- `PvPCoinflipGame`
 - `BetResultEvent`
-- `PvPCoinflipGameCreated`
-- `PvPCoinflipGameResolved`
-- `PvPCoinflipGameCancelled`
+- `PvPCoinflipGameCreatedEvent`
+- `PvPCoinflipGameResolvedEvent`
+- `PvPCoinflipGameCancelledEvent`
+
+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:
+
+- `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
+
+### Parse PvP Coinflip Game Object Data
+
+Use the generated BCS helper when you want to fetch and parse a game object:
+
+```ts
+const game = await client.suigar.bcs.PvPCoinflipGame.get({
+	client,
+	objectId: '0xGAME_ID',
+});
 
-These are generated Move struct/event decoders. Use them to parse Suigar event payloads and structured onchain content.
+console.log(game.json);
+```
 
 ### 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:
@@ -322,36 +503,68 @@ Parsed fields include:
 - `game_details`
 - `metadata`
 
-`game_details` and `metadata` decode as `VecMap<string, vector<u8>>`-shaped data, so values come back as byte arrays.
+`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 textDecoder = new TextDecoder();
+import { parseGameDetails } from '@suigar/sdk/utils';
 
-const metadata = new Map(
-	decoded.metadata.contents.map(({ key, value }) => [
-		key,
-		textDecoder.decode(new Uint8Array(value)),
-	]),
-);
+const decoded = client.suigar.bcs.BetResultEvent.parse(event.bcs);
+const gameDetails = parseGameDetails(decoded.game_details);
 ```
 
-Important:
+`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`.
+
+When the extension is configured with `partner`, decoded event `metadata` will
+contain that partner wallet address under the `partner` entry.
+
+> **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
 
-- use `content`, not `objectBcs`, with these generated parsers
-- the generated parser expects the struct payload, not a full object envelope
+> **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
 
 ### Parse PvP Coinflip Event Data
 
-Use the matching helper for the PvP coinflip event payload you fetched from chain:
+Use the matching helper for each PvP coinflip event payload found in `transactionResult.events`:
 
-- `client.suigar.bcs.PvPCoinflipGameCreated`
-- `client.suigar.bcs.PvPCoinflipGameResolved`
-- `client.suigar.bcs.PvPCoinflipGameCancelled`
+- `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'
 ```