@dimcool/sdk 0.1.24 → 0.1.27

package/README.md

@@ -935,16 +935,23 @@ The wallet module provides functionality for managing Solana wallets, checking b
 
 ### WalletSigner Interface
 
-The SDK exposes a `WalletSigner` interface for transaction and message signing:
+The SDK exposes a `WalletSigner` interface for transaction and message signing. A signer provides exactly one of `signTransaction` or `signAndSendTransaction`:
 
 ```typescript
 interface WalletSigner {
+  address?: string;
   signMessage: (message: string) => Promise<Uint8Array | string>;
-  signTransaction: (transaction: Transaction) => Promise<Transaction>;
+  signTransaction?: (transaction: Transaction) => Promise<Transaction>;
+  signAndSendTransaction?: (transaction: Transaction) => Promise<string>;
 }
 ```
 
-This allows the SDK to remain agnostic about how signing is implemented - you can use Phantom wallet for browser apps, or a Keypair for bot applications.
+**Two signing modes:**
+
+- **`signTransaction`** (server-sent) — the signer returns signed bytes; the server submits the transaction to the network. Used by `@dimcool/wallet` (keypair agents) and Phantom browser extensions.
+- **`signAndSendTransaction`** (client-sent) — the signer signs AND submits the transaction, returning the signature. The SDK then calls a `confirm-signature` endpoint so the backend can track and confirm it via the queue. Used by Phantom embedded wallets (Google/Apple login).
+
+The SDK detects the mode via `sdk.wallet.isSignAndSendMode()` and automatically routes `send()` and `depositForLobby()` through the correct path.
 
 If you're building agents, you can use `@dimcool/wallet` and pass `wallet.getSigner()` directly:
 
@@ -964,12 +971,9 @@ sdk.wallet.setSigner(wallet.getSigner());
 Configure the wallet signer. This must be called before any signing operations.
 
 ```typescript
-// Example: Using Phantom wallet (in apps/web)
-import { useSolana } from '@phantom/react-sdk';
-
-const { solana } = useSolana();
-
+// Example: Phantom extension (signTransaction — server submits)
 sdk.wallet.setSigner({
+  address: connectedAddress,
   signMessage: async (message: string) => {
     return solana.signMessage(new TextEncoder().encode(message));
   },
@@ -980,13 +984,28 @@ sdk.wallet.setSigner({
 ```
 
 ```typescript
-// Example: Using a Keypair (for bots/Node.js)
+// Example: Phantom embedded / Google/Apple (signAndSendTransaction — client submits)
+sdk.wallet.setSigner({
+  address: connectedAddress,
+  signMessage: async (message: string) => {
+    return solana.signMessage(new TextEncoder().encode(message));
+  },
+  signAndSendTransaction: async (transaction: Transaction) => {
+    const result = await solana.signAndSendTransaction(transaction);
+    return typeof result === 'string' ? result : result.signature;
+  },
+});
+```
+
+```typescript
+// Example: Using a Keypair (for bots/Node.js — signTransaction)
 import { Keypair } from '@solana/web3.js';
 import * as nacl from 'tweetnacl';
 
 const keypair = Keypair.fromSecretKey(/* ... */);
 
 sdk.wallet.setSigner({
+  address: keypair.publicKey.toBase58(),
   signMessage: async (message: string) => {
     const messageBytes = new TextEncoder().encode(message);
     return nacl.sign.detached(messageBytes, keypair.secretKey);
@@ -1080,40 +1099,37 @@ const signature = await sdk.wallet.signMessage('Hello, world!');
 
 ### `signTransaction(transaction: Transaction): Promise<Transaction>`
 
-Sign a Solana transaction using the configured signer.
+Sign a Solana transaction using the configured signer. Only available when the signer provides `signTransaction`.
 
 ```typescript
-import { Transaction } from '@solana/web3.js';
-
-const unsignedTransaction = Transaction.from(/* ... */);
 const signedTransaction = await sdk.wallet.signTransaction(unsignedTransaction);
 ```
 
-**Parameters:**
+**Throws** if the signer does not support `signTransaction` (i.e., it only has `signAndSendTransaction`).
 
-- `transaction: Transaction` - The unsigned Solana transaction to sign
+### `signAndSendTransaction(transaction: Transaction): Promise<string>`
 
-**Returns:**
+Sign and send a Solana transaction in one step. Only available when the signer provides `signAndSendTransaction`. Returns the transaction signature.
 
-- `Promise<Transaction>` - The signed transaction
+```typescript
+const signature = await sdk.wallet.signAndSendTransaction(unsignedTransaction);
+```
 
-**Example:**
+**Throws** if the signer does not support `signAndSendTransaction`.
 
-```typescript
-// Transaction should be prepared by the backend first
-const { unsignedTransaction } = await sdk.http.post(
-  '/transactions/prepare-deposit',
-  {
-    lobbyId: 'lobby-id',
-    amount: 100,
-  },
-);
+### `isSignAndSendMode(): boolean`
 
-const tx = Transaction.from(Buffer.from(unsignedTransaction, 'base64'));
-const signedTx = await sdk.wallet.signTransaction(tx);
+Check which signing mode the current signer uses.
+
+```typescript
+if (sdk.wallet.isSignAndSendMode()) {
+  // Client-sent path: signer signs AND sends
+} else {
+  // Server-sent path: signer returns signed bytes
+}
 ```
 
-**Note:** A signer must be configured first using `setSigner()`.
+**Note:** `send()` and `depositForLobby()` use this internally to route automatically.
 
 ### `send(recipient, amount, token?)`
 
@@ -1187,7 +1203,23 @@ Use these only when you explicitly need manual control of signing/submission.
 
 ## Escrow Module (`sdk.escrow`)
 
-The escrow module provides functionality for managing deposits, checking deposit status, and handling the escrow flow for game lobbies. This module works in conjunction with the wallet module to enable secure, blockchain-based deposits.
+The escrow module provides functionality for managing deposits, checking deposit status, and handling the escrow flow for game lobbies. It is constructed with `http` and `wallet` (the wallet is used for signing in `depositForLobby`). Use the wallet module to set a signer via `sdk.wallet.setSigner(...)` before calling `depositForLobby`.
+
+### One-call lobby deposit
+
+For the common case of depositing into a paid lobby in one step, use **`depositForLobby(lobbyId: string): Promise<DepositForLobbyResponse>`**. It starts deposits, prepares the transaction, signs with the configured wallet, submits, and polls until the current user's deposit is confirmed (or all deposits are confirmed for multi-player). Requires a signer to be set (`sdk.wallet.setSigner(...)`).
+
+```typescript
+const result = await sdk.escrow.depositForLobby(lobbyId);
+// result: { signature: string; status: string; canProceedToQueue: boolean }
+if (result.canProceedToQueue) {
+  await sdk.lobbies.joinQueue(lobbyId);
+}
+```
+
+**Response:** `{ signature, status, canProceedToQueue }`. When `canProceedToQueue` is true, call `sdk.lobbies.joinQueue(lobbyId)` to enter matchmaking.
+
+**Throws:** If no signer is configured: "No signer configured. Use sdk.wallet.setSigner(...) first."
 
 ### `startDeposits(lobbyId: string): Promise<void>`
 
@@ -1255,57 +1287,30 @@ const signedTx = await sdk.wallet.signTransaction(unsignedTx);
 
 **Note:** The transaction amount is automatically set to match the lobby's `betAmount`. The transaction is partially signed by the fee payer (server) and requires the user's signature.
 
-### `submitDepositAndJoinQueue(lobbyId: string, signedTransaction: string, lobbies: Lobbies): Promise<Lobby>`
+### `depositForLobbySync(lobbyId: string): Promise<DepositForLobbyResponse>`
 
-Submit a signed deposit transaction and automatically join the queue when the deposit is confirmed. This is a convenience method that combines deposit submission, confirmation waiting, and queue joining.
+Zero-polling deposit variant using server-side `awaitConfirmation`. Only 2 HTTP calls total with no client-side polling. Ideal for agents and bots.
 
 ```typescript
-const finalLobby = await sdk.escrow.submitDepositAndJoinQueue(
-  lobbyId,
-  signedTxBase64,
-  sdk.lobbies,
-);
+const result = await sdk.escrow.depositForLobbySync(lobbyId);
+// result: { signature: string, status: 'confirmed', canProceedToQueue: true }
 ```
 
 **Parameters:**
 
 - `lobbyId: string` - The lobby ID
-- `signedTransaction: string` - The signed transaction (base64 encoded)
-- `lobbies: Lobbies` - The lobbies service instance (from `sdk.lobbies`)
 
 **Returns:**
 
-- `Promise<Lobby>` - The lobby with updated status (will be 'queued' or 'active' if full)
+- `Promise<DepositForLobbyResponse>` - The deposit result with confirmed status
 
 **Behavior:**
 
-1. Submits the signed deposit transaction to the Solana network
-2. Polls deposit status until all deposits are confirmed (max 30 seconds)
-3. Automatically joins the matchmaking queue when deposits are confirmed
-4. Returns the updated lobby
-
-**Example:**
-
-```typescript
-// After signing the transaction from playAgain()
-const signedTxBase64 = signedTx.serialize().toString('base64');
-const finalLobby = await sdk.escrow.submitDepositAndJoinQueue(
-  lobby.id,
-  signedTxBase64,
-  sdk.lobbies,
-);
-
-// Lobby is now in queue or active if full
-console.log(`Lobby status: ${finalLobby.status}`);
-```
-
-**Error Handling:**
-
-- Throws an error if deposit confirmation times out (30 seconds)
-- Throws an error if deposit submission fails
-- Throws an error if queue joining fails
+1. Calls `prepareAndStartDeposit` to prepare the unsigned transaction (1 HTTP call)
+2. Signs the transaction locally and submits with `awaitConfirmation=true` (1 HTTP call)
+3. Server waits for on-chain confirmation before returning
 
-**Note:** This method is typically used after `playAgain()` to complete the "Play Again" flow in one call.
+**Note:** Requires `sdk.wallet.setSigner()` to be configured. The server auto-joins the matchmaking queue when all deposits are confirmed.
 
 ### `submitDeposit(lobbyId: string, signedTransaction: string): Promise<SubmitDepositResponse>`
 
@@ -1708,25 +1713,11 @@ const { lobby, unsignedTransaction } = await sdk.lobbies.playAgain(
   sdk.escrow,
 );
 
-// Decode and sign the transaction
-const binaryString = atob(unsignedTransaction);
-const bytes = new Uint8Array(binaryString.length);
-for (let i = 0; i < binaryString.length; i++) {
-  bytes[i] = binaryString.charCodeAt(i);
-}
-const unsignedTx = Transaction.from(bytes);
-const signedTx = await sdk.wallet.signTransaction(unsignedTx);
-
-// Submit deposit and join queue
-const signedTxBase64 = signedTx.serialize().toString('base64');
-const finalLobby = await sdk.escrow.submitDepositAndJoinQueue(
-  lobby.id,
-  signedTxBase64,
-  sdk.lobbies,
-);
+// Deposit using the sync (server-awaited) variant
+const result = await sdk.escrow.depositForLobbySync(lobby.id);
 ```
 
-**Note:** After signing the transaction, use `submitDepositAndJoinQueue()` to complete the flow and automatically join the matchmaking queue.
+**Note:** After `playAgain()`, use `depositForLobbySync()` (for agents) or `depositForLobby()` (for React hooks) to complete the deposit flow. The server auto-joins the matchmaking queue when all deposits are confirmed.
 
 ### Admin Methods