@stryke-xyz/premarket-sdk 1.2.2 → 1.2.4

package/dist/esm/sync/redis-ws-client.js

@@ -0,0 +1,225 @@
+function _class_call_check(instance, Constructor) {
+    if (!(instance instanceof Constructor)) {
+        throw new TypeError("Cannot call a class as a function");
+    }
+}
+function _defineProperties(target, props) {
+    for(var i = 0; i < props.length; i++){
+        var descriptor = props[i];
+        descriptor.enumerable = descriptor.enumerable || false;
+        descriptor.configurable = true;
+        if ("value" in descriptor) descriptor.writable = true;
+        Object.defineProperty(target, descriptor.key, descriptor);
+    }
+}
+function _create_class(Constructor, protoProps, staticProps) {
+    if (protoProps) _defineProperties(Constructor.prototype, protoProps);
+    if (staticProps) _defineProperties(Constructor, staticProps);
+    return Constructor;
+}
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function scheduleDeferred(callback) {
+    return setTimeout(callback, 1000);
+}
+export var RedisWsClient = /*#__PURE__*/ function() {
+    "use strict";
+    function RedisWsClient(url) {
+        _class_call_check(this, RedisWsClient);
+        _define_property(this, "url", void 0);
+        _define_property(this, "ws", void 0);
+        _define_property(this, "handlers", void 0);
+        _define_property(this, "heartbeat", void 0);
+        _define_property(this, "reconnectTimeout", void 0);
+        _define_property(this, "shouldReconnect", void 0);
+        this.url = url;
+        this.handlers = new Map();
+        this.reconnectTimeout = null;
+        this.shouldReconnect = true;
+        this.connect();
+    }
+    _create_class(RedisWsClient, [
+        {
+            key: "connect",
+            value: function connect() {
+                var _this = this;
+                if (!this.shouldReconnect) return;
+                this.ws = new WebSocket(this.url);
+                this.ws.onopen = function() {
+                    _this.startHeartbeat();
+                    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+                    try {
+                        // Re-subscribe to all channels after reconnection
+                        for(var _iterator = _this.handlers.keys()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                            var channel = _step.value;
+                            _this.subscribeInternal(channel);
+                        }
+                    } catch (err) {
+                        _didIteratorError = true;
+                        _iteratorError = err;
+                    } finally{
+                        try {
+                            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                                _iterator.return();
+                            }
+                        } finally{
+                            if (_didIteratorError) {
+                                throw _iteratorError;
+                            }
+                        }
+                    }
+                };
+                this.ws.onmessage = function(event) {
+                    var message = event.data;
+                    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+                    try {
+                        // Redis messages come directly as strings from the bridge
+                        // Since we subscribe to one channel per client instance in practice,
+                        // we can call all handlers
+                        for(var _iterator = _this.handlers.values()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                            var handlers = _step.value;
+                            handlers.forEach(function(fn) {
+                                return fn(message);
+                            });
+                        }
+                    } catch (err) {
+                        _didIteratorError = true;
+                        _iteratorError = err;
+                    } finally{
+                        try {
+                            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                                _iterator.return();
+                            }
+                        } finally{
+                            if (_didIteratorError) {
+                                throw _iteratorError;
+                            }
+                        }
+                    }
+                };
+                this.ws.onclose = function() {
+                    return _this.reconnect();
+                };
+                this.ws.onerror = function() {
+                    return _this.ws.close();
+                };
+            }
+        },
+        {
+            key: "reconnect",
+            value: function reconnect() {
+                var _this = this;
+                if (!this.shouldReconnect) return;
+                this.stopHeartbeat();
+                this.clearReconnectTimeout();
+                this.reconnectTimeout = scheduleDeferred(function() {
+                    _this.reconnectTimeout = null;
+                    _this.connect();
+                });
+            }
+        },
+        {
+            key: "startHeartbeat",
+            value: function startHeartbeat() {
+                var _this = this;
+                this.heartbeat = setInterval(function() {
+                    if (_this.ws.readyState === WebSocket.OPEN) {
+                        _this.ws.send(JSON.stringify({
+                            type: "ping"
+                        }));
+                    }
+                }, 20000);
+            }
+        },
+        {
+            key: "stopHeartbeat",
+            value: function stopHeartbeat() {
+                if (this.heartbeat) clearInterval(this.heartbeat);
+            }
+        },
+        {
+            key: "clearReconnectTimeout",
+            value: function clearReconnectTimeout() {
+                if (this.reconnectTimeout) {
+                    clearTimeout(this.reconnectTimeout);
+                    this.reconnectTimeout = null;
+                }
+            }
+        },
+        {
+            key: "subscribe",
+            value: function subscribe(channel, handler) {
+                if (!this.handlers.has(channel)) {
+                    this.handlers.set(channel, new Set());
+                    this.subscribeInternal(channel);
+                }
+                this.handlers.get(channel).add(handler);
+            }
+        },
+        {
+            key: "unsubscribe",
+            value: function unsubscribe(channel, handler) {
+                var handlers = this.handlers.get(channel);
+                if (!handlers) return;
+                if (handler) {
+                    handlers.delete(handler);
+                    if (handlers.size === 0) {
+                        this.handlers.delete(channel);
+                        this.unsubscribeInternal(channel);
+                    }
+                } else {
+                    this.handlers.delete(channel);
+                    this.unsubscribeInternal(channel);
+                }
+            }
+        },
+        {
+            key: "subscribeInternal",
+            value: function subscribeInternal(channel) {
+                if (this.ws.readyState === WebSocket.OPEN) {
+                    this.ws.send(JSON.stringify({
+                        type: "subscribe",
+                        channel: channel
+                    }));
+                }
+            }
+        },
+        {
+            key: "unsubscribeInternal",
+            value: function unsubscribeInternal(channel) {
+                if (this.ws.readyState === WebSocket.OPEN) {
+                    this.ws.send(JSON.stringify({
+                        type: "unsubscribe",
+                        channel: channel
+                    }));
+                }
+            }
+        },
+        {
+            key: "close",
+            value: function close() {
+                this.shouldReconnect = false;
+                this.stopHeartbeat();
+                this.clearReconnectTimeout();
+                if (this.ws) {
+                    this.ws.onclose = null;
+                }
+                if (this.ws) {
+                    this.ws.close();
+                }
+            }
+        }
+    ]);
+    return RedisWsClient;
+}();

package/dist/esm/utils/README.md

@@ -0,0 +1,89 @@
+# Utilities Guide
+
+The `utils` folder contains small reusable helpers that do not belong to one
+domain module but are still part of the SDK's public surface.
+
+## Source map
+
+- [`mul-div.ts`](./mul-div.ts) provides deterministic multiply-divide math with
+  optional rounding up
+- [`rand-bigint.ts`](./rand-bigint.ts) provides secure random bigint generation
+- [`orderUtils.ts`](./orderUtils.ts) provides token-pair helpers and a
+  signature-verification shortcut
+
+## `mulDiv` and `Rounding`
+
+`mulDiv(a, b, x, rounding?)` performs integer multiplication and division in one
+step using `bigint` arithmetic.
+
+Public exports:
+
+- `Rounding`
+  - `Ceil`
+  - `Floor`
+- `mulDiv(a, b, x, rounding?)`
+
+```ts
+import { Rounding, mulDiv } from "@stryke-xyz/premarket-sdk";
+
+const floorValue = mulDiv(10n, 3n, 4n);
+const ceilValue = mulDiv(10n, 3n, 4n, Rounding.Ceil);
+```
+
+This helper is especially relevant to the [Vault guide](../vault/README.md),
+where collateral previews need deterministic rounding behavior.
+
+## `randBigInt`
+
+`randBigInt(max)` returns a cryptographically secure random bigint in the range
+`[0, max]`.
+
+```ts
+import { randBigInt } from "@stryke-xyz/premarket-sdk";
+
+const salt = randBigInt((1n << 96n) - 1n);
+```
+
+Implementation notes:
+
+- it requires `globalThis.crypto.getRandomValues`
+- it throws if no secure random source is available
+- it is used by the exchange order builder for default salts
+
+## Order utility helpers
+
+[`orderUtils.ts`](./orderUtils.ts) exports a few low-level helpers that are
+useful when app code needs token-id normalization or direct signature recovery.
+
+Public exports:
+
+- `optionPrmToPrmTokenId(tokenId)`
+- `prmToOptionPrmTokenId(prmTokenId)`
+- `isComplementaryOptionTokenPair(tokenIdA, tokenIdB)`
+- `verifyOrderSignature(order, signature, chainId, exchangeAddress)`
+
+```ts
+import {
+  isComplementaryOptionTokenPair,
+  verifyOrderSignature,
+} from "@stryke-xyz/premarket-sdk";
+
+const complementary = isComplementaryOptionTokenPair(100n, 101n);
+const signer = await verifyOrderSignature(
+  order,
+  signature,
+  4326,
+  exchangeAddress,
+);
+```
+
+Relationship to the domain modules:
+
+- the token-id helpers overlap conceptually with the [Vault guide](../vault/README.md)
+  and [Exchange guide](../exchange/README.md)
+- `verifyOrderSignature` is a thin convenience wrapper around exchange
+  EIP-712 signer recovery
+
+When you want the richer context and invariants, prefer the domain guides. When
+you want the smallest possible helper for a utility task, this module is the
+right place.

package/dist/esm/vault/README.md

@@ -0,0 +1,268 @@
+# Vault Guide
+
+The `vault` module documents the SDK surface built around
+`OptionMarketVault`. It covers token-id derivation, collateral and settlement
+math, role constants, and transaction builders for mint, redeem, withdraw,
+rollover, and related flows.
+
+## Source map
+
+- [`index.ts`](./index.ts) re-exports the public vault surface
+- [`types.ts`](./types.ts) defines vault-level structs used across helpers
+- [`token-ids.ts`](./token-ids.ts) derives `PRM` and `oPRM` token ids
+- [`collateral.ts`](./collateral.ts) mirrors collateral and payoff math
+- [`transactions.ts`](./transactions.ts) builds calldata and transaction envelopes
+- [`constants.ts`](./constants.ts) exports precision constants and role enums
+
+## What this module is for
+
+In plain language:
+
+- it tells integrators how option position tokens are identified
+- it lets frontends and services estimate collateral, fees, and payouts without
+  re-implementing Solidity math
+- it gives callers ABI-backed transaction builders for the public vault flows
+
+## Vault concepts
+
+The vault mints paired ERC-6909 position ids:
+
+- `PRM`
+  - the collateral-side position token
+  - always even
+- `oPRM`
+  - the option claim token
+  - always odd
+
+The pairing rule is simple and intentional:
+
+- `oPrmTokenId = prmTokenId | 1`
+- `optionPrmToPrm(tokenId)` clears the low bit and returns the canonical `PRM`
+  id whether the input is already `PRM` or `oPRM`
+
+This convention is used throughout the SDK and should be treated as canonical.
+
+## Public types
+
+The main type definitions live in [`types.ts`](./types.ts):
+
+- `VaultInstrument`
+  - `{ marketId, tick, isCall }`
+  - used when minting or describing a strike-side instrument
+- `VaultMarket`
+  - bigint-based market shape matching the vault and registry configuration
+- `PrmInfo`
+  - metadata associated with a minted `PRM` family
+- `TokenIdParams`
+  - the full parameter set needed to derive a token id
+
+[`collateral.ts`](./collateral.ts) also exports calculation-specific types:
+
+- `MarketParams`
+- `InstrumentParams`
+- `SpreadBounds`
+
+These smaller helper types are useful when callers only need the math helpers
+and not the full market struct.
+
+## Precision constants and roles
+
+[`constants.ts`](./constants.ts) exposes the shared vault constants:
+
+- `VAULT_TOKEN_PRECISION = 1e18`
+- `FEE_BPS_PRECISION = 1e6`
+- `PNL_PRECISION = 1e18`
+- `Role`
+  - typed enum for vault role ids
+- `ROLE_NAMES`
+  - a friendly lookup from numeric role to display label
+
+Use these constants instead of hardcoding precision values in app code.
+
+## Token-id helpers
+
+[`token-ids.ts`](./token-ids.ts) is the public source of truth for position-id
+derivation.
+
+Public helpers:
+
+- `getPrmTokenId(params)`
+  - derives the even `PRM` token id from vault address, instrument, expiry, and
+    `chainId`
+- `getOptionPrmTokenId(params)`
+  - derives the odd `oPRM` token id
+- `prmToOptionTokenId(prmTokenId)`
+- `optionPrmToPrm(oPrmTokenId)`
+- `isPrmToken(tokenId)`
+- `isOptionPrmToken(tokenId)`
+- `getPositionId(tokenId, userAddress)`
+  - stable string key for app-side storage keyed by token and user
+
+```ts
+import {
+  getOptionPrmTokenId,
+  optionPrmToPrm,
+} from "@stryke-xyz/premarket-sdk";
+
+const oPrmTokenId = getOptionPrmTokenId({
+  vaultAddress: "0xVault",
+  marketId: 12n,
+  tick: 1500n,
+  isCall: true,
+  expiry: 1_735_689_600n,
+  chainId: 4326,
+});
+
+const prmTokenId = optionPrmToPrm(oPrmTokenId);
+```
+
+Implementation detail worth remembering:
+
+- `getPrmTokenId` hashes the vault address, instrument fields, expiry, and
+  `chainId`, then left-shifts once to force even parity
+
+## Collateral and settlement math
+
+[`collateral.ts`](./collateral.ts) mirrors the important deterministic math used
+by the vault contract. This makes it safe to pre-compute values in the UI or a
+backend without sacrificing contract parity.
+
+Public helpers:
+
+- `getSpreadWidth(market)`
+- `getSpreadBounds(instrument, market)`
+- `calculateCollateralAmount(prmAmount, instrument, market)`
+- `calculatePrmAmount(collateralAmount, instrument, market)`
+- `calculateSpreadProfit(instrument, market, finalTick, positionSize)`
+- `calculateSpreadLoss(instrument, market, finalTick, positionSize)`
+- `calculateWithdrawableCollateral(instrument, market, finalTick, positionSize)`
+- `getCollateralPerPosition(instrument, market)`
+- `calculateDepositFees(collateralAmount, depositFeeBps, feeBpsPrecision?)`
+- `calculateRedeemFees(profitAmount, redeemFeeBps, feeBpsPrecision?)`
+- `isInTheMoney(instrument, market, finalTick)`
+- `calculateMoneyness(instrument, market, finalTick)`
+
+```ts
+import {
+  calculateCollateralAmount,
+  calculateWithdrawableCollateral,
+} from "@stryke-xyz/premarket-sdk";
+
+const collateral = calculateCollateralAmount(
+  1_000_000_000_000_000_000n,
+  { marketId: 1n, tick: 1500n, isCall: true },
+  {
+    tickSize: 100n,
+    tickSpacing: 100n,
+    tokensPerTickSize: 1_000_000n,
+    isCollateralScaled: false,
+  },
+);
+
+const withdrawable = calculateWithdrawableCollateral(
+  { marketId: 1n, tick: 1500n, isCall: true },
+  {
+    tickSize: 100n,
+    tickSpacing: 100n,
+    tokensPerTickSize: 1_000_000n,
+    isCollateralScaled: false,
+  },
+  1_600n,
+  1_000_000_000_000_000_000n,
+);
+```
+
+Important behavior captured by the SDK:
+
+- spread width falls back to `1` when `tickSpacing <= tickSize`
+- strike-scaled collateral uses `instrument.tick`
+- collateral calculation rounds up when the final division is not exact
+- inverse `PRM` previews use floor division
+- payoff and withdraw math use deterministic `bigint` arithmetic throughout
+
+## Transaction builders
+
+[`transactions.ts`](./transactions.ts) contains ABI-backed transaction builders.
+These return a lightweight `TransactionCall`:
+
+```ts
+export interface TransactionCall {
+  to: `0x${string}`;
+  value?: bigint;
+  data: Hex;
+}
+```
+
+### User-facing lifecycle builders
+
+- `buildMintTransaction(vaultAddress, instrument, amount)`
+- `buildWithdrawTransaction(vaultAddress, prmTokenId, amount, receiver)`
+- `buildRedeemTransaction(vaultAddress, oPrmTokenId, receiver)`
+- `buildUnwindTransaction(vaultAddress, prmTokenId, amount, receiver)`
+- `buildRolloverTransaction(vaultAddress, oldPrmTokenId)`
+- `buildApproveTransaction(tokenAddress, spender, amount?)`
+- `buildBatchedMintTransactions(collateralTokenAddress, vaultAddress, instrument, collateralAmount, prmAmount)`
+- `buildSetOperatorTransaction(vaultAddress, operator, approved)`
+
+```ts
+import {
+  buildApproveTransaction,
+  buildMintTransaction,
+} from "@stryke-xyz/premarket-sdk";
+
+const approve = buildApproveTransaction(collateralToken, vaultAddress);
+const mint = buildMintTransaction(
+  vaultAddress,
+  { marketId: 12n, tick: 1500n, isCall: true },
+  1_000_000_000_000_000_000n,
+);
+```
+
+### Restricted and role-gated builders
+
+These functions are exported because they are part of the SDK, but they belong
+to operational or keeper-style flows rather than ordinary end-user integrations:
+
+- `buildDelegateRedeemTransaction`
+- `buildDelegateRolloverTransaction`
+- `buildDelegateWithdrawTransaction`
+- `buildFillMarketDeliveryTransaction`
+- `buildSetRolloverEnabledTransaction`
+- `buildSetRoleTransaction`
+- `buildUpdateFinalTickTransaction`
+- `buildUpdateMarketExpiryTransaction`
+- `buildUpdateMarketExpiryFromMarketTransaction`
+
+They should usually be used by privileged services, market operators, or
+automation code that already understands the relevant role checks.
+
+## Typical integration patterns
+
+### 1. Preview before mint
+
+Use the math helpers and token-id helpers together:
+
+1. derive the target `PRM` or `oPRM` id
+2. compute required collateral with `calculateCollateralAmount`
+3. build `approve` and `mint` calls
+
+### 2. Display settlement outcomes
+
+Use:
+
+- `isInTheMoney`
+- `calculateSpreadProfit`
+- `calculateRedeemFees`
+- `calculateWithdrawableCollateral`
+
+This gives UI code a contract-aligned preview for both option holders and
+collateral providers.
+
+### 3. Build sponsored or batched flows
+
+`buildBatchedMintTransactions` is especially helpful when a frontend or relayer
+needs to bundle approval and minting into one user operation or multicall-like
+flow.
+
+For market configuration and market serialization, continue with the
+[Registry guide](../registry/README.md).

package/dist/types/sync/clients/base-client.d.ts

@@ -0,0 +1,56 @@
+import type { SyncStatus } from "../types.js";
+import { RedisWsClient } from "../redis-ws-client.js";
+/**
+ * Base abstract class for sync clients
+ * @template TMessage - The message type (e.g., SequencedMessage, BalanceUpdateMessage)
+ * @template TChange - The change type (e.g., OrderChange, BalanceData[])
+ * @template TData - The data type stored in the map (e.g., StoredOrder, string)
+ * @template TConfig - The config type (must have redisUrl and channel)
+ */
+export declare abstract class BaseSyncClient<TMessage extends {
+    seq: number;
+    previousSeq: number;
+}, TChange, TData, TConfig extends {
+    redisUrl: string;
+    channel: string;
+}> {
+    protected wsClient: RedisWsClient | null;
+    protected config: TConfig;
+    protected status: SyncStatus;
+    protected lastSeq: number;
+    protected incomingQueue: TMessage[];
+    protected isProcessing: boolean;
+    protected statusListeners: Set<(status: SyncStatus) => void>;
+    protected changeListeners: Set<(change: TChange) => void>;
+    protected dataMap: Map<string, TData>;
+    protected snapshotListeners: Set<(data: TData[]) => void>;
+    constructor(config: TConfig);
+    /** Opens the websocket subscription, fetches a fresh snapshot, and starts replaying queued messages. */
+    connect(): Promise<void>;
+    protected enqueueMessage(message: TMessage): void;
+    protected processQueue(): Promise<void>;
+    protected fullResync(): Promise<void>;
+    protected setStatus(status: SyncStatus): void;
+    /** Returns the current connection lifecycle state. */
+    getStatus(): SyncStatus;
+    /** Returns true once the client has finished its initial snapshot sync. */
+    isSynced(): boolean;
+    /** Returns the most recent successfully applied sequence id. */
+    getLastSequence(): number;
+    /** Returns the number of queued messages waiting to be processed. */
+    getBufferedCount(): number;
+    /** Registers a listener for connection status changes. */
+    onStatus(callback: (status: SyncStatus) => void): () => void;
+    /** Registers a listener for individual applied change events. */
+    onChange(callback: (change: TChange) => void): () => void;
+    /** Registers a listener for full snapshot updates. */
+    onSnapshot(callback: (data: TData[]) => void): () => void;
+    protected notifySnapshotListeners(data: TData[]): void;
+    /** Closes the websocket connection and clears queued messages. */
+    disconnect(): Promise<void>;
+    /**
+     * Abstract methods to be implemented by child classes
+     */
+    protected abstract fetchSnapshot(): Promise<void>;
+    protected abstract applyMessage(message: TMessage): Promise<void> | void;
+}

package/dist/types/sync/redis-ws-client.d.ts

@@ -0,0 +1,21 @@
+type Handler<T = any> = (data: T) => void;
+export declare class RedisWsClient {
+    private url;
+    private ws;
+    private handlers;
+    private heartbeat?;
+    private reconnectTimeout;
+    private shouldReconnect;
+    constructor(url: string);
+    private connect;
+    private reconnect;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private clearReconnectTimeout;
+    subscribe<T>(channel: string, handler: Handler<T>): void;
+    unsubscribe(channel: string, handler?: Handler): void;
+    private subscribeInternal;
+    private unsubscribeInternal;
+    close(): void;
+}
+export {};