@suigar/sdk 2.0.0-beta.6 → 2.0.0-beta.8

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @suigar/sdk
 
+## 2.0.0-beta.8
+
+### Patch Changes
+
+- 0292edb: Rename transaction builder option `owner` to `playerAddress` and remove the separate `sender` option so all game transactions use a single explicit player address.
+- 20311be: Improve the public JSDoc for `parseGameDetails`, `toBigInt`, and `toU8` so the
+  generated API surface explains their coercion, validation, and decoding
+  behavior more clearly.
+- a2aa324: Update PvP coinflip lookup helpers to use bulk object reads for unresolved lobby discovery and support forwarded lookup options.
+  - Make `getPvPCoinflipGames()` parse bulk `client.core.getObjects()` results instead of resolving each game individually.
+  - Skip per-object fetch or parse failures by default and continue supporting strict rejection with `throwOnError: true`.
+  - Forward supported lookup options such as `signal` through `getPvPCoinflipGames()` and `resolvePvPConflipGame(gameId, options?)`.
+  - Update tests, README guidance, and repo-local PvP skill documentation to match the current client behavior.
+
+## 2.0.0-beta.7
+
+### Patch Changes
+
+- f0ea104: Align numeric utility names, Move decoding helpers, and PvP BCS event helper references with the current SDK API.
+
 ## 2.0.0-beta.6
 
 ### Patch Changes

package/README.md

@@ -42,11 +42,11 @@ import {
 	DEFAULT_LIMBO_MULTIPLIER_SCALE,
 	DEFAULT_RANGE_SCALE,
 	RANGE_POINT_LIMIT,
-	parseFloat,
+	fromMoveFloat,
+	fromMoveI64,
 	parseGameDetails,
-	parseI64,
-	toBigIntAmount,
-	toU8Number,
+	toBigInt,
+	toU8,
 } from '@suigar/sdk/utils';
 ```
 
@@ -92,7 +92,7 @@ const client = new SuiGrpcClient({
 }).$extend(suigar());
 
 const tx = client.suigar.tx.createBetTransaction('coinflip', {
-	owner: '0x123',
+	playerAddress: '0x123',
 	coinType: '0x2::sui::SUI',
 	stake: 1_000_000_000n,
 	side: 'heads',
@@ -200,17 +200,20 @@ const base64 = await client.suigar.serializeTransactionToBase64(tx);
 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 `resolvePvPConflipGame()`. Registry
+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, failures to resolve an individual game are skipped so one broken or
+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 });
 
@@ -227,14 +230,15 @@ const games = await client.suigar.getPvPCoinflipGames({
 });
 ```
 
-### `resolvePvPConflipGame(gameId)`
+### `resolvePvPConflipGame(gameId, options?)`
 
 Fetches a PvP coinflip game object from chain and parses it into the SDK's
 normalized runtime shape.
 
 This requires the object's `content`, decodes it with the generated
 `PvPCoinflipGame` parser, and normalizes the generic coin type into a standard
-struct tag string.
+struct tag string. You can optionally pass through `getObject()` options such as
+`signal`.
 
 Use this when a product needs the live onchain match state for a specific
 pending match before rendering join or cancel actions, or inspecting the stake
@@ -249,11 +253,19 @@ console.log(game.stake_per_player);
 console.log(game.is_private);
 ```
 
+```ts
+const controller = new AbortController();
+
+const game = await client.suigar.resolvePvPConflipGame('0xGAME_ID', {
+	signal: controller.signal,
+});
+```
+
 > **Note:**
 >
 > - it throws if the object response does not include decodable `content`
 > - the PvP join builder uses this internally to derive the required join stake
-> - after a game is joined and resolved, the live `Game` object is removed from the registry and deleted, so inspect `PvPCoinflipGameResolved` to read the final result
+> - after a game is joined and resolved, the live `Game` object is removed from the registry and deleted, so inspect `PvPCoinflipGameResolvedEvent` to read the final result
 
 > **Tip:** Prefer this helper over manual object parsing when you only need the
 > parsed state for a live PvP coinflip game object.
@@ -274,7 +286,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',
@@ -283,14 +295,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:
@@ -298,12 +309,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
 - `partner` configured via `suigar({ partner })` is appended 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 `owner`
+- the reward object is transferred back to `playerAddress`
 
 Per-game options:
 
@@ -317,14 +327,14 @@ 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: 25,
@@ -359,7 +369,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',
@@ -371,7 +381,7 @@ Join:
 
 ```ts
 const tx = client.suigar.tx.createPvPCoinflipTransaction('join', {
-	owner: '0x123',
+	playerAddress: '0x123',
 	coinType: '0x2::sui::SUI',
 	gameId: '0xGAME_ID',
 });
@@ -381,7 +391,7 @@ Cancel:
 
 ```ts
 const tx = client.suigar.tx.createPvPCoinflipTransaction('cancel', {
-	owner: '0x123',
+	playerAddress: '0x123',
 	coinType: '0x2::sui::SUI',
 	gameId: '0xGAME_ID',
 });
@@ -392,11 +402,10 @@ id for `coinType`.
 
 PvP shared options:
 
-- `owner: string`
+- `playerAddress: string`
 - `coinType: string`
 - `metadata?: Record<string, string | number | boolean | bigint | Uint8Array | number[] | null | undefined>`
 - `gasBudget?: number | bigint`
-- `sender?: string`
 - `allowGasCoinShortcut?: boolean`
 
 Action-specific options:
@@ -413,15 +422,15 @@ 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`
-- `parseI64(float.exp)` converts a generated Move `i64` exponent to a JavaScript number
-- `parseFloat(float)` converts a generated Move `Float` struct to a JavaScript number
+- `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
 - `parseGameDetails(game_details)` decodes `BetResultEvent.game_details` entries into the expected string, number, and boolean values
 
 ### Parse PvP Coinflip Game Object Data
@@ -528,9 +537,9 @@ contain that partner wallet address under the `partner` entry.
 
 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
 
@@ -542,13 +551,13 @@ npm test
 
 ## Example App
 
-This repository now includes a Next.js integration example in [examples/game-integration](/Users/lucas/Documents/Github/suigar-sdk/examples/game-integration).
+This repository includes a Next.js integration example in [examples/game-integration](examples/game-integration).
 
 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(...)`, rendered as compact join/cancel cards filtered by the connected wallet
+- 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

package/dist/{chunk-W3WZ2BHO.js → chunk-YGYMLRE4.js}

@@ -9,21 +9,34 @@ var RANGE_POINT_LIMIT = DEFAULT_RANGE_SCALE * 100;
 var DEFAULT_LIMBO_MULTIPLIER_SCALE = 100;
 
 // src/utils/numeric.ts
-function toBigIntAmount(value, fieldName) {
+function isFiniteNumber(value, message) {
+  if (typeof value !== "number") {
+    throw new Error(`${message}: ${String(value)}`);
+  }
+  if (!Number.isFinite(value)) {
+    throw new Error(`Value must be a finite number: ${value}`);
+  }
+}
+function toBigInt(value) {
   if (typeof value === "bigint") {
     if (value < 0n) {
-      throw new Error(`${fieldName} must be non-negative`);
+      throw new Error(`Value must be non-negative: ${value}`);
     }
     return value;
   }
-  if (!Number.isFinite(value) || value < 0) {
-    throw new Error(`${fieldName} must be a finite non-negative number`);
+  isFiniteNumber(value, "Value must be a bigint or number");
+  if (value < 0) {
+    throw new Error(`Value must be a finite non-negative number: ${value}`);
   }
   return BigInt(Math.trunc(value));
 }
-function toU8Number(value, fieldName) {
-  if (!Number.isInteger(value) || value < 0 || value > 255) {
-    throw new Error(`${fieldName} must be an integer between 0 and 255`);
+function toU8(value) {
+  isFiniteNumber(value, "Value must be a number");
+  if (!Number.isInteger(value)) {
+    throw new Error(`Value must be an integer: ${value}`);
+  }
+  if (value < 0 || value > 255) {
+    throw new Error(`Value must be an integer between 0 and 255: ${value}`);
   }
   return value;
 }
@@ -255,7 +268,7 @@ var GAME_DETAIL_BCS = {
   float: Float,
   string: bcsString
 };
-function parseI64(i64) {
+function fromMoveI64(i64) {
   try {
     const value = BigInt(i64.bits ?? 0);
     const maxPositive = 1n << 63n;
@@ -266,18 +279,18 @@ function parseI64(i64) {
     return 0;
   }
 }
-function parseFloat(float) {
+function fromMoveFloat(float) {
   const mantissa = BigInt(float.mant);
   if (mantissa === 0n) {
     return 0;
   }
-  const exponent = parseI64(float.exp) - 52;
+  const exponent = fromMoveI64(float.exp) - 52;
   const magnitude = Number(mantissa) * Math.pow(2, exponent);
   return float.is_negative ? -magnitude : magnitude;
 }
 function normalizeGameDetailValue(valueType, parsed) {
   if (valueType === "float") {
-    return parseFloat(parsed);
+    return fromMoveFloat(parsed);
   }
   if (valueType === "u64") {
     return Number(parsed);
@@ -307,4 +320,4 @@ function parseGameDetails(gameDetails) {
   }, {});
 }
 
-export { DEFAULT_GAS_BUDGET_MIST, DEFAULT_LIMBO_MULTIPLIER_SCALE, DEFAULT_RANGE_SCALE, Float, MoveStruct, RANGE_POINT_LIMIT, normalizeMoveArguments, parseFloat, parseGameDetails, parseI64, toBigIntAmount, toU8Number };
+export { DEFAULT_GAS_BUDGET_MIST, DEFAULT_LIMBO_MULTIPLIER_SCALE, DEFAULT_RANGE_SCALE, Float, MoveStruct, RANGE_POINT_LIMIT, fromMoveFloat, fromMoveI64, normalizeMoveArguments, parseGameDetails, toBigInt, toU8 };

package/dist/{games--Haw_z7M.d.cts → games-BccpPyWd.d.cts}

@@ -1,3 +1,5 @@
+import { Transaction } from '@mysten/sui/transactions';
+
 declare const GAMES: readonly ["coinflip", "limbo", "plinko", "pvp-coinflip", "range", "wheel"];
 type Game = (typeof GAMES)[number];
 type StandardGame = Exclude<Game, PvPGame>;
@@ -26,22 +28,27 @@ type SuigarConfig = {
     priceInfoObjectIds: SuigarPriceInfoObjectId;
 };
 
-type SharedBetTransactionOptions = {
+type WithGasBudget = {
+    gasBudget?: Parameters<Transaction['setGasBudgetIfNotSet']>[0];
+};
+type WithThrowOnError<T = object> = T & {
+    throwOnError?: boolean;
+};
+type BaseTransactionOptions = WithGasBudget & {
     config: SuigarConfig;
-    owner: string;
+    playerAddress: string;
+};
+type CoinTransactionOptions = {
     coinType: string;
-    stake: number | bigint;
-    cashStake?: number | bigint;
-    betCount?: number | bigint;
     metadata?: BetMetadataInput;
-    gasBudget?: number | bigint;
-    sender?: string;
     allowGasCoinShortcut?: boolean;
 };
-
-type WithThrowOnError<T = object> = T & {
-    throwOnError?: boolean;
+type StakeTransactionOptions = {
+    stake: number | bigint;
+    cashStake?: number | bigint;
+    betCount?: number | bigint;
 };
+type SharedBetTransactionOptions = BaseTransactionOptions & CoinTransactionOptions & StakeTransactionOptions;
 type BuildCoinflipTransactionOptions = SharedBetTransactionOptions & {
     side: CoinSide;
 };
@@ -62,17 +69,9 @@ type BuildWheelTransactionOptions = SharedBetTransactionOptions & {
     configId: number;
 };
 type PvPCoinflipAction = 'create' | 'join' | 'cancel';
-type SharedPvPCoinflipTransactionOptions = {
-    config: SuigarConfig;
-    owner: string;
-    coinType: string;
-    metadata?: BetMetadataInput;
-    gasBudget?: number | bigint;
-    sender?: string;
-    allowGasCoinShortcut?: boolean;
-};
+type SharedPvPCoinflipTransactionOptions = BaseTransactionOptions & CoinTransactionOptions;
 type BuildCreatePvPCoinflipTransactionOptions = SharedPvPCoinflipTransactionOptions & {
-    stake: number | bigint;
+    stake: StakeTransactionOptions['stake'];
     side: CoinSide;
     isPrivate?: boolean;
 };

package/dist/{games--Haw_z7M.d.ts → games-BccpPyWd.d.ts}

@@ -1,3 +1,5 @@
+import { Transaction } from '@mysten/sui/transactions';
+
 declare const GAMES: readonly ["coinflip", "limbo", "plinko", "pvp-coinflip", "range", "wheel"];
 type Game = (typeof GAMES)[number];
 type StandardGame = Exclude<Game, PvPGame>;
@@ -26,22 +28,27 @@ type SuigarConfig = {
     priceInfoObjectIds: SuigarPriceInfoObjectId;
 };
 
-type SharedBetTransactionOptions = {
+type WithGasBudget = {
+    gasBudget?: Parameters<Transaction['setGasBudgetIfNotSet']>[0];
+};
+type WithThrowOnError<T = object> = T & {
+    throwOnError?: boolean;
+};
+type BaseTransactionOptions = WithGasBudget & {
     config: SuigarConfig;
-    owner: string;
+    playerAddress: string;
+};
+type CoinTransactionOptions = {
     coinType: string;
-    stake: number | bigint;
-    cashStake?: number | bigint;
-    betCount?: number | bigint;
     metadata?: BetMetadataInput;
-    gasBudget?: number | bigint;
-    sender?: string;
     allowGasCoinShortcut?: boolean;
 };
-
-type WithThrowOnError<T = object> = T & {
-    throwOnError?: boolean;
+type StakeTransactionOptions = {
+    stake: number | bigint;
+    cashStake?: number | bigint;
+    betCount?: number | bigint;
 };
+type SharedBetTransactionOptions = BaseTransactionOptions & CoinTransactionOptions & StakeTransactionOptions;
 type BuildCoinflipTransactionOptions = SharedBetTransactionOptions & {
     side: CoinSide;
 };
@@ -62,17 +69,9 @@ type BuildWheelTransactionOptions = SharedBetTransactionOptions & {
     configId: number;
 };
 type PvPCoinflipAction = 'create' | 'join' | 'cancel';
-type SharedPvPCoinflipTransactionOptions = {
-    config: SuigarConfig;
-    owner: string;
-    coinType: string;
-    metadata?: BetMetadataInput;
-    gasBudget?: number | bigint;
-    sender?: string;
-    allowGasCoinShortcut?: boolean;
-};
+type SharedPvPCoinflipTransactionOptions = BaseTransactionOptions & CoinTransactionOptions;
 type BuildCreatePvPCoinflipTransactionOptions = SharedPvPCoinflipTransactionOptions & {
-    stake: number | bigint;
+    stake: StakeTransactionOptions['stake'];
     side: CoinSide;
     isPrivate?: boolean;
 };

package/dist/games.d.cts

@@ -1 +1,2 @@
-export { h as BuildCancelPvPCoinflipTransactionOptions, B as BuildCoinflipTransactionOptions, i as BuildCreatePvPCoinflipTransactionOptions, j as BuildJoinPvPCoinflipTransactionOptions, b as BuildLimboTransactionOptions, c as BuildPlinkoTransactionOptions, d as BuildRangeTransactionOptions, a as BuildWheelTransactionOptions, C as CoinSide, P as PvPCoinflipAction } from './games--Haw_z7M.cjs';
+export { h as BuildCancelPvPCoinflipTransactionOptions, B as BuildCoinflipTransactionOptions, i as BuildCreatePvPCoinflipTransactionOptions, j as BuildJoinPvPCoinflipTransactionOptions, b as BuildLimboTransactionOptions, c as BuildPlinkoTransactionOptions, d as BuildRangeTransactionOptions, a as BuildWheelTransactionOptions, C as CoinSide, P as PvPCoinflipAction } from './games-BccpPyWd.cjs';
+import '@mysten/sui/transactions';

package/dist/games.d.ts

@@ -1 +1,2 @@
-export { h as BuildCancelPvPCoinflipTransactionOptions, B as BuildCoinflipTransactionOptions, i as BuildCreatePvPCoinflipTransactionOptions, j as BuildJoinPvPCoinflipTransactionOptions, b as BuildLimboTransactionOptions, c as BuildPlinkoTransactionOptions, d as BuildRangeTransactionOptions, a as BuildWheelTransactionOptions, C as CoinSide, P as PvPCoinflipAction } from './games--Haw_z7M.js';
+export { h as BuildCancelPvPCoinflipTransactionOptions, B as BuildCoinflipTransactionOptions, i as BuildCreatePvPCoinflipTransactionOptions, j as BuildJoinPvPCoinflipTransactionOptions, b as BuildLimboTransactionOptions, c as BuildPlinkoTransactionOptions, d as BuildRangeTransactionOptions, a as BuildWheelTransactionOptions, C as CoinSide, P as PvPCoinflipAction } from './games-BccpPyWd.js';
+import '@mysten/sui/transactions';