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

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @suigar/sdk
 
+## 2.0.0-beta.2
+
+### Patch Changes
+
+- 128cb6c: - `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.
+  - Reworked `SuigarConfig` into a network-resolved structure with `packageIds`, `coinTypes`, and `priceInfoObjectIds`.
+  - Replaced the old Pyth-specific price object resolution flow with supported-coin-based `priceInfoObjectId` resolution.
+  - Split package and coin configuration into explicit `mainnet` and `testnet` maps and updated transaction builders to use the new structure.
+  - Updated generated event helpers, tests, and documentation to match the new configuration and event parsing flow.
+
+  Notes:
+  - Existing prerelease integrations using `suigar({ ...configOverrides })` will need to migrate to `suigar()`.
+  - Runtime config inspection should now use `client.suigar.getConfig()`.
+
+## 2.0.0-beta.1
+
+### Patch Changes
+
+- Updated the npm release workflows to install dependencies without a committed lockfile and removed the obsolete Node.js cache configuration.
+- Simplified previous-release deprecation logic so prerelease publishes do not attempt to deprecate earlier npm versions.
+- Stopped tracking `package-lock.json` and removed the obsolete changeset file after the version bump.
+
 ## 2.0.0-beta.0
 
 ### Major Changes

package/README.md

@@ -2,13 +2,6 @@
 
 TypeScript SDK for building Suigar v2 game transactions on Sui.
 
-The published package entrypoint currently exposes:
-
-- `suigar`
-- `SuigarClient`
-
-It does not currently export the individual game builder functions from the package root.
-
 ## Installation
 
 ```bash
@@ -18,19 +11,59 @@ npm install @suigar/sdk
 Runtime requirements:
 
 - Node.js `>=22`
+- `@mysten/sui`
+
+## What This Package Exposes
+
+The package root currently exposes the extension factory:
+
+```ts
+import { suigar } 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.
+
+What you actually use at runtime is the registered extension instance:
+
+```ts
+const client = new SuiClient({ url }).$extend(suigar());
+
+client.suigar.serializeTransactionToBase64(...);
+client.suigar.getConfig();
+client.suigar.bcs;
+client.suigar.tx;
+```
 
-## Public API
+## Quick Start
 
 ```ts
+import { getFullnodeUrl, SuiClient } from '@mysten/sui/client';
 import { suigar } from '@suigar/sdk';
+
+const client = new SuiClient({
+	url: getFullnodeUrl('testnet'),
+}).$extend(suigar());
+
+const tx = client.suigar.tx.createBetTransaction('coinflip', {
+	owner: '0x123',
+	coinType: '0x2::sui::SUI',
+	stake: 1_000_000_000n,
+	side: 'heads',
+});
+
+const base64 = await client.suigar.serializeTransactionToBase64(tx);
 ```
 
+## Extension Registration
+
 ### `suigar(options?)`
 
 Creates a named Sui client extension. By default, it registers under `client.suigar`.
 
 ```ts
 const client = new SuiClient({ url }).$extend(suigar());
+
 client.suigar;
 ```
 
@@ -39,47 +72,68 @@ You can rename the extension:
 ```ts
 const client = new SuiClient({ url }).$extend(suigar({ name: 'casino' }));
 
-client.casino;
+client.casino.tx;
+client.casino.bcs;
 ```
 
-### `SuigarClient`
+## Config
 
-The registered extension instance exposes:
+`suigar(options?)` resolves config from:
 
-- `serializeTransactionToBase64(transaction)`
-- `bcs.BetResultEvent`
-- `tx.createBetTransaction(gameId, options)`
+- internal package ids by network
+- internal supported coin types by network
+- internal price info object ids by network
+- the connected Sui client network
+- the extension name
 
-## Quick start
+Supported override areas:
+
+- `name`
+
+## Runtime Surface
+
+The registered extension instance exposes three main areas:
+
+- `getConfig()`
+- `serializeTransactionToBase64(transaction, 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`
+- `coinTypes`
+- `priceInfoObjectIds`
 
 ```ts
-import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
-import { suigar } from '@suigar/sdk';
+const config = client.suigar.getConfig();
+console.log(config.packageIds);
+```
 
-const client = new SuiClient({
-	url: getFullnodeUrl('testnet'),
-}).$extend(
-	suigar({
-		pyth: {
-			suiPriceInfoObjectId: '0xPYTH_SUI_PRICE_INFO',
-			usdcPriceInfoObjectId: '0xPYTH_USDC_PRICE_INFO',
-		},
-	}),
-);
+### `serializeTransactionToBase64(transaction, options?)`
 
-const tx = client.suigar.tx.createBetTransaction('coinflip', {
-	owner: '0x123',
-	coinType: '0x2::sui::SUI',
-	stake: 1_000_000_000n,
-	side: 'heads',
-});
+Builds a transaction with the configured Sui client and returns base64-encoded transaction bytes.
 
+Use this when you need a transport-safe payload for a wallet, API, or external signer.
+
+```ts
 const base64 = await client.suigar.serializeTransactionToBase64(tx);
 ```
 
-## Game transactions
+## `tx`
 
-`tx.createBetTransaction(gameId, options)` supports these game ids:
+Transaction builders live under `client.suigar.tx`.
+
+### Standard Games
+
+Use `createBetTransaction(gameId, options)` for:
 
 - `coinflip`
 - `limbo`
@@ -87,7 +141,16 @@ const base64 = await client.suigar.serializeTransactionToBase64(tx);
 - `range`
 - `wheel`
 
-All games share this base option shape:
+```ts
+const tx = client.suigar.tx.createBetTransaction('coinflip', {
+	owner: '0x123',
+	coinType: '0x2::sui::SUI',
+	stake: 1_000_000_000n,
+	side: 'tails',
+});
+```
+
+Shared option shape:
 
 - `owner: string`
 - `coinType: string`
@@ -101,169 +164,156 @@ All games share this base option shape:
 
 Shared behavior:
 
-- `stake` is the logical game stake passed into the Move call
-- `cashStake` is the actual coin balance withdrawn into the bet coin and defaults to `stake`
+- `stake` is the logical stake passed into the Move call
+- `cashStake` controls the withdrawn balance and defaults to `stake`
 - `betCount` defaults to `1`
 - `sender` overrides the transaction sender
 - `metadata` is encoded into `keys` and `values` byte arrays
-- the SDK resolves the Pyth price object from the configured coin mapping
-- the built reward object is transferred back to the owner
+- the SDK resolves the price info object from the configured supported-coin mapping
+- the reward object is transferred back to `owner`
 
-### Coinflip
+Per-game options:
 
-Additional options:
+- `coinflip`: `side: 'heads' | 'tails'`
+- `limbo`: `targetMultiplier: number`, `scale?: number`
+- `plinko`: `configId: number`
+- `range`: `leftPoint: number`, `rightPoint: number`, `outOfRange?: boolean`, `scale?: number`
+- `wheel`: `configId: number`
 
-- `side: 'heads' | 'tails'`
-
-Example:
+Examples:
 
 ```ts
-const tx = client.suigar.tx.createBetTransaction('coinflip', {
+const limboTx = client.suigar.tx.createBetTransaction('limbo', {
 	owner: '0x123',
 	coinType: '0x2::sui::SUI',
 	stake: 1_000_000_000n,
-	side: 'tails',
+	targetMultiplier: 2.5,
 });
-```
-
-### Limbo
-
-Additional options:
-
-- `targetMultiplier: number`
-- `scale?: number`
 
-Behavior:
-
-- `scale` defaults to the SDK limbo multiplier scale
-- `targetMultiplier` is converted with `Math.round(targetMultiplier * scale)`
-
-Example:
-
-```ts
-const tx = client.suigar.tx.createBetTransaction('limbo', {
+const rangeTx = client.suigar.tx.createBetTransaction('range', {
 	owner: '0x123',
 	coinType: '0x2::sui::SUI',
 	stake: 1_000_000_000n,
-	targetMultiplier: 2.5,
+	leftPoint: 0.95,
+	rightPoint: 1.05,
+	outOfRange: false,
 });
 ```
 
-### Plinko
+Notes:
 
-Additional options:
+- 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`
 
-- `configId: number`
+### PvP Coinflip
 
-Behavior:
+Use `createPvPCoinflipTransaction(action, options)` for PvP coinflip flows:
 
-- `configId` must fit in `u8`
+- `create`
+- `join`
+- `cancel`
 
-Example:
+Create:
 
 ```ts
-const tx = client.suigar.tx.createBetTransaction('plinko', {
+const tx = client.suigar.tx.createPvPCoinflipTransaction('create', {
 	owner: '0x123',
 	coinType: '0x2::sui::SUI',
 	stake: 1_000_000_000n,
-	configId: 3,
+	side: 'heads',
+	isPrivate: false,
 });
 ```
 
-### Range
-
-Additional options:
-
-- `leftPoint: number`
-- `rightPoint: number`
-- `outOfRange?: boolean`
-- `scale?: number`
-
-Behavior:
-
-- `scale` defaults to the SDK fixed-point range scale
-- `leftPoint` and `rightPoint` are converted with `Math.round(value * scale)`
-- `outOfRange` is coerced with `Boolean(...)`
-
-Example:
+Join:
 
 ```ts
-const tx = client.suigar.tx.createBetTransaction('range', {
+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,
-	leftPoint: 0.95,
-	rightPoint: 1.05,
-	outOfRange: false,
 });
 ```
 
-### Wheel
-
-Additional options:
-
-- `configId: number`
-
-Behavior:
-
-- `configId` must fit in `u8`
-
-Example:
+Cancel:
 
 ```ts
-const tx = client.suigar.tx.createBetTransaction('wheel', {
+const tx = client.suigar.tx.createPvPCoinflipTransaction('cancel', {
 	owner: '0x123',
 	coinType: '0x2::sui::SUI',
-	stake: 1_000_000_000n,
-	configId: 1,
+	gameId: '0xGAME_ID',
 });
 ```
 
-## BCS helpers
+PvP shared options:
+
+- `owner: string`
+- `coinType: string`
+- `metadata?: ...`
+- `gasBudget?: number | bigint`
+- `sender?: string`
+- `allowGasCoinShortcut?: boolean`
 
-The client extension also exposes a generated MoveStruct helper for Suigar bet result data:
+Action-specific options:
 
-- `client.suigar.bcs.BetResultEvent`
+- `create`: `stake`, `side`, `isPrivate?`
+- `join`: `gameId`, `extraObjectId`, `stake`
+- `cancel`: `gameId`
 
-Use generated BCS types to parse onchain object data. Fetch the object with `include: { content: true }` and pass `object.content` to the generated type's `.parse()` method.
+## `bcs`
 
-Always use `content`, not `objectBcs`, when parsing with generated types. The `objectBcs` field contains a full object envelope with additional metadata and is not the payload expected by the generated struct parser.
+BCS helpers live under `client.suigar.bcs`.
 
-### Parse onchain object content
+Current exposed helpers:
 
-```ts
-async function readBetResult(client: ClientWithCoreApi, id: string) {
-	const { object } = await client.core.getObject({
-		objectId: id,
-		include: {
-			content: true,
-		},
-	});
-
-	const parsed = client.suigar.bcs.BetResultEvent.parse(object.content);
-
-	console.log(parsed.player);
-	console.log(parsed.coin_type.name);
-	console.log(parsed.stake_amount);
-	console.log(parsed.outcome_amount);
-
-	return parsed;
-}
-```
+- `BetResultEvent`
+- `PvPCoinflipGameCreated`
+- `PvPCoinflipGameResolved`
+- `PvPCoinflipGameCancelled`
 
-### Using the generated helper directly
+These are generated Move event decoders. Use them to parse Suigar event payloads from transaction results.
 
-If you already have a content-bearing object response, parse `object.content` directly:
+### Parse Standard Bet Result Data
 
 ```ts
-const { object } = await client.core.getObject({
-	objectId: '0xOBJECT_ID',
+const executeResult = await client.core.executeTransaction({
+	transaction: transactionBytes,
+	signatures: [signature],
 	include: {
-		content: true,
+		events: true,
 	},
 });
 
-const decoded = client.suigar.bcs.BetResultEvent.parse(object.content);
+const finalResult = await client.core.waitForTransaction({
+	result: executeResult,
+	include: {
+		effects: true,
+		events: true,
+	},
+});
+
+if (finalResult.Transaction) {
+	console.log(finalResult.Transaction.digest);
+} else if (finalResult.FailedTransaction) {
+	throw new Error(finalResult.FailedTransaction.status.error.message);
+}
+
+const transactionResult =
+	finalResult.Transaction ?? finalResult.FailedTransaction;
+
+const betResults = [];
+
+for (const event of transactionResult.events ?? []) {
+	try {
+		const decoded = client.suigar.bcs.BetResultEvent.parse(event.bcs);
+		betResults.push(decoded);
+	} catch {
+		// Ignore non-BetResultEvent payloads.
+	}
+}
 ```
 
 Parsed fields include:
@@ -277,12 +327,9 @@ Parsed fields include:
 - `game_details`
 - `metadata`
 
-For `game_details` and `metadata`, the decoded value is a `VecMap<string, vector<u8>>`-shaped structure, so values come back as byte arrays.
-
-Example conversion to strings:
+`game_details` and `metadata` decode as `VecMap<string, vector<u8>>`-shaped data, so values come back as byte arrays.
 
 ```ts
-const decoded = client.suigar.bcs.BetResultEvent.parse(object.data.content);
 const textDecoder = new TextDecoder();
 
 const metadata = new Map(
@@ -293,54 +340,21 @@ const metadata = new Map(
 );
 ```
 
-## Config
+Important:
 
-`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
+- execute or wait for the transaction with `include: { events: true }`
+- parse emitted events from `result.Transaction.events` or `result.FailedTransaction.events`
+- 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
 
-Supported override areas:
+### Parse PvP Coinflip Event Data
 
-- `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:
+Use the matching helper for each PvP coinflip event payload found in `transactionResult.events`:
 
-```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',
-		},
-	}),
-);
-```
+- `client.suigar.bcs.PvPCoinflipGameCreated`
+- `client.suigar.bcs.PvPCoinflipGameResolved`
+- `client.suigar.bcs.PvPCoinflipGameCancelled`
 
 ## Development