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

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @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

package/README.md

@@ -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,6 +253,14 @@ 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`
@@ -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:
@@ -542,7 +551,7 @@ 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:
 

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';

package/dist/index.cjs

@@ -413,20 +413,18 @@ var Float = new MoveStruct({ name: `${$moduleName2}::Float`, fields: {
 function createBaseGameTransaction({
   config,
   game,
-  owner,
-  sender,
+  playerAddress,
   gasBudget
 }) {
   assertConfiguredBetGame(config, game);
   const tx = new transactions.Transaction();
-  tx.setSenderIfNotSet(utils.normalizeSuiAddress(sender ?? owner));
+  tx.setSenderIfNotSet(utils.normalizeSuiAddress(playerAddress));
   tx.setGasBudgetIfNotSet(gasBudget ?? DEFAULT_GAS_BUDGET_MIST);
   return tx;
 }
 function buildSharedStandardGameBetCall({
   config,
-  owner,
-  sender,
+  playerAddress,
   coinType,
   stake,
   cashStake,
@@ -437,7 +435,7 @@ function buildSharedStandardGameBetCall({
   buildRewardCoin
 }) {
   return (tx) => {
-    const normalizedOwner = utils.normalizeSuiAddress(sender ?? owner);
+    const normalizedPlayerAddress = utils.normalizeSuiAddress(playerAddress);
     const normalizedCoinType = utils.normalizeStructTag(coinType);
     const resolvedStake = toBigInt(stake);
     const resolvedCashStake = toBigInt(cashStake ?? stake);
@@ -455,7 +453,7 @@ function buildSharedStandardGameBetCall({
     const rewardCoin = buildRewardCoin({
       tx,
       config,
-      owner: normalizedOwner,
+      playerAddress: normalizedPlayerAddress,
       coinType: normalizedCoinType,
       stake: resolvedStake,
       cashStake: resolvedCashStake,
@@ -464,7 +462,7 @@ function buildSharedStandardGameBetCall({
       priceInfoObjectId,
       betCoin
     });
-    tx.transferObjects([rewardCoin], tx.pure.address(normalizedOwner));
+    tx.transferObjects([rewardCoin], tx.pure.address(normalizedPlayerAddress));
     return rewardCoin;
   };
 }
@@ -1019,39 +1017,53 @@ var SuigarClient = class {
    * Lists unresolved PvP coinflip games from the configured registry and resolves
    * each entry into parsed onchain game state.
    *
-   * This fetches dynamic fields from the PvP coinflip registry object, then loads
-   * each referenced game object through `resolvePvPConflipGame()`. Registry
+   * This fetches dynamic fields from the PvP coinflip registry object, then bulk
+   * loads the referenced game objects through `client.core.getObjects()`. Registry
    * membership is the unresolved-state signal: when a game 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.
    *
    * @param options Optional dynamic field pagination forwarded to `listDynamicFields()`, excluding `parentId`.
-   * Pass `throwOnError: true` to fail the whole lookup when any referenced game
-   * cannot be resolved. By default, failed game resolutions are skipped and only
-   * successfully parsed unresolved games are returned.
+   * Supported options such as `limit`, `cursor`, and `signal` are forwarded to the
+   * underlying lookup calls. Pass `throwOnError: true` to fail the whole lookup
+   * when any referenced game object cannot be fetched or parsed. By default,
+   * failed per-object lookups are skipped and only successfully parsed unresolved
+   * games are returned.
    * @returns Parsed unresolved PvP coinflip game objects for the requested
-   * registry page. When `throwOnError` is `false`, entries that fail
-   * `resolvePvPConflipGame()` are omitted from the returned array.
+   * registry page. When `throwOnError` is `false`, entries that fail object fetch
+   * or parse are omitted from the returned array.
    */
   async getPvPCoinflipGames(options = {
     limit: 50
   }) {
     const { throwOnError = false, ...listOptions } = options;
     const { dynamicFields } = await this.#client.core.listDynamicFields({
-      parentId: this.#config.registryIds.pvpCoinflip,
-      ...listOptions
+      ...listOptions,
+      parentId: this.#config.registryIds.pvpCoinflip
+    });
+    const { objects } = await this.#client.core.getObjects({
+      objectIds: dynamicFields.map(({ childId }) => childId),
+      signal: listOptions.signal,
+      include: {
+        content: true
+      }
+    });
+    const resolvedGames = objects.map((object) => {
+      try {
+        return this.#resolvePvPCoinflipGameObject(object);
+      } catch (error) {
+        return error instanceof Error ? error : new Error(String(error));
+      }
     });
     if (throwOnError) {
-      return Promise.all(
-        dynamicFields.map(({ childId }) => this.resolvePvPConflipGame(childId))
-      );
+      const firstError = resolvedGames.find((game) => game instanceof Error);
+      if (firstError) {
+        throw firstError;
+      }
     }
-    const settledGames = await Promise.allSettled(
-      dynamicFields.map(({ childId }) => this.resolvePvPConflipGame(childId))
-    );
-    return settledGames.flatMap(
-      (result) => result.status === "fulfilled" ? [result.value] : []
+    return resolvedGames.flatMap(
+      (game) => game instanceof Error ? [] : [game]
     );
   }
   /**
@@ -1065,21 +1077,19 @@ var SuigarClient = class {
    * of a specific PvP coinflip match before rendering join, cancel, or result UI.
    *
    * @param gameId On-chain object id of the PvP coinflip game.
+   * @param options Optional `getObject()` options forwarded to the underlying
+   * client lookup, excluding `objectId` and `include`. Supported options include
+   * `signal`.
    * @returns Parsed PvP coinflip game state with a normalized `coinType`.
    * @throws Error If the object cannot be decoded because no content was returned.
    */
-  async resolvePvPConflipGame(gameId) {
+  async resolvePvPConflipGame(gameId, options = {}) {
     const { object } = await this.#client.core.getObject({
+      ...options,
       objectId: gameId,
       include: { content: true }
     });
-    if (!object.content) {
-      throw new Error("Unable to resolve PvP coinflip from game object");
-    }
-    return {
-      ...Game.parse(object.content),
-      coinType: utils.normalizeStructTag(utils.parseStructTag(object.type).typeParams[0])
-    };
+    return this.#resolvePvPCoinflipGameObject(object);
   }
   /**
    * BCS struct constructors for decoding on-chain objects and events related to Suigar games.
@@ -1209,6 +1219,20 @@ var SuigarClient = class {
       });
     };
   }
+  #resolvePvPCoinflipGameObject(object) {
+    if (object instanceof Error) {
+      throw object;
+    }
+    if (!object.content) {
+      throw new Error(
+        "Unable to resolve PvP coinflip game from retrieved object"
+      );
+    }
+    return {
+      ...Game.parse(object.content),
+      coinType: utils.normalizeStructTag(utils.parseStructTag(object.type).typeParams[0])
+    };
+  }
 };
 
 exports.SuigarClient = SuigarClient;

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { M as MoveStruct } from './index-jwSXA8q3.cjs';
 import * as _mysten_bcs from '@mysten/bcs';
 import { ClientWithCoreApi, SuiClientTypes } from '@mysten/sui/client';
 import { Transaction, BuildTransactionOptions } from '@mysten/sui/transactions';
-import { S as StandardGame, B as BuildCoinflipTransactionOptions, a as BuildWheelTransactionOptions, b as BuildLimboTransactionOptions, c as BuildPlinkoTransactionOptions, d as BuildRangeTransactionOptions, e as SuigarConfig, W as WithThrowOnError, P as PvPCoinflipAction, f as BuildPvPCoinflipTransactionOptions, g as SuigarExtensionOptions } from './games--Haw_z7M.cjs';
+import { S as StandardGame, B as BuildCoinflipTransactionOptions, a as BuildWheelTransactionOptions, b as BuildLimboTransactionOptions, c as BuildPlinkoTransactionOptions, d as BuildRangeTransactionOptions, e as SuigarConfig, W as WithThrowOnError, P as PvPCoinflipAction, f as BuildPvPCoinflipTransactionOptions, g as SuigarExtensionOptions } from './games-BccpPyWd.cjs';
 import '@mysten/sui/bcs';
 
 type WithoutConfig<T> = Omit<T, 'config'>;
@@ -44,20 +44,22 @@ declare class SuigarClient {
      * Lists unresolved PvP coinflip games from the configured registry and resolves
      * each entry into parsed onchain game state.
      *
-     * This fetches dynamic fields from the PvP coinflip registry object, then loads
-     * each referenced game object through `resolvePvPConflipGame()`. Registry
+     * This fetches dynamic fields from the PvP coinflip registry object, then bulk
+     * loads the referenced game objects through `client.core.getObjects()`. Registry
      * membership is the unresolved-state signal: when a game 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.
      *
      * @param options Optional dynamic field pagination forwarded to `listDynamicFields()`, excluding `parentId`.
-     * Pass `throwOnError: true` to fail the whole lookup when any referenced game
-     * cannot be resolved. By default, failed game resolutions are skipped and only
-     * successfully parsed unresolved games are returned.
+     * Supported options such as `limit`, `cursor`, and `signal` are forwarded to the
+     * underlying lookup calls. Pass `throwOnError: true` to fail the whole lookup
+     * when any referenced game object cannot be fetched or parsed. By default,
+     * failed per-object lookups are skipped and only successfully parsed unresolved
+     * games are returned.
      * @returns Parsed unresolved PvP coinflip game objects for the requested
-     * registry page. When `throwOnError` is `false`, entries that fail
-     * `resolvePvPConflipGame()` are omitted from the returned array.
+     * registry page. When `throwOnError` is `false`, entries that fail object fetch
+     * or parse are omitted from the returned array.
      */
     getPvPCoinflipGames(options?: WithThrowOnError<Omit<SuiClientTypes.ListDynamicFieldsOptions, 'parentId'>>): Promise<{
         coinType: string;
@@ -90,10 +92,13 @@ declare class SuigarClient {
      * of a specific PvP coinflip match before rendering join, cancel, or result UI.
      *
      * @param gameId On-chain object id of the PvP coinflip game.
+     * @param options Optional `getObject()` options forwarded to the underlying
+     * client lookup, excluding `objectId` and `include`. Supported options include
+     * `signal`.
      * @returns Parsed PvP coinflip game state with a normalized `coinType`.
      * @throws Error If the object cannot be decoded because no content was returned.
      */
-    resolvePvPConflipGame(gameId: string): Promise<{
+    resolvePvPConflipGame(gameId: string, options?: Omit<SuiClientTypes.GetObjectOptions, 'objectId' | 'include'>): Promise<{
         coinType: string;
         id: string;
         creator: string;

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { M as MoveStruct } from './index-jwSXA8q3.js';
 import * as _mysten_bcs from '@mysten/bcs';
 import { ClientWithCoreApi, SuiClientTypes } from '@mysten/sui/client';
 import { Transaction, BuildTransactionOptions } from '@mysten/sui/transactions';
-import { S as StandardGame, B as BuildCoinflipTransactionOptions, a as BuildWheelTransactionOptions, b as BuildLimboTransactionOptions, c as BuildPlinkoTransactionOptions, d as BuildRangeTransactionOptions, e as SuigarConfig, W as WithThrowOnError, P as PvPCoinflipAction, f as BuildPvPCoinflipTransactionOptions, g as SuigarExtensionOptions } from './games--Haw_z7M.js';
+import { S as StandardGame, B as BuildCoinflipTransactionOptions, a as BuildWheelTransactionOptions, b as BuildLimboTransactionOptions, c as BuildPlinkoTransactionOptions, d as BuildRangeTransactionOptions, e as SuigarConfig, W as WithThrowOnError, P as PvPCoinflipAction, f as BuildPvPCoinflipTransactionOptions, g as SuigarExtensionOptions } from './games-BccpPyWd.js';
 import '@mysten/sui/bcs';
 
 type WithoutConfig<T> = Omit<T, 'config'>;
@@ -44,20 +44,22 @@ declare class SuigarClient {
      * Lists unresolved PvP coinflip games from the configured registry and resolves
      * each entry into parsed onchain game state.
      *
-     * This fetches dynamic fields from the PvP coinflip registry object, then loads
-     * each referenced game object through `resolvePvPConflipGame()`. Registry
+     * This fetches dynamic fields from the PvP coinflip registry object, then bulk
+     * loads the referenced game objects through `client.core.getObjects()`. Registry
      * membership is the unresolved-state signal: when a game 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.
      *
      * @param options Optional dynamic field pagination forwarded to `listDynamicFields()`, excluding `parentId`.
-     * Pass `throwOnError: true` to fail the whole lookup when any referenced game
-     * cannot be resolved. By default, failed game resolutions are skipped and only
-     * successfully parsed unresolved games are returned.
+     * Supported options such as `limit`, `cursor`, and `signal` are forwarded to the
+     * underlying lookup calls. Pass `throwOnError: true` to fail the whole lookup
+     * when any referenced game object cannot be fetched or parsed. By default,
+     * failed per-object lookups are skipped and only successfully parsed unresolved
+     * games are returned.
      * @returns Parsed unresolved PvP coinflip game objects for the requested
-     * registry page. When `throwOnError` is `false`, entries that fail
-     * `resolvePvPConflipGame()` are omitted from the returned array.
+     * registry page. When `throwOnError` is `false`, entries that fail object fetch
+     * or parse are omitted from the returned array.
      */
     getPvPCoinflipGames(options?: WithThrowOnError<Omit<SuiClientTypes.ListDynamicFieldsOptions, 'parentId'>>): Promise<{
         coinType: string;
@@ -90,10 +92,13 @@ declare class SuigarClient {
      * of a specific PvP coinflip match before rendering join, cancel, or result UI.
      *
      * @param gameId On-chain object id of the PvP coinflip game.
+     * @param options Optional `getObject()` options forwarded to the underlying
+     * client lookup, excluding `objectId` and `include`. Supported options include
+     * `signal`.
      * @returns Parsed PvP coinflip game state with a normalized `coinType`.
      * @throws Error If the object cannot be decoded because no content was returned.
      */
-    resolvePvPConflipGame(gameId: string): Promise<{
+    resolvePvPConflipGame(gameId: string, options?: Omit<SuiClientTypes.GetObjectOptions, 'objectId' | 'include'>): Promise<{
         coinType: string;
         id: string;
         creator: string;

package/dist/index.js

@@ -225,20 +225,18 @@ function play(options) {
 function createBaseGameTransaction({
   config,
   game,
-  owner,
-  sender,
+  playerAddress,
   gasBudget
 }) {
   assertConfiguredBetGame(config, game);
   const tx = new Transaction();
-  tx.setSenderIfNotSet(normalizeSuiAddress(sender ?? owner));
+  tx.setSenderIfNotSet(normalizeSuiAddress(playerAddress));
   tx.setGasBudgetIfNotSet(gasBudget ?? DEFAULT_GAS_BUDGET_MIST);
   return tx;
 }
 function buildSharedStandardGameBetCall({
   config,
-  owner,
-  sender,
+  playerAddress,
   coinType,
   stake,
   cashStake,
@@ -249,7 +247,7 @@ function buildSharedStandardGameBetCall({
   buildRewardCoin
 }) {
   return (tx) => {
-    const normalizedOwner = normalizeSuiAddress(sender ?? owner);
+    const normalizedPlayerAddress = normalizeSuiAddress(playerAddress);
     const normalizedCoinType = normalizeStructTag(coinType);
     const resolvedStake = toBigInt(stake);
     const resolvedCashStake = toBigInt(cashStake ?? stake);
@@ -267,7 +265,7 @@ function buildSharedStandardGameBetCall({
     const rewardCoin = buildRewardCoin({
       tx,
       config,
-      owner: normalizedOwner,
+      playerAddress: normalizedPlayerAddress,
       coinType: normalizedCoinType,
       stake: resolvedStake,
       cashStake: resolvedCashStake,
@@ -276,7 +274,7 @@ function buildSharedStandardGameBetCall({
       priceInfoObjectId,
       betCoin
     });
-    tx.transferObjects([rewardCoin], tx.pure.address(normalizedOwner));
+    tx.transferObjects([rewardCoin], tx.pure.address(normalizedPlayerAddress));
     return rewardCoin;
   };
 }
@@ -831,39 +829,53 @@ var SuigarClient = class {
    * Lists unresolved PvP coinflip games from the configured registry and resolves
    * each entry into parsed onchain game state.
    *
-   * This fetches dynamic fields from the PvP coinflip registry object, then loads
-   * each referenced game object through `resolvePvPConflipGame()`. Registry
+   * This fetches dynamic fields from the PvP coinflip registry object, then bulk
+   * loads the referenced game objects through `client.core.getObjects()`. Registry
    * membership is the unresolved-state signal: when a game 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.
    *
    * @param options Optional dynamic field pagination forwarded to `listDynamicFields()`, excluding `parentId`.
-   * Pass `throwOnError: true` to fail the whole lookup when any referenced game
-   * cannot be resolved. By default, failed game resolutions are skipped and only
-   * successfully parsed unresolved games are returned.
+   * Supported options such as `limit`, `cursor`, and `signal` are forwarded to the
+   * underlying lookup calls. Pass `throwOnError: true` to fail the whole lookup
+   * when any referenced game object cannot be fetched or parsed. By default,
+   * failed per-object lookups are skipped and only successfully parsed unresolved
+   * games are returned.
    * @returns Parsed unresolved PvP coinflip game objects for the requested
-   * registry page. When `throwOnError` is `false`, entries that fail
-   * `resolvePvPConflipGame()` are omitted from the returned array.
+   * registry page. When `throwOnError` is `false`, entries that fail object fetch
+   * or parse are omitted from the returned array.
    */
   async getPvPCoinflipGames(options = {
     limit: 50
   }) {
     const { throwOnError = false, ...listOptions } = options;
     const { dynamicFields } = await this.#client.core.listDynamicFields({
-      parentId: this.#config.registryIds.pvpCoinflip,
-      ...listOptions
+      ...listOptions,
+      parentId: this.#config.registryIds.pvpCoinflip
+    });
+    const { objects } = await this.#client.core.getObjects({
+      objectIds: dynamicFields.map(({ childId }) => childId),
+      signal: listOptions.signal,
+      include: {
+        content: true
+      }
+    });
+    const resolvedGames = objects.map((object) => {
+      try {
+        return this.#resolvePvPCoinflipGameObject(object);
+      } catch (error) {
+        return error instanceof Error ? error : new Error(String(error));
+      }
     });
     if (throwOnError) {
-      return Promise.all(
-        dynamicFields.map(({ childId }) => this.resolvePvPConflipGame(childId))
-      );
+      const firstError = resolvedGames.find((game) => game instanceof Error);
+      if (firstError) {
+        throw firstError;
+      }
     }
-    const settledGames = await Promise.allSettled(
-      dynamicFields.map(({ childId }) => this.resolvePvPConflipGame(childId))
-    );
-    return settledGames.flatMap(
-      (result) => result.status === "fulfilled" ? [result.value] : []
+    return resolvedGames.flatMap(
+      (game) => game instanceof Error ? [] : [game]
     );
   }
   /**
@@ -877,21 +889,19 @@ var SuigarClient = class {
    * of a specific PvP coinflip match before rendering join, cancel, or result UI.
    *
    * @param gameId On-chain object id of the PvP coinflip game.
+   * @param options Optional `getObject()` options forwarded to the underlying
+   * client lookup, excluding `objectId` and `include`. Supported options include
+   * `signal`.
    * @returns Parsed PvP coinflip game state with a normalized `coinType`.
    * @throws Error If the object cannot be decoded because no content was returned.
    */
-  async resolvePvPConflipGame(gameId) {
+  async resolvePvPConflipGame(gameId, options = {}) {
     const { object } = await this.#client.core.getObject({
+      ...options,
       objectId: gameId,
       include: { content: true }
     });
-    if (!object.content) {
-      throw new Error("Unable to resolve PvP coinflip from game object");
-    }
-    return {
-      ...Game.parse(object.content),
-      coinType: normalizeStructTag(parseStructTag(object.type).typeParams[0])
-    };
+    return this.#resolvePvPCoinflipGameObject(object);
   }
   /**
    * BCS struct constructors for decoding on-chain objects and events related to Suigar games.
@@ -1021,6 +1031,20 @@ var SuigarClient = class {
       });
     };
   }
+  #resolvePvPCoinflipGameObject(object) {
+    if (object instanceof Error) {
+      throw object;
+    }
+    if (!object.content) {
+      throw new Error(
+        "Unable to resolve PvP coinflip game from retrieved object"
+      );
+    }
+    return {
+      ...Game.parse(object.content),
+      coinType: normalizeStructTag(parseStructTag(object.type).typeParams[0])
+    };
+  }
 };
 
 export { SuigarClient, suigar };

package/dist/utils.d.cts

@@ -61,7 +61,30 @@ declare const DEFAULT_RANGE_SCALE = 1000000;
 declare const RANGE_POINT_LIMIT: number;
 declare const DEFAULT_LIMBO_MULTIPLIER_SCALE = 100;
 
+/**
+ * Normalizes a numeric input into a non-negative `bigint`.
+ *
+ * This helper accepts the two number shapes the SDK commonly sees from app
+ * code: plain JavaScript numbers and already-normalized `bigint` values.
+ * Number inputs are truncated toward zero before conversion, so UI-friendly
+ * values like `5.9` become `5n`.
+ *
+ * @param value Value to coerce into a `bigint`.
+ * @returns The normalized non-negative `bigint`.
+ * @throws When `value` is not a finite number or bigint, or when it is negative.
+ */
 declare function toBigInt(value: unknown): bigint;
+/**
+ * Validates that a value can be safely used as a Move `u8`.
+ *
+ * Use this for config ids and other small integer fields that must stay inside
+ * the `0..255` range. Unlike `toBigInt`, this does not coerce fractional
+ * values: the input must already be an integer.
+ *
+ * @param value Value to validate.
+ * @returns The original number once it has been confirmed to be a valid `u8`.
+ * @throws When `value` is not a finite integer between `0` and `255`.
+ */
 declare function toU8(value: unknown): number;
 
 declare const Float: MoveStruct<{
@@ -75,6 +98,18 @@ declare const Float: MoveStruct<{
 type MoveFloat = ReturnType<(typeof Float)['parse']>;
 declare function fromMoveI64(i64: MoveFloat['exp']): number;
 declare function fromMoveFloat(float: MoveFloat): number;
+/**
+ * Decodes `BetResultEvent.game_details` into plain application values.
+ *
+ * Suigar stores game detail entries as `VecMap<string, vector<u8>>`, so raw BCS
+ * decoding leaves each value as bytes. This helper looks up the known schema for
+ * each key, parses the bytes into the expected runtime type, and preserves the
+ * original onchain keys in the returned object. Unknown keys fall back to
+ * string decoding so newer detail fields remain readable by default.
+ *
+ * @param gameDetails Raw `game_details` map from a decoded bet result event.
+ * @returns A plain object with the same keys and decoded string, number, or boolean values.
+ */
 declare function parseGameDetails(gameDetails: BetResultGameDetails): ParsedGameDetails;
 
 export { DEFAULT_GAS_BUDGET_MIST, DEFAULT_LIMBO_MULTIPLIER_SCALE, DEFAULT_RANGE_SCALE, RANGE_POINT_LIMIT, fromMoveFloat, fromMoveI64, parseGameDetails, toBigInt, toU8 };

package/dist/utils.d.ts

@@ -61,7 +61,30 @@ declare const DEFAULT_RANGE_SCALE = 1000000;
 declare const RANGE_POINT_LIMIT: number;
 declare const DEFAULT_LIMBO_MULTIPLIER_SCALE = 100;
 
+/**
+ * Normalizes a numeric input into a non-negative `bigint`.
+ *
+ * This helper accepts the two number shapes the SDK commonly sees from app
+ * code: plain JavaScript numbers and already-normalized `bigint` values.
+ * Number inputs are truncated toward zero before conversion, so UI-friendly
+ * values like `5.9` become `5n`.
+ *
+ * @param value Value to coerce into a `bigint`.
+ * @returns The normalized non-negative `bigint`.
+ * @throws When `value` is not a finite number or bigint, or when it is negative.
+ */
 declare function toBigInt(value: unknown): bigint;
+/**
+ * Validates that a value can be safely used as a Move `u8`.
+ *
+ * Use this for config ids and other small integer fields that must stay inside
+ * the `0..255` range. Unlike `toBigInt`, this does not coerce fractional
+ * values: the input must already be an integer.
+ *
+ * @param value Value to validate.
+ * @returns The original number once it has been confirmed to be a valid `u8`.
+ * @throws When `value` is not a finite integer between `0` and `255`.
+ */
 declare function toU8(value: unknown): number;
 
 declare const Float: MoveStruct<{
@@ -75,6 +98,18 @@ declare const Float: MoveStruct<{
 type MoveFloat = ReturnType<(typeof Float)['parse']>;
 declare function fromMoveI64(i64: MoveFloat['exp']): number;
 declare function fromMoveFloat(float: MoveFloat): number;
+/**
+ * Decodes `BetResultEvent.game_details` into plain application values.
+ *
+ * Suigar stores game detail entries as `VecMap<string, vector<u8>>`, so raw BCS
+ * decoding leaves each value as bytes. This helper looks up the known schema for
+ * each key, parses the bytes into the expected runtime type, and preserves the
+ * original onchain keys in the returned object. Unknown keys fall back to
+ * string decoding so newer detail fields remain readable by default.
+ *
+ * @param gameDetails Raw `game_details` map from a decoded bet result event.
+ * @returns A plain object with the same keys and decoded string, number, or boolean values.
+ */
 declare function parseGameDetails(gameDetails: BetResultGameDetails): ParsedGameDetails;
 
 export { DEFAULT_GAS_BUDGET_MIST, DEFAULT_LIMBO_MULTIPLIER_SCALE, DEFAULT_RANGE_SCALE, RANGE_POINT_LIMIT, fromMoveFloat, fromMoveI64, parseGameDetails, toBigInt, toU8 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@suigar/sdk",
-	"version": "2.0.0-beta.7",
+	"version": "2.0.0-beta.8",
 	"description": "TypeScript SDK for Suigar v2 Move contracts on Sui.",
 	"keywords": [
 		"suigar",