@stryke-xyz/premarket-sdk 1.2.1 → 1.2.2

package/dist/cjs/api/README.md

@@ -1,296 +0,0 @@
-# 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

package/dist/cjs/config/README.md

@@ -1,112 +0,0 @@
-# Config Guide
-
-The `config` module is the SDK's deployment and chain registry. It provides the
-named chain objects, token metadata, and contract addresses that other modules
-expect callers to use instead of hardcoding environment-specific values in each
-app.
-
-## Source map
-
-- [`index.ts`](./index.ts) exports token metadata, contract addresses, and the
-  `CHAIN_ID_TO_CHAIN` lookup
-- [`chains.ts`](./chains.ts) defines custom chain objects and the
-  `SUPPORTED_CHAINS` type
-
-## What this module is for
-
-In plain language:
-
-- it centralizes deployed addresses
-- it gives frontend and backend code a common view of supported chains
-- it keeps order builders, API clients, and smart-account helpers pointed at
-  the same runtime contracts
-
-## Chains
-
-[`chains.ts`](./chains.ts) exports:
-
-- `megaETH`
-  - custom viem chain definition for chain id `4326`
-- `SUPPORTED_CHAINS`
-  - TypeScript union of the currently supported chain ids
-
-[`index.ts`](./index.ts) then maps those ids into a runtime lookup:
-
-- `CHAIN_ID_TO_CHAIN`
-
-```ts
-import {
-  CHAIN_ID_TO_CHAIN,
-  megaETH,
-} from "@stryke-xyz/premarket-sdk";
-
-const chain = CHAIN_ID_TO_CHAIN[megaETH.id];
-```
-
-## Token metadata
-
-`Token` is the shared metadata shape for config entries:
-
-```ts
-export interface Token {
-  name: string;
-  symbol: string;
-  address: `0x${string}`;
-  decimals: number;
-  logoURI?: string;
-}
-```
-
-Public token maps:
-
-- `WETH`
-- `USDC`
-- `USDM`
-- `USDT0`
-
-Important nuance:
-
-- `USDM`, `USDT0`, `MARKETS_REGISTRY`, `FEE_REGISTRY`, and
-  `ERC_TOKENS_RESTRICTION_MODULE` are partial maps because those deployments do
-  not exist on every supported chain
-
-## Contract address maps
-
-Public address maps:
-
-- `PERMIT2_ADDRESS`
-- `OPTION_MARKET_VAULT`
-- `EXCHANGE`
-- `MARKETS_REGISTRY`
-- `ENTRY_POINT`
-- `SIMPLE_ACCOUNT_FACTORY`
-- `FEE_REGISTRY`
-- `ERC_TOKENS_RESTRICTION_MODULE`
-
-```ts
-import {
-  EXCHANGE,
-  OPTION_MARKET_VAULT,
-  SIMPLE_ACCOUNT_FACTORY,
-} from "@stryke-xyz/premarket-sdk";
-
-const chainId = 4326;
-
-const exchangeAddress = EXCHANGE[chainId];
-const vaultAddress = OPTION_MARKET_VAULT[chainId];
-const factoryAddress = SIMPLE_ACCOUNT_FACTORY[chainId];
-```
-
-## How this module fits with the rest of the SDK
-
-- the [Exchange guide](../exchange/README.md) uses `EXCHANGE`
-- the [Vault guide](../vault/README.md) uses `OPTION_MARKET_VAULT`
-- the [Registry guide](../registry/README.md) uses `MARKETS_REGISTRY`
-- the root package's smart-account helpers use `SIMPLE_ACCOUNT_FACTORY` and
-  `ENTRY_POINT`
-
-## Operational guidance
-
-If upstream deployments change, this module should be updated before app teams
-scatter new addresses across their own repositories. This is one of the main
-places where the SDK adds value as an integration boundary.

package/dist/cjs/exchange/README.md

@@ -1,280 +0,0 @@
-# Exchange Guide
-
-The `exchange` module is the trading core of the SDK. It models the native
-order format used by Stryke's `Exchange` contract, reproduces its EIP-712
-signing schema, mirrors the most important fee and crossing math, and encodes
-calldata for fills, matches, cancellation, and batching.
-
-For most trading integrations this is the first module to understand.
-
-## Source map
-
-- [`index.ts`](./index.ts) re-exports the public exchange surface
-- [`types.ts`](./types.ts) defines in-memory and transport-safe order types
-- [`order.ts`](./order.ts) builds and validates orders
-- [`eip712.ts`](./eip712.ts) defines the domain, typed data, hashing, and signer
-  recovery helpers
-- [`math.ts`](./math.ts) mirrors pricing, fee, and crossing math
-- [`exchange-contract.ts`](./exchange-contract.ts) encodes calldata for the
-  shipped `Exchange` ABI
-- [`errors.ts`](./errors.ts) decodes custom errors from core protocol ABIs
-
-## What this module is for
-
-In plain language:
-
-- it tells wallets exactly what they are signing
-- it gives resolvers and frontends a stable order shape
-- it lets backend and UI code compute prices and fill amounts the same way the
-  contract does
-- it builds transaction payloads without each consumer bundling its own ABI
-
-## Core order model
-
-The canonical in-memory order type is [`ExchangeOrder`](./types.ts). Every
-numeric field is a `bigint`, so callers do not lose precision between order
-construction and signature generation.
-
-```ts
-export interface ExchangeOrder {
-  salt: bigint;
-  nonce: bigint;
-  marketId: bigint;
-  makingAmount: bigint;
-  takingAmount: bigint;
-  deadline: bigint;
-  maker: Address;
-  receiver: Address;
-  tradeType: TradeType;
-  signatureType: SignatureType;
-  tokenId: bigint;
-}
-```
-
-Related public types:
-
-- `TradeType`
-  - `BUY = 0`
-  - `SELL = 1`
-- `SignatureType`
-  - `EIP712 = 0`
-  - `ERC1271 = 1`
-- `SerializedExchangeOrder`
-  - string-safe transport version for HTTP or persistence
-- `ExchangeOrderStatus`
-  - `{ isFilledOrCancelled, remaining }`
-- `SerializedExchangeOrderStatus`
-  - string-safe status payload
-- `MulticallResult`
-  - helper type for multicall consumers
-
-## Building orders
-
-`buildExchangeOrder` in [`order.ts`](./order.ts) normalizes an order before it
-is signed or serialized:
-
-- `salt` defaults to a random 96-bit-compatible value
-- `receiver` defaults to `maker`
-- `signatureType` defaults to `SignatureType.EIP712`
-- `makingAmount`, `takingAmount`, and `deadline` must all be positive
-
-```ts
-import {
-  SignatureType,
-  TradeType,
-  buildExchangeOrder,
-} from "@stryke-xyz/premarket-sdk";
-
-const order = buildExchangeOrder({
-  maker: "0x1111111111111111111111111111111111111111",
-  nonce: 12n,
-  marketId: 7n,
-  makingAmount: 1_000_000n,
-  takingAmount: 500_000n,
-  deadline: 1_900_000_000n,
-  tradeType: TradeType.SELL,
-  signatureType: SignatureType.EIP712,
-  tokenId: 123456n,
-});
-```
-
-Public builder and validation helpers:
-
-- `buildExchangeOrder(params)`
-  - returns a normalized `ExchangeOrder`
-- `validateExchangeOrder(order)`
-  - enforces the minimal numeric invariants expected by the contract
-- `isOrderExpired(order, nowSec?)`
-  - compares `deadline` against a supplied or current unix timestamp
-- `getExecutableMakingAmount(order, status)`
-  - resolves the important status edge case where
-    `remaining === 0 && !isFilledOrCancelled` means the order is still fully
-    open
-- `getExchangeOrderHash(order, chainId, exchangeAddress)`
-  - convenience wrapper around the typed-data hashing helper
-
-## Signing and hashing
-
-The EIP-712 implementation in [`eip712.ts`](./eip712.ts) is the contract-aligned
-source of truth for signed order payloads.
-
-Important constants:
-
-- `EXCHANGE_EIP712_NAME = "Exchange"`
-- `EXCHANGE_EIP712_VERSION = "1"`
-- `EXCHANGE_ORDER_TYPES`
-  - the exact typed-data fields and enum serialization used in signatures
-
-Public helpers:
-
-- `getExchangeDomain(chainId, verifyingContract)`
-- `getExchangeTypedData(order, chainId, verifyingContract)`
-- `hashExchangeOrder(order, chainId, verifyingContract)`
-- `recoverExchangeOrderSigner(order, signature, chainId, verifyingContract)`
-
-```ts
-import {
-  getExchangeTypedData,
-  hashExchangeOrder,
-} from "@stryke-xyz/premarket-sdk";
-
-const typedData = getExchangeTypedData(order, 4326, exchangeAddress);
-const digest = hashExchangeOrder(order, 4326, exchangeAddress);
-```
-
-Use these helpers whenever you need exact parity with onchain signature checks.
-That includes CI, frontend signing, backend verification, and smart-account
-flows that still sign the native `Exchange` order shape.
-
-## Serialization helpers
-
-`serializeExchangeOrder` and `deserializeExchangeOrder` in [`types.ts`](./types.ts)
-bridge the two most common representations:
-
-- `ExchangeOrder` for local calculations and signing
-- `SerializedExchangeOrder` for APIs, storage, and JSON payloads
-
-Likewise, `serializeOrderStatus` and `deserializeOrderStatus` make it safe to
-transport status objects without losing `bigint` precision.
-
-## Math helpers
-
-[`math.ts`](./math.ts) contains the SDK's exchange-side arithmetic helpers.
-These are intentionally small, deterministic, and contract-aligned.
-
-Public constants:
-
-- `EXCHANGE_ONE = 10n ** 18n`
-- `FEE_RATE_BASE = 1_000_000n`
-
-Public math functions:
-
-- `getTakingAmount(fillMakingAmount, orderMakingAmount, orderTakingAmount)`
-  - floor division from maker-side fill amount to taker-side fill amount
-- `getMakingAmount(fillTakingAmount, orderMakingAmount, orderTakingAmount)`
-  - inverse of the above, also using floor division
-- `calculateFee(grossAmount, feeRate)`
-  - validates `feeRate` is within `[0, 1e6]`
-- `applyFee(grossAmount, feeRate)`
-  - returns `{ fee, net }`
-- `getOrderPriceWad(order)`
-  - normalizes price into 1e18 precision
-- `optionPrmToPrmId(tokenId)`
-  - canonicalizes `oPRM` token ids to the underlying even `PRM` id
-- `isCrossing(orderA, orderB)`
-  - detects valid crosses for complementary trades and mint/merge style matches
-- `hasValidTokenPairForMatch(orderA, orderB)`
-  - enforces token pairing rules for cross, mint, and merge cases
-
-```ts
-import {
-  applyFee,
-  getTakingAmount,
-  isCrossing,
-} from "@stryke-xyz/premarket-sdk";
-
-const takingAmount = getTakingAmount(250_000n, order.makingAmount, order.takingAmount);
-const { fee, net } = applyFee(takingAmount, 2_000n);
-const crossing = isCrossing(buyOrder, sellOrder);
-```
-
-## Calldata builders
-
-`ExchangeContract` in [`exchange-contract.ts`](./exchange-contract.ts) wraps the
-shipped ABI and returns either raw calldata or a minimal transaction envelope.
-
-```ts
-import { ExchangeContract } from "@stryke-xyz/premarket-sdk";
-
-const exchange = new ExchangeContract(exchangeAddress);
-
-const fillTx = exchange.buildFillOrderTx(order, 500_000n, signature);
-const matchData = exchange.getMatchOrderCalldata(
-  takerOrder,
-  takerSignature,
-  makerOrder,
-  makerSignature,
-  100_000n,
-  100_000n,
-);
-```
-
-Public methods:
-
-- `getFillOrderCalldata(order, fillAmount, signature)`
-- `buildFillOrderTx(order, fillAmount, signature)`
-- `getMatchOrderCalldata(takerOrder, takerSignature, makerOrder, makerSignature, takerFillAmount, makerFillAmount)`
-- `buildMatchOrderTx(takerOrder, takerSignature, makerOrder, makerSignature, takerFillAmount, makerFillAmount)`
-- `getCancelOrderCalldata(order)`
-- `getIncrementNonceCalldata()`
-- `getSetResolverWhitelistCalldata(resolver, isWhitelisted)`
-- `getSetFeeReceiverCalldata(newFeeReceiver)`
-- `getPauseCalldata()`
-- `getUnpauseCalldata()`
-- `getMulticallCalldata(data, allowFailure?)`
-
-`buildFillOrderTx` and `buildMatchOrderTx` are the only helpers that currently
-return a full `{ to, data, value }` transaction object. The remaining methods
-return encoded calldata so the caller can place them inside a broader tx or
-user operation.
-
-Restricted/admin surfaces:
-
-- `getSetResolverWhitelistCalldata`
-- `getSetFeeReceiverCalldata`
-- `getPauseCalldata`
-- `getUnpauseCalldata`
-
-These are documented here because they are part of the export surface, but they
-are operationally restricted and should not be treated as general-user flows.
-
-## Error decoding
-
-`decodeContractError` in [`errors.ts`](./errors.ts) attempts to decode a revert
-payload against the shipped `Exchange`, `OptionMarketVault`, and
-`MarketsRegistry` ABIs.
-
-It returns either `null` or:
-
-```ts
-interface DecodedContractError {
-  contract: "exchange" | "optionMarketVault" | "marketsRegistry";
-  name: string;
-  signature: string;
-  args: readonly unknown[];
-}
-```
-
-This is useful for frontend error messaging, backend diagnostics, and test
-assertions where raw revert bytes are not enough.
-
-## Recommended integration pattern
-
-1. Build a normalized order with `buildExchangeOrder` or `OrderHelper`.
-2. Hash or sign using the typed-data helpers.
-3. Serialize the order before sending it to the API.
-4. Use `ExchangeContract` to build fill or match calldata.
-5. Use `decodeContractError` when surfacing or logging contract reverts.
-
-If you want the higher-level workflow wrapper that bundles these steps together,
-continue with the [API guide](../api/README.md), which documents `OrderHelper`.