@alpha-arcade/sdk 0.3.0 → 0.4.0

package/README.md

@@ -337,6 +337,129 @@ for (const m of rewardMarkets) {
 
 ---
 
+### WebSocket Streams
+
+Real-time data streams via WebSocket. No API key or auth required. Replaces polling with push-based updates.
+
+```typescript
+import { AlphaWebSocket } from '@alpha-arcade/sdk';
+
+// Node.js 22+ and browsers — native WebSocket, nothing extra needed
+const ws = new AlphaWebSocket();
+
+// Node.js < 22 — install `ws` and pass it in:
+// npm install ws
+import WebSocket from 'ws';
+const ws = new AlphaWebSocket({ WebSocket });
+
+// Subscribe to orderbook updates (~5s snapshots)
+const unsub = ws.subscribeOrderbook('will-btc-hit-100k', (event) => {
+  console.log('Orderbook:', event.orderbook);
+});
+
+// Unsubscribe when done
+unsub();
+
+// Close the connection
+ws.close();
+```
+
+#### `subscribeLiveMarkets(callback)`
+
+Receive incremental diffs whenever market probabilities change.
+
+```typescript
+ws.subscribeLiveMarkets((event) => {
+  console.log('Markets changed at', event.ts, event);
+});
+```
+
+#### `subscribeMarket(slug, callback)`
+
+Receive change events for a single market. Uses the market **slug** (not `marketAppId`) — see note on `subscribeOrderbook` below.
+
+```typescript
+ws.subscribeMarket('will-btc-hit-100k', (event) => {
+  console.log('Market update:', event);
+});
+```
+
+#### `subscribeOrderbook(slug, callback)`
+
+Receive full orderbook snapshots on every change (~5s interval). Replaces on-chain polling.
+
+**Note:** The WebSocket API uses market **slugs** (URL-friendly names like `"will-btc-hit-100k"`), not `marketAppId` numbers. You can get a market's slug from the `slug` field on `Market` objects returned by `getLiveMarkets()` or `getMarket()`.
+
+```typescript
+ws.subscribeOrderbook('will-btc-hit-100k', (event) => {
+  // Top-level bids/asks use decimal prices (cents)
+  // Nested yes/no use raw microunit prices with escrowAppId and owner
+  for (const [appId, book] of Object.entries(event.orderbook)) {
+    console.log(`App ${appId}: spread=${book.spread}`);
+    console.log('  Bids:', book.bids);
+    console.log('  Yes bids:', book.yes.bids);
+  }
+});
+```
+
+#### `subscribeWalletOrders(wallet, callback)`
+
+Receive updates when orders for a wallet are created or modified.
+
+```typescript
+ws.subscribeWalletOrders('MMU6X...', (event) => {
+  console.log('Wallet orders changed:', event);
+});
+```
+
+#### Unsubscribing
+
+Each `subscribe*` method returns an unsubscribe function. Call it to stop receiving events for that stream:
+
+```typescript
+const unsub = ws.subscribeOrderbook('my-market', (event) => { /* ... */ });
+
+// Later, stop listening
+unsub();
+```
+
+#### Control Methods
+
+```typescript
+// List active subscriptions on this connection
+const subs = await ws.listSubscriptions();
+
+// Query server properties
+const props = await ws.getProperty('heartbeat');
+```
+
+#### Configuration
+
+```typescript
+import WebSocket from 'ws'; // Only needed on Node.js < 22
+
+const ws = new AlphaWebSocket({
+  WebSocket,                                  // Pass `ws` on Node.js < 22 (not needed in browsers or Node 22+)
+  url: 'wss://custom-endpoint.example.com',   // Override default URL
+  reconnect: true,                            // Auto-reconnect (default: true)
+  maxReconnectAttempts: 10,                   // Give up after 10 retries (default: Infinity)
+  heartbeatIntervalMs: 60_000,                // Ping interval in ms (default: 60000)
+});
+```
+
+#### Connection Details
+
+| Setting | Value |
+|---------|-------|
+| Heartbeat | 60s (auto-handled) |
+| Idle timeout | 180s |
+| Rate limit | 5 messages/sec/connection |
+| Reconnect | Exponential backoff (1s → 30s max) |
+
+The client automatically responds to server pings, sends keepalive pings, and reconnects with exponential backoff on unexpected disconnects. All active subscriptions are restored after reconnect.
+
+---
+
 ### Utility Functions
 
 These are exported for advanced users:

package/dist/index.cjs

@@ -2125,6 +2125,7 @@ var calculateMatchingOrders = (orderbook, isBuying, isYes, quantity, price, slip
 
 // src/constants.ts
 var DEFAULT_API_BASE_URL = "https://platform.alphaarcade.com/api";
+var DEFAULT_WSS_BASE_URL = "wss://wss.platform.alphaarcade.com";
 var DEFAULT_MARKET_CREATOR_ADDRESS = "5P5Y6HTWUNG2E3VXBQDZN3ENZD3JPAIR5PKT3LOYJAPAUKOLFD6KANYTRY";
 
 // src/modules/orderbook.ts
@@ -2514,6 +2515,89 @@ var proposeMatch = async (config, params) => {
     confirmedRound: Number(result.confirmedRound)
   };
 };
+var processMatch = async (config, params) => {
+  const { algodClient, signer, activeAddress, usdcAssetId } = config;
+  const { marketAppId, makerEscrowAppId, takerEscrowAppId } = params;
+  const [marketState, makerAppInfo, takerAppInfo] = await Promise.all([
+    getMarketGlobalState(algodClient, marketAppId),
+    algodClient.getApplicationByID(makerEscrowAppId).do(),
+    algodClient.getApplicationByID(takerEscrowAppId).do()
+  ]);
+  const marketFeeAddress = marketState.fee_address;
+  const yesAssetId = marketState.yes_asset_id;
+  const noAssetId = marketState.no_asset_id;
+  const makerState = decodeGlobalState(
+    makerAppInfo.params?.globalState ?? makerAppInfo.params?.["global-state"] ?? []
+  );
+  const takerState = decodeGlobalState(
+    takerAppInfo.params?.globalState ?? takerAppInfo.params?.["global-state"] ?? []
+  );
+  const makerOwner = makerState.owner ?? "";
+  const takerOwner = takerState.owner ?? "";
+  const makerRemaining = (makerState.quantity ?? 0) - (makerState.quantity_filled ?? 0);
+  const takerRemaining = (takerState.quantity ?? 0) - (takerState.quantity_filled ?? 0);
+  const matchedQuantity = Math.min(makerRemaining, takerRemaining);
+  if (matchedQuantity <= 0) {
+    throw new Error("processMatch: no quantity left to match on maker or taker escrow.");
+  }
+  const signerAccount = { signer, addr: activeAddress };
+  const makerEscrowClient = new EscrowAppClient(
+    { resolveBy: "id", id: makerEscrowAppId, sender: signerAccount },
+    algodClient
+  );
+  const takerEscrowClient = new EscrowAppClient(
+    { resolveBy: "id", id: takerEscrowAppId, sender: signerAccount },
+    algodClient
+  );
+  const marketClient = new MarketAppClient(
+    { resolveBy: "id", id: marketAppId, sender: signerAccount },
+    algodClient
+  );
+  const atc = new algosdk2.AtomicTransactionComposer();
+  const assets = [usdcAssetId, yesAssetId, noAssetId];
+  const sendParamsWithFee = { skipSending: true, fee: algokit4__namespace.microAlgos(3e3) };
+  const sendParamsNoop = { skipSending: true, fee: algokit4__namespace.microAlgos(1e3) };
+  const matchMakerTxn = await makerEscrowClient.matchMaker(
+    { taker: takerEscrowAppId, matchQuantity: matchedQuantity },
+    {
+      assets,
+      apps: [marketAppId],
+      accounts: [takerOwner, marketFeeAddress],
+      sendParams: sendParamsWithFee
+    }
+  );
+  atc.addTransaction({ txn: matchMakerTxn.transaction, signer });
+  const matchTakerTxn = await takerEscrowClient.matchTaker(
+    { maker: makerEscrowAppId },
+    {
+      assets,
+      apps: [marketAppId],
+      accounts: [makerOwner, marketFeeAddress],
+      sendParams: sendParamsWithFee
+    }
+  );
+  atc.addTransaction({ txn: matchTakerTxn.transaction, signer });
+  const processMatchTxn = await marketClient.processPotentialMatch(
+    { maker: makerEscrowAppId, taker: takerEscrowAppId },
+    {
+      assets,
+      accounts: [makerOwner, takerOwner, marketFeeAddress],
+      sendParams: sendParamsNoop
+    }
+  );
+  atc.addTransaction({ txn: processMatchTxn.transaction, signer });
+  const doNoopTxn = await marketClient.doNoop(
+    { callNumber: 1 },
+    { sendParams: sendParamsNoop }
+  );
+  atc.addTransaction({ txn: doNoopTxn.transaction, signer });
+  const result = await atc.execute(algodClient, 4);
+  return {
+    success: true,
+    txIds: result.txIDs,
+    confirmedRound: Number(result.confirmedRound)
+  };
+};
 var amendOrder = async (config, params) => {
   const { algodClient, signer, activeAddress, usdcAssetId } = config;
   const { marketAppId, escrowAppId, price, quantity, slippage = 0 } = params;
@@ -2570,10 +2654,47 @@ var amendOrder = async (config, params) => {
   );
   atc.addTransaction({ txn: amendCall.transaction, signer });
   const result = await atc.execute(algodClient, 4);
+  const allTxIds = [...result.txIDs];
+  let lastConfirmedRound = Number(result.confirmedRound);
+  const orderbook = await getOrderbook(config, marketAppId);
+  let matchingOrders = calculateMatchingOrders(orderbook, isBuy, position === 1, quantity, price, slippage);
+  matchingOrders = matchingOrders.filter((m) => m.escrowAppId !== escrowAppId);
+  if (matchingOrders.length > 0) {
+    let quantityLeft = quantity;
+    const matchedQuantities = [];
+    const matchedPrices = [];
+    for (const m of matchingOrders) {
+      if (quantityLeft <= 0) break;
+      try {
+        const matchResult = await processMatch(config, {
+          marketAppId,
+          makerEscrowAppId: m.escrowAppId,
+          takerEscrowAppId: escrowAppId
+        });
+        allTxIds.push(...matchResult.txIds);
+        lastConfirmedRound = matchResult.confirmedRound;
+        const q = Math.min(m.quantity, quantityLeft);
+        matchedQuantities.push(q);
+        matchedPrices.push((m.price ?? price) * q);
+        quantityLeft -= q;
+      } catch (err) {
+        console.log(`Error matching order: ${JSON.stringify(err)}`);
+        break;
+      }
+    }
+    const totalMatchedQuantity = matchedQuantities.reduce((a, b) => a + b, 0);
+    const matchedPrice = totalMatchedQuantity > 0 ? Math.round(matchedPrices.reduce((a, b) => a + b, 0) / totalMatchedQuantity) : void 0;
+    return {
+      success: true,
+      txIds: allTxIds,
+      confirmedRound: lastConfirmedRound,
+      ...totalMatchedQuantity > 0 && { matchedQuantity: totalMatchedQuantity, matchedPrice }
+    };
+  }
   return {
     success: true,
-    txIds: result.txIDs,
-    confirmedRound: Number(result.confirmedRound)
+    txIds: allTxIds,
+    confirmedRound: lastConfirmedRound
   };
 };
 var splitShares = async (config, params) => {
@@ -3056,6 +3177,19 @@ var AlphaClient = class {
   async proposeMatch(params) {
     return proposeMatch(this.config, params);
   }
+  /**
+   * Matches two existing limit orders (no create-escrow in the group).
+   *
+   * Calls the market app's process_potential_match(maker, taker). Use this
+   * after amending an order: the amended order is the taker (pays the fee),
+   * the counterparty is the maker.
+   *
+   * @param params - Process match params (marketAppId, makerEscrowAppId, takerEscrowAppId)
+   * @returns Whether the match succeeded
+   */
+  async processMatch(params) {
+    return processMatch(this.config, params);
+  }
   /**
    * Amends (edits) an existing unfilled order in-place.
    *
@@ -3233,9 +3367,274 @@ var AlphaClient = class {
   }
 };
 
+// src/websocket.ts
+var WS_OPEN = 1;
+var resolveWebSocket = (provided) => {
+  if (provided) return provided;
+  if (typeof globalThis !== "undefined" && globalThis.WebSocket) {
+    return globalThis.WebSocket;
+  }
+  throw new Error(
+    'No WebSocket implementation found. On Node.js < 22, install the "ws" package and pass it: new AlphaWebSocket({ WebSocket: require("ws") })'
+  );
+};
+var AlphaWebSocket = class {
+  url;
+  reconnectEnabled;
+  maxReconnectAttempts;
+  heartbeatIntervalMs;
+  WebSocketImpl;
+  ws = null;
+  subscriptions = /* @__PURE__ */ new Map();
+  pendingRequests = /* @__PURE__ */ new Map();
+  heartbeatTimer = null;
+  reconnectTimer = null;
+  reconnectAttempts = 0;
+  intentionallyClosed = false;
+  connectPromise = null;
+  constructor(config) {
+    this.url = config?.url ?? DEFAULT_WSS_BASE_URL;
+    this.reconnectEnabled = config?.reconnect ?? true;
+    this.maxReconnectAttempts = config?.maxReconnectAttempts ?? Infinity;
+    this.heartbeatIntervalMs = config?.heartbeatIntervalMs ?? 6e4;
+    this.WebSocketImpl = resolveWebSocket(config?.WebSocket);
+  }
+  /** Whether the WebSocket is currently open and connected */
+  get connected() {
+    return this.ws?.readyState === WS_OPEN;
+  }
+  // ============================================
+  // Subscribe Methods
+  // ============================================
+  /**
+   * Subscribe to live market probability updates (incremental diffs).
+   * @returns An unsubscribe function
+   */
+  subscribeLiveMarkets(callback) {
+    return this.subscribe("get-live-markets", {}, "markets_changed", callback);
+  }
+  /**
+   * Subscribe to change events for a single market.
+   * @param slug - The market slug
+   * @returns An unsubscribe function
+   */
+  subscribeMarket(slug, callback) {
+    return this.subscribe("get-market", { slug }, "market_changed", callback);
+  }
+  /**
+   * Subscribe to full orderbook snapshots (~5s interval on changes).
+   * @param slug - The market slug
+   * @returns An unsubscribe function
+   */
+  subscribeOrderbook(slug, callback) {
+    return this.subscribe("get-orderbook", { slug }, "orderbook_changed", callback);
+  }
+  /**
+   * Subscribe to wallet order updates.
+   * @param wallet - The wallet address
+   * @returns An unsubscribe function
+   */
+  subscribeWalletOrders(wallet, callback) {
+    return this.subscribe("get-wallet-orders", { wallet }, "wallet_orders_changed", callback);
+  }
+  // ============================================
+  // Control Methods
+  // ============================================
+  /** Query the server for the list of active subscriptions on this connection */
+  listSubscriptions() {
+    return this.sendRequest({ method: "LIST_SUBSCRIPTIONS" });
+  }
+  /** Query a server property (e.g. "heartbeat", "limits") */
+  getProperty(property) {
+    return this.sendRequest({ method: "GET_PROPERTY", property });
+  }
+  // ============================================
+  // Lifecycle
+  // ============================================
+  /** Open the WebSocket connection. Called automatically on first subscribe. */
+  connect() {
+    if (this.connectPromise) return this.connectPromise;
+    this.connectPromise = this.doConnect();
+    return this.connectPromise;
+  }
+  /** Close the connection and clean up all resources */
+  close() {
+    this.intentionallyClosed = true;
+    this.clearTimers();
+    this.subscriptions.clear();
+    for (const [, req] of this.pendingRequests) {
+      clearTimeout(req.timer);
+      req.reject(new Error("WebSocket closed"));
+    }
+    this.pendingRequests.clear();
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+    this.connectPromise = null;
+  }
+  // ============================================
+  // Internal
+  // ============================================
+  buildStreamKey(stream, params) {
+    const parts = [stream, ...Object.entries(params).sort().map(([k, v]) => `${k}=${v}`)];
+    return parts.join("&");
+  }
+  buildQueryString() {
+    const subs = [...this.subscriptions.values()];
+    if (subs.length === 0) return "";
+    const first = subs[0];
+    const params = new URLSearchParams({ stream: first.stream, ...first.params });
+    return "?" + params.toString();
+  }
+  subscribe(stream, params, eventType, callback) {
+    const key = this.buildStreamKey(stream, params);
+    this.subscriptions.set(key, { stream, params, callback, eventType });
+    if (this.connected) {
+      this.sendSubscribe(stream, params);
+    } else {
+      this.connect();
+    }
+    return () => {
+      this.subscriptions.delete(key);
+      if (this.connected) {
+        this.sendUnsubscribe(stream, params);
+      }
+    };
+  }
+  async doConnect() {
+    this.intentionallyClosed = false;
+    return new Promise((resolve, reject) => {
+      const qs = this.buildQueryString();
+      const ws = new this.WebSocketImpl(this.url + qs);
+      ws.onopen = () => {
+        this.ws = ws;
+        this.reconnectAttempts = 0;
+        this.startHeartbeat();
+        const subs = [...this.subscriptions.values()];
+        for (const sub of subs.slice(1)) {
+          this.sendSubscribe(sub.stream, sub.params);
+        }
+        resolve();
+      };
+      ws.onmessage = (event) => {
+        this.handleMessage(event.data);
+      };
+      ws.onclose = () => {
+        this.ws = null;
+        this.connectPromise = null;
+        this.stopHeartbeat();
+        if (!this.intentionallyClosed) {
+          this.scheduleReconnect();
+        }
+      };
+      ws.onerror = (err) => {
+        if (!this.ws) {
+          reject(new Error("WebSocket connection failed"));
+        }
+      };
+    });
+  }
+  handleMessage(raw) {
+    let msg;
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (msg.type === "ping") {
+      this.send({ method: "PONG" });
+      return;
+    }
+    if (msg.requestId && this.pendingRequests.has(msg.requestId)) {
+      const req = this.pendingRequests.get(msg.requestId);
+      this.pendingRequests.delete(msg.requestId);
+      clearTimeout(req.timer);
+      req.resolve(msg);
+      return;
+    }
+    const eventType = msg.type;
+    if (!eventType) return;
+    for (const sub of this.subscriptions.values()) {
+      if (sub.eventType === eventType) {
+        try {
+          sub.callback(msg);
+        } catch {
+        }
+      }
+    }
+  }
+  sendSubscribe(stream, params) {
+    this.send({ method: "SUBSCRIBE", stream, ...params });
+  }
+  sendUnsubscribe(stream, params) {
+    this.send({ method: "UNSUBSCRIBE", stream, ...params });
+  }
+  sendRequest(payload, timeoutMs = 1e4) {
+    const requestId = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        reject(new Error("Request timed out"));
+      }, timeoutMs);
+      this.pendingRequests.set(requestId, { resolve, reject, timer });
+      if (!this.connected) {
+        this.connect().then(() => {
+          this.send({ ...payload, requestId });
+        }).catch(reject);
+      } else {
+        this.send({ ...payload, requestId });
+      }
+    });
+  }
+  send(data) {
+    if (this.ws?.readyState === WS_OPEN) {
+      this.ws.send(JSON.stringify(data));
+    }
+  }
+  // ============================================
+  // Heartbeat
+  // ============================================
+  startHeartbeat() {
+    this.stopHeartbeat();
+    this.heartbeatTimer = setInterval(() => {
+      this.send({ type: "ping" });
+    }, this.heartbeatIntervalMs);
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+  // ============================================
+  // Reconnect
+  // ============================================
+  scheduleReconnect() {
+    if (!this.reconnectEnabled) return;
+    if (this.reconnectAttempts >= this.maxReconnectAttempts) return;
+    const delay = Math.min(1e3 * 2 ** this.reconnectAttempts, 3e4);
+    this.reconnectAttempts++;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect().catch(() => {
+      });
+    }, delay);
+  }
+  clearTimers() {
+    this.stopHeartbeat();
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+};
+
 exports.AlphaClient = AlphaClient;
+exports.AlphaWebSocket = AlphaWebSocket;
 exports.DEFAULT_API_BASE_URL = DEFAULT_API_BASE_URL;
 exports.DEFAULT_MARKET_CREATOR_ADDRESS = DEFAULT_MARKET_CREATOR_ADDRESS;
+exports.DEFAULT_WSS_BASE_URL = DEFAULT_WSS_BASE_URL;
 exports.calculateFee = calculateFee;
 exports.calculateFeeFromTotal = calculateFeeFromTotal;
 exports.calculateMatchingOrders = calculateMatchingOrders;