@stryke-xyz/premarket-sdk 1.0.6 → 1.0.7

package/README.md

@@ -4,22 +4,250 @@ TypeScript SDK for Stryke premarket integrations across:
 
 - `option-markets` contracts (`Exchange`, `MarketsRegistry`, `OptionMarketVault`)
 - `smart-account` contracts (`SimpleAccountFactory`, `EntryPoint`)
-- `premarkets-api` HTTP/WebSocket services
+- `premarkets-api` HTTP and WebSocket services
 - `premarkets-interface` frontend runtime
 
+This package is the shared integration layer between onchain contracts and the
+application stack. It gives product teams one place to build orders, hash and
+sign typed data, encode contract calls, read market and user data, subscribe to
+live updates, and consume deployment constants.
+
 ## What This Package Provides
 
-- native `Exchange` order builders, hashing, typed-data signing helpers
-- contract transaction builders for exchange, vault, and registry flows
-- orderbook/premarket API client (`OrderbookApi`)
-- realtime sync clients for depth/activity streams
-- chain/address constants used by backend and frontend repos
+- native `Exchange` order builders, hashing, typed-data signing helpers, and
+  calldata builders
+- `OptionMarketVault` token-id helpers, collateral math, and transaction
+  builders
+- `MarketsRegistry` market serialization and contract calldata builders
+- `OrderHelper` and `OrderbookApi` for backend and frontend integrations
+- realtime sync clients for market depth and activity streams
+- chain definitions, token metadata, and deployed contract addresses
+- smart-account address derivation and deployment checks
+- shared DTOs used by HTTP clients and frontend consumers
+
+## Documentation Map
+
+The new documentation set lives alongside the legacy docs during migration.
+Start here, then drill into the module guide that matches the surface you are
+integrating.
+
+### Module guides
+
+- [Exchange guide](./src/exchange/README.md)
+- [Vault guide](./src/vault/README.md)
+- [Registry guide](./src/registry/README.md)
+- [API guide](./src/api/README.md)
+- [Sync guide](./src/sync/README.md)
+- [Config guide](./src/config/README.md)
+- [Shared types guide](./src/shared/README.md)
+- [Utilities guide](./src/utils/README.md)
+
+### Root-level exports
+
+The package root also exports a handful of single-file helpers that do not live
+under one directory package:
+
+- `smart-account`
+  - Source: [`src/smart-account.ts`](./src/smart-account.ts)
+  - Public surfaces: `SmartAccountHelper`, `getCurrentSalt`,
+    `getSmartAccountAddress`, `getAccountCount`,
+    `isSmartAccountDeployed`, `getCurrentSmartAccount`,
+    `SmartAccountConfig`, `SmartAccountResult`
+- `address`
+  - Source: [`src/address.ts`](./src/address.ts)
+  - Public surface: `Address`
+- `bps`
+  - Source: [`src/bps.ts`](./src/bps.ts)
+  - Public surface: `Bps`
+- compatibility and address helpers
+  - Source: [`src/constants.ts`](./src/constants.ts)
+  - Public surfaces: `ZX`, `getExchangeContract`,
+    `getLimitOrderContract`, `getMarketsRegistryContract`,
+    `getNativeOrderFactoryContract`, `getNativeOrderImplContract`
+- generic utilities
+  - Source: [`src/utils/mul-div.ts`](./src/utils/mul-div.ts),
+    [`src/utils/rand-bigint.ts`](./src/utils/rand-bigint.ts),
+    [`src/utils/orderUtils.ts`](./src/utils/orderUtils.ts)
+  - Public surfaces: `mulDiv`, `Rounding`, `randBigInt`,
+    `optionPrmToPrmTokenId`, `prmToOptionPrmTokenId`,
+    `isComplementaryOptionTokenPair`, `verifyOrderSignature`
+
+## Quick Start
+
+The SDK is designed so an integrator can stay inside the package root for most
+common workflows.
+
+```ts
+import {
+  EXCHANGE,
+  OrderHelper,
+  OrderbookApi,
+  SignatureType,
+  TradeType,
+} from "@stryke-xyz/premarket-sdk";
+
+const chainId = 4326;
+
+const helper = new OrderHelper({
+  chainId,
+  exchangeAddress: EXCHANGE[chainId],
+});
+
+const order = helper.buildOrder({
+  maker: "0x1111111111111111111111111111111111111111",
+  receiver: "0x1111111111111111111111111111111111111111",
+  nonce: 0n,
+  marketId: 1n,
+  makingAmount: 1_000_000n,
+  takingAmount: 500_000n,
+  deadline: 1_900_000_000n,
+  tradeType: TradeType.SELL,
+  signatureType: SignatureType.EIP712,
+  tokenId: 42n,
+});
+
+const payload = helper.serializeOrder(order);
 
-## Docs
+const api = new OrderbookApi({ baseUrl: "https://example.stryke.xyz" });
+await api.queryOrders({ marketId: payload.marketId });
+```
+
+For the exact order model, fill semantics, fee math, and typed-data schema, use
+the [Exchange guide](./src/exchange/README.md). For API payloads and response
+DTOs, use the [API guide](./src/api/README.md) and
+[Shared types guide](./src/shared/README.md).
+
+## Smart-Account Helpers
+
+The package root exports the smart-account helpers from
+[`src/smart-account.ts`](./src/smart-account.ts). These helpers are for
+deterministic account derivation and deployment checks that match the
+`SimpleAccountFactory`-style contract surface used by the wider Stryke stack.
+
+Public types:
+
+- `SmartAccountConfig`
+- `SmartAccountResult`
+
+Public functions:
+
+- `getCurrentSalt(accountCount)`
+- `getSmartAccountAddress(client, factoryAddress, owner, depositor, salt)`
+- `getAccountCount(client, factoryAddress, owner)`
+- `isSmartAccountDeployed(client, address)`
+- `getCurrentSmartAccount(client, factoryAddress, owner, depositor)`
+
+Public class:
+
+- `SmartAccountHelper`
+  - `factoryAddress`
+  - `getAddress(client, owner, depositor, salt)`
+  - `getAccountCount(client, owner)`
+  - `getCurrent(client, owner, depositor)`
+  - `isDeployed(client, address)`
+
+```ts
+import {
+  SIMPLE_ACCOUNT_FACTORY,
+  SmartAccountHelper,
+} from "@stryke-xyz/premarket-sdk";
+
+const helper = new SmartAccountHelper({
+  factoryAddress: SIMPLE_ACCOUNT_FACTORY[4326],
+});
+
+const account = await helper.getCurrent(client, owner, depositor);
+```
 
-- Cross-repo guide: `docs/CROSS_REPO_INTEGRATION.md`
-- Orderbook integration quick reference: `docs/orderbook-integration.md`
-- SDK API reference: `docs/API_REFERENCE.md`
+These helpers are intentionally small. They do not execute user operations or
+act as a full account-abstraction SDK. Their job is to keep address derivation
+and deployment checks aligned with the factory contract.
+
+## Address And Bps Helpers
+
+Two utility classes are exported from the package root for common app-side
+operations.
+
+### `Address`
+
+Source: [`src/address.ts`](./src/address.ts)
+
+Public surfaces:
+
+- `Address.NATIVE_CURRENCY`
+- `Address.zeroAddress`
+- `Address.fromBigInt(val)`
+- `Address.fromFirstBytes(bytes)`
+- `toString()`
+- `equal(other)`
+- `isNative()`
+- `isZero()`
+- `lastHalf()`
+
+This helper wraps address normalization and a few convenience checks that are
+useful in UI and backend code.
+
+### `Bps`
+
+Source: [`src/bps.ts`](./src/bps.ts)
+
+Public surfaces:
+
+- `Bps.ZERO`
+- `Bps.fromPercent(val, base?)`
+- `Bps.fromFraction(val, base?)`
+- `equal(other)`
+- `isZero()`
+- `toPercent(base?)`
+- `toFraction(base?)`
+- `toString()`
+
+`Bps` is a small helper around basis-point values in the inclusive range
+`[0, 10000]`.
+
+## Compatibility Constants And Utilities
+
+### Constants helpers
+
+Source: [`src/constants.ts`](./src/constants.ts)
+
+Public surfaces:
+
+- `ZX`
+- `getExchangeContract(chainId)`
+- `getLimitOrderContract(chainId)`
+- `getMarketsRegistryContract(chainId)`
+- `getNativeOrderFactoryContract(chainId)`
+- `getNativeOrderImplContract(chainId)`
+
+The exchange and registry accessors are still useful. The native order factory
+and impl helpers are compatibility-oriented and should be treated as legacy
+bridge helpers rather than the center of new integrations.
+
+### Utility functions
+
+For the detailed utility reference, use the
+[Utilities guide](./src/utils/README.md). The public root-level utility exports
+are:
+
+- `mulDiv`
+- `Rounding`
+- `randBigInt`
+- `optionPrmToPrmTokenId`
+- `prmToOptionPrmTokenId`
+- `isComplementaryOptionTokenPair`
+- `verifyOrderSignature`
+
+## Documentation Principles
+
+The new docs aim to serve both technical readers and product-adjacent readers:
+
+- each module guide starts with purpose and system role
+- every guide links directly to source files that implement the behavior
+- public exports are documented in terms of both intent and exact runtime shape
+- examples stay realistic and contract-aligned
+- restricted or sensitive surfaces are acknowledged, but the docs avoid becoming
+  an admin or auth operations manual
 
 ## Install
 
@@ -37,9 +265,25 @@ bun test src
 
 ## Source Layout
 
-- `src/exchange`: native order model, typed-data, exchange tx helpers
-- `src/vault`: token-id helpers, collateral math, vault tx helpers
-- `src/registry`: markets registry contract wrapper/types
-- `src/api`: `OrderbookApi` and order helper
-- `src/sync`: websocket sync clients
-- `src/config`: chains, addresses, token constants
+- [`src/exchange`](./src/exchange): native order model, typed-data, math, and
+  exchange calldata builders
+- [`src/vault`](./src/vault): token-id helpers, collateral math, and vault
+  transaction builders
+- [`src/registry`](./src/registry): market serialization and registry calldata
+  builders
+- [`src/api`](./src/api): `OrderHelper`, `OrderbookApi`, and deserializers
+- [`src/sync`](./src/sync): realtime market depth and activity clients
+- [`src/config`](./src/config): chains, addresses, and token constants
+- [`src/shared`](./src/shared): transport DTOs used across SDK, API, and UI
+
+## Legacy Docs
+
+The current docs remain available during the transition:
+
+- [Cross-repo guide](./docs/CROSS_REPO_INTEGRATION.md)
+- [Orderbook integration quick reference](./docs/orderbook-integration.md)
+- [SDK API reference](./docs/API_REFERENCE.md)
+- [Refactor notes and protocol specs](./docs/refactor-docs)
+
+Once the new documentation set is fully adopted, these older guides can be
+trimmed or removed with less migration risk.

package/dist/cjs/abi/MarketsRegistry.abi.json

@@ -98,6 +98,16 @@
 						"name": "nonRollable",
 						"type": "bool",
 						"internalType": "bool"
+					},
+					{
+						"name": "isSpread",
+						"type": "bool",
+						"internalType": "bool"
+					},
+					{
+						"name": "useAbsoluteSpreadCollateral",
+						"type": "bool",
+						"internalType": "bool"
 					}
 				]
 			}
@@ -319,6 +329,16 @@
 						"name": "nonRollable",
 						"type": "bool",
 						"internalType": "bool"
+					},
+					{
+						"name": "isSpread",
+						"type": "bool",
+						"internalType": "bool"
+					},
+					{
+						"name": "useAbsoluteSpreadCollateral",
+						"type": "bool",
+						"internalType": "bool"
 					}
 				]
 			}
@@ -772,6 +792,16 @@
 						"name": "nonRollable",
 						"type": "bool",
 						"internalType": "bool"
+					},
+					{
+						"name": "isSpread",
+						"type": "bool",
+						"internalType": "bool"
+					},
+					{
+						"name": "useAbsoluteSpreadCollateral",
+						"type": "bool",
+						"internalType": "bool"
 					}
 				]
 			},

package/dist/cjs/api/README.md

@@ -0,0 +1,296 @@
+# API Guide
+
+The `api` module gives the SDK two high-level integration surfaces:
+
+- `OrderHelper`
+  - a workflow helper for building, hashing, serializing, signing, and
+    recovering orders
+- `OrderbookApi`
+  - the HTTP client for orderbook, market, user, history, and analytics reads
+
+This is the module most frontend and backend product teams use directly.
+
+## Source map
+
+- [`index.ts`](./index.ts) re-exports the public API surface
+- [`order-helper.ts`](./order-helper.ts) wraps exchange helpers into an
+  integration-friendly class
+- [`orderbook-api/index.ts`](./orderbook-api/index.ts) implements the HTTP
+  client
+- [`orderbook-api/deserializers.ts`](./orderbook-api/deserializers.ts) converts
+  string-heavy responses into bigint-friendly client-side objects
+- [`../shared/types.ts`](../shared/types.ts) defines the request and response
+  DTOs consumed by `OrderbookApi`
+
+## OrderHelper
+
+`OrderHelper` exists so most consumers do not need to manually stitch together
+`buildExchangeOrder`, `getExchangeTypedData`, `hashExchangeOrder`, and the
+serialization helpers.
+
+```ts
+import {
+  OrderHelper,
+  SignatureType,
+  TradeType,
+} from "@stryke-xyz/premarket-sdk";
+
+const helper = new OrderHelper({
+  chainId: 4326,
+  exchangeAddress: "0xCf24f40D2dd88084e9C28FE34Ba9E24AFDACb7C2",
+});
+
+const order = helper.buildOrder({
+  maker: "0x1111111111111111111111111111111111111111",
+  receiver: "0x1111111111111111111111111111111111111111",
+  nonce: 0n,
+  marketId: 1n,
+  makingAmount: 1_000_000n,
+  takingAmount: 500_000n,
+  deadline: 1_900_000_000n,
+  tradeType: TradeType.SELL,
+  signatureType: SignatureType.EIP712,
+  tokenId: 42n,
+});
+```
+
+### Constructor config
+
+`OrderHelperConfig`:
+
+- `chainId`
+  - used for hashing and typed-data generation
+- `exchangeAddress`
+  - the verifying contract used in EIP-712 signatures
+
+### Public methods
+
+- `buildOrder(params)`
+  - generic normalized order builder
+- `buildSellOrder(params)`
+  - convenience helper that pins `tradeType = SELL`
+- `buildBuyOrder(params)`
+  - convenience helper that pins `tradeType = BUY`
+- `serializeOrder(order)`
+  - converts `ExchangeOrder` into `SerializedExchangeOrder`
+- `hashOrder(order)`
+  - EIP-712 digest for the configured chain and exchange address
+- `getTypedData(order)`
+  - typed-data payload suitable for a wallet signer
+- `signEip712Order(order, walletClient)`
+  - only valid for `SignatureType.EIP712`
+- `signSimpleAccountOrder(order, ownerWalletClient)`
+  - only valid for `SignatureType.ERC1271`
+  - intended for `SimpleAccount`-compatible flows where the maker contract
+    validates a raw owner signature against the native order hash
+- `signOrder(order, walletClient)`
+  - compatibility alias for `signEip712Order`
+- `recoverOrderSigner(order, signature)`
+  - recovers the address that signed the order payload
+
+```ts
+const signature = await helper.signEip712Order(order, walletClient);
+const payloadOrder = helper.serializeOrder(order);
+const signer = await helper.recoverOrderSigner(order, signature);
+```
+
+## OrderbookApi
+
+`OrderbookApi` is a fetch-based client that understands the backend's envelope
+format, normalizes URLs, surfaces clearer errors, and exposes typed return
+values for the main public read and write flows.
+
+```ts
+import { OrderbookApi } from "@stryke-xyz/premarket-sdk";
+
+const api = new OrderbookApi({
+  baseUrl: "https://example.stryke.xyz",
+});
+```
+
+### Constructor config
+
+`OrderbookApiConfig` from [`../shared/types.ts`](../shared/types.ts):
+
+- `baseUrl`
+  - root URL for the backend
+- `fetchFn?`
+  - optional injected `fetch` implementation for tests or custom runtimes
+
+## Order endpoints
+
+Public order methods:
+
+- `createOrder(params, bearerToken)`
+  - creates a new order with bearer auth
+- `getOrder(orderHash)`
+  - returns `StoredOrder | null`
+- `queryOrders(params)`
+  - list endpoint for orderbook snapshots
+- `getUserOrders(maker, marketId)`
+  - market-scoped user order lookup
+- `getDepthSnapshot(marketId, tokenId)`
+  - point-in-time depth snapshot for a market and token pair
+
+```ts
+const api = new OrderbookApi({ baseUrl: "https://example.stryke.xyz" });
+
+await api.createOrder(
+  {
+    marketId: payloadOrder.marketId,
+    order: payloadOrder,
+    signature,
+    timeInForce: "GTC",
+    postOnly: false,
+  },
+  bearerToken,
+);
+
+const snapshot = await api.queryOrders({ marketId: "1", limit: 50 });
+const mine = await api.getUserOrders(
+  "0x1111111111111111111111111111111111111111",
+  "1",
+);
+```
+
+Important integration note:
+
+- `getUserOrders` enforces `marketId` at runtime
+- `queryOrders` accepts an optional `marketId` in its TypeScript type, but the
+  documented backend contract expects callers to provide one for reliable
+  integration behavior
+
+## Market endpoints
+
+Public market methods:
+
+- `getMarkets()`
+  - returns `MarketsResponse["data"]`
+- `getMarketRecentTrades(marketId, limit?)`
+  - returns `MarketTradeItem[]`
+- `getMarket(marketId)`
+  - returns `MarketResponse["data"] | null`
+
+```ts
+const markets = await api.getMarkets();
+const market = await api.getMarket("12");
+const trades = await api.getMarketRecentTrades("12", 25);
+```
+
+## User positions and PnL
+
+Public user analytics methods:
+
+- `getUserPositions(userAddress)`
+- `getUserTradingPnL(userAddress)`
+- `getUserPnL(userAddress)`
+- `getTokenPnL(userAddress, tokenId)`
+- `getErc20PnL(userAddress, tokenAddress)`
+
+These methods return the shared transport DTOs documented in the
+[Shared types guide](../shared/README.md).
+
+```ts
+const positions = await api.getUserPositions(userAddress);
+const trading = await api.getUserTradingPnL(userAddress);
+const summary = await api.getUserPnL(userAddress);
+```
+
+## Histories
+
+Public history methods:
+
+- `getUserHistories(userAddress, limit?)`
+- `getMintHistory(userAddress, limit?)`
+- `getRedeemHistory(userAddress, limit?)`
+- `getUnwindHistory(userAddress, limit?)`
+- `getTransferHistory(userAddress, limit?)`
+- `getFillHistory(userAddress, limit?)`
+
+These methods are useful when a frontend needs user-facing activity feeds, or
+when a backend wants typed access to grouped historical data without hand-rolled
+endpoint wrappers.
+
+## Deserializers
+
+The API returns string-heavy DTOs because JSON cannot safely transport `bigint`
+values. [`orderbook-api/deserializers.ts`](./orderbook-api/deserializers.ts)
+provides opt-in conversion helpers for clients that prefer `bigint` values.
+
+Public helpers:
+
+- `marketInstrumentToBigInt`
+- `marketToBigInt`
+- `marketsToBigInt`
+- `positionToBigInt`
+- `tradingPnLToBigInt`
+- `mintHistoryToBigInt`
+- `redeemHistoryToBigInt`
+- `unwindHistoryToBigInt`
+- `transferHistoryToBigInt`
+- `fillHistoryToBigInt`
+
+```ts
+import {
+  marketsToBigInt,
+  OrderbookApi,
+} from "@stryke-xyz/premarket-sdk";
+
+const api = new OrderbookApi({ baseUrl: "https://example.stryke.xyz" });
+const marketData = await api.getMarkets();
+const bigintMarketData = marketsToBigInt(marketData);
+```
+
+## Public request and response types
+
+The API client relies on the DTOs exported from [`../shared/types.ts`](../shared/types.ts).
+The most important public request and response shapes are:
+
+- order write and read types
+  - `CreateOrderParams`
+  - `CreateOrderRequest`
+  - `StoredOrder`
+  - `OrderQueryParams`
+  - `OrdersSnapshot`
+  - `QueryOrdersResponse`
+  - `DepthSnapshot`
+- market types
+  - `Market`
+  - `MarketInstrument`
+  - `MarketResponse`
+  - `MarketsResponse`
+  - `MarketTradeItem`
+- user and analytics types
+  - `UserPosition`
+  - `TradingPnL`
+  - `UserPnL`
+  - `TokenPnL`
+  - `Erc20PnL`
+  - `UserHistories`
+  - `MintHistoryItem`
+  - `RedeemHistoryItem`
+  - `UnwindHistoryItem`
+  - `TransferHistoryItem`
+  - `OrderFillHistoryItem`
+
+Those interfaces are broken down field-by-field in the
+[Shared types guide](../shared/README.md).
+
+## Restricted and sensitive surfaces
+
+`OrderbookApi` also exposes auth helpers:
+
+- `getChallenge({ address, chainId })`
+- `verifyAuth({ account, nonce, signature, chainId, expiresAt })`
+
+These methods are part of the public SDK surface, but this document does not
+provide a field-by-field auth payload reference. The goal of the new docs is to
+cover the general integration contract well without turning the repository docs
+into an auth operations manual.
+
+## How to choose between exchange and api modules
+
+- use the [Exchange guide](../exchange/README.md) when you need low-level order
+  math, typed-data primitives, or calldata builders
+- use this module when you want the ergonomics most applications need:
+  `OrderHelper`, `OrderbookApi`, and optional bigint deserializers