@stryke-xyz/premarket-sdk 1.2.1 → 1.2.2

package/dist/cjs/registry/README.md

@@ -1,150 +0,0 @@
-# Registry Guide
-
-The `registry` module wraps the `MarketsRegistry` contract surface that the SDK
-needs for market configuration and market serialization. It is intentionally
-small: the goal is to keep market definitions consistent across contracts,
-backend services, and frontend consumers.
-
-## Source map
-
-- [`index.ts`](./index.ts) re-exports the public registry surface
-- [`types.ts`](./types.ts) defines market structs and serializers
-- [`markets-registry-contract.ts`](./markets-registry-contract.ts) encodes
-  `MarketsRegistry` calldata
-
-## What this module is for
-
-In plain language:
-
-- it describes the market configuration shape used across the system
-- it converts that shape between `bigint` form and string-safe transport form
-- it encodes the registry's live write surface without each consumer shipping
-  its own ABI wrapper
-
-## Market types
-
-[`types.ts`](./types.ts) exports the registry's main data model:
-
-- `MarketType`
-  - `ERC20xERC20`
-  - `ERC20xERC6909`
-- `RegistryMarket`
-  - bigint-based market definition used in code
-- `SerializedRegistryMarket`
-  - string-safe market definition for JSON payloads and config files
-
-Core fields include:
-
-- token addresses: `underlying`, `collateral`, `delivery`, `owner`
-- sizing and strike metadata: `tickSize`, `tickSpacing`, `tokensPerTickSize`
-- expiry and fee fields: `expiry`, `depositFeeBps`, `redeemFeeBps`,
-  `makerFeeBps`, `takerFeeBps`, `rolloverFeeBps`
-- runtime flags: `marketType`, `isCollateralScaled`, `nonRollable`
-
-Serialization helpers:
-
-- `serializeRegistryMarket(market)`
-- `deserializeRegistryMarket(market)`
-
-```ts
-import {
-  MarketType,
-  serializeRegistryMarket,
-} from "@stryke-xyz/premarket-sdk";
-
-const market = serializeRegistryMarket({
-  underlying: "0x1111111111111111111111111111111111111111",
-  collateral: "0x2222222222222222222222222222222222222222",
-  delivery: "0x3333333333333333333333333333333333333333",
-  owner: "0x4444444444444444444444444444444444444444",
-  tickSize: 100n,
-  tickSpacing: 100n,
-  tokensPerTickSize: 1_000_000n,
-  expiry: 1_900_000_000n,
-  depositFeeBps: 0n,
-  redeemFeeBps: 0n,
-  makerFeeBps: 2_000n,
-  takerFeeBps: 2_000n,
-  rolloverFeeBps: 0n,
-  marketType: MarketType.ERC20xERC6909,
-  isCollateralScaled: false,
-  nonRollable: false,
-});
-```
-
-## Contract wrapper
-
-`MarketsRegistryContract` in
-[`markets-registry-contract.ts`](./markets-registry-contract.ts) wraps the
-shipped registry ABI and returns either calldata or a minimal tx envelope.
-
-```ts
-import {
-  MarketType,
-  MarketsRegistryContract,
-} from "@stryke-xyz/premarket-sdk";
-
-const registry = new MarketsRegistryContract(registryAddress);
-
-const tx = registry.buildAddMarketTx({
-  underlying: "0x1111111111111111111111111111111111111111",
-  collateral: "0x2222222222222222222222222222222222222222",
-  delivery: "0x3333333333333333333333333333333333333333",
-  owner: "0x4444444444444444444444444444444444444444",
-  tickSize: 100n,
-  tickSpacing: 100n,
-  tokensPerTickSize: 1_000_000n,
-  expiry: 1_900_000_000n,
-  depositFeeBps: 0n,
-  redeemFeeBps: 0n,
-  makerFeeBps: 2_000n,
-  takerFeeBps: 2_000n,
-  rolloverFeeBps: 0n,
-  marketType: MarketType.ERC20xERC6909,
-  isCollateralScaled: false,
-  nonRollable: false,
-});
-```
-
-Public surfaces:
-
-- `RegistryTransactionCall`
-  - `{ to, value?, data }`
-- `MarketsRegistryContract`
-  - `getAddMarketCalldata(market)`
-  - `buildAddMarketTx(market)`
-  - `getUpdateTokenCalldata(token, isStable, isDelete)`
-  - `getSetWhitelistedCalldata(account, allowed)`
-  - `getUpdateMarketExpiryCalldata(marketId, expiry)`
-  - `getMulticallCalldata(data)`
-
-Important nuance:
-
-- only `buildAddMarketTx` currently returns a full transaction object
-- the remaining helpers return raw calldata, which is often what relayers,
-  deployment scripts, or admin consoles actually want
-
-## Restricted surfaces
-
-Most registry writes are administrative by nature. The SDK documents them
-because they are exported and useful to privileged tooling, but they should not
-be treated as ordinary end-user operations:
-
-- `getAddMarketCalldata`
-- `buildAddMarketTx`
-- `getUpdateTokenCalldata`
-- `getSetWhitelistedCalldata`
-- `getUpdateMarketExpiryCalldata`
-- `getMulticallCalldata`
-
-## How this module fits with the rest of the SDK
-
-- the [Vault guide](../vault/README.md) uses registry-aligned market fields for
-  collateral and settlement math
-- the [Config guide](../config/README.md) ships deployed registry addresses
-- the [API guide](../api/README.md) returns market DTOs that map naturally back
-  to `RegistryMarket`-style concepts
-
-When protocol market semantics change, this module is one of the first places
-that should be updated, because downstream consumers assume it represents the
-canonical market shape.

package/dist/cjs/shared/README.md

@@ -1,235 +0,0 @@
-# Shared Types Guide
-
-The `shared` module collects the DTOs that move between the SDK, the HTTP API,
-and frontend consumers. These types are intentionally transport-oriented:
-numeric fields are usually strings so they can be serialized safely over JSON.
-
-## Source map
-
-- [`index.ts`](./index.ts) re-exports the shared surface
-- [`types.ts`](./types.ts) defines order, market, PnL, history, and snapshot DTOs
-
-## Why this module matters
-
-These types are the glue between:
-
-- `OrderbookApi` in the [API guide](../api/README.md)
-- frontend state and caches
-- backend responses and request payloads
-- SDK helpers that need a JSON-safe representation of onchain data
-
-## Order transport types
-
-### `Order`
-
-`Order` is the serialized transport-safe order shape used by HTTP payloads:
-
-```ts
-export interface Order {
-  salt: string;
-  nonce: string;
-  marketId: string;
-  makingAmount: string;
-  takingAmount: string;
-  deadline: string;
-  maker: string;
-  receiver: string;
-  tradeType: number;
-  signatureType: number;
-  tokenId: string;
-}
-```
-
-Related order types:
-
-- `OrderSignature`
-  - raw `0x...` signature bytes
-- `OrderStatus`
-  - `OPEN`, `PARTIALLY_FILLED`, `FULLY_FILLED`, `CANCELLED`, `EXPIRED`
-- `TimeInForce`
-  - `FOK`, `FAK`, `GTC`, `GTD`
-- `CreateOrderParams`
-  - request body for `OrderbookApi.createOrder`
-- `CreateOrderRequest`
-  - alias of `CreateOrderParams`
-- `StoredOrder`
-  - persisted order record including status, side, price, remaining amount, and
-    timestamps
-- `MatchableOrder`
-  - alias of `StoredOrder`
-- `MatchRequest`
-  - matching-oriented request model
-- `MatchedOrder`
-  - one resolved match leg
-- `MatchResult`
-  - aggregate match outcome
-- `CreateOrderResult`
-  - order creation result plus match details
-- `OrderQueryParams`
-  - query filters for list reads
-- `OrderResponse`
-  - generic envelope shape used by some backend responses
-- `OrdersSnapshot`
-  - `{ orders, count }`
-- `QueryOrdersResponse`
-  - paginated query result with `limit` and `offset`
-- `DepthSnapshot`
-  - point-in-time depth view for one market and token pair
-
-### `CreateOrderParams`
-
-This is the main order write payload:
-
-```ts
-export interface CreateOrderParams {
-  marketId: string;
-  order: Order;
-  signature: OrderSignature;
-  operator?: string;
-  timeInForce?: TimeInForce;
-  postOnly?: boolean;
-}
-```
-
-### `StoredOrder`
-
-This is the main order read model:
-
-```ts
-export interface StoredOrder {
-  orderHash: string;
-  signature: OrderSignature;
-  marketId: string;
-  tokenId: string;
-  remainingMakerAmount: string;
-  order: Order;
-  operator?: string;
-  createdAt: number;
-  status: OrderStatus;
-  side: "bid" | "ask";
-  price: number;
-}
-```
-
-## Market DTOs
-
-The market section of [`types.ts`](./types.ts) defines what the API returns for
-catalog and single-market reads.
-
-Public types:
-
-- `MarketInstrument`
-- `Market`
-- `MarketResponse`
-- `MarketsResponse`
-
-`MarketInstrument` carries the tradable strike-level data:
-
-- ids and labels
-- `tick`, `isSpread`, `isCall`
-- paired token ids: `prmTokenId`, `oPrmTokenId`
-- top-of-book and recent price fields
-- collateral and supply totals
-
-`Market` wraps the market-level metadata:
-
-- identifiers and descriptive fields
-- price band and increment fields
-- token addresses for `underlying`, `collateral`, and `delivery`
-- fee fields and expiry
-- `marketType`, `isCollateralScaled`, `nonRollable`
-- nested `instruments`
-
-`MarketsResponse` has the shape:
-
-```ts
-{
-  success: true;
-  data: {
-    markets: Market[];
-    total: number;
-  };
-}
-```
-
-## Position and PnL DTOs
-
-Public types:
-
-- `UserPosition`
-- `TradingPnL`
-- `UserPnL`
-- `TokenPnL`
-- `Erc20PnL`
-
-These types separate position-level accounting from trading-level accounting:
-
-- `UserPosition`
-  - current holding and realized position PnL for one token id
-- `TradingPnL`
-  - realized trading activity grouped by asset and optional token id
-- `UserPnL`
-  - top-level aggregate summary
-- `TokenPnL`
-  - combined position and trading breakdown for one ERC-6909 token id
-- `Erc20PnL`
-  - combined trading breakdown for one ERC-20 token address
-
-Use these types when rendering user dashboards or analytics screens.
-
-## History DTOs
-
-Public history types:
-
-- `MintHistoryItem`
-- `RedeemHistoryItem`
-- `UnwindHistoryItem`
-- `TransferHistoryItem`
-- `OrderFillHistoryItem`
-- `MarketTradeItem`
-  - alias of `OrderFillHistoryItem`
-- `UserHistories`
-
-`UserHistories` groups the main public activity feeds:
-
-```ts
-export interface UserHistories {
-  mints: MintHistoryItem[];
-  redeems: RedeemHistoryItem[];
-  unwinds: UnwindHistoryItem[];
-  transfers: TransferHistoryItem[];
-  fills: OrderFillHistoryItem[];
-}
-```
-
-The individual item types carry the fields that matter to product experiences:
-
-- transaction hash and block context
-- token ids and amount strings
-- sender, receiver, maker, and taker addresses where applicable
-- timestamps suitable for activity feeds
-
-## Depth snapshot type
-
-`DepthSnapshot` is the HTTP snapshot companion to the realtime sync clients. It
-contains the current bid and ask ladders plus market and token identifiers.
-
-This type is commonly paired with the [Sync guide](../sync/README.md), where
-`MarketDepthSyncClient` turns snapshot state into a continuously updated local
-book.
-
-## Sensitive and restricted DTOs
-
-`types.ts` also exports `AuthChallenge`. The SDK keeps that type public because
-the auth helpers use it, but this guide intentionally does not provide a full
-field-by-field auth payload walkthrough. The focus here is the general public
-integration contract used by application code.
-
-## How to use these types well
-
-- use `OrderHelper` or exchange serializers when converting between bigint
-  orders and `Order`
-- treat numeric strings as exact values, not display-formatted strings
-- convert to `bigint` only at the application boundary where you need math
-- prefer the deserializers in [`../api/orderbook-api/deserializers.ts`](../api/orderbook-api/deserializers.ts)
-  when you want typed bigint conversion rather than ad hoc parsing

package/dist/cjs/shared/utils.js

@@ -1 +0,0 @@
-"use strict";

package/dist/cjs/sync/README.md

@@ -1,215 +0,0 @@
-# Sync Guide
-
-The `sync` module contains the SDK's realtime clients. These clients keep a
-frontend or service in sync with depth and activity streams without each
-consumer rewriting its own websocket lifecycle, reconnect, sequencing, and
-normalization logic.
-
-## Source map
-
-- [`index.ts`](./index.ts) re-exports the public sync surface
-- [`types.ts`](./types.ts) defines shared lifecycle and sequencing types
-- [`clients/base-client.ts`](./clients/base-client.ts) provides an extensible
-  base class for Redis-backed sequenced streams
-- [`clients/order-client.ts`](./clients/order-client.ts) implements
-  market-depth syncing
-- [`clients/activity-client.ts`](./clients/activity-client.ts) implements order
-  fill activity syncing
-
-## What this module is for
-
-In plain language:
-
-- it keeps a local orderbook view current
-- it emits lifecycle updates such as connecting, syncing, and recovering
-- it gives callers normalized callback hooks instead of raw websocket messages
-
-## Shared sync types
-
-[`types.ts`](./types.ts) exports the shared lifecycle and sequencing model:
-
-- `SyncStatus`
-  - `"connecting" | "syncing" | "synced" | "recovering" | "disconnected" | "error"`
-- `OrderChange`
-  - a single `INSERT`, `UPDATE`, or `DELETE` orderbook mutation
-- `SequencedMessage`
-  - `{ seq, previousSeq, marketId, change, timestamp }`
-- `SyncClientConfig`
-  - base config shape for sequenced sync clients
-
-## MarketDepthSyncClient
-
-`MarketDepthSyncClient` is the main realtime client for market depth. It keeps
-token-level bid and ask books, tracks per-token sequence ids, normalizes price
-keys, handles reconnect logic, and exposes readable snapshot and delta hooks.
-
-### Config
-
-`MarketDepthClientConfig` from [`clients/order-client.ts`](./clients/order-client.ts):
-
-- `wsUrl`
-- `marketId`
-- `tokenIds`
-- `heartbeatIntervalMs?`
-- `heartbeatTimeoutMs?`
-- `maxReconnectAttempts?`
-- `initialReconnectDelayMs?`
-- `maxReconnectDelayMs?`
-
-### Connection methods
-
-- `connect()`
-- `disconnect()`
-- `getStatus()`
-
-### Read methods
-
-- `getTokenIds()`
-- `getTokenState(tokenId)`
-- `getBids(tokenId)`
-- `getAsks(tokenId)`
-- `getBestBid(tokenId)`
-- `getBestAsk(tokenId)`
-- `getLastPrice(tokenId)`
-- `getSeq(tokenId)`
-- `getSpread(tokenId)`
-- `getDepthAtPrice(tokenId, side, price)`
-
-### Listener hooks
-
-- `onStatus(callback)`
-- `onSnapshot(callback)`
-- `onDelta(callback)`
-
-### Public event types
-
-- `DepthLevel`
-- `TokenDepthSnapshot`
-- `DepthLevelUpdate`
-- `DepthChangeEvent`
-- `DepthUpdate`
-
-```ts
-import { MarketDepthSyncClient } from "@stryke-xyz/premarket-sdk";
-
-const client = new MarketDepthSyncClient({
-  wsUrl: "wss://example.stryke.xyz",
-  marketId: "12",
-  tokenIds: ["123", "124"],
-});
-
-client.onSnapshot((snapshots) => {
-  console.log("initial snapshots", snapshots);
-});
-
-client.onDelta((marketId, update) => {
-  console.log("delta", marketId, update);
-});
-
-await client.connect();
-```
-
-Useful details captured by the implementation:
-
-- the client rejects invalid non-websocket URLs
-- it waits for initial snapshots before resolving `connect()`
-- it deduplicates sequence ids and detects gaps
-- depth lookups normalize equivalent price strings like `"1"` and `"1.000000"`
-
-## ActivitySyncClient
-
-`ActivitySyncClient` subscribes to order-fill activity for a market, a user, or
-both. It is intentionally simpler than the depth client because it does not
-maintain a mutable book; it forwards fill events as they arrive.
-
-### Config
-
-`ActivityClientConfig` from [`clients/activity-client.ts`](./clients/activity-client.ts):
-
-- `wsUrl`
-- `marketId?`
-- `userAddress?`
-- `heartbeatIntervalMs?`
-- `heartbeatTimeoutMs?`
-- `maxReconnectAttempts?`
-- `initialReconnectDelayMs?`
-- `maxReconnectDelayMs?`
-
-At least one of `marketId` or `userAddress` is required.
-
-### Connection methods
-
-- `connect()`
-- `disconnect()`
-- `getStatus()`
-
-### Listener hooks
-
-- `onStatus(callback)`
-- `onOrderFill(callback)`
-- `onUserFill(callback)`
-- `onMarketFill(callback)`
-
-### Event type
-
-- `OrderFillEvent`
-
-```ts
-import { ActivitySyncClient } from "@stryke-xyz/premarket-sdk";
-
-const activity = new ActivitySyncClient({
-  wsUrl: "wss://example.stryke.xyz",
-  marketId: "12",
-});
-
-activity.onMarketFill((event) => {
-  console.log("fill", event.orderHash, event.makingAmount, event.takingAmount);
-});
-
-await activity.connect();
-```
-
-## BaseSyncClient
-
-`BaseSyncClient` in [`clients/base-client.ts`](./clients/base-client.ts) is an
-advanced extension surface for sequenced Redis-backed streams. It is exported so
-integrators can build their own sync clients on the same foundation when
-necessary.
-
-Public methods:
-
-- `connect()`
-- `disconnect()`
-- `getStatus()`
-- `isSynced()`
-- `getLastSequence()`
-- `getBufferedCount()`
-- `onStatus(callback)`
-- `onChange(callback)`
-- `onSnapshot(callback)`
-
-What it handles for subclasses:
-
-- websocket subscription lifecycle
-- initial snapshot gating
-- sequence ordering and deduplication
-- full resync on gap detection
-- listener registration and notification
-
-What subclasses must provide:
-
-- `fetchSnapshot()`
-- `applyMessage(message)`
-
-If you do not need to build a custom client, prefer `MarketDepthSyncClient` or
-`ActivitySyncClient`.
-
-## Recommended usage
-
-- use `MarketDepthSyncClient` when the UI needs an interactive orderbook
-- use `ActivitySyncClient` when the UI needs trade tape or user activity feeds
-- use `BaseSyncClient` only when you are creating a new specialized sync client
-  on top of the same sequencing model
-
-For snapshot DTOs used alongside these streams, see the
-[Shared types guide](../shared/README.md).