@suigar/sdk 2.0.0-beta.3 → 2.0.0-beta.5

package/CHANGELOG.md

@@ -1,17 +1,53 @@
 # @suigar/sdk
 
+## 2.0.0-beta.5
+
+### Patch Changes
+
+- bf98e0a: Update PvP coinflip registry lookups so `getPvPCoinflipGames()` can skip
+  individual game resolution failures by default while still supporting
+  `rejectOnError: true` for strict rejection.
+  - Document the `rejectOnError` behavior in the public JSDoc and README examples.
+  - Clarify repo guidance and skill documentation to distinguish general PvP game
+    guidance from the current PvP coinflip-specific runtime surface.
+
+## 2.0.0-beta.4
+
+### Patch Changes
+
+- 6daa819: Add BCS parser helpers and a Next.js game integration example app.
+  - expose parser helpers through `@suigar/sdk/utils`
+  - add `parseGameDetails` for decoding `BetResultEvent.game_details`
+  - document generated BCS event decoding and game detail parsing guidance
+  - add a testnet-only `examples/game-integration` app for standard and PvP Suigar transactions
+  - integrate Mysten dApp Kit wallet connection, signing, and execution
+  - add live transaction code previews and shared decoded event logging with SDK parser helpers
+  - add Suigar-themed responsive UI, supported coin selection, and human-readable stake handling
+  - update PvP coinflip join so callers only provide `gameId` and the SDK derives the join stake while using the configured price info object id
+
+- b89d0b4: Add a public `@suigar/sdk/games` export subpath for shared game option types, and export `SuigarClient` from the package root.
+- bf1f71b: Add `registryIds` to `SuigarConfig` and resolve it from the network config registry map.
+
+  Document the PvP coinflip runtime helpers more clearly by describing
+  registry-backed unresolved game discovery through `getPvPCoinflipGames()` and
+  the normalized live-game lookup behavior of `resolvePvPConflipGame()`.
+
+- 4861f55: Add public utility exports for shared scaling constants in `@suigar/sdk/utils`, including `RANGE_POINT_LIMIT` and `DEFAULT_RANGE_SCALE`. Update the SDK example app and documentation to use the exported constants and document limbo/range scaling behavior more clearly.
+
 ## 2.0.0-beta.3
 
 ### Patch Changes
 
-- e1cdedc: - Fix exported transaction option types so `BuildGameOptions` and `BuildPvPGameOptions` no longer require the internal `config` field
+- e1cdedc: Improve public transaction builder typings and refresh Sui 2.0+ integration guidance around the gRPC client.
+  - Fix exported transaction option types so `BuildGameOptions` and `BuildPvPGameOptions` no longer require the internal `config` field
   - Update installation and integration documentation for Sui 2.0+ by switching examples to `SuiGrpcClient`, clarifying required peer dependencies, and aligning transaction-result examples with the current client API.
 
 ## 2.0.0-beta.2
 
 ### Patch Changes
 
-- 128cb6c: - `suigar()` now only accepts the extension `name`.
+- 128cb6c: Make SDK configuration network-resolved and expose runtime config inspection through the client extension.
+  - `suigar()` now only accepts the extension `name`.
   - The SDK now validates the connected client network and supports `mainnet` and `testnet`.
   - Added `client.suigar.getConfig()` to inspect the resolved network config at runtime.
   - Exported the `SuiNetwork` type and `resolveGamePackageId()` helper.

package/README.md

@@ -19,14 +19,53 @@ This SDK targets Sui TypeScript SDK 2.0+ only. Follow the official [Sui 2.0 migr
 
 ## 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,
+	RANGE_POINT_LIMIT,
+	parseFloat,
+	parseGameDetails,
+	parseI64,
+	toBigIntAmount,
+	toU8Number,
+} from '@suigar/sdk/utils';
+```
+
+Game-specific type exports are available from the dedicated `games` subpath:
+
+```ts
+import type {
+	BuildCoinflipTransactionOptions,
+	CoinSide,
+} from '@suigar/sdk/games';
+import type {
+	BuildCreatePvPCoinflipTransactionOptions,
+	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:
 
@@ -35,6 +74,8 @@ const client = new SuiGrpcClient({ baseUrl, network }).$extend(suigar());
 
 client.suigar.serializeTransactionToBase64(...);
 client.suigar.getConfig();
+client.suigar.getPvPCoinflipGames(...);
+client.suigar.resolvePvPConflipGame(...);
 client.suigar.bcs;
 client.suigar.tx;
 ```
@@ -66,12 +107,24 @@ 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 append that wallet address to supported
+> bet metadata automatically.
+
 ```ts
-const client = new SuiGrpcClient({ baseUrl, network }).$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
@@ -96,13 +149,21 @@ client.games.bcs;
 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 three main areas:
+The registered extension instance exposes the main runtime surface:
 
 - `getConfig()`
 - `serializeTransactionToBase64(transaction, options?)`
+- `getPvPCoinflipGames(options?)`
+- `resolvePvPConflipGame(gameId)`
 - `bcs`
 - `tx`
 
@@ -116,6 +177,7 @@ resolved package ids or supported coin mappings for the active client network.
 It includes:
 
 - `packageIds`
+- `registryIds`
 - `coinTypes`
 - `priceInfoObjectIds`
 
@@ -134,6 +196,69 @@ 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 `resolvePvPConflipGame()`. 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
+already-deleted registry entry does not reject the full lookup. Pass
+`rejectOnError: true` if you want the call to reject instead.
+
+```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,
+	rejectOnError: true,
+});
+```
+
+### `resolvePvPConflipGame(gameId)`
+
+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.
+
+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
+and privacy flag for a game.
+
+```ts
+const game = await client.suigar.resolvePvPConflipGame('0xGAME_ID');
+
+console.log(game.creator);
+console.log(game.coinType);
+console.log(game.stake_per_player);
+console.log(game.is_private);
+```
+
+> [!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
+
+> [!TIP]
+> Prefer this helper over manual object parsing when you only need the parsed state for a live PvP coinflip game object.
+
 ## `tx`
 
 Transaction builders live under `client.suigar.tx`.
@@ -176,6 +301,8 @@ Shared behavior:
 - `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`
 
@@ -201,17 +328,25 @@ const rangeTx = client.suigar.tx.createBetTransaction('range', {
 	owner: '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,8 +375,6 @@ const tx = client.suigar.tx.createPvPCoinflipTransaction('join', {
 	owner: '0x123',
 	coinType: '0x2::sui::SUI',
 	gameId: '0xGAME_ID',
-	extraObjectId: '0xEXTRA_OBJECT_ID',
-	stake: 1_000_000_000n,
 });
 ```
 
@@ -255,11 +388,14 @@ const tx = client.suigar.tx.createPvPCoinflipTransaction('cancel', {
 });
 ```
 
+Join derives the stake from `gameId` and uses the configured price info object
+id for `coinType`.
+
 PvP shared options:
 
 - `owner: string`
 - `coinType: string`
-- `metadata?: ...`
+- `metadata?: Record<string, string | number | boolean | bigint | Uint8Array | number[] | null | undefined>`
 - `gasBudget?: number | bigint`
 - `sender?: string`
 - `allowGasCoinShortcut?: boolean`
@@ -267,7 +403,7 @@ PvP shared options:
 Action-specific options:
 
 - `create`: `stake`, `side`, `isPrivate?`
-- `join`: `gameId`, `extraObjectId`, `stake`
+- `join`: `gameId`
 - `cancel`: `gameId`
 
 ## `bcs`
@@ -276,12 +412,41 @@ BCS helpers live under `client.suigar.bcs`.
 
 Current exposed helpers:
 
+- `PvPCoinflipGame`
 - `BetResultEvent`
 - `PvPCoinflipGameCreated`
 - `PvPCoinflipGameResolved`
 - `PvPCoinflipGameCancelled`
 
-These are generated Move event decoders. Use them to parse Suigar event payloads from transaction results.
+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
+- `parseGameDetails(game_details)` decodes `BetResultEvent.game_details` entries into the expected string, number, and boolean values
+
+### Parse PvP Coinflip Game Object Data
+
+Use the BCS helper directly when you already fetched the object with `content`:
+
+```ts
+const { object } = await client.core.getObject({
+	objectId: '0xGAME_ID',
+	include: { content: true },
+});
+
+if (!object.content) {
+	throw new Error('Missing game content');
+}
+
+const parsed = client.suigar.bcs.PvPCoinflipGame.parse(object.content);
+```
+
+If you only need the parsed game object, prefer the convenience method:
+
+```ts
+const parsed = await client.suigar.resolvePvPConflipGame('0xGAME_ID');
+```
 
 ### Parse Standard Bet Result Data
 
@@ -333,27 +498,32 @@ 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.
 
-- 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
-- `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
+> [!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
+
+> [!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
 
@@ -370,3 +540,24 @@ npm run build
 npm run typecheck
 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).
+
+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
+- 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
+- decoding `BetResultEvent` and PvP events into a persistent event log
+- parsing `BetResultEvent.game_details` with `parseGameDetails`
+
+Run it from the repo root with:
+
+```bash
+npm --prefix examples/game-integration install
+npm --prefix examples/game-integration run dev
+```