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

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,42 +11,33 @@ npm install @suigar/sdk
 Runtime requirements:
 
 - Node.js `>=22`
+- `@mysten/sui`
+
+## What This Package Exposes
 
-## Public API
+The package root currently exposes the extension factory:
 
 ```ts
 import { suigar } from '@suigar/sdk';
 ```
 
-### `suigar(options?)`
+It does not export the individual transaction builders from the package root.
+It also does not export `SuigarClient` as a public root symbol.
 
-Creates a named Sui client extension. By default, it registers under `client.suigar`.
+What you actually use at runtime is the registered extension instance:
 
 ```ts
 const client = new SuiClient({ url }).$extend(suigar());
-client.suigar;
-```
-
-You can rename the extension:
-
-```ts
-const client = new SuiClient({ url }).$extend(suigar({ name: 'casino' }));
 
-client.casino;
+client.suigar.serializeTransactionToBase64(...);
+client.suigar.bcs;
+client.suigar.tx;
 ```
 
-### `SuigarClient`
-
-The registered extension instance exposes:
-
-- `serializeTransactionToBase64(transaction)`
-- `bcs.BetResultEvent`
-- `tx.createBetTransaction(gameId, options)`
-
-## Quick start
+## Quick Start
 
 ```ts
-import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
+import { getFullnodeUrl, SuiClient } from '@mysten/sui/client';
 import { suigar } from '@suigar/sdk';
 
 const client = new SuiClient({
@@ -77,9 +61,101 @@ const tx = client.suigar.tx.createBetTransaction('coinflip', {
 const base64 = await client.suigar.serializeTransactionToBase64(tx);
 ```
 
-## Game transactions
+## 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;
+```
+
+You can rename the extension:
+
+```ts
+const client = new SuiClient({ url }).$extend(suigar({ name: 'casino' }));
+
+client.casino.tx;
+client.casino.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
+
+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:
+
+```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',
+		},
+	}),
+);
+```
+
+## Runtime Surface
+
+The registered extension instance exposes three main areas:
+
+- `serializeTransactionToBase64(transaction, options?)`
+- `bcs`
+- `tx`
+
+### `serializeTransactionToBase64(transaction, options?)`
+
+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);
+```
+
+## `tx`
+
+Transaction builders live under `client.suigar.tx`.
+
+### Standard Games
 
-`tx.createBetTransaction(gameId, options)` supports these game ids:
+Use `createBetTransaction(gameId, options)` for:
 
 - `coinflip`
 - `limbo`
@@ -87,7 +163,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,159 +186,119 @@ 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 Pyth price info object from the configured 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:
 
-The client extension also exposes a generated MoveStruct helper for Suigar bet result data:
+- `owner: string`
+- `coinType: string`
+- `metadata?: ...`
+- `gasBudget?: number | bigint`
+- `sender?: string`
+- `allowGasCoinShortcut?: boolean`
 
-- `client.suigar.bcs.BetResultEvent`
+Action-specific options:
 
-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.
+- `create`: `stake`, `side`, `isPrivate?`
+- `join`: `gameId`, `extraObjectId`, `stake`
+- `cancel`: `gameId`
 
-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`
 
-### Parse onchain object content
+BCS helpers live under `client.suigar.bcs`.
 
-```ts
-async function readBetResult(client: ClientWithCoreApi, id: string) {
-	const { object } = await client.core.getObject({
-		objectId: id,
-		include: {
-			content: true,
-		},
-	});
+Current exposed helpers:
 
-	const parsed = client.suigar.bcs.BetResultEvent.parse(object.content);
+- `BetResultEvent`
+- `PvPCoinflipGameCreated`
+- `PvPCoinflipGameResolved`
+- `PvPCoinflipGameCancelled`
 
-	console.log(parsed.player);
-	console.log(parsed.coin_type.name);
-	console.log(parsed.stake_amount);
-	console.log(parsed.outcome_amount);
+These are generated Move struct/event decoders. Use them to parse Suigar event payloads and structured onchain content.
 
-	return parsed;
-}
-```
-
-### Using the generated helper directly
-
-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({
@@ -277,12 +322,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 +335,18 @@ const metadata = new Map(
 );
 ```
 
-## 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
+Important:
 
-Supported override areas:
+- use `content`, not `objectBcs`, with these generated parsers
+- the generated parser expects the struct payload, not a full object envelope
 
-- `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]`
+### Parse PvP Coinflip Event Data
 
-Example:
+Use the matching helper for the PvP coinflip event payload you fetched from chain:
 
-```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
 

package/dist/index.cjs

@@ -853,8 +853,6 @@ function BetResultEvent(...typeParameters) {
     metadata: VecMap(bcs.bcs.string(), bcs.bcs.vector(bcs.bcs.u8()))
   } });
 }
-
-// src/client.ts
 function suigar({
   name = "suigar",
   ...options
@@ -877,14 +875,19 @@ var SuigarClient = class {
     this.#config = resolveSuigarConfig(options);
   }
   /**
-   * Builds a transaction with the configured Sui client and returns the BCS bytes as a base64 string.
+   * Builds a transaction with the configured Sui client and encodes the resulting BCS bytes as base64.
+   *
+   * Use this when an external wallet, API, or transport expects the built transaction payload as a base64 string
+   * instead of raw bytes. The SDK always injects the configured Sui client, so `options` accepts the standard
+   * transaction build options except for `client`.
    *
-   * @param transaction Transaction block to serialize.
+   * @param transaction Transaction to build and serialize.
+   * @param options Optional transaction build options forwarded to `transaction.build()`, excluding `client`.
    * @returns Base64-encoded transaction bytes ready to send over the wire.
    */
-  async serializeTransactionToBase64(transaction) {
-    const bytes = await transaction.build({ client: this.#client });
-    return Buffer.from(bytes).toString("base64");
+  async serializeTransactionToBase64(transaction, options) {
+    const bytes = await transaction.build({ ...options, client: this.#client });
+    return utils.toBase64(bytes);
   }
   /**
    * BCS struct constructors for decoding Suigar events emitted on-chain.
@@ -965,5 +968,4 @@ var SuigarClient = class {
   };
 };
 
-exports.SuigarClient = SuigarClient;
 exports.suigar = suigar;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { SuiClientTypes, ClientWithCoreApi } from '@mysten/sui/client';
-import { Transaction } from '@mysten/sui/transactions';
+import { Transaction, BuildTransactionOptions } from '@mysten/sui/transactions';
 import { BcsType, BcsStruct } from '@mysten/sui/bcs';
 
 type BetMetadataPrimitive = string | number | boolean | bigint;
@@ -227,12 +227,17 @@ declare class SuigarClient {
         options: SuigarOptions;
     });
     /**
-     * Builds a transaction with the configured Sui client and returns the BCS bytes as a base64 string.
+     * Builds a transaction with the configured Sui client and encodes the resulting BCS bytes as base64.
      *
-     * @param transaction Transaction block to serialize.
+     * Use this when an external wallet, API, or transport expects the built transaction payload as a base64 string
+     * instead of raw bytes. The SDK always injects the configured Sui client, so `options` accepts the standard
+     * transaction build options except for `client`.
+     *
+     * @param transaction Transaction to build and serialize.
+     * @param options Optional transaction build options forwarded to `transaction.build()`, excluding `client`.
      * @returns Base64-encoded transaction bytes ready to send over the wire.
      */
-    serializeTransactionToBase64(transaction: Transaction): Promise<string>;
+    serializeTransactionToBase64(transaction: Transaction, options?: Omit<BuildTransactionOptions, 'client'>): Promise<string>;
     /**
      * BCS struct constructors for decoding Suigar events emitted on-chain.
      */
@@ -277,4 +282,4 @@ declare class SuigarClient {
     };
 }
 
-export { SuigarClient, suigar };
+export { suigar };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { SuiClientTypes, ClientWithCoreApi } from '@mysten/sui/client';
-import { Transaction } from '@mysten/sui/transactions';
+import { Transaction, BuildTransactionOptions } from '@mysten/sui/transactions';
 import { BcsType, BcsStruct } from '@mysten/sui/bcs';
 
 type BetMetadataPrimitive = string | number | boolean | bigint;
@@ -227,12 +227,17 @@ declare class SuigarClient {
         options: SuigarOptions;
     });
     /**
-     * Builds a transaction with the configured Sui client and returns the BCS bytes as a base64 string.
+     * Builds a transaction with the configured Sui client and encodes the resulting BCS bytes as base64.
      *
-     * @param transaction Transaction block to serialize.
+     * Use this when an external wallet, API, or transport expects the built transaction payload as a base64 string
+     * instead of raw bytes. The SDK always injects the configured Sui client, so `options` accepts the standard
+     * transaction build options except for `client`.
+     *
+     * @param transaction Transaction to build and serialize.
+     * @param options Optional transaction build options forwarded to `transaction.build()`, excluding `client`.
      * @returns Base64-encoded transaction bytes ready to send over the wire.
      */
-    serializeTransactionToBase64(transaction: Transaction): Promise<string>;
+    serializeTransactionToBase64(transaction: Transaction, options?: Omit<BuildTransactionOptions, 'client'>): Promise<string>;
     /**
      * BCS struct constructors for decoding Suigar events emitted on-chain.
      */
@@ -277,4 +282,4 @@ declare class SuigarClient {
     };
 }
 
-export { SuigarClient, suigar };
+export { suigar };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { normalizeSuiAddress, normalizeStructTag, SUI_TYPE_ARG } from '@mysten/sui/utils';
+import { normalizeSuiAddress, toBase64, normalizeStructTag, SUI_TYPE_ARG } from '@mysten/sui/utils';
 import { bcs, BcsStruct, TypeTagSerializer } from '@mysten/sui/bcs';
 import { Transaction, isArgument } from '@mysten/sui/transactions';
 
@@ -851,8 +851,6 @@ function BetResultEvent(...typeParameters) {
     metadata: VecMap(bcs.string(), bcs.vector(bcs.u8()))
   } });
 }
-
-// src/client.ts
 function suigar({
   name = "suigar",
   ...options
@@ -875,14 +873,19 @@ var SuigarClient = class {
     this.#config = resolveSuigarConfig(options);
   }
   /**
-   * Builds a transaction with the configured Sui client and returns the BCS bytes as a base64 string.
+   * Builds a transaction with the configured Sui client and encodes the resulting BCS bytes as base64.
+   *
+   * Use this when an external wallet, API, or transport expects the built transaction payload as a base64 string
+   * instead of raw bytes. The SDK always injects the configured Sui client, so `options` accepts the standard
+   * transaction build options except for `client`.
    *
-   * @param transaction Transaction block to serialize.
+   * @param transaction Transaction to build and serialize.
+   * @param options Optional transaction build options forwarded to `transaction.build()`, excluding `client`.
    * @returns Base64-encoded transaction bytes ready to send over the wire.
    */
-  async serializeTransactionToBase64(transaction) {
-    const bytes = await transaction.build({ client: this.#client });
-    return Buffer.from(bytes).toString("base64");
+  async serializeTransactionToBase64(transaction, options) {
+    const bytes = await transaction.build({ ...options, client: this.#client });
+    return toBase64(bytes);
   }
   /**
    * BCS struct constructors for decoding Suigar events emitted on-chain.
@@ -963,4 +966,4 @@ var SuigarClient = class {
   };
 };
 
-export { SuigarClient, suigar };
+export { suigar };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@suigar/sdk",
-	"version": "2.0.0-beta.0",
+	"version": "2.0.0-beta.1",
 	"description": "TypeScript SDK for Suigar v2 Move contracts on Sui.",
 	"license": "Apache-2.0",
 	"type": "module",